Running a carbon study
This guide takes a compiled WS4 dataset and a FEMIC carbon package through a baseline carbon run, an optional simulation merge, a carbon-aware optimization, and optional fertilization. It is the task path; the package tables, failure codes, and engine boundary are in Carbon accounting and planning.
Before you start
You need three things:
A compiled WS4 dataset that passes
ws4 validate. The package joins to the dataset by exacttracks.name; a name that differs by one state token is a hard failure.A FEMIC carbon package. The producer guide is FEMIC carbon package export. The package is static inventory plus crosswalks; it contains no WS4 schedule.
The optional carbon engine:
python -m pip install -e ".[carbon]". A core WS4 install does not importlibcbm.
Carbon is a sidecar, not a new dataset column. The compiled dataset remains the runtime contract, and the package can be replaced without rebuilding the matrix.
1. Validate the package
Run the producer-side validator once, then let WS4 load it on the first carbon command:
femic carbon validate output/carbon/tsa24
ws4 carbon \
--dataset output/ws4/tsa24/compiled \
--package output/carbon/tsa24 \
--schedule schedules/baseline.csv \
--out out/carbon/tsa24-baseline \
--audit-sit
The loader checks the manifest, table hashes, units, classifiers, inventory, yield rows, and every track’s declared eco boundary. Keep the package id, fingerprint, and CBM defaults hash in the study record.
2. Read the baseline outputs
A carbon-only run writes:
carbon_pools.csvandcarbon_pools_long.csvcarbon_flux.csvandcarbon_flux_long.csvcarbon_accounts.csvcarbon_manifest.jsoncarbon_sit/when--audit-sitis set
Check the manifest first. It records the package id and fingerprint, the dataset and
schedule hashes, the engine version, and the CBM defaults version and hash. Then read the
carbon.ecosystem.total and carbon.stock.change series. --density writes
tC/ha instead of tC when you want a per-hectare view.
3. Merge carbon into a simulation run
Use --merge-into when the schedule already has a simulation run and you want one
report:
ws4 carbon \
--dataset output/ws4/tsa24/compiled \
--package output/carbon/tsa24 \
--schedule out/ws4/tsa24-baseline/schedule.csv \
--out out/carbon/tsa24-baseline \
--merge-into out/ws4/tsa24-baseline
carbon.* and, when fertilization is configured, fertilization.* rows are replaced
so a rerun is idempotent. Other accounts are preserved.
4. Add a carbon target to the optimizer
A carbon target uses the same weighted-goal objective, periods, normalization, and priority tiers as any other account. Pass the package so the target can be priced:
ws4 optimize \
--dataset output/ws4/tsa24/compiled \
--targets targets/tsa24-carbon.yaml \
--carbon-package output/carbon/tsa24 \
--out out/ws4/tsa24-carbon-search
A minimal target is a ceiling on ecosystem carbon in one period:
targets:
- account: carbon.ecosystem.total
period: 5
maximum: 134000
period_width: 1
The block-level ledger is area-additive and caches per-block trajectories. It is the
search path, not the final authority: re-run the winning schedule with ws4 carbon and
record the exact result. When several blocks share a source track, a full-schedule event
is allocated at the track/classifier-set level; the ledger is block-exact, so the two can
differ slightly after disturbances. Always verify the final schedule with the exact run.
5. Add fertilization
Fertilization has two modes. Curve mode is the materialized path: produce a public TIPSY response curve with FEMIC, then declare it as an application in the YAML.
femic carbon fertilization-curve \
--package output/carbon/tsa24 \
--track "AU(2401005)+IFM(unmanaged)+ORIGIN(natural)+SILV_STATE(baseline)+RETENTION(0)+treatment()" \
--species SW \
--site-index 20 \
--response-age 40 \
--fertilization-config config/carbon/fertilization.bc.yaml \
--out output/carbon/tsa24/fertilized/f1-2401005.csv
applications:
- treatment: f1
source_track: "AU(2401005)+IFM(unmanaged)+ORIGIN(natural)+SILV_STATE(baseline)+RETENTION(0)+treatment()"
target_track: "AU(2401005)+IFM(unmanaged)+ORIGIN(natural)+SILV_STATE(baseline)+RETENTION(0)+treatment()+F1"
curve: output/carbon/tsa24/fertilized/f1-2401005.csv
Then pass the config to either runtime:
ws4 carbon \
--dataset output/ws4/tsa24/compiled \
--package output/carbon/tsa24 \
--schedule schedules/fertilization.csv \
--fertilization-config config/carbon/fertilization.bc.yaml \
--out out/carbon/tsa24-fertilized
ws4 optimize \
--dataset output/ws4/tsa24/compiled \
--targets targets/tsa24-carbon.yaml \
--carbon-package output/carbon/tsa24 \
--carbon-fertilization config/carbon/fertilization.bc.yaml \
--out out/ws4/tsa24-fertilized-search
Curve mode preserves stand age across the source and target tracks, adds a recovery event
after the response window, and records the gas accounts. Without applications, WS4
falls back to a scalar growth multiplier; use that only for calibration or a quick run,
not for a species/site-specific claim. The public TIPSY response and emissions factors
are documented in FEMIC fertilization audit.
6. Add the HWP lifecycle and system balance
Ecosystem carbon is only one part of the forest-sector balance. Add an HWP configuration to count product storage, end-of-life emissions, and displacement:
ws4 carbon \
--dataset output/ws4/tsa24/compiled \
--package output/carbon/tsa24 \
--schedule schedules/baseline.csv \
--hwp-config config/carbon/hwp.bc.yaml \
--out out/carbon/tsa24-hwp
The public config in FEMIC uses the corrected fresh-yan conventions: 85% utilized
fibre, a 50/50 paper/solid split, exact half-life survival, and a displacement credit on
solid-wood inflow. Those parameters are scenario assumptions, not a single calibrated
truth. Run a grid over plausible half-lives and displacement factors.
The new accounts include carbon.hwp.total, carbon.co2e.hwp.eol,
carbon.co2e.displacement, carbon.system.total, and
carbon.co2e.system.emissions. A system target needs the same config on the optimizer:
ws4 optimize \
--dataset output/ws4/tsa24/compiled \
--targets targets/tsa24-system.yaml \
--carbon-package output/carbon/tsa24 \
--carbon-hwp config/carbon/hwp.bc.yaml \
--out out/ws4/tsa24-system-search
See FEMIC HWP lifecycle for the equations and boundaries.
7. Compile carbon yield curves
ws4 carbon-curves runs one stand per track through libcbm and writes stock and
emission yield curves. Managed curves use the public simulated-clearcut method, so age 0
is the post-harvest state rather than a spun-up reset.
ws4 carbon-curves \
--dataset output/ws4/tsa24/compiled \
--package output/carbon/tsa24 \
--out out/carbon/tsa24-curves \
--rotation-age 120 \
--years 300 \
--mode cycle
The output is carbon_curves.csv plus carbon_curves_manifest.json. Use the curves
for a reduced LP or external scenario formulation; label a curve-based result as a
surrogate and verify the final schedule with the exact ws4 carbon run.
8. Read a GCBM result (optional bridge)
ws4 gcbm reads a raw GCBM results database without FLINT, Wine, or the GCBM runtime:
ws4 gcbm --results gcbm_output.db --out out/gcbm/tsa46 \
--compare-carbon out/carbon/tsa46-baseline
This is a format and bridge check. GCBM and libcbm are separate CFS CBM implementations, and WS4 does not target numerical equality between them. The FEMIC walltowall export is the producer side; see Carbon accounting and planning and Limitations and boundaries before interpreting a comparison.
Common problems
Symptom |
What it usually means |
|---|---|
|
The carbon engine is optional. Install |
|
The dataset and package disagree on a track name. Rebuild the package against the compiled dataset; do not rename a dataset track by hand. |
CBM defaults hash mismatch |
The package and installed database differ. Rebuild the package, or use
|
A carbon target is rejected before search |
Add |
An HWP or system target is rejected before search |
Add |
Ledger and exact run differ after disturbance |
The full run allocates events at track/classifier-set level. Use the exact
|
GCBM comparison is empty |
Check the GCBM 2.5.x schema and whether the run has the same footprint. The reader is tabular; it does not map GCBM rasters to WS4 blocks. |
Next
Carbon accounting and planning — package tables, SIT compilation, optimizer ledger, fertilization, HWP lifecycle, curve method, failure codes, and the GCBM boundary.
Limitations and boundaries — carbon runtime and evidence caveats.
FEMIC carbon package workflow — producer-side export, validation, and crosswalk provenance.
FEMIC HWP lifecycle — public product assumptions and their boundaries.