Wood Supply Simulation System (WS4)

Welcome to the Wood Supply Simulation System (ws4) documentation. WS4 is an open-source, command-line-first forest estate model that treats space as first-class: fragments are the decision units, blocks aggregate them at runtime, and adjacency, patch structure, and road access are enforced inside simulation and optimization rather than allocated after the fact.

Who Is This Documentation For?

  • New users — forest planners, students, and land managers running a first wood supply simulation. Start with Getting started.

  • Analysts and planners — people building scenarios, targeting even flow or patch size distributions, routing products to mills, accounting for carbon, or repeating and scaling runs. See How-to guides and Guides.

  • Researchers and policy analysts — people asking what the model assumes, where the evidence lives, and what a result does not claim. Start with Concepts, Carbon accounting and planning, and Limitations and boundaries.

  • Instructors and students — people learning forest estate modelling from a runnable, inspectable example. Start with Your first model and the Examples.

  • LLM coding agents — assistants that read and edit this repository. Follow AGENTS.md, docs/llms.txt, and Reference for the contracts, invariants, and conventions to respect.

Quick Navigation

Section

For Whom

What You Will Learn

Getting started

New users

Installation, a first run, and how the pieces fit together.

Concepts

New and returning users

What the model is: fragments, strata, annual growth, periods, and the objective.

How-to guides

Analysts

Task guides: targets, even flow, patch size distributions, routes, the Python API.

Examples

Everyone

Runnable notebooks, with their output, that you can read or adapt.

Carbon accounting and planning and Running a carbon study

Analysts, researchers, agents

Carbon packages, libcbm runs, carbon targets, fertilization, HWP lifecycle, carbon yield curves, and the GCBM bridge.

Guides

Power users

Troubleshooting, and what WS4 deliberately does not do yet.

Reference

Everyone

The dataset contract, the simulator, the optimizer, spatial rules, and roads.

3D fire demo

Everyone

A playable 3D fire scene over a real VRI polygon cluster, with synthetic trees and the P156 FBP growth field.

Documentation Sections

Getting started

Concepts

Guides

Reference

Tooling

Indices and Tables