FHOPS handoff

.. py:module:: nemora.export

Export adapters for external consumers.

The FHOPS adapter writes a standalone individual-tree inventory. It does not import FHOPS or create a FHOPS scenario; FHOPS remains a consumer of the exported contract.

.. py:class:: FhopsTreeExport(inventory_path, metadata_path, inventory_sha256, tree_count, block_id) :module: nemora.export

Bases: :py:class:object

Paths and provenance for one FHOPS tree-inventory export.

.. py:attribute:: FhopsTreeExport.block_id :module: nemora.export :type: str

.. py:attribute:: FhopsTreeExport.inventory_path :module: nemora.export :type: ~pathlib.Path

.. py:attribute:: FhopsTreeExport.inventory_sha256 :module: nemora.export :type: str

.. py:attribute:: FhopsTreeExport.metadata_path :module: nemora.export :type: ~pathlib.Path

.. py:method:: FhopsTreeExport.to_dict() :module: nemora.export

  Return a JSON-serializable export summary.


  :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:attribute:: FhopsTreeExport.tree_count :module: nemora.export :type: int

.. py:function:: export_fhops_tree_inventory(trees, output_dir, *, block_id=’GAVIN_EMPIRICAL’, inventory_id=’nemora-phase9-gavin-empirical’, crs=’EPSG:3005’, origin_x=0.0, origin_y=0.0, size_m=100.0, seed=20261030, producer=’Nemora’, method=’Plot-conditioned empirical resampling; synthetic placement.’, source_id=’bc-faib-psp’, caveats=(‘Synthetic plot-conditioned tree inventory; not a surveyed stand or real tree map.’, ‘Coordinates are deterministic synthetic placement inside a one-hectare block context.’)) :module: nemora.export

Write a FHOPS fhops.tree.inventory.v1 CSV and metadata file.

:type trees: :sphinx_autodoc_typehints_type:\:py\:class\:\~pandas.DataFrame`    :param trees: Synthetic tree rows with ``tree_id``, ``species_code``, ``dbh_cm``, and                  ``height_m``. Extra columns are ignored.    :type output_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path`    :param output_dir: Directory for ``tree_inventory.csv`` and ``tree_inventory.meta.json``.    :type block_id: :sphinx_autodoc_typehints_type::py:class:`str`    :param block_id: FHOPS block identifier.    :type inventory_id: :sphinx_autodoc_typehints_type::py:class:`str`    :param inventory_id: Stable inventory identifier.    :type crs: :sphinx_autodoc_typehints_type::py:class:`str`    :param crs: CRS label for the synthetic coordinates.    :type origin_x: :sphinx_autodoc_typehints_type::py:class:`float`    :param origin_x: Synthetic square block context in the export CRS.    :type origin_y: :sphinx_autodoc_typehints_type::py:class:`float`    :param origin_y: Synthetic square block context in the export CRS.    :type size_m: :sphinx_autodoc_typehints_type::py:class:`float`    :param size_m: Synthetic square block context in the export CRS.    :type seed: :sphinx_autodoc_typehints_type::py:class:`int`    :param seed: Deterministic placement seed.    :type producer: :sphinx_autodoc_typehints_type::py:class:`str`    :param producer: Provenance fields written to the metadata.    :type method: :sphinx_autodoc_typehints_type::py:class:`str`    :param method: Provenance fields written to the metadata.    :type source_id: :sphinx_autodoc_typehints_type::py:class:`str`    :param source_id: Provenance fields written to the metadata.    :type caveats: :sphinx_autodoc_typehints_type::py:class:`tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]` :param caveats: Provenance fields written to the metadata.

:raises KeyError: If a required tree column is missing. :raises ValueError: If the input is empty or size_m is not positive.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.export.FhopsTreeExport``

.. py:module:: nemora.fhops_handoff

Register a FHOPS scenario against an exported tree inventory.

This is an external handoff adapter. It writes FHOPS scenario metadata and checksums without importing FHOPS or changing its core.

.. py:class:: FhopsScenarioRegistration(scenario_path, inventory_path, metadata_path, inventory_sha256, metadata_sha256, block_id, work_required_m3) :module: nemora.fhops_handoff

Bases: :py:class:object

Paths and checksums for a registered FHOPS scenario.

.. py:attribute:: FhopsScenarioRegistration.block_id :module: nemora.fhops_handoff :type: str

.. py:attribute:: FhopsScenarioRegistration.inventory_path :module: nemora.fhops_handoff :type: ~pathlib.Path

