Onboarding

This page gives first-time readers one controlled path through setup, a useful demo, and evidence review. It mirrors docs/ONBOARDING.md but keeps the Sphinx navigation self-contained.

First-Run Contract

Use the onboarding path when you need a reproducible first look, not a parity claim:

  1. create a local virtual environment,

  2. install from the hash-pinned lock file when reviewing release state,

  3. run the hero demo,

  4. refresh the checksummed evidence bundle,

  5. read the blocked and accepted rows before quoting any result.

Pinned Environment

For a current source checkout on Python 3.12, use the minimal hash-pinned lock file before installing the editable package:

python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --require-hashes -r requirements/minimal.txt
python -m pip install --no-deps -e .

For documentation work, use requirements/docs.txt. For CI-equivalent local review on Python 3.12, use requirements/ci-py312.txt. Regenerate lock files only through tools/regenerate-requirements.sh so the hash-pinned surfaces stay consistent.

Hero Demo

The shortest useful demo is the minimal equilibrium run followed by the full-reproduction evidence wrapper:

python examples/minimal.py --grid 17 --equilibrium-iters 4
scpn-fusion repro --full

The first command exercises an inspectable local Grad-Shafranov path. The second command refreshes validation/reports/full_reproduction_evidence.json and validation/reports/full_reproduction_evidence.md with SHA-256 checksums for the full-fidelity campaign source reports. The expected top-level status is not_full_fidelity until external same-case parity artifacts close the blocked rows.

Environment Check

Record what actually ran before interpreting output:

python -c "import scpn_fusion; print(scpn_fusion.__version__)"
python -c "from scpn_fusion.core import RUST_BACKEND; print(RUST_BACKEND)"
reuse lint

The backend flag reports whether optional Rust bindings loaded; it is not a speed measurement. A healthy repro --full run may still report not_full_fidelity because the command preserves external evidence blockers. Idle CUDA utilization likewise means only that the selected path is not currently executing a GPU kernel; consult the report’s backend and hardware metadata before diagnosing a fault.

Reader Tracks

Reader

Start with

Evidence boundary

New user

README.md and this page

Run the hero demo before reading benchmark values.

Contributor

docs/API_OVERVIEW.md and the relevant tests

Update code, tests, docs, and generated reports together.

Fusion-domain reviewer

docs/BENCHMARKS.md and validation/reports/

Treat blocked rows as missing parity evidence, not hidden failures.

Release reviewer

docs/RELEASE_READINESS.md and requirements/*.txt

Confirm hash-pinned dependency state and report freshness.

Commercial evaluator

docs/APPLICATIONS_AND_MARKET.md and RESULTS.md

Evaluate a bounded evidence package, not a plant-readiness promise.

Next Reading