Installation

SCPN-Fusion-Core supports three installation paths: a pure-Python core install (fastest to get started), an optional Rust-accelerated install, and a Docker-based install. Native performance is kernel-, input-, build-, and hardware-specific; use the linked benchmark reports instead of a generic speedup multiplier.

Requirements

  • Python 3.10 or later

  • NumPy >= 1.24

  • SciPy >= 1.8

Optional runtime stacks are exposed via extras:

  • [ui]: Streamlit dashboard

  • [ml]: JAX/JAXLIB ML lanes

  • [rl]: Gymnasium RL environments

  • [full]: all optional runtime stacks + physics extras

From Source (Pure Python)

Clone the repository and install in editable mode:

git clone https://github.com/anulum/scpn-fusion-core.git
cd scpn-fusion-core
pip install -e .

This installs the pure-Python package. Every module auto-detects the Rust extension at import time and falls back to NumPy/SciPy if it is not available. You will see a one-time info message at import:

INFO: scpn_fusion_rs not found -- using NumPy fallback.

Development Install

For running the test suite, linters, and building documentation:

pip install -e ".[dev]"
pytest tests/ -v

The [dev] extra installs test/type-check tooling only.

Pinned Review Install

For release review, external reproduction, or onboarding where dependency drift must be minimized, use the hash-pinned lock files under requirements/ before installing the editable source tree. The Python 3.12 minimal path is:

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 .

Use requirements/docs.txt for documentation-only work and requirements/ci-py312.txt for CI-equivalent Python 3.12 review. These files are generated from requirements/*.in by tools/regenerate-requirements.sh with hashes enabled; edit the .in files first, then regenerate the locked .txt outputs.

Rust Kernel Build (Optional)

The scpn-fusion-rs/ directory contains a 13-crate Rust workspace that mirrors the Python package structure. Building it enables selected native equilibrium, control, transport, phase, GPU, and polyglot kernels. It does not make every Python path native, and backend availability alone is not benchmark evidence.

Prerequisites:

  • Rust stable toolchain (rustup recommended)

  • maturin (pip install maturin)

Build steps:

cd scpn-fusion-rs

# Build the native library
cargo build --release

# Run Rust tests
cargo test --all-features

# Build Python bindings (produces scpn_fusion_rs.pyd / .so)
cd crates/fusion-python
maturin develop --release

After building, restart Python and the package will auto-detect the Rust extension:

>>> from scpn_fusion.core import RUST_BACKEND
>>> print(RUST_BACKEND)
True

RUST_BACKEND confirms dispatch availability only. For measured values, follow docs/BENCHMARKS.md, RESULTS.md, and the referenced JSON/Markdown artifacts; compare only equivalent workloads and hardware metadata.

Rust Benchmarks

Criterion micro-benchmarks are included for the SOR stencil, inverse solver, and neural transport MLP:

cd scpn-fusion-rs
cargo bench

Docker

A Docker image is provided for zero-dependency deployment:

# Run the Streamlit dashboard
docker compose up

# Or build and run manually
docker build -t scpn-fusion-core .
docker run -p 8501:8501 scpn-fusion-core

# With dev dependencies (for running tests inside the container)
docker build --build-arg INSTALL_DEV=1 -t scpn-fusion-core:dev .
docker run scpn-fusion-core:dev pytest tests/ -v

The Docker image includes both the Python package and the pre-compiled Rust extension.

Verifying the Installation

After installation, verify that the package loads correctly:

python -c "import scpn_fusion; print(scpn_fusion.__version__)"

Run a quick equilibrium solve to confirm numerical correctness:

scpn-fusion kernel

Expected output: a converged Grad-Shafranov equilibrium with magnetic axis position, safety factor profile, and plasma current reported to stdout.