Install Profiles¶

SC-NeuroCore keeps the default install small. Start with the base package, then add extras only for the workflows you actually run.

Base install¶

Bash

pip install sc-neurocore

For scripts, Dockerfiles, or lab SOPs that want every install command to name a profile explicitly, minimal and core are stable aliases for the same base dependency set:

Bash

pip install "sc-neurocore[minimal]"
pip install "sc-neurocore[core]"

The base wheel installs the public Python package surface and the core numeric dependencies declared in pyproject.toml: numpy and scipy. It does not install PyTorch, JAX, Qiskit, PennyLane, Lava, FastAPI, MPI, Vivado, Yosys, or other hardware toolchains.

The base path is enough for:

core stochastic-computing layers and bitstream utilities;
Python simulation and many model-zoo examples;
HDL generation and project scaffolding;
CPU-side report parsing and JSON planning tools.

Base install evidence¶

The metadata audit separates packaged event-dataset and ANN/QCFS conversion runtime sources from source-only neuron research kernels. Its nine exact Julia, Go and Mojo runtime patterns follow the installed wheel contract; broader patterns, undeclared runtime patterns and missing matching files fail the audit. The report lists both the allowed patterns and their actual files. Shipping these sources does not install or qualify their external toolchains.

The install-profile audit in benchmarks/results/install_profile_audit.json derives the current base boundary from metadata and packaged files. Its install_measurement.measured field is false; this report contains no fresh timed installation. The historical 2026-06-27 measured run installed the local sc-neurocore wheel with its declared base dependencies, imported the public package, and verified that PyTorch, JAX, Qiskit, PennyLane, Lava, FastAPI, MPI, NIR, HTTP client, plotting, GPU, and Studio stacks were not pulled into the base environment.

Historical measured evidence (2026-06-27):

Field	Value
Command	`python -m pip install <repo>`
Explicit profile command	`pip install "sc-neurocore[minimal]"`
Elapsed time	12.942 s
Installed packages	`defusedxml`, `numpy`, `pip`, `sc-neurocore`, `scipy`
Heavy optional packages installed	None
Public import smoke	`sc_neurocore.__version__ == "3.16.0"` and 45 public exports

The root package import and distribution contracts are enforced by tests/test_public_api_lazy_facades.py, tests/test_public_api_install_profiles.py, and tests/test_public_api_packaged_resources.py. The 2026-06-27 scoped verification passed Ruff, Ruff docstring checks, strict mypy, 11 passed public API tests, and 100% isolated coverage for src/sc_neurocore/__init__.py. That test surface covers the lazy public symbol facade, invalid attribute handling, dir() membership, version metadata, install extras, packaged HDL resources, and exclusion of research-only polyglot source trees from the base wheel.

The 30-second smoke path is:

Bash

python examples/minimal_smoke_demo.py

It uses the same dependency-light surface as pip install "sc-neurocore[minimal]": root public API imports, deterministic stochastic bitstream generation, a StochasticLIFNeuron bitstream pass, and packaged Verilog primitive discovery. It does not import quantum, Lava, gdsfactory, PyTorch, JAX, or hardware-only dependencies.

Reproducible source workstation¶

Use the workstation lock when a source checkout needs the contributor tools, Julia bridge, Rust build frontend, plotting stack, and Jupyter surface in one environment:

Bash

uv venv --python 3.12.14 .venv
uv pip install --python .venv/bin/python --require-hashes \
  -r requirements/workstation.txt
uv pip install --python .venv/bin/python --no-deps --no-build-isolation \
  --editable .
source .venv/bin/activate
command -v python pip pip-compile maturin mojo julia go rustc pixi node

requirements/workstation.txt is compiled from pyproject.toml with the dev and julia extras, requirements/build.in, requirements/maturin.in, and the notebook-only requirements/workstation.in. The lock pins every Python package and archive hash. Activating .venv puts its Python tools and the locked Mojo executable on PATH. Rust, Go, Julia, Pixi, Node, and HDL executables must also be available on PATH at the versions pinned by the CI workflows and project toolchain manifests.

The packaged juliapkg.json constrains JuliaCall to Julia 1.11.9, matching the required CI runtime. This prevents JuliaUp from silently selecting a newer installed release during first import.

Execution lanes in each distribution¶

The published wheel is pure Python. What each execution lane needs:

Lane	Provided by	Needs
Python	every distribution	nothing further
Rust	the separate `sc_neurocore_engine` package	installing that package
Julia	a source checkout	the Julia model kernel sources, which the wheel does not ship, and JuliaCall (the `julia` extra)
Go	a source checkout	shared libraries built from the Go sources
Mojo	a source checkout	shared libraries built with the Mojo toolchain

The wheel does carry the dense IF conversion sources for Rust, Go, Mojo and Julia and the event-dataset Julia sources, which those public APIs load or build on their own (see ANN-to-SNN conversion). They are not model kernels, so they do not make the Julia, Go or Mojo lane present.

