Optimizer

The optimizer searches for a schedule that meets a set of goal-programming targets over a compiled dataset. It is a layered, pluggable stack (notes/adr/0007): an objective, a problem adapter, a registry of neighbourhood operators, and a metaheuristic solver. Every search records its seed, so a result is reproducible.

Objective

A target names one account and one accounting period, with a minimum, a maximum, or both. The target is an aspiration with a one-sided penalty, not a hard feasibility bound: a minimum charges shortfall and leaves over-performance free unless a maximum is also supplied. A minimum set above the achievable level is therefore a legitimate pull-up device, not an infeasible constraint. The simulation step is one year and is not configurable. Treatments, growth, transitions and road events are all simulated annually, at a simulation offset (offset 0 is the first year); the account time step is a whole number of years — the period length — and is what period_width sets (default 1). Five and ten years are the convention in forest planning; any whole multiple of a year is accepted. For an additive account (volume, area, a count) the account value for the period is the sum of its offsets, compared to the levels, so a decade target is period_width: 10; the penalty is the weighted shortfall below the minimum plus the weighted excess above the maximum, and the objective is the total penalty (lower is better). A patch account is a snapshot of the map rather than an additive quantity, so a patch target is read at the end offset of its period. A carbon account is additive at the block level; the block ledger prices the ecosystem and, with --carbon-hwp, the product/system accounts. See Carbon accounting and planning. Targets load from a YAML file:

targets:
  - account: feature.Volume
    period: 0
    maximum: 500
  - account: product.Yield.managed.Conif
    period: 1
    minimum: 800000
    maximum: 800000
    period_width: 10
  - account: patch.harvest.10_50.size
    period: 1
    minimum: 100
    min_weight: 10000
    shape: non_linear

Period numbering: period 0 is the zero-length pre-simulation snapshot at offset -1, and periods 1 to N are the accounting periods the targets are set on. A target at period: 1 with period_width: 10 reads offsets 0 to 9; period 2 reads offsets 10 to 19, and so on. The year is a display label only: it is the year the period ends on (offset + 1), so period 1 with width 10 displays as the decade ending in year 10. year remains accepted for older target files, but write period.

Flow targets express even flow or non-declining yield without pinning the level, which is the established way to state them: the flow target is set to zero with a weight, and a separate target on the same account sets the level.

targets:
  # the level
  - account: product.Yield.managed.Conif
    period: 1
    minimum: 900000
    maximum: 1400000
    period_width: 10
  # even flow: every period is compared with the reference period, here the final one
  - account: product.Yield.managed.Conif
    period: 1
    flow: even
    period_width: 10
    minimum: 0
    maximum: 0
    min_weight: 0.001
    max_weight: 0.001
  # non-declining yield over the final periods: a period may fall 1% below the one before it,
  # and rise 1% above it, before a penalty is charged. A minimum of 0 instead of -1 allows no
  # decline at all, and leaving the maximum out makes growth free.
  - account: product.Yield.managed.Conif
    period: 1
    flow: ndy
    period_width: 10
    flow_start_period: 16
    flow_end_period: 19
    minimum: -1
    maximum: 1
    min_weight: 1.0
    max_weight: 1.0

flow.even gives each period its percent difference from a reference period, 100 * (x_p - x_ref) / x_ref, where the reference is the final period of the window unless flow_reference_period names another; the reference period itself contributes no value. flow.ndy gives each period the percent change from the one before it, 100 * (x_p - x_{p-1}) / x_{p-1}. flow_start_period and flow_end_period (inclusive) clip the window, defaulting to the whole horizon, and period_width sets the years per period.

Both definitions were checked against the established implementation: its specification describes comparing every period with the final one for even flow and comparing a selected period with an offset period — the previous one for a closing inventory — and its sample scenario makes exactly those two calls. The account is created with a factor of 100, so the values are percentages, and period 0, the state before the simulation starts, is not compared. Two idioms follow from that and are worth copying:

  • The two sides are independent, and each one is a policy. For non-declining yield the value is the percent change from the previous period, so minimum: -1 lets a period come in one percent below its predecessor before anything is charged, and maximum: 1 mirrors it by letting a period come in one percent above. Setting only the minimum is the common case, because the decline is what a policy usually constrains, but the upper side is available when a case wants it. even reads the same way, a percent either side of its reference period.

  • A strict non-declining target is a minimum of zero with no maximum. That is what the sample scenario does for a closing inventory: no decline from the period before is tolerated at all, and growth is free because nothing constrains the upper side. Adding a maximum there would charge the growth as well.

  • Every period of a non-declining window is compared, including the first, which is measured against the period immediately before the window. An even-flow window compares to its reference instead, so its first period is an ordinary member of the band. A window that starts at period 0 has no period before it, so its first period contributes no value.

flow_end_period is inclusive; the legacy year-based flow_end key remains exclusive. A ten-period window covering periods 1 to 10 is flow_end_period: 10 (or legacy flow_end: 101).

The target’s minimum, maximum, weights and shape are applied period by period, so minimum: -1 with maximum: 1 is a one-percent-either-way safe band that the scheduler is free to move inside:

targets:
  # pull the level up; a minimum only, so it never pins the level
  - account: product.Yield.managed.Conif
    period: 1
    minimum: 2000000
    period_width: 10
  # hold the profile flat: +-1% of the final period, and far from free outside that
  - account: product.Yield.managed.Conif
    period: 1
    flow: even
    period_width: 10
    minimum: -1
    maximum: 1
    min_weight: 10000
    max_weight: 10000
    shape: non_linear

That pairing is the useful idiom: the band constrains only the shape, while the level target pulls the profile up. The level target can be deliberately higher than any achievable level; it then acts as a persistent pull-up aspiration rather than a promise. With a dominant flow target, the pair converges on the maximum even-flow harvest the forest can sustain, without the level ever being specified — so the same two targets work across scenarios.

The amount of “dominance” matters. A high flow weight leaves the level term active as a pull and still lets shape win most trade-offs. A priority-tier gap is much more nearly lexicographic: because adjacent tiers are separated by PRIORITY_SCALE (1e9), a lower-tier level target has almost no influence unless the higher-tier flow penalty is effectively tied. Use a tier gap when that hard ordering is intended; use weights when the goal is “dominant but still balanced.”

Because both flow kinds divide by a balance, the term is infinite while that balance is zero — for even the reference period, for ndy every period a comparison starts from. That is definitional, which is why a flow account is switched on only after the reference period is primed: run first with a linear volume minimum above the sustainable level so that every period carries wood, then add the flow target. run_watch takes an initial schedule for exactly that: continue from the primed run.

The weights file is accepted by the command line and the configuration. The spatial constraints add a weighted penalty to the objective (see Spatial structure and constraints): a maximum opening size, a green-up interval, and a core-area rule. Edge contrast accounts (--edge-elements) are added to the account values, so they can be targeted. The penalties are disabled only by the explicit --spatial-override.

Normalization and priority tiers

Targets with different units compete on different scales: a volume floor in cubic metres can dominate a patch-size share or a cost ceiling. Two opt-in target fields make the trade-off explicit.

normalization: auto divides the target’s weighted penalty by the larger absolute minimum/maximum, floored at one. normalization: none is the default and keeps the old behaviour. The scale is recorded in report_targets.csv beside the raw and normalized penalty.

targets:
  - account: product.Yield.managed.Conif
    period: 1
    period_width: 10
    minimum: 800000
    normalization: auto
  - account: patch.harvest.10_50.size
    period: 1
    minimum: 10
    normalization: auto

priority is a positive integer tier, and priority 1 is the strongest tier. Targets at the same tier add normally. When more than one tier is present, a lower-priority tier is multiplied by PRIORITY_SCALE per step (1e9), so a small priority-1 penalty outranks a larger priority-2 one in the scalar search. This is a priority-weighted objective, not a certified lexicographic solve; the run report still carries every target’s raw and normalized penalty so a reviewer can inspect the trade-off. The default priority is one, which leaves the current objective unchanged.

ws4 optimize --dataset build/compiled --targets targets.yaml --out opt

The report columns are raw_penalty, penalty (normalized), scale, normalization, and priority. The incremental evaluator and the MIP/LP option model use the same scale; sensitivity reports the effective normalized marginal.

Search stack

The problem adapter (ws4.opt.core.Problem) carries the objective evaluator, the candidate moves per block, and the operator registry. The operators are:

  • toggle — assign a treatment to a block, or clear an assigned block;

  • shift — move an assigned block to a different year for the same treatment;

  • swap — exchange the assignments of two blocks;

  • lns — large-neighbourhood search: destroy a fraction of the schedule and repair it;

  • cluster — rechoose a connected cluster of blocks, so a move follows the block topology and changes a patch-shaped set at once;

  • merge — treat the negative space between two proximal patches: a gap block that is one criterion short of membership is given a chain that joins the patches;

  • split — clear an articulation block, so its patch separates — the inverse of a merge.

Each operator carries a selection weight. toggle, shift, swap and lns are enabled by default; cluster, merge and split ship at weight zero, so a configuration must give them a weight (--cluster-weight, --merge-weight, --split-weight, or OptimizeConfig.cluster_weight and friends) before they are selected. The CLI disables lns by default when a carbon package is present: a bulk move creates many new stand-state carbon evaluations, and on the tested 500-block and 5,000-block cases the single-block operators were both faster and at least as good. Pass --lns-weight explicitly to re-enable it.

The solvers are simulated annealing (sa), tabu search (tabu), iterated local search (ils), and threshold accepting (threshold), selected by --engine (OptimizeConfig.metaheuristic). A run may use multiple starts (OptimizeConfig.starts), serial or across a process pool (OptimizeConfig.workers), keeping the best. OptimizeConfig.warm_start seeds the search from each block’s first candidate.

Threshold accepting (--engine threshold) accepts an improving move always, and accepts a worsening move while its increase is no larger than the current threshold. The threshold is multiplied by the cooling factor each iteration; --threshold sets the initial value and --cooling sets the factor. It is simpler to explain and tune than SA and is competitive on spatial harvest scheduling. Like SA, it honours --patience and --reversion.

Seeding a target by construction

