Skip to content

Getting Started

Installation

Bash
# From PyPI
pip install sc-neurocore

# From source (editable Python package)
pip install -e .

# With development tools
pip install -e ".[dev]"

# Training with PyTorch-backed cells
pip install -e ".[training]"

# NIR interop (Norse, snnTorch, Lava-DL)
pip install -e ".[nir]"

# Research plotting/export stack
pip install -e ".[research]"

# GPU acceleration experiments (CuPy)
pip install -e ".[gpu]"

# Local full research environment only
pip install -e ".[full]"

pip install sc-neurocore installs the public Python package. If you are editing the Rust bridge locally, install bridge/ in the same environment or run source-tree commands with PYTHONPATH=src:bridge. For the complete dependency boundary, see Install Profiles.

Requirements

  • Python >= 3.10
  • NumPy >= 1.24
  • SciPy >= 1.10
  • PyTorch (optional, pip install sc-neurocore[training])
  • Numba (optional, pip install sc-neurocore[accel])
  • Matplotlib (optional, pip install sc-neurocore[research])
  • Hardware toolchains such as Vivado, Quartus, and Yosys are external and only needed for synthesis or implementation, not for the base package.

Running Tests

Bash
# Full repository suite (long-running)
pytest tests/ -v --cov=sc_neurocore --cov-report=term

# Quick smoke test
pytest tests/test_integration.py -v

First Steps

1. Create a Bitstream Encoder

Python
from sc_neurocore import BitstreamEncoder, bitstream_to_probability

encoder = BitstreamEncoder(x_min=0.0, x_max=1.0, length=1024)
bitstream = encoder.encode(0.7)
recovered = bitstream_to_probability(bitstream)
print(f"Encoded 0.7 -> recovered {recovered:.3f}")

2. Build a Neuron Layer

Python
from sc_neurocore import VectorizedSCLayer

layer = VectorizedSCLayer(n_inputs=4, n_neurons=2, length=512)
output = layer.forward([0.3, 0.7, 0.5, 0.2])
print(f"Output firing rates: {output}")

3. Single Neuron with Visualization

Python
import numpy as np
import matplotlib.pyplot as plt
from sc_neurocore import StochasticLIFNeuron

neuron = StochasticLIFNeuron(tau_mem=10.0, dt=1.0, v_threshold=1.0, noise_std=0.05)

potentials, spikes = [], []
for t in range(100):
    spike = neuron.step(0.15)
    potentials.append(neuron.v)
    spikes.append(spike)

fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 6))
ax1.plot(potentials)
ax1.axhline(y=1.0, color='r', linestyle='--', label='Threshold')
ax1.set_ylabel('Voltage')
ax1.legend()
ax2.stem(spikes, linefmt='g-', markerfmt='go', basefmt=' ')
ax2.set_ylabel('Spike')
ax2.set_xlabel('Time (ms)')
plt.tight_layout()
plt.savefig('quickstart_output.png')

4. Stochastic Network (Source → Synapse → Neuron)

Python
from sc_neurocore.sources.bitstream_current_source import BitstreamCurrentSource
from sc_neurocore import StochasticLIFNeuron

source = BitstreamCurrentSource(
    x_inputs=[0.8, 0.5, 0.2],
    weight_values=[1.0, 0.5, 0.0],
    x_min=0.0, x_max=1.0,
    w_min=0.0, w_max=1.0,
)
neuron = StochasticLIFNeuron()

for t in range(100):
    current = source.step()
    neuron.step(current)

5. Run the Full SCPN Stack

Python
from sc_neurocore.scpn import create_full_stack, run_integrated_step, get_global_metrics

stack = create_full_stack()
outputs = run_integrated_step(stack, dt=0.01)
metrics = get_global_metrics(stack)
for name, value in metrics.items():
    print(f"  {name}: {value:.4f}")

6. ArcaneNeuron — Self-Referential Cognition

Python
from sc_neurocore.neurons.models.arcane_neuron import ArcaneNeuron

neuron = ArcaneNeuron()
for t in range(500):
    spike = neuron.step(current=0.8 if t < 200 else 0.1)

state = neuron.get_state()
print(f"Identity (deep compartment): {state['v_deep']:.4f}")
print(f"Confidence: {state['confidence']:.3f}")
print(f"Meta-learning rate: {state['meta_lr']:.4f}")