Installing the julia extra into a wheel installation adds JuliaCall only; the Julia model-kernel lane still needs a source checkout. sc-neurocore info reports, for each lane, whether this installation holds its resources and, when it does not, what is missing. The report reads the installed files; it does not start Julia or load a native library, and an individual kernel still checks its own artefact before use.

Rust engine¶

The Rust engine is optional acceleration. If an engine wheel or local source build is present, SC-NeuroCore detects sc_neurocore_engine at import time and uses it for supported hot paths. If it is absent, Python/NumPy fallbacks remain available.

Release automation builds pre-built sc_neurocore_engine wheels with maturin for Python 3.10-3.14 on Linux x86_64/aarch64, macOS, and Windows. Prefer a matching release wheel:

Bash

python -m pip install sc_neurocore_engine

If no matching wheel exists for the active platform or Python version, use a source checkout and a local Rust toolchain:

Bash

git clone https://github.com/anulum/sc-neurocore.git
cd sc-neurocore
python -m pip install --require-hashes -r requirements/maturin.txt
cd bridge
python -m maturin develop --release

Check what the current environment can use:

Bash

sc-neurocore info

Contributor environments must keep the editable Python package, Rust engine wheel, and checked-in release metadata on the same version. After changing release metadata or rebuilding the engine, refresh the editable install and run the version audit:

Bash

python -m pip install -e ".[dev]"
python tools/version_surface_audit.py

The audit checks installed distribution metadata as well as pyproject.toml, src/sc_neurocore/__init__.py, engine/Cargo.toml, and bridge/pyproject.toml; stale .dist-info or .egg-info metadata must be refreshed rather than ignored.

Optional extras¶

Install command	Use when	Adds
`pip install "sc-neurocore[minimal]"`	Explicit v4 minimal install for 30-second smoke demos, Dockerfiles, and lab SOPs	No additional packages beyond base `numpy` / `scipy`
`pip install "sc-neurocore[core]"`	Explicit base install for reproducible scripts and Dockerfiles	No additional packages beyond base `numpy` / `scipy`
`pip install "sc-neurocore[training]"`	Training PyTorch-backed models; `auto_device()` skips CUDA GPUs unsupported by the installed PyTorch build	`torch`
`pip install "sc-neurocore[nir]"`	Importing/exporting Neuromorphic Intermediate Representation graphs	`nir`
`pip install "sc-neurocore[neuroml]"`	Writing NeuroML 2 documents and validating them against the schema	`libNeuroML`
`pip install "sc-neurocore[sonata]"`	Reading SONATA circuits through the reference library	`libsonata`
`pip install "sc-neurocore[hdl]"`	Equation-to-HDL workflows, unit-checked equations, packaged HDL primitives	`pint`; bundled `.v` / `.sv` / OpenROAD helper artefacts
`pip install "sc-neurocore[optics]"`	Source-checkout photonic-layout and GDSII round-trip checks	`gdsfactory`
`pip install "sc-neurocore[gpu]"`	Research-grade CuPy CUDA experiments; requires local CUDA compatibility and does not change PyTorch CUDA architecture support	`cupy-cuda12x`
`pip install "sc-neurocore[jax]"`	Research-grade JAX experiments; requires local accelerator/runtime compatibility	`jax`, `jaxlib`
`pip install "sc-neurocore[annealing]"`	D-Wave `neal` parity checks for the quantum-annealing bridge	`dwave-neal`, `dimod`
`pip install "sc-neurocore[quantum]"`	Research-grade quantum-circuit experiments; Qiskit/PennyLane are optional and never installed by default	`qiskit`, `pennylane`, `qiskit-aer`
`pip install "sc-neurocore[studio]"`	Web studio / local design UI	`fastapi`, `uvicorn`, `httpx`, `httpx2`; `nir` for the canvas's NIR export and import; `pint` and `sympy` for candidate-model units and equation diffs
`pip install "sc-neurocore[bioware]"`	Biological closed-loop and spike-sorting prototypes	`scikit-learn`
`pip install "sc-neurocore[docs]"`	Building this documentation locally	`mkdocs`, `mkdocs-material`, `mkdocstrings`
`pip install "sc-neurocore[dev]"`	Contributor lint/test work	`pytest`, `ruff`, `mypy`, `bandit`, docs helpers

Use full only for local research environments where large optional packages are acceptable:

Bash

pip install "sc-neurocore[full]"

The hdl and full profiles use the same wheel artefact set as the base package: source RTL primitives under hardware/, baseline offline HDL primitives under hdl/primitives/, safety SystemVerilog under hdl_gen/safety/, and OpenROAD helper scripts under hdl_gen/openroad_flow/. Those files are bundled with the wheel so install-time extras only decide which Python dependencies are added; external synthesis tools still produce device-specific bitstreams or routed reports locally.

