Architecture¶

Superseded by SYSTEM_MAP.md (2026-06-23). This page is retained for history. Current inventory is generated by tools/capability_manifest.py: 154 Python model source modules, 159 lazy-loaded Python model classes, 187 Rust PyO3 model wrappers, and a 163-model NetworkRunner dispatch list. Use SYSTEM_MAP.md as the canonical architecture map.

Package Structure¶

Text Only

sc_neurocore/
├── Core Tier (Beta package surface — ships in pip install sc-neurocore)
│   ├── neurons/       159 Python classes / 187 Rust PyO3 wrappers (163 NetworkRunner names)
│   ├── synapses/      4 synapse types (bitstream, dot product, STDP, R-STDP)
│   ├── layers/        8 layer types (dense, conv, learning, vectorized, recurrent, memristive, fusion, attention)
│   ├── sources/       Bitstream current sources
│   ├── recorders/     Spike and voltage recording
│   ├── utils/         RNG, bitstreams, connectomes, decorrelators, fault injection
│   ├── accel/         GPU backend (CuPy), JIT kernels (Numba), JAX, MPI, vector ops
│   ├── compiler/      IR graph → SystemVerilog + MLIR/CIRCT pipeline
│   ├── hardware/      HDL generation (Verilog emitter)
│   ├── hdl_gen/       Equation-to-Verilog RTL compiler
│   ├── nir_bridge/    NIR import/export (18/18 primitives, Norse/snnTorch/SpikingJelly/Sinabs/Rockpool interop)
│   ├── identity/      Persistent spiking network, trace encoder/decoder, checkpoint, L16 Director
│   ├── network/       Population-Projection-Network engine (Python, Rust, MPI backends)
│   ├── learning/      13 plasticity rules (STDP, BPTT, TBPTT, EWC, e-prop, R-STDP, MAML, STP, BCM, ...)
│   ├── training/      Surrogate gradient training cells
│   ├── hdc/           Hyper-dimensional computing (VSA)
│   ├── quantum/       Quantum circuit bridge (Qiskit + PennyLane)
│   ├── math/          SC arithmetic (add, mul, div, CORDIV)
│   ├── solvers/       ODE solvers (RK4, Euler)
│   ├── graphs/        Petri nets, graph algorithms
│   ├── ensembles/     Multi-agent consensus
│   ├── transformers/  Stochastic transformer blocks
│   ├── model_zoo/     10 pre-built network configs, 3 pre-trained weight sets
│   ├── models/        Pre-built network architectures
│   ├── export/        ONNX export
│   ├── adapters/      SCPN layer adapters (L1-L16), holonomic (JAX)
│   ├── scpn/          SCPN layer implementations (L1-L16)
│   ├── conversion/    ANN-to-SNN conversion (convert(), QCFS)
│   ├── cli/           Command-line interface (info, deploy, benchmark)
│   └── exceptions/    Custom exception hierarchy
│   ├── security/      Pickle allowlist, input sanitisation
│   └── verification/  Property-based test helpers
│
├── Simulation Tier (Available from source)
│   ├── analysis/      127-function spike train analysis toolkit
│   ├── viz/           14 visualization plots (raster, voltage, ISI, PSD, ...)
│   ├── bio/           Biological circuits (gap junctions, tripartite, cortical column)
│   ├── chaos/         Chaotic RNG
│   ├── optics/        Optical/photonic neuron models
│   ├── physics/       Wolfram hypergraph
│   ├── robotics/      Swarm coupling
│   ├── sleep/         Sleep protocol optimiser
│   ├── spatial/       3D voxel grids, point clouds
│   ├── pipeline/      Data ingestion and training loops
│   ├── profiling/     Performance profiling
│   ├── datasets/      Dataset loaders (MNIST, SHD, DVS)
│   ├── interfaces/    SpikeInterface adapter, external tool bridges
│   ├── integrations/  Third-party integrations
│   ├── drivers/       Hardware driver interfaces
│   ├── experiments/   Experiment management
│   ├── dashboard/     Terminal-based monitoring
│   ├── audio/         Audio processing with spiking networks
│   ├── swarm/         Swarm intelligence
│   ├── generative/    Generative spiking models
│   ├── world_model/   World model / predictive coding
│   └── core/          Core bitstream types
│
└── Contrib Tier (Speculative — research/ directory)
    ├── eschaton/      Heat death, holographic principle, nested universes
    ├── exotic/        Anyons, chemical RD, Dyson grids, mycelium, matrioshka
    ├── meta/          DAO governance, omega point, singularity, time crystals
    ├── post_silicon/  Claytronics, femtotech, reversible computing
    └── transcendent/  Multiverse, noetic fields, spacetime, vacuum decay

Data Flow¶

Text Only

Input Values (float)
    │
    ▼
BitstreamEncoder → Bitstream (uint8 array of 0/1)
    │
    ▼
SCDenseLayer / VectorizedSCLayer
    │  (packed 64-bit AND + popcount)
    ▼
Output Firing Rates (float)

Hardware Path¶

Text Only

Python Model ──► VerilogGenerator ──► Verilog RTL ──► FPGA Synthesis
                                         │
                                         ▼
                                   Co-Simulation
                                   (bit-true verification)

GPU Acceleration¶

The accel package provides transparent GPU acceleration:

HAS_CUPY flag detects CuPy availability
xp module alias (CuPy or NumPy)
to_device() / to_host() for data transfer
Numba JIT kernels for CPU hot paths