.. py:attribute:: FhopsScenarioRegistration.inventory_sha256 :module: nemora.fhops_handoff :type: str

.. py:attribute:: FhopsScenarioRegistration.metadata_path :module: nemora.fhops_handoff :type: ~pathlib.Path

.. py:attribute:: FhopsScenarioRegistration.metadata_sha256 :module: nemora.fhops_handoff :type: str

.. py:attribute:: FhopsScenarioRegistration.scenario_path :module: nemora.fhops_handoff :type: ~pathlib.Path

.. py:method:: FhopsScenarioRegistration.to_dict() :module: nemora.fhops_handoff

  Return a JSON-serializable summary.


  :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:attribute:: FhopsScenarioRegistration.work_required_m3 :module: nemora.fhops_handoff :type: float | None

.. py:function:: register_fhops_scenario(scenario_template, output_dir, inventory_dir, *, block_id=’B01’, work_required_m3=None) :module: nemora.fhops_handoff

Copy a scenario template and pin an exported tree inventory.

:type scenario_template: :sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`~pathlib.Path`    :param scenario_template: Directory containing ``scenario.yaml`` and its ``data/`` files.    :type output_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path`    :param output_dir: Destination scenario directory. It is replaced if it exists.    :type inventory_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path`    :param inventory_dir: Directory containing ``tree_inventory.csv`` and                          ``tree_inventory.meta.json``.    :type block_id: :sphinx_autodoc_typehints_type::py:class:`str`    :param block_id: FHOPS block to reconcile in ``data/blocks.csv``.    :type work_required_m3: :sphinx_autodoc_typehints_type::py:class:`float` | :py:obj:`None`` :param work_required_m3: Optional replacement for the block’s work_required value.

:returns: Registered paths and checksums. :rtype: FhopsScenarioRegistration

:raises FileNotFoundError: If an expected input file is missing. :raises ValueError: If the inventory metadata is inconsistent or the block is absent.

.. py:function:: validate_fhops_scenario_pin(scenario_path) :module: nemora.fhops_handoff

Return whether a scenario’s tree inventory pin matches its files.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\bool``

.. py:module:: nemora.yield_check

Independent inventory-volume checks for FHOPS handoff scenarios.

The estimator is deliberately simple and transparent. It is not a taper model and must not be treated as an operational yield estimate.

.. py:class:: InventoryVolumeEstimate(tree_count, total_volume_m3, mean_volume_m3, merchantable_height_ratio, form_factor, formula) :module: nemora.yield_check

Bases: :py:class:object

Independent volume estimate for a tree inventory.

.. py:attribute:: InventoryVolumeEstimate.form_factor :module: nemora.yield_check :type: float

.. py:attribute:: InventoryVolumeEstimate.formula :module: nemora.yield_check :type: str

.. py:attribute:: InventoryVolumeEstimate.mean_volume_m3 :module: nemora.yield_check :type: float

.. py:attribute:: InventoryVolumeEstimate.merchantable_height_ratio :module: nemora.yield_check :type: float

.. py:method:: InventoryVolumeEstimate.to_dict() :module: nemora.yield_check

  Return a JSON-serializable summary.


  :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`

.. py:attribute:: InventoryVolumeEstimate.total_volume_m3 :module: nemora.yield_check :type: float

.. py:attribute:: InventoryVolumeEstimate.tree_count :module: nemora.yield_check :type: int

.. py:function:: compare_volume_estimates(estimate_m3, *, registered_work_required_m3=None, fhops_processed_m3=None) :module: nemora.yield_check

Compare independent, registered, and FHOPS-processed volumes.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]`

.. py:function:: estimate_inventory_volume(trees, *, merchantable_height_ratio=0.7, form_factor=0.5) :module: nemora.yield_check

Estimate total volume for a tree table with dbh_cm and height_m.

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.yield_check.InventoryVolumeEstimate``

.. py:function:: estimate_tree_volume_m3(dbh_cm, height_m, *, merchantable_height_m=None, merchantable_height_ratio=0.7, form_factor=0.5) :module: nemora.yield_check

Estimate one tree’s volume with a paraboloid-style formula.

V = pi/4 * D^2 * H_m * form_factor with D in metres. The default merchantable height is 70% of total height and the default form factor is 0.5. This is an independent check, not a taper model.

:raises ValueError: If inputs are non-finite, non-positive, or outside (0, 1].

:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\float``

See also