Journey 02 — Scaffold, check-model, dry-run

Scaffold a runnable study with solvjump init, validate the model contract with check-model, and preview grid size with run --dry-run — no SolvSRK budget spent.

Prerequisites: Journey 01 — active license (or dev optional-license build). Scenario: A runnable model.py + study.yaml without integrating yet

Key APIs

solvjump init <name>
solvjump check-model model.py:make_rhs
solvjump.inspect_model()
solvjump run study.yaml --dry-run

Concepts to internalize

Model contract — make_rhs(params) -> (rhs, y0, t_span) is required for every study.
terminal_metrics — required for ranking, finalists CSV, and adaptive strategy; make_rhs alone is enough for trajectory-only sweeps.
Dry-run — plans grid size and strategy; never integrates. Use in CI to catch YAML mistakes.
init template — damped-oscillator scaffold with both hooks; safe throwaway folder for learning.

Important code

The guided tour script wraps this pattern. Copy the production shape into your pipeline:

solvjump init demo_study
solvjump check-model demo_study/model.py:make_rhs
solvjump run demo_study/study.yaml --dry-run

Act-by-act walkthrough

Act 1 — What you are doing

solvjump init writes a damped-oscillator template with make_rhs and terminal_metrics. You validate the contract, then --dry-run prints grid size and strategy without spending SolvSRK budget.

Act 2 — Scaffold

Writing into _journey02_demo/ (throwaway — safe to delete).

Field	Value	Notes
`model`	<product-root>\python\examples_journey02_demo\demo_study\model.py
`study`	<product-root>\python\examples_journey02_demo\demo_study\study.yaml

Act 3 — check-model / inspect_model

The CLI wraps inspect_model(). Ranking/adaptive need terminal_metrics; make_rhs alone is enough to sweep trajectories.

Field	Value	Notes
`make_rhs`	True
`terminal_metrics`	True
`supports_ranking`	True
`result`	OK	no finalist_sort_key(metrics) hook - using the default ordering (comm_ok/mission_ok gates, else 'rank', else insertion order).

Act 4 — Dry-run

plan_study / solvjump run --dry-run never integrates. Use it in CI to catch YAML mistakes.

Study

Field	Value	Notes
`model`	<product-root>\python\examples_journey02_demo\demo_study\model.py:make_rhs
`dynamics_params`	k in [0.5, 5], c in [0, 1]
`t_span`	[0.0, 10.0]
`sweep_horizon`	10.0 (steps 200 x dt 0.05)

Plan

Field	Value	Notes
`strategy`	adaptive (operator-free MFBO, SRK-verified finalists)
`grid_points`	256
`est_srk_solves`	64 (25% of grid)
`acquisition`	auto
`history_mode`	auto
`finalists`	50	Warm-start: no prior observations for this family yet (first run)

Dry run only - no session created. Re-run without --dry-run to execute.

Field	Value	Notes
`study`	study.yaml
`model`	<product-root>\python\examples_journey02_demo\demo_study\model.py:make_rhs
`dynamics_params`	k in [0.5, 5], c in [0, 1]
`t_span`	[0.0, 10.0]
`sweep_horizon`	10.0
`horizon_aligned`	True
`solvtune_objective`	balanced
`noise_type`	gaussian
`grid_points`	256
`strategy_requested`	adaptive
`strategy_resolved`	adaptive
`warm_start_observations`	0

Act 5 — Next

Journey 03 runs a real 9-point Brusselator study. Delete examples/_journey02_demo whenever you like.

Guided tour output

Verified console capture from 02_init_check_dry_run.py:

A runnable model.py + study.yaml without integrating yet

-- Act 1 - What you are doing --
  -> solvjump init writes a damped-oscillator template with make_rhs and terminal_metrics. You validate the contract, then --dry-run prints grid size and strategy without spending SolvSRK budget.

-- Act 2 - Scaffold --
  -> Writing into _journey02_demo/ (throwaway — safe to delete).
  model: <product-root>\python\examples\_journey02_demo\demo_study\model.py
  study: <product-root>\python\examples\_journey02_demo\demo_study\study.yaml

-- Act 3 - check-model / inspect_model --
  -> The CLI wraps inspect_model(). Ranking/adaptive need terminal_metrics; make_rhs alone is enough to sweep trajectories.
  make_rhs: True
  terminal_metrics: True
  supports_ranking: True
  result: OK
  -> no finalist_sort_key(metrics) hook - using the default ordering (comm_ok/mission_ok gates, else 'rank', else insertion order).

-- Act 4 - Dry-run --
  -> plan_study / solvjump run --dry-run never integrates. Use it in CI to catch YAML mistakes.
  _section: Study
  model: <product-root>\python\examples\_journey02_demo\demo_study\model.py:make_rhs
  dynamics_params: k in [0.5, 5], c in [0, 1]
  t_span: [0.0, 10.0]
  sweep_horizon: 10.0 (steps 200 x dt 0.05)
  _section: Plan
  strategy: adaptive (operator-free MFBO, SRK-verified finalists)
  grid_points: 256
  est_srk_solves: 64 (25% of grid)
  acquisition: auto
  history_mode: auto
  finalists: 50
  -> Warm-start: no prior observations for this family yet (first run)
  log: Dry run only - no session created. Re-run without --dry-run to execute.
  study: study.yaml
  model: <product-root>\python\examples\_journey02_demo\demo_study\model.py:make_rhs
  dynamics_params: k in [0.5, 5], c in [0, 1]
  t_span: [0.0, 10.0]
  sweep_horizon: 10.0
  horizon_aligned: True
  solvtune_objective: balanced
  noise_type: gaussian
  grid_points: 256
  strategy_requested: adaptive
  strategy_resolved: adaptive
  warm_start_observations: 0

-- Act 5 - Next --
  -> Journey 03 runs a real 9-point Brusselator study. Delete examples/_journey02_demo whenever you like.

-- Run complete --

Run it

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/02_init_check_dry_run.py
 
# Production one-liner — same API call you ship:
solvjump init demo_study

What comes next

Journey 03 runs the first real Brusselator YAML study and writes a results CSV.

Navigation

← Journey 01 — License and first contact · Journey 03 — First YAML study →

01 License and first contact 03 First YAML study