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
If you need to |
Read |
|---|---|
Export a package |
|
Understand the whole carbon lane |
|
Apply the public HWP assumptions |
|
Apply the public fertilization response |
|
Consume the package in WS4 |
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
libcbmfor 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
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_version0.1for this contract.package_idProducer-assigned identifier, normally containing the instance and a hash.
created_utcISO-8601 creation timestamp.
producernameandversion.sourcesUpstream source records with a public-safe
pathand asha256digest. The crosswalk files (config/carbon/*.bc.csv) are recorded here so the package states which crosswalk version produced it.cbm_defaultsThe CBM default parameter database
version,sha256, andsource. For the first lane this is the database bundled withlibcbm.unitsarea=ha,volume=m3/ha,carbon=tC,carbon_density=tC/ha,co2e=tCO2e.boundariesThe CBM administrative and ecological boundary names.
mappingtrack_key=track_name, the species classifier name, and the disturbance classifier name (user_dist_type).event_sourcews4.schedule.transition_sourcews4.treatments.table_filesOptional table name to file name mapping; defaults to the layout above.
table_hashesOptional table name to SHA-256 digest. When present, the consumer verifies every digest.
Tables
classifiers.csvLong-form classifier values:
classifier_id,classifier,value, and optionaldescription. A classifier id has one name; aclassifier_id/valuepair is unique.classifier_iddefines the order used bytrack_carbon_map.classifier_set. In the first lane the species classifier values are the CBM species names (for exampleWhite spruce), not the softwood/hardwood aggregate, so CBM can use its species-specific volume-to-biomass parameters.disturbance_types.csvuser_dist_type,default_dist_type,removes_biomass,transition_reset_age,regen_delay, and optionalnotes. Each WS4 treatment gets its own user type even when several map to the same CBM default; this keeps transition rules unambiguous.age_classes.csvnameandclass_size. The first row has size 0; every later row has a positive, constant width. The yield table is sampled on this grid.inventory.csvtrack_name,age,area_ha,delay,landclass,historic_disturbance,last_pass_disturbance, and optionaleco_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 optionalstand_idmay be added later for fragment-level mapping.yield.csvtrack_name,species,leading_species,age,volume_m3_ha. The key istrack_name/species/age. Every track has at least one row. Volume is merchantable volume inm3/ha.speciesandleading_speciesboth carry the CBM species classifier value.track_carbon_map.csvThe bridge table:
track_name,classifier_set,leading_species,softwood_share,hardwood_share,landclass,last_disturbance,eco_boundary,volume_feature_label.classifier_setis a semicolon-separated list in ascendingclassifier_idorder. Shares are 0-1 and sum to at most one. Every leading species is in the species map.curve_carbon_map.csvtrack_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.csvbc_species,cbm_species,wood_type,confidence, and optionalnotes.wood_typeissoftwoodorhardwood. The table is unique bybc_species.boundaries.csvadmin_boundaryandeco_boundary, with optionalspatial_unit_id,source, andnotes. The table may declare more than one pair; the manifest still names the primary boundary, and every track’seco_boundarymust 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 speciesfor an unmapped conifer.Unspecified hardwood speciesfor 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 Fertilization Response and Emissions 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_defaultsversion 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 <package> 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, exacttrack_namejoin, CBM species names, unitsha/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.
libcbmis 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 Harvested wood product 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:
A public release is available with a versioned package and input contract.
A CBM4 driver can consume the SIT/package boundary (directly or through a documented adapter) and emit the same pool, flux, and account semantics.
A parity run on the TSA24 clipped fixture and the real TSA24 package passes the existing tolerance and replay checks.
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
libcbmis an optional extra, pinned exactly to2.10.2in 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
libcbmLinux/macOS wheels and the bundled CBM defaults database.Windows and Wine paths for GCBM
moja.cli.exeandgcbmwalltowall.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
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?
MKRF is a custom research-forest boundary near Maple Ridge; confirm its Pacific Maritime assignment before treating it as a TSA row.
Which retention and partial-harvest cases must the first version represent exactly rather than reject?
When CBM4 is public, does it accept this SIT-compatible package directly or require an adapter, and what is its spatial-input contract?