Offline HDL shipping profile¶

The hdl-offline shipping profile is the audited baseline for machines where Vivado is unavailable or intentionally excluded from the install image. It ships the static primitive RTL used by the baseline stochastic-computing FPGA path:

sc_bitstream_encoder.v
sc_bitstream_synapse.v
sc_dense_layer_core.v
sc_dotproduct_to_current.v
sc_firing_rate_bank.v
sc_lif_neuron.v

Python consumers can enumerate or read those files from the installed wheel:

Python

from sc_neurocore.hdl.resources import baseline_primitive_text, list_baseline_primitive_rtl

for name in list_baseline_primitive_rtl():
    rtl = baseline_primitive_text(name)

Docker and conda consume the same wheel-contained resources:

Bash

docker build -f deploy/Dockerfile --build-arg INSTALL_EXTRAS=hdl -t sc-neurocore:hdl .
conda build conda/

The install-profile audit fails if the package-data pattern, static primitive files, Docker HDL profile hook, or conda base runtime dependencies drift from the release contract. Current audit evidence is recorded in benchmarks/results/install_profile_audit.json.

The full profile is the CPU-side union for training, NIR, Studio, HDL, codec, bioware, and quantum workflows. It is a local research environment profile, not the standard user install. It deliberately does not pull GPU-, MPI-, Lava-, Julia-, Go-, Mojo-, WGSL-, JAX-, or D-Wave-annealing-specific stacks because those depend on local hardware, drivers, external runtimes, or reference samplers used only by focused parity tests.

For the architecture-level classification of every optional extra, package discovery exclude, and Cargo workspace exclude, see the Package Boundary Decision. For the CI/dev install boundary of optional stacks such as gdsfactory, dwave-neal, ONNX, Lava, snnTorch, SpikingJelly, CuPy, and MPI, see the Optional Dependency Matrix.

Heavy backends are always opt-in. Qiskit, PennyLane, CuPy, JAX, Lava, MPI, Julia, Go, Mojo, and WGSL tooling are research-grade integration surfaces until their target environment, install profile, and verification artefacts are named explicitly in the relevant docs. A default installation must not require them.

Research-only polyglot layer¶

The source tree contains Julia, Go, Mojo, and WGSL implementations for selected kernels. Treat this as a research and benchmarking layer, not as the shipped runtime shape.

This layer exists to compare implementation strategies under controlled parity and timing harnesses. It supports internal acceleration research only; it is not a user-facing install profile, not part of the default wheel contract, and not a prerequisite for standard simulation, training, NIR export, HDL generation, or FPGA deployment.

Rules of thumb:

A base pip install sc-neurocore does not require Julia, Go, Mojo, or WGSL tooling.
pip install "sc-neurocore[full]" still does not imply a Julia, Go, Mojo, or WGSL toolchain; those runtimes remain source-checkout research dependencies.
FPGA deployment emits SystemVerilog and tool scripts; it does not ship the polyglot benchmark matrix to the device.
A polyglot file is authoritative only when a maintained Python loader uses it and tests cover that path.
Mirror or transcript files under src/sc_neurocore/accel/ are not evidence that a feature is shipped.

See Acceleration Mirror Authority for the authoritative-entrypoint list.

Hardware toolchains¶

FPGA and ASIC tools are external to Python packaging:

Yosys / nextpnr are needed only when you want open-source synthesis or place-and-route.
Vivado is needed only for Xilinx implementation and power/timing reports.
Quartus is needed only for Intel FPGA implementation and reports.

The deploy command can still scaffold a project without those tools. Synthesis and power reports appear only after an external toolchain has produced them.

Version evidence for hardware reports¶

Hardware reports must name the EDA tool version that produced them. Current release evidence uses:

Tool	Version status	Scope
AMD Vivado	`v2025.2`	SHD / PYNQ-Z2 synthesis evidence in `docs/CHANGELOG.md`.
OpenROAD	Not release-pinned yet	The ASIC flow can generate OpenROAD-compatible decks, but no committed OpenROAD place-and-route report is release evidence yet.
Yosys	Report-specific	Existing reports name the Yosys version beside the numbers because generic-cell counts vary by release.

Do not quote OpenROAD area, power, timing, or GDS results until the exact OpenROAD binary or container digest and PDK revision are recorded with the report.

Before publishing a hardware report, capture the local toolchain inventory:

Bash

python tools/eda_toolchain_versions.py --pretty --out build/eda-toolchain.json

Release gates can also require specific tools and version substrings:

Bash

python tools/eda_toolchain_versions.py \
  --require vivado --expect vivado=v2025.2 \
  --require yosys --expect yosys=0.63

The JSON inventory records Vivado, OpenROAD, Yosys, nextpnr, IceStorm, Trellis, Quartus, Lattice Diamond/Radiant, PYNQ, and OpenROAD/PDK pin fields.