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 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.Volume at offset 0 is 340 = 2.0 * 170: block 1’s 3.0 ha of natural track is gone, and block 2’s 2.0 ha remains.

  • product.Volume at offset 0 is 360 = 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 calibrate runs 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 watch paints 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.