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: -1lets a period come in one percent below its predecessor before anything is charged, andmaximum: 1mirrors 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.evenreads 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
GPU search
ws4 gpu-run is the checked-in path for the exact sparse GPU population search. It loads
the simulator and candidate caches from --cache-dir, loads a persisted effect table,
runs the resident session for every --seeds value, writes one schedule per seed, and
replays every result with a fresh IncrementalObjective. The effect table is
target-specific and is supplied by the caller; this command does not rebuild it.
ws4 gpu-run --dataset build/compiled --targets targets.yaml \
--seed-schedule seed.csv --table effects-lean.pt \
--cache-dir runtime/gpu-cache --out-dir runtime/gpu-run \
--seeds 7,8,9 --years 200 --generations 1000
The simulator and candidate caches are content-fingerprinted against the compiled dataset;
pass --rebuild-caches after changing it. The GPU extra is optional and must be
installed separately. Without a GPU device, use --device cpu for a small exactness run.
The GPU path keeps the prototype contract: one priority tier, no patch accounts, no route
accounts, and no spatial rules.
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 |
|---|---|
|
The incumbent schedule ( |
|
The run summary: objective, iterations, patience, reversion, seed, metaheuristic, operators, block count, status, time-limit flag, dataset reference. and the dataset manifest. |
|
The simulated account and product values for the incumbent schedule. |
|
The account summary and the per-target status, including target kind and normalized penalty. |
|
The final feature-inventory value per account at the last offset. |
|
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 fullOptimizeConfig, 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 compactdata_qualityblock 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,periodCSV 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_weightandmax_weight;ws4 calibraterescales 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_startit 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.csvandau_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
islandsor process-parallel starts are active.- Type:
int
- seed_candidates
The most candidate chains per block that
--seed-greedyscores. 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_pathfor the adjacency andblock_coordinates_pathfor the bearings.- Type:
str
- block_coordinates_path
A CSV of block centroids (a block id, an
xand ay), read for the spread accounts’ bearings.- Type:
str
- flood_screen_config_path
An optional
ws4.hydrology.flood_screen.v1configuration. When set, the optimizer evaluatesflood.*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 readsIncrementalObjective.values_frame()instead.- Returns:
pandas.DataFrame – The account values, with
offset,account, andvaluecolumns, 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_accountnames a target with a maximum, that target is reduced to its maximum and the other maximum targets are its cost ceilings. Seews4.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
islandsis set (and there is more than one), the islands run in parallel forepisodesrounds, 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 underout_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>.jsonlbeside 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.
- 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 probabilitychi_0atc_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.0when 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
windowiterations form a random walk that estimates the initial temperature, and each following group ofwindowiterations recomputes it from the spread of the objectives seen. In geometric mode the temperature is multiplied bycooling.- 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
targetslist. Each entry names one accounting period withperiod(period 1 is the first accounting period and period 0 the initial snapshot) and any ofminimum,maximum,min_weight,max_weight,period_width(years per period),shape(linearornon_linear), the flow keysflow(evenorndy),flow_start_periodandflow_end_period(inclusive period window),flow_reference_period, andactive.yearand the year-based flow keys are still accepted for older files; a period key takes precedence when both are present.normalizationisnoneorauto;priorityis a positive integer tier.aggregationselects the scenario risk statistic (defaultsingle), withrisk_alpha,risk_minimum, andrisk_maximumas 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_widthyears. Period 1 is the first accounting period (years 1 toperiod_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
periodandperiod_width. Kept because account values are stored by year; preferperiodin 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,
yearis derived asperiod * 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 at0with 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_startis derived.- Type:
int or None
- flow_end_period
The last period of a flow term’s window, inclusive. When given,
flow_endis derived.- Type:
int or None
- flow_reference_period
The reference period for an even-flow comparison. When given,
flow_referenceis 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_SCALEper 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, orregret.- Type:
str
- risk_alpha
The tail or quantile level for
cvarandquantile, 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 >= 1covers offsets(p - 1) * widththroughp * width - 1.yearremains a display label only: the 1-based year the period ends on.- Returns:
tuple of int – The offsets of the target’s period.
- 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, andvaluecolumns.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_penaltydivided bynormalization_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
normalizationisauto, 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_SCALEfor 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:
evenis 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, orflow_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
flowis"even"or"ndy".years (int) – The horizon, in years; the window’s end when
flow_endis not set.pending (mapping of (int, str) to float, optional) – A move’s change per cell, added to
indexwithout 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: -1andmaximum: 1is a one-percent-either-way safe range: around the reference period foreven, and around the previous period forndy, where a minimum of-1tolerates a one-percent decline and a maximum of1tolerates 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
flowis"even"or"ndy".years (int) – The horizon, in years; the window’s end when
flow_endis not set.pending (mapping of (int, str) to float, optional) – A move’s change per cell, added to
indexwithout 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, andvaluecolumns.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(): aproduct.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 targetireached 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
peaksandtargetsdiffer 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 aSpatialPenaltyModel.- 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.
- 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.
- 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 oneOptimizer._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.
- class ws4.opt.patch.PatchModel(optimizer: Optimizer, accounts: Sequence[PatchAccount])[source]
The patch size-distribution accounts of an 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 (
chainis 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_distancemetres 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 inyear, 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()(untilcommit()). 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.
- 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.
- 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.
Nonemeans 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
cfgcarries 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, andelapsed.
- 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.
- 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.
- 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
accountare 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/maxdirections 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
ndyoreven.
- 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.. Aproduct.account is harvested output, not closing inventory.- Parameters:
values (pandas.DataFrame) – Account values with
offset,account, andvalue.- Returns:
pandas.DataFrame –
offset,account, andvalueat 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_hafor 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_blocksis 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
- 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
- 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.
- 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
maxandobjectiveis alwaysmin.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.jsondocument.near_front_epsilon (float, optional) – The largest Chebyshev distance in the normalized outcome box that is still labelled near-front.
0keeps 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
baseis None. Defaults to 200.years (int, optional) – The horizon when
baseis None. Defaults to 50.threads (int, optional) – BLAS threads when
baseis 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.
- 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.
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.