Frequently asked questions
Where do I start?
Quickstart: the command line on the command line, or Quickstart: the Python API if you would rather script it. Then read Your first model, which runs a complete small study.
Why is my optimized schedule empty?
Because nothing in the objective charged for doing nothing. An unconstrained year is free, so the search leaves it alone. Add a floor on the years you care about, or a shape target (Even flow and non-declining yield). See Your first model.
Why does the flow term print ``inf``?
A flow target divides by a balance — the reference period for even, the period before for
ndy. While that balance is zero the term is infinite, by definition. Run once with a linear
volume floor so every period carries wood, then switch the flow target on. See Even flow and non-declining yield.
How do I make the search hold harvest flat?
An even-flow target: a band around zero on the harvest account, plus a separate floor that pulls the level up. The band constrains shape, the floor constrains level, and the same pair works across scenarios. See Even flow and non-declining yield.
How do I require openings of a certain size?
A patch size-distribution target, with a topology edge list. The merge and split
operators exist for this and ship disabled, so give them a weight. See Patch size-distribution targets.
One target is eating the whole objective. What now?
The weights are unbalanced. ws4 calibrate runs a short pilot and writes a targets file with the
weights rescaled so the terms’ peaks are comparable. See Write targets.
Which account do I target?
Standing values are feature.*; what treatments produced are product.*; the shape of the map
is patch.*; routed costs are route.*; carbon is carbon.*, and with an HWP config the
whole-sector balance is carbon.system.* and carbon.co2e.system.*. Run one simulation on an
empty schedule and look at account_values.csv: that is the complete list of what your dataset
can report.
Why is a patch or route run so much slower?
Patch work is confined to the years a target reads, so a patch target on every period of a long horizon keeps many states alive. Routing is incremental for haul, maintenance, and volume, but a build route account, a duplicate account, or edge contrast forces a whole-schedule pass per evaluation. Tune without them, then add them. See Performance and scale.
What about the ``–weights`` file?
It is optional and kept for compatibility; the weights that apply are each target’s
min_weight and max_weight, and ws4 calibrate writes a rescaled targets file for you.
How do I repeat a run exactly?
Record the seed, the horizon, and the whole configuration: the same inputs, seed, and code path give
the same schedule. summary.json carries the seed and the dataset manifest’s digests, which is
what makes a run auditable. See Automate a study.
How do I use all my cores?
Process-level parallelism: starts with workers, or islands with episodes. Threads do
not help the numeric core, which holds the GIL. See Automate a study.
Can I edit a compiled dataset by hand?
No. It is a contract with a manifest that records the inputs’ digests, and every command re-validates it. Change the inputs or the recipe and recompile. See Prepare a dataset.
How do I add carbon to a study?
Use a FEMIC carbon package with ws4 carbon, or --carbon-package on the optimizer.
The package joins by exact track name, so rebuild it against the compiled dataset when the
matrix changes. See Running a carbon study and Carbon accounting and planning.
How do I count harvested wood products, half-life, and displacement?
Add --hwp-config to a carbon run or --carbon-hwp to an optimization. The public
assumptions live in FEMIC’s config/carbon/hwp.bc.yaml. The model reports product
pools, end-of-life emissions, displacement, and whole-system carbon. The parameters are
scenario evidence, not a single calibrated truth; run a range. See
Carbon accounting and planning.
Why are carbon yield curves not the optimizer’s result?
They are an audit and interchange artifact derived from single-stand libcbm runs using the
simulated-clearcut method. The optimizer prices the exact block ledger; a curve-based LP
or surrogate is a different path and must be verified with ws4 carbon. See
Running a carbon study.
Can I compare WS4 carbon with GCBM?
You can read and compare tabular GCBM output, but the comparison is a bridge check, not a parity claim. GCBM and libcbm are separate CFS implementations; do not tune one to match the other. See Limitations and boundaries.
Where do I report a problem, or read what is deliberately missing?
The repository’s issue tracker, and Limitations and boundaries for what WS4 does not do yet.