Context and target applications

fresh-cbm exists because the same deterministic libcbm stand-state calculation is repeated across analyses, scenarios, and optimizer iterations. The cache stores those exact states once and turns later carbon evaluation into a keyed array lookup.

The problem

libcbm is exact and aspatial: a stand’s trajectory is determined by its track, initial age, treatment chain, CBM defaults, and the package configuration. That makes it a good fit for caching. It is also expensive to initialize a model for every state on every search move.

In the TSA41 work, building the removal-effect table through the ordinary CarbonLedger path took:

  • about 156 s for a 5,000-block sample; and

  • about 976 s for the full 148,828-block landscape.

The cache removes that repeated state construction. It does not approximate it.

What this package is

fresh-cbm is a package-level, exact stand-state cache:

  • one row per (track, age, chain) state;

  • per-hectare carbon accounts for every stored year;

  • a versioned manifest that pins the package, CBM defaults, libcbm version, horizon, dtype, accounts, and offsets;

  • a small Python client for lookup; and

  • a builder, validator, and release tooling for producing cache products.

A block effect is produced by the consumer as an area-weighted sum of state rows. The cache itself contains no blocks, topology, or planning targets.

What it is not

Not this

Why

A learned surrogate

Every cached value is an exact libcbm output. Missing states must fall back to libcbm, not to interpolation.

A spatial model

CBM is aspatial. Topology, adjacency, openings, and routes belong to the consuming model.

A policy recommendation

The cache is modelling infrastructure. Policy interpretation belongs in the project that consumes the cache.

A full libcbm replacement

The cache covers only the declared state family. New packages, chains, ages, or configurations need a new or extended cache.

A block inventory

Block area and fragment mapping are dataset-specific and stay outside the state cache.

Who it is for

  • WS4/FEMIC developers who need to remove repeated CBM state construction from carbon optimization and analysis.

  • Carbon analysts running repeated scenarios on a fixed package and state family.

  • Research software engineers publishing reproducible carbon state products.

  • Collaborators and students who need an inspectable, exact carbon state table without running libcbm first.

  • Coding agents that need a stable contract and an explicit fallback path.

Target applications

  1. WS4 carbon removal optimization

    ws4 carbon-removal –state-cache PATH reads carbon cells from the cache and non-carbon cells from the WS4 simulator. The exact effect table is then searched with the GPU population or the MILP knapsack. This is the first production consumer.

  2. Repeated scenario and sensitivity analyses

    Build the state family once, then evaluate many schedules, targets, or policies against the same package without rebuilding CBM state.

  3. Multi-TSA cache products

    Each cache is a package-scoped artifact with its own manifest. TSA-specific products can be published together as long as each names its package and configuration.

  4. Regression and validation fixtures

    The exact state table makes it possible to test carbon consumers against a fixed, inspectable state set instead of a live model build.

  5. Teaching and reproducibility

    A cache release records the exact engine and package identity behind every value, which is useful when a result must be reproduced later.

When to use it

Use the cache when most of the following are true:

  • the same package, CBM defaults, HWP configuration, and horizon will be reused;

  • the required state family is known and bounded;

  • exactness matters more than covering arbitrary future treatment chains;

  • the storage and one-time build cost are acceptable; and

  • you can pin the cache identity in the consuming result.

Run libcbm directly when the analysis is a one-off, the state family is unknown, or the package/configuration changes on every run.

Scope boundary

The cache covers stand states, not landscapes. A consumer still owns:

  • block and fragment inventory;

  • area weighting;

  • spatial and operational constraints;

  • target definitions;

  • final exact replay and reporting.

The first published family is TSA41, actual track/age states, untreated plus one CC event at offsets 0–49. Multi-event chains, fertilization variants, and other packages require additional caches.

A worked example is in Applications and worked example. The data contract is in Cache format; the internal flow is in Architecture and data flow.