Your first model
The quickstart proved the plumbing. This page runs a complete small study and reads the result, with every figure checkable by hand. It uses the same two-block example, so the arithmetic stays visible.
The question
> We need some early harvest volume, and we do not want to liquidate the natural stand.
Two accounts answer it. feature.Volume is the volume on the natural track, so it measures
what is left standing; product.Volume is what the treatments produced. Both are reported per
year, in cubic metres.
Step 1: state the question as targets
A target is an account, an accounting period, and a bound. Write them in a file:
# tmp/getting-started/study.yaml
targets:
- account: feature.Volume # keep at least 340 m3 standing in the first year
period: 1
minimum: 340
period_width: 1
- account: product.Volume # produce at least 300 m3 in the first year
period: 1
minimum: 300
period_width: 1
The two floors are deliberately close to the two arms of the trade-off: 340 is exactly what is
standing if block 1 is cleared (2.0 * 170), and 300 is a little less than what clearing it
produces (3.0 * 120 = 360). Period 1 with width 1 reads offset 0, the first simulation year.
Step 2: search
ws4 optimize --dataset tmp/getting-started/compiled \
--targets tmp/getting-started/study.yaml \
--years 5 --time-limit 00:00:05 --seed 1 --threads 1 \
--out tmp/getting-started/study
The same search from Python, for comparison:
optimizer = Optimizer.from_dataset(
dataset,
OptimizeConfig(years=5, iterations=500, seed=1, targets_path="tmp/getting-started/study.yaml"),
)
summary = optimizer.run(Path("tmp/getting-started/study"))
Step 3: read the result
Four files matter. schedule.csv is the decision:
block_id,treatment,offset
1,CC,0
2,CC,3
summary.json says whether the search reached a feasible point:
incumbent_objective: 0.0
blocks_scheduled: 2
iterations: 500
report_targets.csv says how each target fared (year is the display label, the year the period
ends on):
account,year,value,minimum,maximum,penalty,status
feature.Volume,1,340.0,340,,0.0,met
product.Volume,1,360.0,300,,0.0,met
and report_accounts.csv summarises the whole profile (including the offset -1 snapshot):
account,min,max,mean,final
feature.Volume,45.0,700.0,315.8,70.0
product.Volume,355.0,360.0,357.5,355.0
Step 4: check it by hand
feature.Volumeat offset 0 is340 = 2.0 * 170: block 1’s 3.0 ha of natural track is gone, and block 2’s 2.0 ha remains.product.Volumeat offset 0 is360 = 3.0 * 120: block 1’s harvest is in.Both floors are met, so the penalty is zero and the objective is zero.
Step 5: notice what the result does not say
Block 2 is cleared at offset 3, and that choice is arbitrary: nothing in the target set reads any offset after 0, so clearing block 2 at offset 1 and clearing it at offset 4 cost exactly the same. A zero-cost search is an indifferent search.
That is the most common surprise for a new user, and the fix is to say what you care about:
a floor on later years, to stop the search emptying them;
an even-flow target, to hold the harvest profile flat, or a non-declining one, to stop the closing inventory declining (see Even flow and non-declining yield);
a patch target, to require that harvesting lands as openings of a certain size (see Patch size-distribution targets).
Step 6: iterate
A study is a loop: state targets, search, read the statuses and the penalties, then tighten or loosen. Two habits make the loop short:
Calibrate the weights when one term drowns out the others:
ws4 calibrateruns a short pilot search and rescales the weights so the terms are comparable (see Write targets).Watch instead of waiting, so you see which term is binding while the search runs:
ws4 watchpaints the target window live (see Watch a run).
Next
How-to guides — the task guides, including the two targets above with teeth.
Examples — runnable notebooks, with output, for the same material.
How WS4 is put together — why the trade-offs behave the way they do.