7. Identity Substrate

Python
from sc_neurocore.identity import IdentitySubstrate, Checkpoint, StateDecoder

substrate = IdentitySubstrate(n_cortical=200, n_inhibitory=80, n_memory=40)
substrate.inject_experience("The cat sat on the mat. It was a rainy day.")
substrate.run(duration=0.5)

decoder = StateDecoder(substrate)
print(decoder.generate_priming_context())

Checkpoint.save(substrate, "identity_checkpoint.npz")
restored = Checkpoint.load("identity_checkpoint.npz")

8. Model Zoo

Python
from sc_neurocore.model_zoo import brunel_balanced_network, load_pretrained

net = brunel_balanced_network()
net.run(0.1)

classifier = load_pretrained("mnist")

10 configurations + 3 pre-trained weight sets (MNIST, SHD, DVS gesture).

9. Source-Only Visualization Helpers

Python
from sc_neurocore.viz.plots import raster_plot, voltage_trace, firing_rate_plot

# After running a network with monitors:
raster_plot(spike_monitor)
voltage_trace(state_monitor, neuron_ids=[0, 1, 2])
firing_rate_plot(spike_monitor, bin_ms=10)

sc_neurocore.viz is excluded from the default wheel. Use a source checkout (pip install -e ".[dev]") before importing it.

10. Source-Only Hardware Deployment (PYNQ)

Python
from sc_neurocore.drivers.sc_neurocore_driver import SC_NeuroCore_Driver

driver = SC_NeuroCore_Driver(mode="EMULATION")
result = driver.run_step(input_vector=[0.5, 0.8, 0.1])

For physical FPGA deployment on PYNQ-Z1/Z2, synthesize the bitstream using the FPGA Toolchain Guide, then switch to mode="HARDWARE".

sc_neurocore.drivers is excluded from the default wheel. Use a source checkout before importing it.

Dense Path Selection

  • Single-sample and tiny batches (1-4): use DenseLayer.forward_fast
  • Larger batches (>=10): use DenseLayer.forward_batch_numpy
  • Default DenseLayer.forward auto-selects

Analysis Toolkit

The analysis toolkit lives in the source distribution, not the default wheel. Install from a source checkout before importing sc_neurocore.analysis.

SC-NeuroCore includes 132 spike train analysis functions across 24 modules -- statistics, variability, rate estimation, distance metrics, correlation, spectral, temporal, stimulus, LFP coupling, surrogates, information theory, causality, dimensionality reduction, decoding, network, point process, sorting quality, waveform, statistics, patterns, SPADE, GPFA, and explainability. Pure NumPy, zero external dependencies.

Python
from sc_neurocore.analysis import (
    firing_rate, cv_isi, fano_factor, cross_correlation,
    victor_purpura_distance, phase_locking_value, gpfa, spade_detect,
)

See the Spike Train Analysis tutorial and API reference for the full 126-function listing.

Network Simulation

Build multi-population networks with the Population-Projection-Network engine:

Python
from sc_neurocore.network import Population, Projection, Network

exc = Population("Izhikevich", 800)
inh = Population("Izhikevich", 200)
net = Network()
net.add_population(exc)
net.add_population(inh)
net.add_projection(Projection(exc, inh, probability=0.1, weight=5.0))
net.add_projection(Projection(inh, exc, probability=0.1, weight=-4.0))
net.run(duration_ms=1000, dt=0.1)

Three backends: Python (NumPy), Rust (NetworkRunner with 81 models, Rayon parallel), and MPI (billion-neuron distributed via mpi4py).

Loading Pre-Trained Models

The model zoo provides 10 ready-to-run network configurations and 3 pre-trained weight sets:

Python
from sc_neurocore.model_zoo.configs import brunel_balanced_network, mnist_classifier

# Pre-configured Brunel balanced network
net = brunel_balanced_network()

# MNIST digit classifier with pre-trained weights
classifier = mnist_classifier()

Available weight sets: MNIST (784-128-10), SHD speech (700-256-20), DVS gesture (256-256-11).

MPI Distributed Simulation

For billion-neuron scale runs across multiple nodes:

Bash
pip install sc-neurocore[mpi]
mpirun -np 4 python my_large_network.py
Python
from sc_neurocore.network import Network

net = Network(backend="mpi")
# Populations are automatically distributed across MPI ranks

What's Next?