Installation¶

SCPN-Fusion-Core supports three installation paths: a pure-Python core install (fastest to get started), a Rust-accelerated install (10–50x faster numerics), and a Docker-based install (zero local dependencies).

Requirements¶

Python 3.9 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 PyPI (Recommended)¶

Pre-built wheels include the Python core package:

pip install scpn-fusion

Install optional stacks explicitly as needed:

pip install "scpn-fusion[ui]"
pip install "scpn-fusion[ml]"
pip install "scpn-fusion[rl]"
pip install "scpn-fusion[full]"

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.

Rust Kernel Build (Optional)¶

The scpn-fusion-rs/ directory contains a 11-crate Rust workspace that mirrors the Python package structure. Building it provides 10–50x speedups for equilibrium solves, inverse reconstruction, and transport stepping.

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 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.