Carbon Package Export
femic carbon export-package builds the static carbon input package consumed by
WS4 and WS3. The package contains the CBM classifiers, disturbance map, age
classes, initial inventory, merchantable yield table, track and species maps,
boundaries, and a provenance manifest.
This page is the command guide. The lane map is Carbon package workflow; the schema authority is Forest Carbon Domain and CBM Package Contract. The package is the cross-repo contract. It does not contain schedule events or WS4 treatment transitions; WS4 adds those at run time.
Prerequisites
A FEMIC model-input bundle with
au_table.csv,curve_table.csv, andcurve_points_table.csv.A FEMIC checkpoint feather with the fragment inventory.
The draft crosswalks under
config/carbon/.A CBM defaults version and SHA-256. When
libcbmis installed in the active environment, FEMIC detects both from the bundled database. Otherwise pass--cbm-defaults-versionand--cbm-defaults-sha256explicitly.Optional: a compiled WS4 dataset. When supplied, FEMIC reads its
tracks.parquetand resolves exacttrack_namevalues from theAU(<id>)andIFM(<state>)tokens. Without it, FEMIC generates the canonicalAU(<id>)+IFM(<ifm>)+treatment()names.
Command
The supported form selects an instance configuration:
femic carbon export-package \
--config config/carbon/tsa24.yaml \
--bundle-dir data/model_input_bundle \
--checkpoint data/vri_vclr1p_checkpoint7.feather \
--output-dir output/carbon/tsa24 \
--dataset-dir output/ws4/tsa24/compiled
config/carbon/tsa24.yaml and config/carbon/mkrf.yaml carry the default
boundary, crosswalk paths, CBM defaults hash, age grid, and review status. The
config also supplies the TSA/FMU codes, so --tsa is optional when
--config is used.
The explicit form remains available for a one-off export:
femic carbon export-package \
--tsa 24 \
--bundle-dir data/model_input_bundle \
--checkpoint data/vri_vclr1p_checkpoint7.feather \
--output-dir output/carbon/tsa24 \
--dataset-dir output/ws4/tsa24/compiled \
--admin-boundary "British Columbia" \
--eco-boundary "Montane Cordillera"
The CLI resolves paths through the active instance context. Use
--instance-root when the current directory is not the instance root.
The carbon: block is documented by config/carbon/carbon.example.yaml.
Every key has a default except the crosswalk paths, the boundaries, and the CBM
defaults version. validation.expected_area_ha and
validation.expected_track_count are optional pins for a fixture or a release
check.
What it writes
output/carbon/tsa24/
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
The manifest records the source hashes, producer version, CBM defaults version and hash, units, boundaries, table files, and table hashes. The package id contains a short fingerprint of the tables and sources.
Model choices in the first version
One leading species per track. The yield table uses the total merchantable volume curve and assigns it to the CBM species classifier (for example
White spruce), following the WS3 reference. The softwood and hardwood shares remain in the track map for provenance and for a later species-resolved curve.Canonical track names when no dataset is supplied. The default
AU(<id>)+IFM(<ifm>)+treatment()form matches the simple matrix builder. A model with additional themes should pass--dataset-diror supply an explicit track-name map in code.Land class follows the CBM-CFS3 definitions. Managed forest land is class
0(Forest Land remaining Forest Land); unmanaged forest land is class16(Unmanaged Forest Land). This deliberately differs from the WS3 parity fixture, which used0for both. An IFM state with no mapping is an error rather than a silent class-0 fallback.A missing species code falls back explicitly. The fallback is
Unspecified softwood speciesorUnspecified hardwood speciesand is recorded in the package; it is not a silent zero. Species keys follow the public BC VRI data dictionary (for exampleBlsubalpine fir,Sbblack spruce,Eppaper birch), with clearly marked legacy aliases.
Validation
Run the producer-side validator before handing a package to WS4:
femic carbon validate output/carbon/tsa24
femic carbon validate output/carbon/tsa24 --config config/carbon/tsa24.yaml
femic carbon validate output/carbon/tsa24 --expect-area-ha 6016466.4
The command checks the manifest shape, table files and hashes, package
fingerprint, boundaries, classifiers, inventory, yield grid, curve shares, and
declared disturbances. It exits non-zero on an area, classifier, or manifest
mismatch. The optional --expect-area-ha and --expect-tracks flags can be
pinned in the instance config under validation for a fixture.
The public-safe TSA24 fixture at
tests/fixtures/carbon/tsa24_minimal exercises the validator in CI. It is a
synthetic one-track package, not real TSA24 inventory.
WS4 exposes the consumer-side checks in docs/reference/carbon.rst and
ws4/carbon/package.py.
Caveats
The crosswalks under
config/carbon/are draft defaults and need CBM/CFS review.The exporter does not run a carbon engine. Use WS4 for the SIT compile and the libcbm run.
The exporter does not model retention splits or partial harvest beyond the disturbance map. WS4 rejects unsupported retention explicitly.
The exporter writes every observed eco boundary and per-row boundary shares. Multi-boundary packages are supported and validated for TSA08, TSA16, TSA40, and TSA41; a source checkpoint without the ecozone field still falls back to the dominant boundary and records that boundary in the package.
The merchantable yield table is the package authority. WS4 does not resample the compiled dataset’s curves.