--seed-greedy builds a starting schedule from the targets instead of relying on the one-block moves to find hundreds of them. In the default mode the declared floors are the goal: candidates are ranked by the penalty they remove per unit of the declared cost ceilings, and taken until the ceilings would be breached. This is the aggregate-area case (#133/P14).

ws4 optimize –dataset build/compiled –targets targets.yaml –seed-greedy …

A reduction goal uses --seed-account instead. The named target must be active and have a maximum; the other maximum targets are its cost ceilings. Candidates are ranked by the penalty they remove from that target per unit of cost, and taken until the target is met or the budget is exhausted. This is the hazard-shaped case:

ws4 optimize –dataset build/compiled –targets hazard.yaml

–seed-greedy –seed-account feature.FuelHazard …

The seed is a starting point, not an enforcement: the search remains free to soften any bound. The goal seed is exact for the simulator’s account deltas, so its result is checked by the same report_targets.csv as a normal run.

Both seed modes score blocks in fork workers when --threads is greater than one, and both stop at the run deadline. If the deadline is reached during seeding, the partial schedule becomes the starting point and the remaining search loop still runs. This keeps a large seed from consuming the entire budget before iteration 1. --seed-candidates caps the chains scored per block; the default is one, because a seed is a starting point and scoring every offset variant is usually not worth a full 50-year evaluation.

For a large feature goal with product cost ceilings, the seed first shortlists the 40,000 blocks with the cheapest direct feature-curve reduction per dollar, then prices the shortlisted chains exactly. The screen is a heuristic for speed; it never substitutes an estimated value for the reported result. Other goal shapes use the full candidate set.

Simulated annealing cools geometrically by default (OptimizeConfig.temperature and OptimizeConfig.cooling). Setting OptimizeConfig.cooling_mode to adaptive (--cooling-mode adaptive) uses the polynomial-time schedule of Aarts and Van Laarhoven instead: the initial temperature is set from the observed uphill moves and decreased from the objective spread, so the schedule needs no per-instance tuning. OptimizeConfig.cooling_window (--cooling-window) sets the iterations per temperature; geometric remains the default.

For scale, an island model (OptimizeConfig.islands and episodes, or --islands / --episodes) runs several islands in parallel as processes and, after each episode, migrates the global best schedule into every island as the next episode’s starting point. The result is deterministic for a given seed.

A continuous search can stop on stability instead of a fixed budget: OptimizeConfig.patience (--patience) ends a start after that many iterations without an incumbent improvement, and 0 disables the rule. The run summary records patience beside iterations and time_limit_reached; the web player exposes the same field as Patience. The stability stop is deterministic for a seed because it counts iterations, not wall-clock time.

A search can also revert to its incumbent: OptimizeConfig.reversion (--reversion) resets the current solution to the best schedule every N accepted moves, then continues from there. 0 disables it. Reversion is a cheap intensification step that recovers a search which has wandered into a poor neighbourhood; the run summary records reversion with the other search settings. It is applied by SA, tabu, and ILS.

The mixed-integer layer (ws4.opt.mip) solves an option-selection MILP (HiGHS via scipy.optimize.milp) for a penalty lower bound and a candidate schedule. Enabling OptimizeConfig.mip_bound (--mip-bound) records the bound, the gap, and the bound status in the summary. With --topology and --max-opening-ha the bound also enforces the stand-centred opening constraints, which tighten it as the cap falls.

Exact option model

ws4 solve-mip solves the option-selection model for a small instance or a declared block subset and writes the same run artefacts as a search:

ws4 solve-mip --dataset build/compiled --targets targets.yaml --out runtime/mip \
  --years 50 --topology topology.csv --max-opening-ha 40

It writes mip.json, schedule.csv, account_values.csv, and report_targets.csv. The model prices additive targets and the optional stand-centred opening rows. It does not model green-up, core area, patch distribution, routes, or spread connectivity, so mip.json records the option objective, the replayed target penalty, the spatial violation count, and that model boundary. --limit-blocks is a diagnostic subproblem, not a fair whole-landscape solve.

scripts/exact_vs_heuristic.py runs the exact lane and a heuristic under the same targets, horizon, and budget, then writes both schedules and an exact_vs_heuristic.json/.md gap report. A zero gap means the heuristic matched the bounded option model; it is not an optimality claim for the full spatial problem.

ws4 optimize --lp-bound records the LP relaxation’s lp_bound, lp_gap, and lp_status in the run summary. validate_search.py --lp-bound carries it through a sweep, and scenario comparison includes the bound/gap fields when a run has them.

Constraint strategies

The spatial rules are penalties by default: an opening, green-up, or core-area violation adds a weighted penalty to the objective, and the search may trade it against the targets. Two opt-in policies make the rules hard:

ws4 optimize --dataset build/compiled --targets targets.yaml --out opt \
  --topology topology.csv --max-opening-ha 40 --min-green-up-years 3 \
  --constraint-strategy reject

penalize is the default. reject refuses a move that would leave the schedule infeasible. repair first tries a one-block local repair — drop an added block, restore a removed one, or restore a modified chain — and rejects the move if the result is still infeasible. The guard wraps the operator registry, so SA delta, SA, tabu, ILS, and threshold all see the same policy.

An infeasible warm start or construction seed is made feasible before the search by removing the blocks in violating patches or green-up pairs. The run summary records constraint_strategy, constraint_stats (proposed, feasible, rejected, repaired, initial removals), and constraint_feasible. The run directory also contains constraint_report.json with the same counts and the final violation records. penalize keeps the scalable incremental penalty path; reject and repair evaluate the full schedule per proposal, so use them on a constrained subproblem or when hard feasibility matters more than throughput.

Flow ceiling

scripts/max_flow.py binary-searches a constant per-period volume floor. It replaces the targets on the chosen account with one floor per accounting period, keeps the other targets, and probes the existing optimizer at each level. A probe passes when every period meets the level within a relative tolerance and the optimizer reports no spatial violations.

python scripts/max_flow.py \
  --dataset build/compiled --targets targets.yaml \
  --account product.Yield.managed.Conif --out runtime/max-flow \
  --years 100 --period-width 10 --iterations 300 --probes 10 \
  --topology topology.csv --max-opening-ha 40 --constraint-strategy reject \
  --flow ndy --flow-tolerance 0

The optional --flow ndy|even adds the matching flow target to every probe; the report keeps floor feasibility and flow feasibility separate and records the worst period change. The high bound is an additive envelope: for each block, the best candidate contribution per period, summed over blocks. It is an upper bound, not a schedule. The advisory ceiling is the highest level a finite probe verified; the output contains max_flow.json, max_flow.md, probe-config.json, the probe run directories, and best-schedule.csv. A zero ceiling still writes a valid report. The ceiling is not a certified maximum.

Run

ws4 optimize --dataset build/compiled --targets targets.yaml \
             --threads 8 --seed 42 --out opt

When a route configuration is given (OptimizeConfig.route_config_path or --route-config), the objective is evaluated with the route model, and the route accounts and duplicate accounts (see Roads, routes, and mills) are resolved into the account values, so targets can be set on accounts such as route.Total.haul.

Validation sweep

scripts/validate_search.py runs the same targets, horizon, and iteration budget through several engines and seeds, then reports the distribution of incumbents. It is orchestration of the same Optimizer the CLI uses, so a record can be reproduced with the equivalent ws4 optimize command. The report is advisory; it does not change a schedule.

python scripts/validate_search.py \
  --dataset build/compiled --targets targets.yaml \
  --engines sa,tabu,ils --seeds 1,2,3 --iterations 500 --years 50 \
  --out runtime/validation

Use --reversion to include the reversion interval in every run, so a sweep can compare a reverted search with the plain one. The JSON records each run’s objective, zero-penalty status, output directory, reversion interval, and (with --mip-bound) the lower bound and gap. The Markdown table reports runs, best, mean, median, worst, and population standard deviation per engine. Use it before a release or a benchmark claim: a single seed is an anecdote, and a single engine is not a comparison.

Target sensitivity

scripts/sensitivity.py reads a completed run’s report_targets.csv and the target file that produced it, then reports each target’s distance to its nearest bound, whether it is binding, and the per-unit objective weight that applies when a bound is relaxed. It is advisory and does not change a schedule.

python scripts/sensitivity.py --run opt --targets targets.yaml --out opt/evidence

A missed target has a marginal cost per unit; a target with slack is not controlling the plan. A binding target exactly at its bound with zero shortfall has no penalty to remove, so its marginal is also zero. The JSON and Markdown reports are suitable for a plan review or an AAC negotiation record.

Search portfolio and Pareto front

The search minimizes one weighted-goal penalty. A decision review often needs the neighbouring answers too, so scripts/portfolio.py re-runs the existing optimizer over a grid of target-weight factors. Every member keeps its objective and realized metrics; ws4.opt.archive keeps the elites and filters the nondominated front.

python scripts/portfolio.py \
  --dataset build/compiled --targets targets.yaml --out runtime/portfolio \
  --vary "product.Yield.managed.Conif=0.5,1,2;feature.Old=1,2" \
  --metrics product.Yield.managed.Conif,feature.Old \
  --directions "product.Yield.managed.Conif=max;feature.Old=max" \
  --seeds 1,2,3 --iterations 500 --years 50

A five- to seven-target scan can exceed a useful run count. Keep --mode grid for an exact Cartesian product, or use --mode random with --max-members and --sample-seed to take a deterministic sample of distinct grid positions without materializing the full product:

python scripts/portfolio.py \
  --dataset build/compiled --targets targets.yaml --out runtime/portfolio \
  --vary "product.Yield=0.5,1,2;feature.Old=0.5,1,2;feature.Habitat=1,2" \
  --mode random --max-members 64 --sample-seed 7 --workers 4 \
  --metrics feature.Old,feature.Habitat --directions "feature.Old=max;feature.Habitat=max"

--workers runs independent members in separate processes. Each worker loads its own copy of the compiled dataset, so the default is one; raise it only when the host has memory for the model copies. --initial-schedule supplies a starting schedule for every member, which is needed when flow targets cannot be satisfied from an empty start. The web launcher also offers a level-only target copy for scans that should ignore flow rows. The output layout, per-member summaries, and seeded replay are unchanged.

A factor multiplies the matching targets’ min_weight and max_weight; the bounds and the other targets are unchanged. An account@period key varies one period. The metrics read account_values.csv: a bare name is the last offset, name@sum sums the horizon, and name@<offset> reads one year. The output directory contains the member runs, portfolio.json, portfolio.md, front.csv, and an archive/ directory with the manifest and one schedule CSV per archived elite.

The front is a finite grid under a fixed budget and seed set. It is advisory, not a certified optimum, and a weight vector that reaches the same metric point as another keeps the lower scalar objective. The reported front/outcome_front is computed from every successful member over the declared outcome metrics; the scalar objective remains an optional dimension but does not define dominance. The archive/ directory remains capacity-bounded so it can keep one schedule per retained elite without growing without limit. Use ws4.opt.solution_space.build_solution_space() or GET /api/search/{name}/space to read the full-member view.

Tuner

scripts/tune.py runs a grid or a seeded random sample over a small set of OptimizeConfig fields. Every candidate uses the same dataset, targets, seeds, and iteration budget; the report ranks by best and then median objective, so one lucky seed does not choose the winner. Path fields and the evaluation seed are not tunable.

cat > runtime/space.json <<'JSON'
{"temperature": [100, 500, 1000], "cooling": [0.9, 0.95, 0.99]}
JSON
python scripts/tune.py \
  --dataset build/compiled --targets targets.yaml --space runtime/space.json \
  --out runtime/tuning --seeds 1,2,3 --iterations 300 --years 50

Use --mode random --budget 12 to sample instead of crossing the grid. The directory contains one run per candidate and seed, tuning.json, tuning.md, and best.json for the winning parameters. A failed seed is named in the report rather than aborting the sweep. The ranking compares a finite budget; it is not an optimality claim.

LP dual and reduced-cost sensitivity

scripts/lp_sensitivity.py relaxes the option-selection model’s binary variables to [0, 1] and solves the same target and opening rows with HiGHS through scipy.optimize.linprog. The LP objective is a lower bound on the mixed-integer penalty. Each target row reports a dual: the objective reduction from relaxing its bound by one unit (lowering a minimum or raising a maximum). Each option variable reports its LP value and reduced cost.

python scripts/lp_sensitivity.py \
  --dataset build/compiled --targets targets.yaml --out runtime/lp \
  --years 10 --limit-blocks 2000 --top 20

Use --limit-blocks to declare a subproblem; a full landscape is much larger than this report is intended to solve. --topology and --max-opening-ha add the same stand-centred opening rows as the MIP bound. The JSON and Markdown are advisory: they price the relaxation, not a schedule, and a zero dual on a non-binding row is expected.

Watch

ws4 watch runs the same search and paints the realized-versus-target window of an account in place: one column per period, the minimum/maximum target band shaded, and the realized value drawn over it, coloured by status (green inside the window, red below the minimum, blue above the maximum). Targets are per period; the view groups offsets into periods of --period-width years, so per-period levels that sum to a periodic target read as the periodic window. --plain prints one final frame instead of a live view. The live view repaints on a fixed heartbeat (--refresh seconds, default 2), independent of the search, so the header (iteration rate, objective) stays current even between improvements.

Repeat --account to watch several accounts side by side, one window each — each with its own axis, title and penalty, so accounts with different units read correctly. A percentage account (the patch size-class …<class>.size shares of total patch area) is averaged over a period, not summed, since summing a share would multiply it by the period length. That is how to see a volume target (m3 per period) and a patch size-class target (percent of patch area) converging together:

ws4 watch --dataset build/compiled --targets targets.yaml \
          --account product.Yield.managed.Conif --account patch.harvest.10_50.size \
          --period-width 10 --years 200 --iterations 5000 --warm-start \
          --patch-accounts patches.yaml --topology topology.csv

Patch size distribution

Patch accounts (the size distribution of connected patches of a criteria feature — see Spatial structure and constraints) are non-additive: a patch spans adjacent blocks, so the move-based delta does not apply directly. Give --patch-accounts (a YAML of definitions) with --topology, and set targets on the sub-accounts:

accounts:
  - name: patch.harvest
    criteria: feature.Seral.young
    threshold: 0.5
    size_classes: [5.0, 10.0, 50.0, 250.0, .inf]
    search_distance: 200.0

Targets then read patch.harvest.50_250.area, …size, …frequency, or …shape.

Patch accounts are not additive, so the simulator reports them in patch_accounts.csv rather than in the account values. A run’s report_targets.csv folds them back in before pricing the targets, so a patch target’s status and penalty are the same ones the search saw.

search_distance (metres) is how far apart two blocks may be and still be neighbours. It defaults to 0, which joins only blocks that literally touch (their polygons share a vertex); a larger value admits more neighbour edges, so patches can only get larger. The topology’s DISTANCE column is the shortest distance between the two blocks’ polygons, so a non-zero value is a real gap — a road, a creek, a right-of-way — that the default keeps out of a patch.

The criteria feature decides what a patch is. feature.Seral.regen is a recently disturbed stand (up to ~37 years), which is what a harvest opening looks like; feature.Seral.young is a seral stage 42-97 years after disturbance, so a patch of it is a band of young forest, not an opening. Pick the criterion that matches the question.

Each block’s criterion series is cached per chain, the adjacency is indexed by block, and a move updates only the components near the moved block — a resize, a merge, a new standalone patch, or a removal/split. A patch move therefore costs a few milliseconds of patch work rather than a full re-simulation. Patch statistics are also kept only at the offsets a target actually reads (the end offset of each period), because the simulation is annual while the accounting is periodic; on a 200-year, 20-period benchmark with a volume floor and a patch ramp that change alone took the search from 62 to 310 iterations/s.

Spread connectivity

Spread-connectivity accounts (how fragmented the fuel body a fire could run through is — see Spatial structure and constraints) are non-additive for the same reason patch accounts are: a compartment is a property of the whole landscape, and no per-block delta can see it. When one is configured, delta_evaluator declines and every move is priced by a full re-simulation, so this is the slowest spatial target to search against.

Give --spread-accounts (a YAML of definitions) with --block-coordinates (a CSV of block,x,y), and set targets on the sub-accounts:

# spread.yaml
accounts:
  - name: spread.ft
    criteria: product.Treated.managed.FT
    bearing: 225
    tolerance: 60
    search_distance: null
# targets.yaml
targets:
  - account: spread.ft.largest_component
    period: 20
    period_width: 10
    maximum: 50000
    max_weight: 1.0

A run writes spread_metrics.csv (and, when block coordinates are available, spread_membership.csv for the map), and report_targets.csv folds the metrics back in before pricing the targets, so the status and penalty are the ones a re-simulation gives. The option is on optimize, watch and calibrate. bearing is the direction the fire travels (the wind direction), in degrees clockwise from north; tolerance is the half-width of the fast-edge cone.

Calibrate

Targets of different magnitudes unbalance the objective: the largest term dominates and the search freezes before the others are considered. ws4 calibrate runs a short pilot search, records the largest penalty each target reaches, and writes a targets file whose weights are rescaled so the peaks match. Pass the result to optimize or watch.

ws4 calibrate --dataset build/compiled --targets targets.yaml --out calibrated.yaml \
              --topology topology.csv --patch-accounts patches.yaml --warm-start
ws4 optimize --dataset build/compiled --targets calibrated.yaml --out opt

A target that never fires in the pilot keeps its own weights. Match --warm-start to the run’s setting: a warm-started pilot starts from the same schedule, so terms that only appear once blocks are harvested (such as a patch term) register.

Outputs

File

Contents

schedule.csv

The incumbent schedule (block_id,treatment,offset).

summary.json

The run summary: objective, iterations, patience, reversion, seed, metaheuristic, operators, block count, status, time-limit flag, dataset reference. and the dataset manifest.

account_values.csv, product_values.csv

The simulated account and product values for the incumbent schedule.

report_accounts.csv, report_targets.csv

The account summary and the per-target status, including target kind and normalized penalty.

ending_inventory.csv

The final feature-inventory value per account at the last offset.

telemetry.jsonl

A run header and one record per search step.

Run manifest and data quality

Every run writes two review artefacts beside the summary:

  • run_manifest.json: the ws4 version and Git revision (when available), the dataset reference and source hashes, the full OptimizeConfig, the seeds, the Python/package environment, and a reproduce command. The command repeats the principal settings; the full configuration is in the manifest.

  • data_quality.json: the dataset manifest metadata, Parquet table row counts, target-account coverage, and a list of explicit unknowns and model limitations. The run summary carries a compact data_quality block and the report path.

Install a tracked sidecar and check it in one command with ws4 quality --sidecar PATH --check. The quality status distinguishes not supplied from checked and good. A dataset with no metadata reports unknown and names the missing inventory-vintage/imputation/coverage fields rather than treating an empty block as a pass. Derived accounts (patch.*, route.*, spread.*) are reported separately because they are not rows in accounts.parquet. The dataset may carry a data_quality.yaml sidecar; see Limitations and boundaries for the provenance contract and the GBR caveats.

Scenario comparison

scripts/compare_scenarios.py reads completed runs and compares them over one landscape:

python scripts/compare_scenarios.py \
  --run base=runtime/base --run dense=runtime/dense \
  --metric product.Yield.managed.Conif:max --metric feature.Old:min \
  --out runtime/compare

Each --run takes label=path. The output contains scenarios.json, scenarios.md, scenario_runs.csv, scenario_targets.csv, scenario_accounts.csv, scenario_ending.csv, and scenario_flows.csv. With --metric the command also reports the nondominated front over those accounts; an account missing from a run keeps that run off the front rather than inventing a value. A missing summary, target report, or constraint report is shown as unavailable, not as passing.

API

class ws4.opt.engine.OptimizeConfig(threads: int = 1, time_limit: str = '01:00:00', seed: int = 42, targets_path: str = '', initial_schedule_path: str = '', control_path: str = '', weights_path: str = '', years: int = 50, iterations: int = 500, patience: int = 0, reversion: int = 0, temperature: float = 1000.0, threshold: float = 1.0, cooling: float = 0.99, cooling_mode: str = 'geometric', cooling_window: int = 64, metaheuristic: str = 'sa', tenure: int = 10, perturbation: int = 2, starts: int = 1, workers: int = 1, islands: int = 0, episodes: int = 1, warm_start: bool = False, greedy_seed: bool = False, seed_account: str = '', mip_bound: bool = False, lp_bound: bool = False, topology_path: str = '', sdmd_dir: str = '', route_config_path: str = '', edge_elements_path: str = '', max_opening_ha: float | None = None, min_green_up_years: int | None = None, core_buffer_m: float | None = None, min_core_area_ha: float | None = None, spatial_weight: float = 1.0, allow_spatial_override: bool = False, constraint_strategy: str = 'penalize', toggle_weight: float = 1.0, shift_weight: float = 1.0, swap_weight: float = 0.5, lns_weight: float = 0.2, lns_destroy: float = 0.1, lns_max_destroy: int = 64, cluster_weight: float = 0.0, cluster_size: int = 8, coalesce_weight: float = 0.0, coalesce_size: int = 8, coalesce_min_area_ha: float = 5.0, coalesce_max_area_ha: float = 40.0, warm_cache: bool = False, patch_accounts_path: str = '', carbon_package_path: str = '', carbon_fertilization_path: str = '', carbon_hwp_path: str = '', carbon_workers: int = 1, seed_candidates: int = 1, spread_accounts_path: str = '', block_coordinates_path: str = '', flood_screen_config_path: str = '', merge_weight: float = 0.0, split_weight: float = 0.0, flow_repair_trials: int = 0, flow_repair_chains: int = 4, scenario_path: str = '', risk_validation_fraction: float | None = None)[source]

Configuration for an optimization run.

A configuration is the complete, reproducible description of a run: the objective targets, the horizon and accounting period, the metaheuristic and its schedule, the neighbourhood operator weights, the spatial constraints, and the optional patch and route models. Every stochastic search is seeded from seed.

threads

The number of BLAS threads each process may use, and, on the command line, the number of worker processes. One thread per process is the right default for a pool: the numeric core is NumPy-heavy, so oversubscribing the pools costs more than it buys.

Type:

int

time_limit

The wall-clock limit, as HH:MM:SS.

Type:

str

control_path

A JSON file the search polls: {"action": "pause"} holds it between iterations and {"action": "stop"} makes it return its best schedule and write its summary. Empty when the run has no control file.

Type:

str

seed

The random seed. A run is reproducible for a given seed.

Type:

int

targets_path

The YAML file of goal-programming targets.

Type:

str

initial_schedule_path

A block_id,treatment,period CSV to start the search from. It is shared by every start and island.

Type:

str

weights_path

Accepted for compatibility and not read. The weights that apply are each target’s own min_weight and max_weight; ws4 calibrate rescales them into a targets file.

Type:

str

years

The horizon in years. The simulation step is one year.

Type:

int

iterations

The iteration budget of the search.

Type:

int

patience

Stop a start after this many iterations without an incumbent improvement; 0 disables the criterion. It is the stability stop for a continuous search.

Type:

int

reversion

Reset the current solution to the incumbent every this many accepted moves; 0 disables it. Applied by SA, tabu, and ILS.

Type:

int

temperature

The initial simulated-annealing temperature.

Type:

float

threshold

The initial threshold-accepting threshold, in objective units.

Type:

float

cooling

The geometric cooling factor.

Type:

float

cooling_mode

"geometric" or "adaptive" (Aarts and Van Laarhoven).

Type:

str

cooling_window

The iterations per temperature in adaptive mode.

Type:

int

metaheuristic

"sa", "tabu", "ils", or "threshold".

Type:

str

tenure

The tabu tenure, in iterations.

Type:

int

perturbation

The number of moves per perturbation in iterated local search.

Type:

int

starts

The number of independent starts, keeping the best.

Type:

int

workers

The number of processes used for the starts; 1 runs them serially.

Type:

int

islands

The number of islands in the island model; 0 disables it.

Type:

int

episodes

The number of migration episodes in the island model.

Type:

int

warm_start

Whether to seed the search from each block’s first candidate chain.

Type:

bool

greedy_seed

Whether to seed the search from a schedule built by construction instead: candidates ranked by the penalty they remove from the declared floors per unit of the declared ceilings, taken in that order while no ceiling is breached. Unlike warm_start it reads the targets, so it respects a budget rather than ignoring it.

Type:

bool

seed_account

When set with greedy_seed, the target account to reduce to its maximum instead of satisfying floors. Other maximum targets are its cost ceilings; this is the hazard-shaped seed. Empty uses the floor mode.

Type:

str

mip_bound

Whether to solve the mixed-integer lower bound and record it in the summary.

Type:

bool

lp_bound

Whether to solve the LP relaxation and record its bound, gap, and status.

Type:

bool

topology_path

The block topology edge list, for the spatial and patch models.

Type:

str

sdmd_dir

An SDMD store with regimes.csv and au_constraints.csv. When set, every move must satisfy the per-AU entry cap and interval, and the guard rejects an infeasible seed.

Type:

str

route_config_path

The route configuration, for the road model.

Type:

str

edge_elements_path

The edge-contrast element definitions.

Type:

str

max_opening_ha

The maximum opening size, in hectares; None disables the rule.

Type:

float or None

min_green_up_years

The green-up interval; None disables the rule.

Type:

int or None

core_buffer_m

The core-area buffer distance, in metres; None disables the rule.

Type:

float or None

min_core_area_ha

The minimum core area, in hectares; None disables the rule.

Type:

float or None

spatial_weight

The weight on the combined spatial penalty.

Type:

float

allow_spatial_override

Whether to run with the spatial penalties explicitly disabled.

Type:

bool

constraint_strategy

"penalize" (the default) prices a spatial violation in the objective; "reject" refuses an infeasible move; "repair" tries to keep the feasible part of a move before rejecting it.

Type:

str

toggle_weight

The selection weight of the toggle operator.

Type:

float

shift_weight

The selection weight of the shift operator.

Type:

float

swap_weight

The selection weight of the swap operator.

Type:

float

lns_weight

The selection weight of the large-neighbourhood search operator.

Type:

float

lns_destroy

The fraction of the schedule the large-neighbourhood search destroys.

Type:

float

lns_max_destroy

The maximum number of blocks one LNS move may destroy. A cap keeps the move’s cost bounded as the schedule grows.

Type:

int

cluster_weight

The selection weight of the cluster operator; 0 disables it and its topology.

Type:

float

cluster_size

The maximum number of blocks in a cluster move.

Type:

int

coalesce_weight

The selection weight of the coalesce operator, which aligns a connected cluster onto one treatment year; 0 disables it.

Type:

float

coalesce_size

The maximum number of blocks in a coalesce move.

Type:

int

coalesce_min_area_ha

The smallest opening area a coalesce move will build.

Type:

float

coalesce_max_area_ha

The largest opening area a coalesce move will build.

Type:

float

warm_cache

Whether to pre-warm the per-block delta cache before the search.

Type:

bool

patch_accounts_path

The patch account definitions, enabling the patch size-distribution targets.

Type:

str

carbon_package_path

The FEMIC carbon package. When set, carbon accounts are added to the objective and the run report, and carbon.* targets are allowed.

Type:

str

carbon_fertilization_path

The fertilization YAML. When set with carbon_package_path, the carbon ledger applies the materialized curve transitions or the growth multiplier and includes the emissions accounts.

Type:

str

carbon_hwp_path

The HWP lifecycle YAML. When set with carbon_package_path, the carbon ledger adds the product pools, end-of-life emissions, displacement, and whole-system carbon accounts.

Type:

str

carbon_workers

Fork workers for the carbon ledger’s empty-schedule base. One is serial. The optimizer forces one when islands or process-parallel starts are active.

Type:

int

seed_candidates

The most candidate chains per block that --seed-greedy scores. A seed is a starting point, so the default is one; raise it only when a wider shortlist is worth the extra full-chain evaluations.

Type:

int

spread_accounts_path

A YAML file of spread-connectivity account definitions; needs topology_path for the adjacency and block_coordinates_path for the bearings.

Type:

str

block_coordinates_path

A CSV of block centroids (a block id, an x and a y), read for the spread accounts’ bearings.

Type:

str

flood_screen_config_path

An optional ws4.hydrology.flood_screen.v1 configuration. When set, the optimizer evaluates flood.* accounts from the registered FEMIC bundle and mapping. Refused schedules receive the configured penalty instead of extrapolating.

Type:

str

merge_weight

The selection weight of the merge operator, which treats gap blocks.

Type:

float

split_weight

The selection weight of the split operator, which clears articulation blocks.

Type:

float

flow_repair_trials

The number of exact candidate moves a bounded flow-directed repair pass may price after the search, or 0 to disable it. The pass shifts harvest from periods above an even-flow target into periods below it and accepts only exact improvements.

Type:

int

flow_repair_chains

The most directed candidate chains the repair pass prices for one block.

Type:

int

scenario_path

An optional scenario YAML/JSON file. When set, the optimizer evaluates risk targets through a fast account-multiplier overlay. Risk targets require non-single aggregation. Empty keeps the deterministic objective.

Type:

str

risk_validation_fraction

When set with a scenario file, split the ensemble and write a train/validation risk report for the incumbent. None skips the split.

Type:

float or None

class ws4.opt.engine.Optimizer(dataset_dir: Path, cfg: OptimizeConfig)[source]

A simulated-annealing optimizer over a compiled dataset.

The optimizer owns the search stack for one compiled dataset: the simulator and its caches, the candidate chains per block, the operator registry, and the optional route, edge-contrast, and patch models. It is constructed once per configuration and reused across evaluations.

Parameters:
  • dataset_dir (Path) – The compiled dataset directory.

  • cfg (OptimizeConfig) – The run configuration.

classmethod from_dataset(dataset_dir: Path, cfg: OptimizeConfig) → Optimizer[source]

Build an optimizer that reads the given compiled dataset.

Parameters:
  • dataset_dir (Path) – The compiled dataset directory.

  • cfg (OptimizeConfig) – The run configuration.

Returns:

Optimizer – The optimizer for that dataset and configuration.

route() → tuple[RouteModel | None, tuple[RouteAccount, ...], tuple[DuplicateAccount, ...]][source]

Return the route model, route accounts, and duplicate accounts, loaded once.

Returns:

tuple – (model, route_accounts, duplicate_accounts). The model is None when no route configuration is set.

maintenance() → MaintenanceCharge[source]

Return how the configured run charges a used road’s maintenance.

Returns:

MaintenanceCharge – The reading named under the configuration’s divergences, or the reference’s own when it names none.

candidates() → dict[int, list[tuple[tuple[str, int], ...]]][source]

Return the possible treatment chains for each block.

A block may be treated more than once. A chain is built by walking the track transitions: a treatment applies over an age window, so its schedule years are the years the block reaches that window; after a treatment the block moves to the successor track at the treatment’s reset age, and the next rotation is read from there. The window start, midpoint, and end are taken per rotation, up to a rotation cap, and each block’s chain list is capped.

Returns:

dict of int to list of Chain – The candidate treatment chains per block (single rotations first, earliest first, then multi-rotation chains).

simulator() → Simulator[source]

Return a reusable simulator, built once and reset before each use.

Returns:

Simulator – The simulator. Its mutable state is reset by Simulator.reset() before each evaluation, so one dataset load serves the whole search.

last_account_values() → DataFrame[source]

Return the account values of the most recent objective evaluation.

The objective computes an account-values frame for every whole-schedule evaluation, and a run records the frame it writes, so this returns what the optimizer last saw — useful for inspecting a result without rereading the run directory. A search driven by per-move deltas does not build a frame per move: after run() this holds the incumbent’s values, and mid-search a caller reads IncrementalObjective.values_frame() instead.

Returns:

pandas.DataFrame – The account values, with offset, account, and value columns, or an empty frame with those columns before any evaluation.

patch_accounts() → tuple[PatchAccount, ...][source]

Return the configured patch accounts (empty when none).

Returns:

tuple of PatchAccount – The definitions.

carbon_ledger() → CarbonLedger | None[source]

Return the block-level carbon ledger when a package is configured.

Returns:

CarbonLedger or None – The ledger, or None when the run names no carbon package.

spread_accounts() → tuple[SpreadAccount, ...][source]

Return the spread-connectivity accounts the configuration names, loaded once.

Returns:

tuple of SpreadAccount – The definitions, or an empty tuple when the configuration names none.

spread_topology() → tuple[list[tuple[int, int, float]], dict[int, tuple[float, float]]][source]

Return the spread edges with their distances and the block centroids, loaded once.

Returns:

tuple of (list of (int, int, float), dict of int to tuple of float) – The (src, dst, distance_m) edges of the configured topology, and the (x, y) centroid per block. Both are empty when the configuration names no spread accounts.

patch_model() → PatchModel | None[source]

Return the patch model when patch accounts are configured, built once.

Returns:

PatchModel or None – The model, or None when no patch accounts are configured.

flood_model() → FloodRiskModel | None[source]

Return the optional schedule flood-risk model, loaded once.

Returns:

FloodRiskModel or None – The model, or None when no flood-screen configuration is set.

active_patch_model() → PatchModel | None[source]

Return the patch model the current evaluator is maintaining.

Returns:

PatchModel or None – The live model, or None when the run has no patch accounts or no evaluator yet.

set_active_patch_model(model: PatchModel | None) → None[source]

Record the patch model the current evaluator is maintaining.

Parameters:

model (PatchModel or None) – The live model, or None.

last_risk_evaluation() → RiskEvaluation | None[source]

Return the most recent risk evaluation, or None.

Returns:

RiskEvaluation or None – The per-scenario values, aggregation, and objective from the last evaluation.

delta_evaluator(targets: Sequence[Target], extra_accounts: Sequence[str] = ()) → IncrementalObjective | None[source]

Return a move-based objective evaluator when the configuration supports one.

The evaluator tracks only the accounts the targets read (plus any extra_accounts), so it is used when the run has no route accounts, duplicate accounts, or edge contrast (each rewrites or extends the account values). When it returns None the caller falls back to whole-schedule evaluation.

Parameters:
  • targets (sequence of Target) – The goals.

  • extra_accounts (sequence of str, optional) – Further accounts to track for display; they do not affect the objective.

Returns:

IncrementalObjective or None – The evaluator, or None when the configuration needs whole-schedule values.

edge_elements() → tuple[EdgeElement, ...][source]

Return the edge contrast elements, loading them once.

Returns:

tuple of EdgeElement – The edge elements, or an empty tuple when none are configured.

greedy_schedule(targets: Sequence[Target] | None = None, seed_account: str | None = None, workers: int | None = None) → dict[int, tuple[tuple[str, int], ...]][source]

Return a schedule built by construction against the run’s targets, or an empty one.

A starting point for the search rather than a result: candidate chains are ranked by the penalty they remove from the declared floors per unit of the declared ceilings, and taken in that order while no ceiling is breached. When seed_account names a target with a maximum, that target is reduced to its maximum and the other maximum targets are its cost ceilings. See ws4.opt.seeding.greedy_schedule().

Parameters:
  • targets (sequence of Target or None, optional) – The targets to build against, or None to load the run’s own.

  • seed_account (str or None, optional) – The reduction goal account, or None to use the configuration’s seed_account.

  • workers (int or None, optional) – Forked processes for candidate scoring, or None to use the configuration’s workers. Both seed modes support the fork path.

Returns:

Schedule – The block-to-chain mapping, empty when the run declares no floor or has no evaluator.

search(out_dir: Path | None = None, initial: dict[int, tuple[tuple[str, int], ...]] | None = None) → tuple[dict[int, tuple[tuple[str, int], ...]], float, list[Target]][source]

Run the search and return the incumbent.

When islands is set (and there is more than one), the islands run in parallel for episodes rounds, and the global best schedule is migrated into every island as the next round’s starting point. Otherwise the starts run independently (serially or across a process pool). A process-pool worker writes its own telemetry under out_dir, so a fast search does not funnel every island through one writer.

Parameters:
  • out_dir (Path or None, optional) – The run directory; workers write telemetry-<island>.jsonl beside the summary.

  • initial (Schedule or None, optional) – A starting schedule shared by every start or island.

Returns:

tuple of (Schedule, float, list of Target) – The best schedule, its objective, and the targets.

run(out_dir: Path) → dict[str, Any][source]

Run the search and write the incumbent schedule and a summary.

Parameters:

out_dir (Path) – Directory to write the run outputs into.

Returns:

dict of str to Any – The run summary.

class ws4.opt.cooling.AdaptiveCooling(initial_acceptance: float = 0.9, delta: float = 0.1)[source]

The Aarts and Van Laarhoven (1985) polynomial-time cooling rule.

Parameters:
  • initial_acceptance (float, optional) – The acceptance ratio the initial temperature targets, in (0, 1). Defaults to 0.9.

  • delta (float, optional) – The distance from stationarity the decrement allows; it must be positive. Defaults to 0.1.

initial_temperature(increases: Sequence[float]) → float[source]

Return the initial temperature for a sample of uphill move costs.

c_0 = mean(positive dE) / ln(1 / chi_0), so a move that raises the objective by the observed average is accepted with probability chi_0 at c_0.

Parameters:

increases (sequence of float) – The objective changes of the sampled moves. Only positive changes are used.

Returns:

float – The initial temperature, or 0.0 when no sampled move was uphill.

cool(temperature: float, spread: float) → float[source]

Return the next temperature from the current one and its objective spread.

c_{k+1} = c_k / (1 + c_k ln(1 + delta) / (3 sigma_k)). A non-positive spread leaves the temperature unchanged, because the rule is undefined there.

Parameters:
  • temperature (float) – The current temperature.

  • spread (float) – The population standard deviation of the objectives at the current temperature.

Returns:

float – The next temperature.

class ws4.opt.cooling.TemperatureSchedule(initial: float, cooling: float, adaptive: bool, window: int, rule: AdaptiveCooling = <factory>)[source]

Advance the temperature: geometric, or the adaptive Aarts–Van Laarhoven rule.

The schedule owns the temperature the solver reads each iteration. In adaptive mode the first window iterations form a random walk that estimates the initial temperature, and each following group of window iterations recomputes it from the spread of the objectives seen. In geometric mode the temperature is multiplied by cooling.

Parameters:
  • initial (float) – The starting temperature, used as-is in geometric mode.

  • cooling (float) – The geometric factor, used only in geometric mode.

  • adaptive (bool) – Whether to use the adaptive rule.

  • window (int) – The number of iterations per temperature in adaptive mode.

  • rule (AdaptiveCooling) – The adaptive rule’s parameters.

temperature

The temperature the next iteration should read.

Type:

float

observe(increase: float, objective: float) → None[source]

Record one iteration, then advance the temperature.

Parameters:
  • increase (float) – The objective change the move proposed (positive for a worse objective).

  • objective (float) – The objective of the current configuration after the move.

static effective_window(iterations: int, window: int) → int[source]

Return the adaptive window for an iteration budget.

The warm-up and at least one cooling step both need a window of iterations, so the window is capped at half the budget.

Parameters:
  • iterations (int) – The iteration budget.

  • window (int) – The requested window.

Returns:

int – The window to use, at least one.

class ws4.opt.core.Problem(evaluate: Callable[[dict[int, tuple[tuple[str, int], ...]]], float], candidates: dict[int, list[tuple[tuple[str, int], ...]]], registry: OperatorRegistry[dict[int, tuple[tuple[str, int], ...]], dict[int, list[tuple[tuple[str, int], ...]]]], snapshot: Callable[[dict[int, tuple[tuple[str, int], ...]]], Mapping[Any, float]] | None = None)[source]

The WS4 problem a solver searches.

Parameters:
  • evaluate (callable) – The exact objective evaluator (lower is better).

  • candidates (Candidates) – The candidate chains per block.

  • registry (OperatorRegistry) – The neighbourhood operators.

  • snapshot (callable or None, optional) – Return the realized account cells for a schedule, for a live map and target view. When omitted, a solver that would otherwise emit a snapshot sends an empty mapping.

ws4.opt.objective.load_targets(path: Path) → list[Target][source]

Load targets from a YAML file.

The file is a mapping with a targets list. Each entry names one accounting period with period (period 1 is the first accounting period and period 0 the initial snapshot) and any of minimum, maximum, min_weight, max_weight, period_width (years per period), shape (linear or non_linear), the flow keys flow (even or ndy), flow_start_period and flow_end_period (inclusive period window), flow_reference_period, and active.

year and the year-based flow keys are still accepted for older files; a period key takes precedence when both are present. normalization is none or auto; priority is a positive integer tier. aggregation selects the scenario risk statistic (default single), with risk_alpha, risk_minimum, and risk_maximum as its parameters.

Parameters:

path (Path) – The targets file.

Returns:

list of Target – The parsed targets.

class ws4.opt.objective.Target(account: str, year: int = 0, minimum: float | None = None, maximum: float | None = None, min_weight: float = 1.0, max_weight: float = 1.0, period_width: int = 1, shape: str = 'linear', flow: str = '', flow_start: int = 0, flow_end: int | None = None, flow_reference: int | None = None, period: int | None = None, flow_start_period: int | None = None, flow_end_period: int | None = None, flow_reference_period: int | None = None, active: bool = True, normalization: str = 'none', priority: int = 1, aggregation: str = 'single', risk_alpha: float = 0.9, risk_minimum: float | None = None, risk_maximum: float | None = None)[source]

One goal-programming target.

A target is periodic: it applies to one accounting period of period_width years. Period 1 is the first accounting period (years 1 to period_width), period 2 the next, and period 0 is the initial snapshot at year 0. Treatments are still scheduled by year; only the accounting is aggregated.

account

The account label the target applies to.

Type:

str

year

The end year of the period, derived from period and period_width. Kept because account values are stored by year; prefer period in the target file.

Type:

int

period

The period index. Period 0 is the initial snapshot; periods 1 to N are the accounting periods. When given, year is derived as period * period_width.

Type:

int or None

minimum

The lower bound; a value below it is penalized.

Type:

float or None

maximum

The upper bound; a value above it is penalized.

Type:

float or None

min_weight

The weight on the shortfall below the minimum.

Type:

float

max_weight

The weight on the excess above the maximum.

Type:

float

period_width

The account time step, in whole years: the number of years the account is summed over for this target. One year is the simulation step; five or ten are the planning convention.

Type:

int

shape

The penalty shape: "linear" adds the weighted deviation, "non_linear" adds the weighted squared deviation (the weight is applied after squaring, matching the default non-premultiplied scaling).

Type:

str

flow

A flow term: "" for an ordinary level target, "even" for even flow, or "ndy" for non-declining yield. A flow target’s value is an aggregate over the periods of its window, not a period’s account value, and it is normally targeted at 0 with a weight.

Type:

str

flow_start

The first year of a flow term’s window.

Type:

int

flow_end

The year the flow window ends (exclusive), or None for the end of the horizon.

Type:

int or None

flow_reference

The first year of the flow term’s reference period, or None for the final period of the window. Every other period is measured as a percent difference from it.

Type:

int or None

flow_start_period

The first period of a flow term’s window, inclusive. When given, flow_start is derived.

Type:

int or None

flow_end_period

The last period of a flow term’s window, inclusive. When given, flow_end is derived.

Type:

int or None

flow_reference_period

The reference period for an even-flow comparison. When given, flow_reference is derived.

Type:

int or None

active

Whether the search prices this target. An inactive target stays in the file and is reported, but its penalty is not part of the objective.

Type:

bool

normalization

"none" (the default) or "auto". Auto divides the weighted penalty by the larger absolute minimum/maximum, floored at one, so targets with different units are comparable.

Type:

str

priority

The priority tier, at least one. Targets at the same tier add; lower-priority tiers are multiplied by PRIORITY_SCALE per step so higher priorities dominate the scalar search. Default one leaves the objective unchanged.

Type:

int

aggregation

The scenario aggregation: single (default, no scenario dimension), mean, min, max, cvar (lower-tail), cvar_lower, cvar_upper, quantile, probability, or regret.

Type:

str

risk_alpha

The tail or quantile level for cvar and quantile, in (0, 1). Default 0.9.

Type:

float

risk_minimum

An optional bound for the aggregated statistic, overriding the target’s minimum.

Type:

float or None

risk_maximum

An optional bound for the aggregated statistic, overriding the target’s maximum.

Type:

float or None

cell_offsets() → tuple[int, ...][source]

Return the simulation offsets of the target’s period.

Period 0 is the snapshot at offset -1. Period p >= 1 covers offsets (p - 1) * width through p * width - 1. year remains a display label only: the 1-based year the period ends on.

Returns:

tuple of int – The offsets of the target’s period.

end_offset() → int[source]

Return the offset the period is read at for a level account.

Returns:

int – The last offset of the period, or -1 for the snapshot.

ws4.opt.objective.objective(values: DataFrame, targets: Sequence[Target]) → float[source]

Return the total weighted penalty over a set of targets.

Parameters:
  • values (pandas.DataFrame) – Account values, with year, account, and value columns.

  • targets (sequence of Target) – The targets.

Returns:

float – The total penalty.

ws4.opt.objective.penalty(value: float, target: Target) → float[source]

Return the weighted, optionally normalized, penalty for one target.

Parameters:
  • value (float) – The account value.

  • target (Target) – The target.

Returns:

float – raw_penalty divided by normalization_scale().

ws4.opt.objective.raw_penalty(value: float, target: Target) → float[source]

Return the weighted shortfall and excess before normalization.

Parameters:
  • value (float) – The account value.

  • target (Target) – The target.

Returns:

float – The weighted shortfall plus the weighted excess (zero when in range).

ws4.opt.objective.normalization_scale(target: Target) → float[source]

Return the divisor for a target’s weighted penalty.

Parameters:

target (Target) – The target.

Returns:

float – The larger absolute bound when normalization is auto, floored at one so a near-zero bound does not amplify the deviation. Otherwise one.

ws4.opt.objective.priority_total(targets: Sequence[Target], penalties: Sequence[float]) → float[source]

Return the scalar objective for per-target penalties under priority tiers.

Targets with the same priority contribute additively. When more than one tier is present, a tier’s contribution is multiplied by PRIORITY_SCALE for every tier above it. This makes higher-priority tiers dominate the scalar search; it is a priority-weighted objective, not a certified lexicographic solve.

Parameters:
  • targets (sequence of Target) – The targets, in the same order as penalties.

  • penalties (sequence of float) – One penalty per target.

Returns:

float – The weighted total. With every target at the default priority 1, this is the sum.

Raises:

ValueError – When the two sequences differ in length.

ws4.opt.objective.flow_values(index: Mapping[tuple[int, str], float], target: Target, years: int, pending: Mapping[tuple[int, str], float] | None = None) → list[float][source]

Return a flow target’s percent value for each period it compares.

A flow target constrains the shape of the account’s profile over the periods, not its level; the level comes from a separate target on the same account, and the flow target itself is normally a narrow band around zero. The two kinds differ in what they compare, and both give one value per period, so the target’s minimum, maximum, weights and shape apply period by period:

  • even is the percent difference of each period from a reference period: 100 * (x_p - x_ref) / x_ref. The reference is the final period of the window by default, or flow_reference (the first year of the period to use), and it contributes no value of its own.

  • ndy (non-declining yield) is the percent change between consecutive periods: 100 * (x_p - x_{p-1}) / x_{p-1}. Every period in the window is compared, the first of them with the period immediately before the window when one exists.

Both divide by a balance that can be zero, in which case every period that depends on it is infinite. A run primes that balance first, for example with a linear volume target above the sustainable level so that every period has wood, and only then switches the flow account on. This is the definitional behaviour, not a defect.

Parameters:
  • index (mapping of (int, str) to float) – The account values by (year, account).

  • target (Target) – A target whose flow is "even" or "ndy".

  • years (int) – The horizon, in years; the window’s end when flow_end is not set.

  • pending (mapping of (int, str) to float, optional) – A move’s change per cell, added to index without copying it.

Returns:

list of float – One percent value per compared period; empty when the window holds fewer than two periods.

ws4.opt.objective.flow_penalty(index: Mapping[tuple[int, str], float], target: Target, years: int, pending: Mapping[tuple[int, str], float] | None = None) → float[source]

Return a flow target’s penalty: each period’s percent value, priced by the target.

The target’s minimum, maximum, weights and shape are applied per period, so a band of minimum: -1 and maximum: 1 is a one-percent-either-way safe range: around the reference period for even, and around the previous period for ndy, where a minimum of -1 tolerates a one-percent decline and a maximum of 1 tolerates a one-percent rise. Either side may be left out; with only a minimum, growth is free.

Parameters:
  • index (mapping of (int, str) to float) – The account values by (year, account).

  • target (Target) – A target whose flow is "even" or "ndy".

  • years (int) – The horizon, in years; the window’s end when flow_end is not set.

  • pending (mapping of (int, str) to float, optional) – A move’s change per cell, added to index without copying it.

Returns:

float – The summed per-period penalty.

ws4.opt.objective.objective_terms(values: DataFrame, targets: Sequence[Target], point_in_time: Callable[[str], bool] | None = None) → list[float][source]

Return the penalty of each target, in order.

Parameters:
  • values (pandas.DataFrame) – Account values, with year, account, and value columns.

  • targets (sequence of Target) – The targets.

  • point_in_time (callable or None, optional) – Returns True for an account that is a snapshot rather than an additive quantity (a patch account); such a target is read at its period’s end year. Defaults to None, which applies accumulates(): a product. account sums its period, everything else is a level.

Returns:

list of float – One penalty per target.

ws4.opt.objective.balance_targets(targets: Sequence[Target], peaks: Sequence[float]) → list[Target][source]

Rescale the targets so no single penalty term dominates the objective.

peaks[i] is the largest penalty target i reached in a pilot run. Every target that fired is rescaled so its peak matches the mean peak of the firing targets; a target that never fired keeps its own weights. This automates the first pass of the manual rescaling Lockwood and Moore (1993) used to make the terms decrease at similar rates.

Parameters:
  • targets (sequence of Target) – The targets.

  • peaks (sequence of float) – The peak penalty per target, in the same order.

Returns:

list of Target – The rescaled targets.

Raises:

ValueError – If peaks and targets differ in length.

class ws4.opt.incremental.IncrementalObjective(optimizer: Optimizer, targets: Sequence[Target], extra_accounts: Sequence[str] = (), patch_accounts: Sequence[PatchAccount] = ())[source]

Exact objective deltas for single-block moves over raw account targets.

The evaluator holds the running account totals, so a move is priced by its exact delta rather than by recomputing the whole schedule. Patch accounts are not additive, so they are priced separately through a PatchModel; the spatial rules are priced through a SpatialPenaltyModel.

Parameters:
  • optimizer (Optimizer) – The optimizer that owns the caches this evaluator reuses.

  • targets (sequence of Target) – The goals.

  • extra_accounts (sequence of str, optional) – Further accounts to track (for example, accounts a viewer displays); they do not affect the objective.

  • patch_accounts (sequence of PatchAccount, optional) – Patch size-distribution accounts, priced by a patch model.

optimizer

The optimizer that owns the caches this evaluator reuses.

Type:

Optimizer

targets

The goals.

Type:

list of Target

accounts

The account labels the targets read.

Type:

set of str

totals

The realized total per (year, account) cell.

Type:

dict of (int, str) to float

assignments

The current schedule.

Type:

dict of int to tuple of (str, int)

reset(schedule: dict[int, tuple[tuple[str, int], ...]]) → None[source]

Set the state to the empty-schedule base plus the schedule’s contributions.

Parameters:

schedule (dict of int to tuple of (str, int)) – The schedule to evaluate.

contribution(block: int, chain: tuple[tuple[str, int], ...]) → dict[tuple[int, str], float][source]

Return (and cache) a chain’s tracked-cell contribution (feature, product, route).

Parameters:
  • block (int) – The block.

  • chain (tuple of (str, int)) – The treatment chain.

Returns:

dict of (int, str) to float – The value this chain would add to each tracked cell, relative to leaving the block untreated. Cached, so a caller may ask repeatedly, which is what a schedule built by construction needs.

warm(candidates: dict[int, list[tuple[tuple[str, int], ...]]]) → None[source]

Precompute every candidate chain’s contribution.

The search then has no contribution misses, which suits long runs (the one-off cost is paid once instead of as misses scattered through the search).

Parameters:

candidates (dict of int to list of Chain) – The candidate chains per block.

revert() → None[source]

Undo a move’s patch and spatial changes that were not committed.

prefetch(changed: Sequence[int], schedule: dict[int, tuple[tuple[str, int], ...]]) → None[source]

Fill the contribution cache for a move’s blocks before pricing it.

A one-block move has one contribution to price, so the lazy cache is already the right path. A large-neighbourhood move re-assigns tens of blocks at once, and each new chain would otherwise miss the cache one at a time. This collects the missing (block, chain) pairs into one Optimizer._block_deltas() call (which shares the chain-independent empty-chain work), then stores the filtered contributions the pending sum reads. One-block moves never call it.

Parameters:
  • changed (sequence of int) – The blocks the move changes.

  • schedule (dict of int to tuple of (str, int)) – The schedule after the move.

property objective: float

Return the objective for the current state (periods summed).

Returns:

float – The total weighted penalty.

delta(changed: Sequence[int], schedule: dict[int, tuple[tuple[str, int], ...]]) → float[source]

Return the exact objective change a move would make, without applying it.

Parameters:
  • changed (sequence of int) – The blocks the move changes.

  • schedule (dict of int to tuple of (str, int)) – The schedule after the move.

Returns:

float – The objective after minus the objective before.

apply(changed: Sequence[int], schedule: dict[int, tuple[tuple[str, int], ...]]) → None[source]

Apply a move to the state.

Parameters:
  • changed (sequence of int) – The blocks the move changes.

  • schedule (dict of int to tuple of (str, int)) – The schedule after the move.

values_frame() → DataFrame[source]

Return the tracked account values as a frame (offset, account, value).

Returns:

pandas.DataFrame – One row per tracked (offset, account) cell.

class ws4.opt.patch.PatchModel(optimizer: Optimizer, accounts: Sequence[PatchAccount])[source]

The patch size-distribution accounts of an optimizer.

optimizer

The optimizer (its topology and simulator are reused).

Type:

Optimizer

accounts

The definitions.

Type:

tuple of PatchAccount

series(block: int, chain: tuple[tuple[str, int], ...] | None) → dict[str, dict[int, float]][source]

Return (and cache) a block chain’s criterion series per label.

An untreated block (chain is None) keeps its inventory series, so the empty chain is a real, cacheable state rather than a zero.

Parameters:
  • block (int) – The block.

  • chain (tuple or None) – The treatment chain, or None for an untreated block.

Returns:

dict of str to dict of int to float – The criterion value per label and year.

adjacency(search_distance: float | None) → dict[int, tuple[tuple[int, float], ...]][source]

Return (and cache) the block adjacency within a topology search distance.

Only edges no longer than search_distance metres join blocks, so a patch stays within the neighbourhood the account defines.

Parameters:

search_distance (float or None) – The search distance, in metres; None keeps every edge.

Returns:

dict of int to tuple of (int, float) – The (neighbour, shared_length) pairs per block.

reset(schedule: dict[int, tuple[tuple[str, int], ...]]) → None[source]

Set the state to the schedule’s patch accounts.

Parameters:

schedule (dict of int to Chain) – The schedule.

set_focus_years(years: Sequence[int]) → None[source]

Record the years the objective reads, and maintain the states only for those.

The simulation runs one year at a time but the accounting is periodic, so patch statistics are only needed where a patch target reads them. Restricting the maintained years is the difference between 200 year-states and one per accounting period.

Parameters:

years (sequence of int) – The years the patch targets are accounted in.

value(block: int, chain: tuple[tuple[str, int], ...] | None, label: str, year: int) → float[source]

Return a block’s criterion value in a year under a chain (None is untreated).

Parameters:
  • block (int) – The block.

  • chain (tuple or None) – The treatment chain, or None for an untreated block.

  • label (str) – The criterion feature label.

  • year (int) – The year.

Returns:

float – The criterion value.

find_gap(year: int, rng: Random, *, samples: int = 8) → tuple[int, str, float] | None[source]

Return (block, label, threshold) for a gap in year, or None.

A gap is a non-member block whose member-neighbours span two or more components, so treating it would join those patches. Sampling a few blocks keeps a proposal O(1) rather than a scan of the whole forest.

Parameters:
  • year (int) – The year to look in.

  • rng (random.Random) – The random source.

  • samples (int, optional) – The number of blocks to test. Defaults to 8.

Returns:

tuple of (int, str, float) or None – The gap block, the criterion label, and the threshold, or None if none was found.

pending(changed: Sequence[int], schedule: dict[int, tuple[tuple[str, int], ...]]) → dict[tuple[int, str], float][source]

Apply a move to the states and return the patch-cell change.

The change can be undone with revert() (until commit()). A small move updates each changed block’s value in place; a large one (an LNS move) rebuilds the affected years, which is cheaper than hundreds of local updates.

Parameters:
  • changed (sequence of int) – The blocks the move changes.

  • schedule (dict of int to Chain) – The schedule after the move.

Returns:

dict of (int, str) to float – The change per (year, account) cell.

revert() → None[source]

Undo a pending() move that was not committed.

commit(changed: Sequence[int], schedule: dict[int, tuple[tuple[str, int], ...]]) → None[source]

Apply a move to the model.

Parameters:
  • changed (sequence of int) – The blocks the move changes.

  • schedule (dict of int to Chain) – The schedule after the move.

cell_map() → dict[tuple[int, str], float][source]

Return the current patch cells as a (year, account) -> value mapping.

Returns:

dict of (int, str) to float – The patch account value per (year, account) cell.

class ws4.opt.operators.OperatorRegistry(operators: Sequence[Operator[State, Context]] | None = None)[source]

A weighted set of operators.

Parameters:

operators (sequence of Operator, optional) – The operators to choose between. When omitted the registry is empty and pick() raises.

property operators: list[Operator[State, Context]]

Return the registered operators in selection order.

Returns:

list of Operator – A copy of the operator list.

names() → list[str][source]

Return the operator names in registration order.

Returns:

list of str – The names.

weights() → dict[str, float][source]

Return the operator weights by name.

Returns:

dict of str to float – The selection weight per operator name.

pick(rng: Random) → Operator[State, Context][source]

Return a weighted-random operator.

Parameters:

rng (random.Random) – The random source.

Returns:

Operator – The chosen operator.

Raises:

ValueError – When the registry is empty or every weight is non-positive.

ws4.opt.operators.restore(state: MutableMapping[Key, Value], undo: Mapping[Key, Value | None]) → None[source]

Undo an in-place move, restoring each touched unit’s previous value.

Parameters:
  • state (MutableMapping) – The mutated state.

  • undo (Mapping) – The previous value per touched unit. None means the unit was absent.

ws4.opt.calibrate.pilot_peaks(optimizer: Optimizer, targets: Sequence[Target], *, iterations: int, seed: int = 42, samples: int = 32, warm_start: bool = False) → list[float][source]

Run a pilot search and return the peak penalty each target reaches.

Parameters:
  • optimizer (Optimizer) – The optimizer. It supplies the candidates, the registry, and the evaluator.

  • targets (sequence of Target) – The targets to calibrate.

  • iterations (int) – The pilot budget.

  • seed (int, optional) – The pilot seed. Defaults to 42.

  • samples (int, optional) – How often the per-term penalties are sampled. Defaults to 32.

  • warm_start (bool, optional) – Start the pilot from each block’s first candidate, matching a warm-started run. Defaults to False (the empty schedule).

Returns:

list of float – The peak penalty per target, in order.

Raises:

ValueError – If the configuration cannot be priced by the move-based evaluator.

ws4.opt.calibrate.calibrate(optimizer: Optimizer, targets: Sequence[Target], *, iterations: int = 2000, seed: int = 42, samples: int = 32, warm_start: bool = False) → list[Target][source]

Return the targets with their weights balanced by a pilot search.

Parameters:
  • optimizer (Optimizer) – The optimizer.

  • targets (sequence of Target) – The targets to calibrate.

  • iterations (int, optional) – The pilot budget. Defaults to 2000.

  • seed (int, optional) – The pilot seed. Defaults to 42.

  • samples (int, optional) – How often the per-term penalties are sampled. Defaults to 32.

  • warm_start (bool, optional) – Start the pilot from each block’s first candidate. Defaults to False.

Returns:

list of Target – The rescaled targets.

ws4.opt.calibrate.write_targets(path: Path, targets: Sequence[Target]) → Path[source]

Write targets to a YAML file that ws4.opt.objective.load_targets() reads.

Parameters:
  • path (Path) – The file to write.

  • targets (sequence of Target) – The targets.

Returns:

Path – The path written.

ws4.opt.watch.run_watch(optimizer: Optimizer, targets: Sequence[Target], accounts: Sequence[str], *, period_width: int = 10, label: str | None = None, refresh: float = 2.0, plain: bool = False, console: Console | None = None, initial: dict[int, tuple[tuple[str, int], ...]] | None = None) → dict[str, Any][source]

Run the search and paint the target window until it stops improving.

Parameters:
  • optimizer (Optimizer) – The configured optimizer (its cfg carries the solver settings).

  • targets (sequence of Target) – The goals the objective uses.

  • accounts (sequence of str) – The account labels to watch; each gets its own target window.

  • period_width (int, optional) – The number of years per period.

  • label (str or None, optional) – A display label for the header; defaults to the accounts joined with +.

  • refresh (float, optional) – The heartbeat interval, in seconds, between repaints.

  • plain (bool, optional) – Print a single final frame instead of a live view.

  • console (rich.console.Console or None, optional) – The console to draw on; a new one when omitted.

  • initial (dict or None, optional) – A starting schedule; it takes precedence over warm_start. Use it to continue from an earlier run, which a flow target needs: its reference period must already carry wood.

Returns:

dict – objective, penalty (summed across the windows), evaluations, blocks, and elapsed.

class ws4.opt.watch.TargetWindow(account: str, period_width: int, realized: tuple[float, ...], minimum: tuple[float | None, ...], maximum: tuple[float | None, ...])[source]

The realized values and target window of an account over periods.

account

The display label.

Type:

str

period_width

The number of years per period.

Type:

int

realized

The realized account value per period.

Type:

tuple of float

minimum

The minimum target level per period, or None where none is set.

Type:

tuple of float or None

maximum

The maximum target level per period, or None where none is set.

Type:

tuple of float or None

property n_periods: int

Return the number of periods.

Returns:

int – The number of accounting periods in the window.

shortfalls() → tuple[float, ...][source]

Return each period’s shortfall below its minimum (zero when satisfied).

Returns:

tuple of float – The shortfall per period.

excesses() → tuple[float, ...][source]

Return each period’s excess above its maximum (zero when satisfied).

Returns:

tuple of float – The excess per period.

penalties() → tuple[float, ...][source]

Return each period’s total penalty.

Returns:

tuple of float – The shortfall plus the excess per period.

total_penalty() → float[source]

Return the summed per-period penalty.

Returns:

float – The window’s total penalty.

statuses() → tuple[str, ...][source]

Return each period’s status: ok, below, or above.

Returns:

tuple of str – The status per period.

ws4.opt.mip.bound_for(dataset_dir: Path, targets: Sequence[Target], candidates: dict[int, list[tuple[tuple[str, int], ...]]], years: int, topology_path: Path | None = None, max_opening_ha: float | None = None) → MipResult[source]

Compute a penalty lower bound for a dataset and a target set.

Parameters:
  • dataset_dir (Path) – The compiled dataset.

  • targets (sequence of Target) – The targets.

  • candidates (Candidates) – The candidate options per block.

  • years (int) – The simulation horizon.

  • topology_path (Path or None, optional) – The block topology. When given with max_opening_ha, the stand-centred opening constraints (Gunn and Richards 2005, eq. 6) tighten the bound.

  • max_opening_ha (float or None, optional) – The maximum opening (harvest block) area the stand-centred constraints enforce.

Returns:

MipResult – The bound and the chosen schedule.

class ws4.opt.constraints.ConstraintGuard(optimizer: Optimizer)[source]

Apply a hard-feasibility policy to every proposed operator move.

Parameters:

optimizer (Optimizer) – The optimizer whose configuration, topology, and block areas the guard reads.

set_schedule_check(check: Callable[[Mapping[int, Any]], bool] | None) → None[source]

Set a whole-schedule predicate, such as the SDMD AU guard.

Parameters:

check (callable or None) – A predicate over the proposed schedule. Each move calls it before the spatial rules; None disables it.

wrap(registry: OperatorRegistry[dict[int, tuple[tuple[str, int], ...]], dict[int, list[tuple[tuple[str, int], ...]]]]) → OperatorRegistry[dict[int, tuple[tuple[str, int], ...]], dict[int, list[tuple[tuple[str, int], ...]]]][source]

Return a registry whose operators obey the guard.

Parameters:

registry (OperatorRegistry) – The base registry.

Returns:

OperatorRegistry – The wrapped registry, or the original when the policy is the default.

consider(before: Mapping[int, Any], proposed: Mapping[int, Any], changed: Sequence[int]) → dict[int, tuple[tuple[str, int], ...]] | None[source]

Return the accepted schedule for a proposal, or None when it is rejected.

Parameters:
  • before (mapping of int to chain) – The feasible schedule before the move.

  • proposed (mapping of int to chain) – The schedule the operator proposed.

  • changed (sequence of int) – The blocks the operator touched.

Returns:

dict of int to chain or None – The feasible proposal or repair, or None when the move is rejected.

prepare(schedule: dict[int, tuple[tuple[str, int], ...]] | None) → dict[int, tuple[tuple[str, int], ...]][source]

Return a feasible starting schedule.

An infeasible seed is repaired by removing every block in a violating patch or green-up pair, repeating until the schedule is feasible. The empty schedule is feasible, so this terminates.

Parameters:

schedule (dict of int to chain or None) – The proposed starting schedule.

Returns:

dict of int to chain – A feasible schedule.

feasible(schedule: Mapping[int, Any]) → bool[source]

Return whether a schedule satisfies every active spatial rule.

Parameters:

schedule (mapping of int to chain) – The schedule to check.

Returns:

bool – True when the spatial penalty is zero within tolerance.

penalty(schedule: Mapping[int, Any]) → float[source]

Return the spatial penalty for a schedule.

Parameters:

schedule (mapping of int to chain) – The schedule to check.

Returns:

float – The opening, green-up, and core-area penalty.

violations(schedule: Mapping[int, Any]) → list[dict[str, object]][source]

Return the final spatial violation records.

Parameters:

schedule (mapping of int to chain) – The schedule to inspect.

Returns:

list of dict – Opening, green-up, and core-area records.

violating_blocks(schedule: Mapping[int, Any]) → set[int][source]

Return the blocks involved in any spatial violation.

Parameters:

schedule (mapping of int to chain) – The schedule to inspect.

Returns:

set of int – The block identifiers to remove for a feasible seed.

summary() → dict[str, object][source]

Return the strategy and counts for the run summary.

Returns:

dict of str to object – The strategy, enabled flag, move counts, and initial repairs.

ws4.opt.max_flow.run_max_flow(*, dataset: Path, targets: Path, account: str, out_dir: Path, years: int = 100, period_width: int = 10, iterations: int = 100, seed: int = 1, metaheuristic: str = 'sa', threads: int = 1, probes: int = 8, tolerance: float = 0.01, high: float | None = None, topology: Path | None = None, max_opening_ha: float | None = None, min_green_up_years: int | None = None, core_buffer_m: float | None = None, min_core_area_ha: float | None = None, constraint_strategy: str = 'reject', flow: str = '', flow_tolerance: float = 0.0, flow_reference_period: int | None = None, initial_schedule: Path | None = None) → dict[str, Any][source]

Binary-search the highest feasible constant flow floor.

Parameters:
  • dataset (Path) – The compiled dataset.

  • targets (Path) – The base targets. Targets on account are replaced by the probe floors; all other targets are preserved.

  • account (str) – The volume account.

  • out_dir (Path) – The output directory.

  • years (int, optional) – The horizon. Defaults to 100.

  • period_width (int, optional) – The accounting period width. Defaults to 10.

  • iterations (int, optional) – The iteration budget per probe. Defaults to 100.

  • seed (int, optional) – The probe seed. Defaults to 1.

  • metaheuristic (str, optional) – The optimizer engine. Defaults to "sa".

  • threads (int, optional) – BLAS threads. Defaults to 1.

  • probes (int, optional) – The binary-search probes. Defaults to 8.

  • tolerance (float, optional) – The relative shortfall allowed per period. Defaults to 0.01.

  • high (float or None, optional) – A known upper bound. None computes the additive envelope.

  • topology (Path or None, optional) – The spatial topology.

  • max_opening_ha (float or None, optional) – The maximum opening area.

  • min_green_up_years (int or None, optional) – The green-up interval.

  • core_buffer_m (float or None, optional) – The core-area buffer.

  • min_core_area_ha (float or None, optional) – The minimum core area.

  • constraint_strategy (str, optional) – The spatial policy for the probes. Defaults to "reject".

  • flow (str, optional) – "ndy" or "even" to require a flow shape in every probe. Empty disables it.

  • flow_tolerance (float, optional) – The allowed percent change for the flow condition. Defaults to zero.

  • flow_reference_period (int or None, optional) – The reference period for an even-flow target. One makes the first period the reference; None keeps the optimizer default.

  • initial_schedule (Path or None, optional) – A primed schedule passed to every probe.

Returns:

dict of str to Any – The ceiling, probes, high bound, and a Markdown report.

Raises:

ValueError – When the horizon, period width, probe count, or tolerance is invalid.

ws4.opt.repro.write_reproducibility(out_dir: Path, dataset_dir: Path, cfg: OptimizeConfig) → dict[str, Any][source]

Write the run manifest and data-quality report.

Parameters:
  • out_dir (Path) – The run directory.

  • dataset_dir (Path) – The compiled dataset.

  • cfg (OptimizeConfig) – The run configuration.

Returns:

dict of str to Any – The manifest and quality report, with their file paths.

ws4.opt.repro.dataset_quality(dataset_dir: Path, targets_path: Path | None = None) → dict[str, Any][source]

Summarize the dataset’s metadata, table counts, and target coverage.

Parameters:
  • dataset_dir (Path) – The compiled dataset directory.

  • targets_path (Path or None, optional) – The targets file, used to check whether target accounts are in the matrix.

Returns:

dict of str to Any – The full quality report, including checks, table counts, and a compact summary.

ws4.opt.scenarios.compare_scenarios(runs: Sequence[tuple[str, Path]], out_dir: Path, *, metrics: Mapping[str, Literal['min', 'max']] | None = None) → dict[str, Any][source]

Compare labelled runs and write the reports.

Parameters:
  • runs (sequence of (str, Path)) – The label and run directory pairs.

  • out_dir (Path) – The comparison directory.

  • metrics (mapping of str to str or None, optional) – Named account metrics and their min/max directions for the front. No metrics means no front.

Returns:

dict of str to Any – The records, front, directions, and Markdown report.

Raises:

ValueError – When no runs or a duplicate label is supplied.

ws4.opt.max_flow.high_bound(optimizer: Optimizer, account: str, years: int, period_width: int) → float[source]

Return an additive upper envelope for the account’s period values.

Parameters:
  • optimizer (Optimizer) – The optimizer whose block deltas are read.

  • account (str) – The account name.

  • years (int) – The simulation horizon.

  • period_width (int) – The years per accounting period.

Returns:

float – The minimum over periods of the empty-schedule base plus each block’s best option contribution. It is an upper bound, not a schedule.

ws4.opt.max_flow.flow_feasibility(values: Mapping[int, float], flow: str, tolerance: float, reference_period: int | None = None) → tuple[bool, float | None][source]

Return whether a period profile satisfies an NDY or even-flow condition.

Parameters:
  • values (mapping of int to float) – The account value per 1-based period.

  • flow (str) – "ndy" or "even".

  • tolerance (float) – The allowed percent change, as a percentage.

  • reference_period (int or None, optional) – The 1-based period even flow is compared against. None uses the final period.

Returns:

tuple of (bool, float or None) – Whether the condition holds and the worst signed percent change. A non-positive balance makes the condition false.

Raises:

ValueError – When the flow is not ndy or even.

ws4.report.ending_inventory(values: DataFrame) → DataFrame[source]

Return the final feature-inventory values.

The ending inventory is the state at the last offset for accounts whose name starts with feature.. A product. account is harvested output, not closing inventory.

Parameters:

values (pandas.DataFrame) – Account values with offset, account, and value.

Returns:

pandas.DataFrame – offset, account, and value at the final offset. Empty with those columns when there are no feature accounts.

ws4.opt.mip.relaxation_for(dataset_dir: Path, targets: Sequence[Target], candidates: dict[int, list[tuple[tuple[str, int], ...]]], years: int, topology_path: Path | None = None, max_opening_ha: float | None = None) → LpResult[source]

Compute the LP relaxation and its target duals for a dataset and target set.

Parameters:
  • dataset_dir (Path) – The compiled dataset.

  • targets (sequence of Target) – The targets.

  • candidates (Candidates) – The candidate options per block.

  • years (int) – The simulation horizon.

  • topology_path (Path or None, optional) – The block topology, used with max_opening_ha for the opening constraints.

  • max_opening_ha (float or None, optional) – The maximum opening area.

Returns:

LpResult – The LP bound, duals, and reduced costs.

ws4.opt.exact.solve_option_model(dataset: Path, targets: list[Target], years: int, *, topology_path: Path | None = None, max_opening_ha: float | None = None, limit_blocks: int | None = None) → MipResult[source]

Solve the option-selection model, optionally over the first N blocks.

Parameters:
  • dataset (Path) – The compiled dataset.

  • targets (list of Target) – The targets priced by the model.

  • years (int) – The simulation horizon.

  • topology_path (Path or None, optional) – The topology for the stand-centred opening rows.

  • max_opening_ha (float or None, optional) – The maximum opening area.

  • limit_blocks (int or None, optional) – Keep only the first N blocks by identifier. This is a diagnostic subproblem.

Returns:

MipResult – The option model’s bound, schedule, status, and variable count.

Raises:

ValueError – When limit_blocks is not positive.

ws4.opt.exact.write_exact_result(out_dir: Path, dataset: Path, targets: list[Target], years: int, result: MipResult, *, topology_path: Path | None = None, max_opening_ha: float | None = None, limit_blocks: int | None = None) → dict[str, Any][source]

Write the exact schedule, replay it, and return the artefact report.

Parameters:
  • out_dir (Path) – The output directory.

  • dataset (Path) – The compiled dataset.

  • targets (list of Target) – The targets.

  • years (int) – The simulation horizon.

  • result (MipResult) – The option model result.

  • topology_path (Path or None, optional) – The topology used for the opening rows and replay.

  • max_opening_ha (float or None, optional) – The maximum opening area.

  • limit_blocks (int or None, optional) – The diagnostic block subset, recorded in the report.

Returns:

dict of str to Any – The model status, option objective, replayed target penalty, and paths.

class ws4.opt.mip.LpResult(objective: float, status: str, variables: int, duals: tuple[TargetDual, ...], reduced_costs: tuple[OptionReducedCost, ...], message: str = '')[source]

The LP relaxation’s bound, target duals, and option reduced costs.

objective

The LP relaxation objective: a lower bound on the mixed-integer penalty.

Type:

float

status

The solver status.

Type:

str

variables

The number of option variables.

Type:

int

duals

One record per target bound.

Type:

tuple of TargetDual

reduced_costs

One record per option variable.

Type:

tuple of OptionReducedCost

message

The solver message.

Type:

str

as_dict() → dict[str, object][source]

Return a JSON-ready record.

Returns:

dict of str to object – The objective, status, variables, duals, reduced costs, and message.

class ws4.opt.archive.Elite(objective: float, metrics: Mapping[str, float], schedule: dict[int, tuple[tuple[str, int], ...]], source: str = '', seed: int | None = None, iteration: int | None = None)[source]

One archived schedule and its outcomes.

objective

The scalar weighted-goal penalty the search minimized.

Type:

float

metrics

The named outcomes the Pareto filter compares.

Type:

mapping of str to float

schedule

The schedule’s treatment chains per block.

Type:

Schedule

source

A label for where the candidate came from, such as a portfolio member.

Type:

str, optional

seed

The search seed, when known.

Type:

int or None, optional

iteration

The iteration that produced the candidate, when known.

Type:

int or None, optional

as_dict() → dict[str, Any][source]

Return a JSON-ready record without the schedule.

Returns:

dict of str to object – The objective, metrics, source, seed, iteration, and block count.

class ws4.opt.archive.EliteArchive(capacity: int = 20, directions: Mapping[str, str]=<factory>)[source]

A bounded set of elite schedules.

Parameters:
  • capacity (int, optional) – The most candidates to retain. When the archive is over capacity, the highest scalar objective is dropped first, so the cap is a practical memory bound rather than an exact Pareto guarantee.

  • directions (mapping of str to str, optional) – The direction per metric. Every added candidate must carry all of them.

property elites: list[Elite]

Return the retained candidates, lowest objective first.

Returns:

list of Elite – A copy of the retained list.

add(elite: Elite) → bool[source]

Consider one candidate for the archive.

A candidate dominated by a retained member is rejected. A candidate that dominates retained members replaces them. An exact metric tie keeps the lower objective.

Parameters:

elite (Elite) – The candidate.

Returns:

bool – True when the candidate was retained.

Raises:

ValueError – When its metrics do not match the archive directions.

front() → list[Elite][source]

Return the nondominated subset of the retained candidates.

Returns:

list of Elite – The front, ordered by scalar objective.

write(directory: Path) → dict[str, Path][source]

Write the archive manifest and one schedule CSV per retained candidate.

Parameters:

directory (Path) – Destination directory. It is created when missing.

Returns:

dict of str to Path – The manifest and the schedule files keyed by candidate index.

ws4.opt.archive.pareto_front(elites: Sequence[Elite], directions: Mapping[str, str]) → list[Elite][source]

Return the nondominated candidates, stably ordered by objective.

Parameters:
  • elites (sequence of Elite) – The candidates to filter. Exact metric ties keep the lowest scalar objective and then the first candidate in the input order.

  • directions (mapping of str to str) – The "min" or "max" direction per metric.

Returns:

list of Elite – One candidate per distinct metric vector, sorted by objective and source.

Raises:

ValueError – When a candidate has a metric without a direction.

ws4.opt.portfolio.run_portfolio(*, dataset: Path, targets: Path, out_dir: Path, vary: Mapping[str, Sequence[float]], metrics: Sequence[str], seeds: Sequence[int] = (1,), iterations: int = 200, years: int = 50, threads: int = 1, metaheuristic: str = 'sa', directions: Mapping[str, Literal['min', 'max']] | None = None, archive_size: int = 20, max_members: int = 64, weight_mode: str = 'grid', sample_seed: int = 1, workers: int = 1, initial_schedule: Path | None = None, runner_factory: Callable[[Path, OptimizeConfig], Runner] | None = None) → dict[str, Any][source]

Run the portfolio and write its members, front, and reports.

Parameters:
  • dataset (Path) – Compiled ws4 dataset.

  • targets (Path) – The base targets YAML.

  • out_dir (Path) – The portfolio directory.

  • vary (mapping of str to sequence of float) – The weight factors per account.

  • metrics (sequence of str) – The realized account metrics that define the front.

  • seeds (sequence of int, optional) – One run per seed per weight vector. Defaults to (1,).

  • iterations (int, optional) – The iteration budget per run. Defaults to 200.

  • years (int, optional) – The simulation horizon. Defaults to 50.

  • threads (int, optional) – BLAS threads per run. Defaults to 1.

  • metaheuristic (str, optional) – The engine name. Defaults to "sa".

  • directions (mapping of str to str or None, optional) – The direction per metric. Missing metrics default to max and objective is always min.

  • archive_size (int, optional) – The archive capacity. Defaults to 20.

  • max_members (int, optional) – The most weight vectors. Defaults to 64.

  • weight_mode (str, optional) – "grid" keeps the exact Cartesian product; "random" samples distinct grid positions deterministically when the product is over the cap. Defaults to "grid".

  • sample_seed (int, optional) – The deterministic sample seed for weight_mode="random". Defaults to 1.

  • workers (int, optional) – Process workers. The default of one keeps memory bounded; each worker loads its own dataset, so raise it only when the host has memory for the model.

  • initial_schedule (Path or None, optional) – A schedule used as the starting point for every member. Without it, a search from an empty schedule can fail flow targets that need a primed account.

  • runner_factory (callable or None, optional) – Builds a runner from the dataset and a configuration. Defaults to Optimizer.from_dataset(); tests substitute a fake. With more than one worker the factory must be picklable.

Returns:

dict of str to Any – The members, front labels, directions, and a Markdown report.

Raises:

ValueError – When no metrics are named, a seed list is empty, the worker count is invalid, or the weight sample is invalid.

ws4.opt.solution_space.build_solution_space(payload: Mapping[str, Any], *, near_front_epsilon: float = 0.0) → dict[str, Any][source]

Build the browser’s exact solution-space payload from a portfolio report.

Parameters:
  • payload (mapping) – A parsed portfolio.json document.

  • near_front_epsilon (float, optional) – The largest Chebyshev distance in the normalized outcome box that is still labelled near-front. 0 keeps only exact front members. The label is explicit; a near-front member is not called Pareto.

Returns:

dict – Dimensions, directions, ideal/nadir, exact front keys, points, and counts.

Raises:

ValueError – When no metrics are declared or a metric direction is unknown.

ws4.opt.default_scenario.build_default_stock90_targets(source: Path, destination: Path, *, initial_stock: float, stock_account: str, volume_multiplier: float = 2.0, stock_fraction: float = 0.9, force_volume_multiplier: bool = False) → Path[source]

Write a default target file with an even-flow structure and a 90% stock floor.

Parameters:
  • source (Path) – The instance’s base targets YAML.

  • destination (Path) – The cache path to write.

  • initial_stock (float) – Initial managed growing stock.

  • stock_account (str) – The exact growing-stock account label from the run.

  • volume_multiplier (float, optional) – Factor applied to managed harvest level targets when the base file has no final-period stock guard. Defaults to 2.

  • stock_fraction (float, optional) – Final-period stock floor as a fraction of initial stock. Defaults to 0.9.

  • force_volume_multiplier (bool, optional) – Raise volume targets even when an existing final-period stock guard is present. Defaults to False.

Returns:

Path – The generated file path.

ws4.opt.default_scenario.initial_managed_stock(run_dir: Path) → tuple[str, float] | None[source]

Return the exact account name and initial managed growing-stock value.

Parameters:

run_dir (Path) – A completed run directory containing account_values.csv.

Returns:

tuple of str and float or None – The account label and its initial value, or None when the run has no managed growing-stock total at the initial offset.

ws4.opt.tune.run_tuning(*, dataset: ~pathlib.Path, targets: ~pathlib.Path, out_dir: ~pathlib.Path, space: ~collections.abc.Mapping[str, ~collections.abc.Sequence[~typing.Any]], mode: str = 'grid', budget: int = 16, seeds: ~collections.abc.Sequence[int] = (1,), base: ~ws4.opt.engine.OptimizeConfig | None = None, iterations: int = 200, years: int = 50, threads: int = 1, random_seed: int = 42, max_candidates: int = 64, runner_factory: ~collections.abc.Callable[[~pathlib.Path, ~ws4.opt.engine.OptimizeConfig], ~fresh_solutions.kernel.runner.Runner] = <bound method Optimizer.from_dataset of <class 'ws4.opt.engine.Optimizer'>>) → dict[str, Any][source]

Run the tuner and write its candidates, ranking, and winner.

Parameters:
  • dataset (Path) – Compiled ws4 dataset.

  • targets (Path) – The targets YAML.

  • out_dir (Path) – The tuning directory.

  • space (mapping of str to sequence) – The candidate values per configuration field.

  • mode (str, optional) – "grid" or "random". Defaults to "grid".

  • budget (int, optional) – The random-mode sample size. Defaults to 16.

  • seeds (sequence of int, optional) – One run per seed per candidate. Defaults to (1,).

  • base (OptimizeConfig or None, optional) – The base configuration. Defaults to a fresh configuration with the targets, horizon, iteration budget, thread count, and seed set.

  • iterations (int, optional) – The iteration budget when base is None. Defaults to 200.

  • years (int, optional) – The horizon when base is None. Defaults to 50.

  • threads (int, optional) – BLAS threads when base is None. Defaults to 1.

  • random_seed (int, optional) – The sampler seed. Defaults to 42.

  • max_candidates (int, optional) – The grid cap. Defaults to 64.

  • runner_factory (callable, optional) – Builds a runner from the dataset and a configuration. Defaults to Optimizer.from_dataset(); tests substitute a fake.

Returns:

dict of str to Any – The candidates, winner, failures, and a Markdown report.

Raises:

ValueError – When the seeds are empty or the base configuration is incompatible with the space.

class ws4.opt.telemetry.RunLogger(path: Path, run_id: str, config: Mapping[str, Any], *, auto_flush: bool = True)[source]

Append-only JSONL telemetry for one optimization run.

The file opens with one run header, then one record per search step. A search is reproducible from the header (the seed and the configuration) and the step records.

Parameters:
  • path (Path) – The JSONL file to write.

  • run_id (str) – The run identifier.

  • config (mapping) – The run configuration to record in the header.

  • auto_flush (bool, optional) – Flush after every record, so a live reader sees each step promptly. A header-only parent log can turn it off; a worker’s own log leaves it on.

flush() → None[source]

Flush buffered records to the file for a live reader.

step(iteration: int, objective: float, island: str | None = None) → None[source]

Record one iteration’s objective.

Parameters:
  • iteration (int) – The iteration index.

  • objective (float) – The incumbent objective at that iteration.

  • island (str or None, optional) – The worker that reported it, when the search runs more than one.

trace(iteration: int, objective: float, current: float, accepted: int, island: str | None = None) → None[source]

Record one iteration’s incumbent, current objective, and accepted move count.

Parameters:
  • iteration (int) – The iteration index.

  • objective (float) – The incumbent objective at that iteration.

  • current (float) – The current solution’s objective, which moves even while the incumbent is flat.

  • accepted (int) – The number of accepted moves since the last reversion, or the run’s accepted count.

  • island (str or None, optional) – The worker that reported it, when the search runs more than one.

targets(iteration: int, values: Mapping[tuple[int, str], float], island: str | None = None) → None[source]

Record the realized value of every tracked account cell at an iteration.

Parameters:
  • iteration (int) – The iteration index.

  • values (mapping of (int, str) to float) – The realized total per (year, account) cell, as the move-based evaluator holds it.

  • island (str or None, optional) – The worker that reported it, when the search runs more than one.

schedule(iteration: int, schedule: Mapping[int, Sequence[tuple[str, int]]], island: str | None = None) → None[source]

Record the incumbent’s blocks that changed since the last snapshot.

A full schedule every snapshot would be large and mostly still; the analyst needs the movement, so only the changed blocks are written. A block removed from the schedule is sent with an empty treatment and an offset of -1. Each worker keeps its own previous schedule, so a parallel search never reports one island’s blocks as another’s removal.

Parameters:
  • iteration (int) – The iteration index.

  • schedule (mapping of int to sequence of (str, int)) – The incumbent schedule: each block’s treatment chain, as (treatment, offset) events.

  • island (str or None, optional) – The worker that reported it, when the search runs more than one.

close() → None[source]

Close the log.

ws4.opt.telemetry.read_records(path: Path) → list[dict[str, Any]][source]

Read a telemetry JSONL file.

Parameters:

path (Path) – The JSONL file.

Returns:

list of dict – The parsed records.

Cached route events and profiling

A route configuration whose network is fully open and has no delivery target uses cached per-block route events for per-segment accounts (build, maintain) and additive deltas for haul and volume. Delivery targets, initial_roads: existing, and edge contrast keep the full simulator.

Measure the cached path against the full simulation on a real schedule:

python scripts/benchmark_route_events.py \
  --dataset build/compiled \
  --targets targets.yaml \
  --route-config route.yaml \
  --schedule runtime/runs/run-1/schedule.csv \
  --years 50 --repeats 3 --out route-events.json

It reports full, cold-cache, and warm-cache times, the event count, and the largest cell difference. To profile the full path and see its hot functions:

python scripts/profile_route.py \
  --dataset build/compiled \
  --targets targets.yaml \
  --route-config route.yaml \
  --schedule runtime/runs/run-1/schedule.csv \
  --years 50 --repeats 3 --out route-profile.json

The design, fallback conditions, and parity plan are in notes/design/ws4-incremental-route.md. The P46 close-out records the c5 evidence in notes/reports/p46-closeout.md.

Risk targets

A target may carry an aggregation field (mean, min, max, cvar, cvar_upper, quantile, probability, or regret). Risk-aggregated targets need a scenario file:

ws4 optimize ... --scenario-file scenarios.yaml

The optimizer uses a fast account-overlay path: one deterministic account frame is evaluated under each scenario’s account_multipliers, then the existing risk layer aggregates the targets. The per-move delta evaluator is bypassed. This is not a process-driven stochastic simulation; see Risk-aware optimization.