Limitations and boundaries
Every model has edges. This page names WS4’s, so a study is not built on a guess. Each entry says what the boundary is, why, and what to do instead.
The model
Treatments move a stand through a matrix; they are not arbitrary actions. A treatment applies to
a stratum, resets state variables, and moves the area to the resulting stratum’s track. Effects a
treatment has beyond that transition — an unsupported succession or produce semantic — are
not modelled. If your model needs one, express it as a state the transition reaches, or keep it out
of the simulation.
Growth and yield come from curves over an age grid. Ages above the curve’s maximum clamp to its last value, matching linear interpolation. A curve that ends before your rotations do will silently flatten, so extend the curves in the recipe instead.
The expression library is finite. Select statements are evaluated by WS4’s own expression evaluator, which implements the comparisons, the boolean and arithmetic operators, and the function set listed in ForestModelXML recipe. An expression it cannot parse falls back to a term matcher that skips the terms it does not understand, so a compile is best-effort for a model that uses an unsupported function. Check the compiled strata if a select looks wrong.
Space
A patch is what a criterion says it is. Patch membership is a feature curve plus a threshold, so “patch” is only as meaningful as the criterion you choose: a recent-opening criterion gives openings, a seral-stage criterion gives bands of young forest. There is exactly one criterion per patch account; a rule that depends on several cannot be expressed as a patch account.
Adjacency comes from a topology file, and distance is real. search_distance defaults to 0,
which joins only blocks whose polygons touch. The topology’s distance column is the true gap, so
raising the threshold admits roads, creeks, and right-of-ways into patches. That is a modelling
choice, and the default keeps it out.
Patch statistics are kept only at the years a target reads. This is deliberate — it is what makes a patch search affordable — and it means a patch target’s period is a snapshot at its first year, not an average over the period. A patch target on every period of a long horizon costs accordingly.
Roads
Routing is inside the objective, and most of it is incremental. Haul, maintenance, and volume
route accounts are additive over blocks, so a move is priced by a route delta. Three things are not
additive and force a whole-schedule evaluation per step: a route account of kind build, a
duplicate account, and any edge-contrast element. Keep those out while you tune the rest of a study
on a large estate.
Destination choice is exclusive. One destination per product per block, the least-haul-cost reachable eligible one. A split between two mills is not expressible, and a product with no reachable eligible destination is recorded as surplus.
Carbon
Carbon is a sidecar, not a dataset column. The compiled dataset remains the runtime contract. A FEMIC package supplies the static inventory and crosswalks; a schedule supplies events; libcbm supplies ecosystem pools and fluxes. If the package and dataset disagree on a track name, the join fails rather than guessing.
The HWP lifecycle is an explicit public parameter set, not a calibrated truth. The paper/solid split, half-lives, displacement factors, and utilization rate are scenario inputs. Run a range. The first version treats product decay as immediate end-of-life emission to the atmosphere; landfill and inert long-lived pools are not represented.
The block ledger is exact for the block path, not a certificate for every full run.
CBM is area-additive, so the ledger sums blocks exactly. A full-schedule SIT event is
allocated by classifier set and area; when several blocks share a source track, the exact
landscape run can differ slightly after a disturbance. Re-run the winning schedule with
ws4 carbon and report that result.
Carbon yield curves are an interchange and audit artifact. The simulated-clearcut curves expose the public method and a reduced account set, but the WS4 optimizer’s exact path is the block ledger. A curve-based surrogate must be labelled as such and verified against the exact engine before a result is reported.
GCBM is a bridge, not a parity oracle. GCBM and libcbm are separate CFS CBM implementations. Same-footprint bridge runs check export, format, and reader coverage; they do not establish numerical equivalence, and WS4 does not target it.
Optimization
The search finds good schedules, not optimal ones. The solvers are metaheuristics plus exact
per-move deltas. --mip-bound records a penalty lower bound for an option-selection relaxation,
and ws4 solve-mip solves that bounded model exactly for a small instance or subset. Neither is a
certificate of optimality for the full spatial problem: green-up, core area, patch distribution,
routes, and spread connectivity are outside the option model.
Priority tiers are a large multiplier, not a lexicographic proof. priority makes a
higher-priority tier dominate lower tiers in the scalar objective, but a sufficiently large
lower-tier penalty can still compete. The report keeps every raw and normalized target penalty
visible so a review can inspect that trade-off.
Reproducibility is per configuration. The same inputs, seed, and code path give the same result;
changing workers or islands is a different search.
Tooling and platform
Linux only, in practice. WS4 is developed and measured on Linux. Nothing in the runtime is platform-specific, but macOS and Windows are unverified, and the documentation build uses a symlink in the repository layout.
One host. Parallelism is process-level on a single machine (worker processes, islands). There is no distributed execution.
No sample estate ships with the repository. The examples use a small synthetic landscape so the arithmetic stays checkable. Load your own model to see realistic behaviour.
A weights file is not applied. ws4 optimize accepts --weights for compatibility and does
not read it: the weights that apply are each target’s min_weight and max_weight. Applying a
per-account factor file is a capability nobody has asked for yet; the option is optional, so the
trap of a required no-op flag is gone. One settings gap remains tracked: threads is documented
but not applied.
Dataset provenance
The compiled matrix does not know where its inventory came from. A dataset may carry a
data_quality.yaml provenance sidecar with inventory vintage, imputation share, coverage, curve
provenance, and THLB provenance. When the sidecar is absent, ws4 quality and the P26
data_quality block report the field as unknown, not as a pass.
The Great Bear Rainforest instances are not reviewed GBR yield tables. Their natural curves use VDYP, and their managed curves use BatchTIPSY 4.7 under predecessor-TSR assumptions. Their THLB is predecessor-derived rather than a reviewed GBR netdown. Their imputation share and coverage are not recorded in the source manifest. Treat the AAC as a model ceiling, not an operational guarantee.
A schedule is not an operability, market, fire, or access guarantee. The model prices the targets and constraints it is given; it does not certify that a block can be harvested, sold, or treated, or that a landscape will resist fire. State those assumptions in the study record.
Documentation
No textbook section yet. The reference pages explain mechanism, the how-to guides explain tasks, and the notebooks show runs end to end, but WS4 does not yet ship a teaching text equivalent to the conceptual material a new analyst may want alongside it.
What is tracked
The repository’s notes/backlog.md is the live list of known gaps and deferred work, and
notes/design/ holds the measurements and decisions behind the boundaries above. When something
here changes, those notes change first.