Product documentation — installation, licensing, and integration guides.
SolvJump Configurator
Examples
06 Proprietary chemistry

Journey 06 — Proprietary chemistry

Sweep stiff Robertson kinetics with cache control: trajectory-only models (no terminal_metrics) still complete but produce no ranked finalists CSV.

Prerequisites: Journeys 01–05 — comfortable with YAML studies and sessions. Scenario: Robertson (S3) | cache disabled | no terminal_metrics

Key APIs

  • solvjump run examples/robertson_study.yaml
  • SOLVJUMP_DISABLE_CACHE=1
  • solvjump run ... --cache-only
  • Session.sweep()

Concepts to internalize

  • S3 stiffness — Robertson is the stiff chemistry tutorial; jump may calibrate but ranking hooks are absent.
  • No terminal_metrics — sweep completes; no finalists sort key; honest limitation, not failure.
  • Cache semantics — disable cache when validating operator drift; cache_only for miss testing.
  • Proprietary models — your make_rhs stays in your repo; SolvJump never uploads it.

Important code

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

# Force fresh calibration (PowerShell):
# $env:SOLVJUMP_DISABLE_CACHE=1
solvjump run examples/robertson_study.yaml

Act-by-act walkthrough

Act 1 — The situation

Rate constants come from in-house experiments. SOLVJUMP_DISABLE_CACHE=1 forces a fresh calibration instead of a pack hit. robertson_model.py has no terminal_metrics — you read yields from CSV, and adaptive ranking is unavailable.

FieldValueNotes
make_rhsTrue
terminal_metricsFalse
supports_rankingFalse

Act 2 — cache_only miss

mode: cache_only refuses to calibrate. brusselator_study_cache_only.yaml uses a slug that is not in the pack — the product command should error.

Study definition

FieldValueNotes
model<product-root>\python\examples\brusselator_model.py:make_rhs
dynamics_paramsa in [0.8, 1.2], b in [2.5, 3.5]
y0[1.0, 3.0]
t_span[0.0, 10.0]
modecache_only
calibration_seeds20

Operator routing, calibration & sweep (3 steps)

FieldValueNotes
model<product-root>\python\examples\brusselator_model.py:make_rhs
dim2
stiffness_nomS1
horizon[0.0, 10.0]
problem_set_operatorsnot loadedkepler
  • Jump recommendation: confidence=exact, cache_ref=<operator_id>, mode=cache_only

  • Expected refusal: RecalibrationRequired: no cache operator for fingerprint

Act 3 — Wire the model

k2 spanning 8k-12k. Species A starts at 100%.

FieldValueNotes
model<product-root>\python\examples\robertson_model.py:make_rhs
parametersk1=0.04, k2 in [8000, 12000]
cacheSOLVJUMP_DISABLE_CACHE=1
model<product-root>\python\examples\robertson_model.py:make_rhs
dim3
stiffness_nomS3
horizon[0.0, 100.0]
problem_set_operatorsnot loadedrobertson
  • Jump recommendation: confidence=exact, cache_ref=<operator_id>, mode=auto
FieldValueNotes
seeds12
reasonno exact cache match for this modelCollecting trajectory training pairs: jump lag=0.1s, SolvTune arm=solvsrk, objective=balanced, target chain=unknown
  • SRK collection done - 48 train pairs from 3 trajectories (0 failed, need >=8 train)

  • Fitted nominal+guard kernels - train median SCD=6.51, holdout median SCD=6.42 (n=8/8)

  • Rollout validation - SCD by chain depth [1:6.42, 10:5.44, 50:2.80], max_valid_chain=50 (short_chain)

  • Accuracy gate passed (operator <operator_id>)

Operator setup

  • SolvJump fitted a fast approximation and checked it against full SolvSRK — it passed.
FieldValueNotes
accuracy_checkexcellent quality
operator_id<operator_id>
fit_time908 ms (one-time before the sweep)

Act 4 — Sweep k2

