Forest Carbon Domain and CBM Package Contract ============================================= Status: reviewed against public VRI/CBM/GIS sources; residual model extensions documented Phase: P115 (forest carbon domain and CBM packages) Purpose ------- This page is the producer-side contract for FEMIC's forest carbon packages. FEMIC owns the static carbon domain: the CBM boundaries, the species and disturbance crosswalks, the initial inventory, the merchantable yield curves, and the provenance that ties them to a source dataset. WS4 consumes the package, joins it to a compiled dataset by track name, adds the schedule-dependent events and treatment-dependent transitions, and runs the carbon engine. WS3 is the reference implementation and parity oracle. The package is the stable cross-repo contract. The engine is replaceable: ``libcbm`` now, CBM4 later, and GCBM as a separate spatially explicit lane. Reader paths ------------ .. list-table:: :header-rows: 1 :widths: 34 66 * - If you need to - Read * - Export a package - :doc:`../../guides/carbon-export` * - Understand the whole carbon lane - :doc:`../../guides/carbon-overview` * - Apply the public HWP assumptions - :doc:`../../guides/hwp-lifecycle` * - Apply the public fertilization response - :doc:`../../guides/fertilization-audit` * - Consume the package in WS4 - `WS4 carbon reference `_ What belongs in FEMIC --------------------- - The package schema, units, rounding, and manifest. - The BC species to CBM species crosswalk. - The TSA/AU to CBM eco-boundary crosswalk. - Land-class and historical-disturbance defaults. - The initial inventory and the SIT-compatible yield tables. - The WS4 treatment label to CBM disturbance-type crosswalk. - The public HWP lifecycle assumptions in ``config/carbon/hwp.bc.yaml``. - The GCBM walltowall export, when that lane is active. What does not belong in FEMIC ----------------------------- - Running ``libcbm`` for every WS4 schedule. - Schedule-dependent disturbance events. - WS4 treatment transitions. - A CBM4 implementation. - A promise that the first crosswalks are science-complete. They are reviewed defaults with explicit confidence and fallbacks. Package layout -------------- .. code-block:: text carbon_package/ manifest.json classifiers.csv disturbance_types.csv age_classes.csv inventory.csv yield.csv track_carbon_map.csv curve_carbon_map.csv species_map.csv boundaries.csv CSV is the interchange form so a reviewer can inspect the crosswalks and the inventory without a database. Strings are written as strings so classifier codes and species codes keep their leading characters. Manifest -------- ``manifest.json`` is a closed schema. Unknown fields are rejected by the consumer so a typo cannot silently disable a check. Required content: ``schema_version`` ``0.1`` for this contract. ``package_id`` Producer-assigned identifier, normally containing the instance and a hash. ``created_utc`` ISO-8601 creation timestamp. ``producer`` ``name`` and ``version``. ``sources`` Upstream source records with a public-safe ``path`` and a ``sha256`` digest. The crosswalk files (``config/carbon/*.bc.csv``) are recorded here so the package states which crosswalk version produced it. ``cbm_defaults`` The CBM default parameter database ``version``, ``sha256``, and ``source``. For the first lane this is the database bundled with ``libcbm``. ``units`` ``area`` = ``ha``, ``volume`` = ``m3/ha``, ``carbon`` = ``tC``, ``carbon_density`` = ``tC/ha``, ``co2e`` = ``tCO2e``. ``boundaries`` The CBM administrative and ecological boundary names. ``mapping`` ``track_key`` = ``track_name``, the species classifier name, and the disturbance classifier name (``user_dist_type``). ``event_source`` ``ws4.schedule``. ``transition_source`` ``ws4.treatments``. ``table_files`` Optional table name to file name mapping; defaults to the layout above. ``table_hashes`` Optional table name to SHA-256 digest. When present, the consumer verifies every digest. Tables ------ ``classifiers.csv`` Long-form classifier values: ``classifier_id``, ``classifier``, ``value``, and optional ``description``. A classifier id has one name; a ``classifier_id``/``value`` pair is unique. ``classifier_id`` defines the order used by ``track_carbon_map.classifier_set``. In the first lane the species classifier values are the CBM species names (for example ``White spruce``), not the softwood/hardwood aggregate, so CBM can use its species-specific volume-to-biomass parameters. ``disturbance_types.csv`` ``user_dist_type``, ``default_dist_type``, ``removes_biomass``, ``transition_reset_age``, ``regen_delay``, and optional ``notes``. Each WS4 treatment gets its own user type even when several map to the same CBM default; this keeps transition rules unambiguous. ``age_classes.csv`` ``name`` and ``class_size``. The first row has size 0; every later row has a positive, constant width. The yield table is sampled on this grid. ``inventory.csv`` ``track_name``, ``age``, ``area_ha``, ``delay``, ``landclass``, ``historic_disturbance``, ``last_pass_disturbance``, and optional ``eco_boundary``. When the optional boundary is present, it is the area-weighted source for splitting a track that spans more than one eco boundary. The consumer checks area, age, delay, land class, and that each disturbance is declared. An optional ``stand_id`` may be added later for fragment-level mapping. ``yield.csv`` ``track_name``, ``species``, ``leading_species``, ``age``, ``volume_m3_ha``. The key is ``track_name``/``species``/``age``. Every track has at least one row. Volume is merchantable volume in ``m3/ha``. ``species`` and ``leading_species`` both carry the CBM species classifier value. ``track_carbon_map.csv`` The bridge table: ``track_name``, ``classifier_set``, ``leading_species``, ``softwood_share``, ``hardwood_share``, ``landclass``, ``last_disturbance``, ``eco_boundary``, ``volume_feature_label``. ``classifier_set`` is a semicolon-separated list in ascending ``classifier_id`` order. Shares are 0-1 and sum to at most one. Every leading species is in the species map. ``curve_carbon_map.csv`` ``track_name``, ``feature_label``, ``species``, ``share``. It maps a WS4 feature label to a species component. The key is unique; share is 0-1. ``species_map.csv`` ``bc_species``, ``cbm_species``, ``wood_type``, ``confidence``, and optional ``notes``. ``wood_type`` is ``softwood`` or ``hardwood``. The table is unique by ``bc_species``. ``boundaries.csv`` ``admin_boundary`` and ``eco_boundary``, with optional ``spatial_unit_id``, ``source``, and ``notes``. The table may declare more than one pair; the manifest still names the primary boundary, and every track's ``eco_boundary`` must appear in this table. Why the join key is the track name ---------------------------------- Dataset-local track ids are stable only within one compiled matrix. Track names carry the state vocabulary and survive a rebuild. The package records the exact ``tracks.name`` strings and WS4 matches them exactly. An unmatched dataset track is a hard failure by default; a fallback is allowed only when the caller records it in the run provenance. Crosswalks ---------- The crosswalk files live under ``config/carbon/`` and are versioned with the code. Each row carries a ``confidence`` and a source note. The first versions are deliberately conservative. Species ~~~~~~~ ``config/carbon/species_map.bc.csv`` maps public BC VRI species codes to CBM default species names. Where a CBM default is broader than the VRI code, the mapping uses the broader default and lowers the confidence. Two explicit fallbacks exist: - ``Unspecified softwood species`` for an unmapped conifer. - ``Unspecified hardwood species`` for an unmapped broadleaf. A fallback is recorded in the package manifest; it is never a silent zero. Eco boundary ~~~~~~~~~~~~ ``config/carbon/eco_boundary.bc.csv`` maps known TSA codes to CBM eco boundaries. The current table was checked by intersecting the public BCGW ``WHSE_ADMIN_BOUNDARIES.FADM_TSA`` polygons with the AAFC Terrestrial Ecozones (2026-10-26). It records the dominant boundary and the overlap share in the notes. ``config/carbon/ecozone_map.bc.csv`` maps the public VRI ``CFS_ECOZONE`` code to the CBM eco-boundary name. The exporter uses that field when the checkpoint carries it, writes every observed pair to ``boundaries.csv``, and keeps the per-row ``eco_boundary`` in the inventory. WS4 compiles the admin/eco SIT classifiers and splits a track's dataset area by the package's boundary shares. The multi-boundary path is implemented and validated for TSA08, TSA16, TSA40, and TSA41; the table may still mark a case as ``split required`` when the source checkpoint lacks the field. MKRF is represented by the ``mkrf`` FMU code in ``config/carbon/mkrf.yaml`` with the Pacific Maritime boundary. Disturbance ~~~~~~~~~~~ ``config/carbon/disturbance_map.bc.csv`` maps normalized WS4 treatment labels to CBM default disturbance types. Matching is case-insensitive. Treatments that do not remove biomass are marked ``removes_biomass = false`` and use a no-stock-change CBM type. ``ct`` uses ``40% commercial thinning`` as an upper-bound proxy for a 40% basal-area removal from below; the actual merchantable-volume removal is normally lower. ``mpb`` uses the 10% moderate default as an evergreen placeholder and must be replaced with a severity-specific type when the instance supplies one. Fertilization is deliberately **not** a plain CBM disturbance row: mapping ``f1``-``f3`` to a no-op would be wrong. WS4 accepts those labels only when ``--fertilization-config`` supplies either materialized curve transitions or the scalar growth-response fallback; the run then adds the audited emissions accounts. The public TIPSY ``FertRespMOF.txt`` table provides the growth response by species, site index, and fertilization age (FDC, SS, SW, PLI, FDI), with the default 80% effectiveness applied over 10 years. The thesis implementation uses a 200 kg N/ha dose and records per-hectare factors of approximately 17.14 kg CO2, 0.0557 kg CH4, and 20.00 kg N2O for one application, with 40.00/60.00 kg N2O for two/three applications. FEMIC exposes the curve transform and the emissions audit; WS4 owns the curve transition, recovery event, and optimizer ledger wiring. The producer guide is :doc:`../../guides/fertilization-audit`; the consumer reference is `WS4 carbon `_. Land class ~~~~~~~~~~ ``config/carbon/land_class.bc.csv`` declares the CBM-CFS3 UNFCCC land class by IFM state: managed forest land is ``0`` (Forest Land remaining Forest Land) and unmanaged forest land is ``16`` (Unmanaged Forest Land), following the definitions in the CBM-CFS3 v1.2 User's Guide, Table 3-2. Nonforest area must be mapped explicitly to its actual land-use class (cropland, grassland, wetland, settlement, or other); there is no generic nonforest default. An unmapped IFM state is a hard error. Provenance and reproducibility ------------------------------ The manifest records: - every upstream source and its hash; - the producer version; - the ``cbm_defaults`` version and hash; - the table hashes; - the package units and boundaries. The consumer computes a package fingerprint over the manifest and table hashes. A package is reproducible when re-exporting the same inputs produces the same fingerprint. A run that uses a different ``cbm_defaults`` database must record the mismatch. Validation rules ---------------- FEMIC validation and the WS4 loader enforce the same contract: - required tables and columns; - unique declared keys; - positive inventory area, non-negative ages and delays; - land class in 0-22; - classifier sets with the right number of values and defined values; - every leading species in the species map; - every yield track present, with non-negative volume; - shares in 0-1 and summing to at most one; - every track's eco boundary declared in ``boundaries.csv``; - declared disturbance types for inventory and treatment mappings; - table hashes when present; - the package fingerprint and the manifest boundaries. ``femic carbon validate `` runs these producer-side checks and exits non-zero on an area, classifier, or manifest mismatch. The public-safe ``tests/fixtures/carbon/tsa24_minimal`` package is the CI fixture. Engine adapter and CBM4 readiness --------------------------------- The package and the SIT tables are the stable contract; the carbon engine is replaceable. The current runtime is ``libcbm==2.10.2`` with the bundled CBM defaults database ``1.2.9300.391`` (SHA-256 ``4bd722d8825abeda3c9cf77247bbd4903824259e2fcc046d9a335336c8842155``). WS4 owns the schedule-to-events/transitions step; FEMIC owns the static package. Neither side imports CBM4 today. The adapter boundary is: - **Package** — schema ``0.1``, exact ``track_name`` join, CBM species names, units ``ha``/``m3/ha``/``tC``, and a manifest with source, table, and CBM-defaults hashes. - **SIT tables** — classifiers, disturbance types, age classes, inventory, yield, events, and transitions. The compiler is engine-neutral in shape, even where the first driver consumes libcbm. - **Driver** — turns SIT tables plus a schedule into pools, fluxes, accounts, and a manifest. ``libcbm`` is the first driver; a CBM4 driver would implement the same outputs and provenance. - **Reporting** — ``carbon.*`` accounts, the block ledger, the optimizer objective, and the run report do not depend on a particular engine. HWP lifecycle (WS4-derived) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The package also does not contain a product-lifecycle ledger. FEMIC publishes the public assumptions in ``config/carbon/hwp.bc.yaml``; WS4 applies them to the merchantable carbon that a disturbance transfers to products. The accounts include paper and solid-wood pools, exact half-life decay, end-of-life emissions, displacement, and the whole-system balance. The method and its boundary are in :doc:`../../guides/hwp-lifecycle`. Carbon yield curves (WS4-derived) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The package does **not** contain carbon stock or emission curves. It contains the static merchantable yield table and the crosswalks. WS4 compiles carbon curves from the package and the compiled dataset by simulating a single stand through libcbm: the managed curve grows to a rotation age, a clearcut transfers the pools and emits the disturbance losses, and the post-event trajectory becomes age 0. The public ``fresh-yan`` repository records the method and the reset-error evidence; the WS4 command is ``ws4 carbon-curves``. This keeps the expensive, schedule-independent curve compile on the consumer side while FEMIC retains the stable, auditable package contract. CBM4 status (2026-10-26) ~~~~~~~~~~~~~~~~~~~~~~~~ CBM4 is the Canadian Forest Service's next-generation, spatially explicit forest carbon model. Public CFS material from May 2026 describes it as open-source with public availability targeted for the latter half of 2026, and a CBM4 workshop was scheduled for IBFRA 2026. No public CBM4 Python package, input schema, or release artifact is pinned in this repository, so CBM4 is treated as **unreleased** until a public source and version are verified. The public ``cat-cfs`` organization currently exposes `libcbm_py `_, `cbm_defaults `_, and `gcbmwalltowall `_. ``gcbmwalltowall`` includes an external ``convert`` path from a prepared GCBM project to CBM4, but it is not a FEMIC runtime dependency and is not used by this phase. The CBM4 status and timing are from the CFS presentation at the EEA/JRC LULUCF Workshop (May 2026) and the IBFRA 2026 workshop listing. Migration triggers ~~~~~~~~~~~~~~~~~~ Revisit CBM4 when all of the following hold: 1. A public release is available with a versioned package and input contract. 2. A CBM4 driver can consume the SIT/package boundary (directly or through a documented adapter) and emit the same pool, flux, and account semantics. 3. A parity run on the TSA24 clipped fixture and the real TSA24 package passes the existing tolerance and replay checks. 4. The release license and platform support are acceptable for the lab environment. What changes and what does not ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A CBM4 migration would change the driver, its version pin, its output mapping, and the calibration/parameter provenance. It would **not** change the package schema, the exact ``track_name`` join, the WS4 event/transition compiler, the ``carbon.*`` account names, the block ledger, the optimizer target interface, or the report contract. Version-pin policy ~~~~~~~~~~~~~~~~~~ - ``libcbm`` is an optional extra, pinned exactly to ``2.10.2`` in FEMIC and WS4. - The CBM defaults version and SHA-256 are recorded in every package and run manifest. - An engine or defaults upgrade requires a new package fingerprint, a parity run, and a changelog entry; it is not a silent dependency refresh. - CBM4 must not be added as a dependency before a public release is verified. Platform watchlist ~~~~~~~~~~~~~~~~~~ - ``libcbm`` Linux/macOS wheels and the bundled CBM defaults database. - Windows and Wine paths for GCBM ``moja.cli.exe`` and ``gcbmwalltowall``. - CBM4 public repository, wheels, input schema, and CFS support policy. - CBM-CFS3 archive tooling, kept only as a reference and not as a runtime dependency. Open questions -------------- 1. Which CBM species default is acceptable for the BC interior hybrid spruce complex, and when should the package use a species-resolved curve instead of a softwood/hardwood share? 2. MKRF is a custom research-forest boundary near Maple Ridge; confirm its Pacific Maritime assignment before treating it as a TSA row. 3. Which retention and partial-harvest cases must the first version represent exactly rather than reject? 4. When CBM4 is public, does it accept this SIT-compatible package directly or require an adapter, and what is its spatial-input contract? Related ------- - :doc:`../../guides/carbon-overview` — producer-side workflow map. - :doc:`../../guides/carbon-export` — package export and validation. - :doc:`../../guides/hwp-lifecycle` — public HWP, displacement, and EOL assumptions. - :doc:`../../guides/fertilization-audit` — public TIPSY response and emissions. - :doc:`../../guides/gcbm-export` — separate GCBM walltowall bridge. - `WS4 carbon reference `_ — consumer-side loader, runtime, HWP accounts, and optimizer ledger. - `fresh-yan `_ — corrected public accounting, curve generation, and HWP grid. - `yan-yancun-masc-thesis-paper `_ — manuscript method and evidence. - ``planning/phase115_forest_carbon.md`` — phase plan and task map. - ``UBC-FRESH/ws3`` — reference implementation and parity oracle.