10 points; 50 steps x 0.5 s. If jump refused, fallback is full-grid SRK screen.

  • Sweep finished - example params {'k1': 0.04, 'k2': 8000.0}, final state ~ [0.736, 0.0, 0.264]

  • SRK timing sample: 3 point(s) integrated for comparison

FieldValueNotes
! Horizon mismatchoperator jump_lag=0.1 s but sweep dt=0.5 s — ranking vs SRK will be unreliable
! Degeneracy guard tripped on 4 grid point(s) - sweep modesrk_fallback

Sweep results

FieldValueNotes
completed5 parameter sets
skipped4 outside safe boundsLow: params={'k1': 0.04, 'k2': 8000.0}
  • Mid: params={'k1': 0.04, 'k2': 10000.0}

  • High: params={'k1': 0.04, 'k2': 12000.0}

How long did this take?

FieldValueNotes
search_methodfast jump sweep
grid_size9
operator_fit908 ms
fast_sweep266 ms
this_run_total1.2 s
vs_full_SolvSRK_on_every_study_point~299 ms for all 9 points in this study (extrapolated from 3 spot checks — not a larger search)
speedup_vs_full_grid~1.1× (jump sweep vs brute estimate)All results CSV: <session-dir>\sweep_results.csv
highest_C_yield_k28000.0
center_candidate{'k1': 0.04, 'k2': 8000.0}

Act 5 — Deliverables

Receipts under <session-dir>. No ranked finalists CSV on this model. If this session is calibrated, Journey 05 can propagate it.

Why run SolvJump here?

  • Calibrate a jump operator on proprietary stiff kinetics the warm-start pack does not know — your RHS stays in your repo.

  • Map k2 across the design window (5 points) without hand-rolling SRK dispatch.

  • Kill gate blocks a bad operator before you trust an overnight 100-point study.

  • Every parameter set gets a trajectory row — compare yields from CSV even without a ranking hook on this model.

  • Stiff S3 chemistry is where jump pays off at scale — small grids understate the gap.

Guided tour output

Verified console capture from 06_proprietary_chemistry.py:

Robertson (S3) | cache disabled | no terminal_metrics

-- Act 1 - The situation --
  -> Rate constants come from in-house experiments. SOLVJUMP_DISABLE_CACHE=1 forces a fresh calibration instead of a pack hit. robertson_model.py has no terminal_metrics — you read yields from CSV, and adaptive ranking is unavailable.
  make_rhs: True
  terminal_metrics: False
  supports_ranking: False

-- Act 2 - cache_only miss --
  -> mode: cache_only refuses to calibrate. brusselator_study_cache_only.yaml uses a slug that is not in the pack — the product command should error.
  _section: Study definition
  model: <product-root>\python\examples\brusselator_model.py:make_rhs
  dynamics_params: a in [0.8, 1.2], b in [2.5, 3.5]
  y0: [1.0, 3.0]
  t_span: [0.0, 10.0]
  mode: cache_only
  calibration_seeds: 20
  _section: Operator routing, calibration & sweep (3 steps)
  model: <product-root>\python\examples\brusselator_model.py:make_rhs
  dim: 2
  stiffness_nom: S1
  horizon: [0.0, 10.0]
  problem_set_operators: not loaded
  -> kepler | dim=2 | stiffness=S0 | dynamics=conservative
  log: Jump recommendation: confidence=exact, cache_ref=<operator_id>, mode=cache_only
  log: Expected refusal: RecalibrationRequired: no cache operator for fingerprint

-- Act 3 - Wire the model --
  -> k2 spanning 8k-12k. Species A starts at 100%.
  model: <product-root>\python\examples\robertson_model.py:make_rhs
  parameters: k1=0.04, k2 in [8000, 12000]
  cache: SOLVJUMP_DISABLE_CACHE=1
  model: <product-root>\python\examples\robertson_model.py:make_rhs
  dim: 3
  stiffness_nom: S3
  horizon: [0.0, 100.0]
  problem_set_operators: not loaded
  -> robertson | dim=3 | stiffness=S2 | dynamics=relaxation
  log: Jump recommendation: confidence=exact, cache_ref=<operator_id>, mode=auto
  seeds: 12
  reason: no exact cache match for this model
  -> Collecting trajectory training pairs: jump lag=0.1s, SolvTune arm=solvsrk, objective=balanced, target chain=unknown
  log: SRK collection done - 48 train pairs from 3 trajectories (0 failed, need >=8 train)
  log: Fitted nominal+guard kernels - train median SCD=6.51, holdout median SCD=6.42 (n=8/8)
  log: Rollout validation - SCD by chain depth [1:6.42, 10:5.44, 50:2.80], max_valid_chain=50 (short_chain)
  log: Accuracy gate passed (operator <operator_id>)
  _section: Operator setup
  log: SolvJump fitted a fast approximation and checked it against full SolvSRK — it passed.
  accuracy_check: excellent quality
  operator_id: <operator_id>
  fit_time: 908 ms (one-time before the sweep)

-- Act 4 - Sweep k2 --
  -> 10 points; 50 steps x 0.5 s. If jump refused, fallback is full-grid SRK screen.
  log: Sweep finished - example params {'k1': 0.04, 'k2': 8000.0}, final state ~ [0.736, 0.0, 0.264]
  log: SRK timing sample: 3 point(s) integrated for comparison
  ! Horizon mismatch: operator jump_lag=0.1 s but sweep dt=0.5 s — ranking vs SRK will be unreliable
  ! Degeneracy guard tripped on 4 grid point(s) - sweep mode: srk_fallback
  _section: Sweep results
  completed: 5 parameter sets
  skipped: 4 outside safe bounds
  -> Low:  params={'k1': 0.04, 'k2': 8000.0}
  log: Mid:  params={'k1': 0.04, 'k2': 10000.0}
  log: High: params={'k1': 0.04, 'k2': 12000.0}
  _section: How long did this take?
  search_method: fast jump sweep
  grid_size: 9
  operator_fit: 908 ms
  fast_sweep: 266 ms
  this_run_total: 1.2 s
  vs_full_SolvSRK_on_every_study_point: ~299 ms for all 9 points in this study (extrapolated from 3 spot checks — not a larger search)
  speedup_vs_full_grid: ~1.1× (jump sweep vs brute estimate)
  -> All results CSV: <session-dir>\sweep_results.csv
  highest_C_yield_k2: 8000.0
  center_candidate: {'k1': 0.04, 'k2': 8000.0}

-- Act 5 - Deliverables --
  -> Receipts under <session-dir>. No ranked finalists CSV on this model. If this session is calibrated, Journey 05 can propagate it.
  _section: Why run SolvJump here?
  log: Calibrate a jump operator on proprietary stiff kinetics the warm-start pack does not know — your RHS stays in your repo.
  log: Map k2 across the design window (5 points) without hand-rolling SRK dispatch.
  log: Kill gate blocks a bad operator before you trust an overnight 100-point study.
  log: Every parameter set gets a trajectory row — compare yields from CSV even without a ranking hook on this model.
  log: Stiff S3 chemistry is where jump pays off at scale — small grids understate the gap.

-- Run complete --
  session_id: <session_id>
  results_folder: <session-dir>
  points_completed: 5 ok, 0 skipped (of 9)
  fast_sweep: 265.6 ms
  timing_sample: 99.6 ms (3 full-SolvSRK spot checks)
  vs_full_SolvSRK_on_every_study_point: ~299 ms for all 9 points in this study (from 3 spot checks — not a larger search)
  speedup: ~1.1× vs full SolvSRK on every grid point
  receipt_calibration: <session-dir>\calibration_receipt.json
  receipt_sweep: <session-dir>\sweep_receipt.json

Run it

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/06_proprietary_chemistry.py
 
# Production one-liner — same API call you ship:
$env:SOLVJUMP_DISABLE_CACHE=1; solvjump run examples/robertson_study.yaml

What comes next

Journey 07 ranks a 256-point drone battery mission envelope with mission_ok.

Navigation

← Journey 05 — Sessions and live what-if · Journey 07 — Ranked mission envelope →