Crate ferromorphic

Expand description

§ferromorphic — neuromorphic computing for Physical AI

The IPAI @ BMI neuromorphic stack, in pure Rust: spiking neuron models checked against their closed forms, sparse event-driven networks with per-synapse delays, spike encoders that state what they cost, and — first-class, not an appendix — an energy ledger that charges for the memory traffic a synaptic operation needs and refuses to report a figure when the device’s prices are unstated.

The neuroscience is old and open: Lapicque’s integrate-and-fire (1907), Hodgkin and Huxley (1952), Mahowald’s address-event representation (1992), Mead’s Neuromorphic Electronic Systems (1990), Izhikevich (2003), spike-timing-dependent plasticity (Bi and Poo, 1998). What a neuromorphic chip accelerates is exactly these loops; what it charges for is moving the weights. Both belong in the open commons, runnable on every compute fabric — CPU today, GPU and wasm in the browser, event-driven silicon where there is silicon anyone can get.

§The position this crate takes

A synaptic operation count is not an energy measurement. The standard figure in this field is a SOP count multiplied by a datasheet joule-per-SOP. That prices the arithmetic and sets the cost of fetching the weight to zero — and the fetch is the term that scales with where the model lives rather than with how often it fires, so it is exactly the term that separates a benchmark from a deployment. This Institute has made the analogous mistake before, in a different crate, where omitting attention’s score matrix made a published arithmetic-intensity figure wrong by 847x while looking entirely reasonable.

So ledger::Prices carries e_syn_fetch, every device table in this crate leaves it None, and ledger::Ledger::joules therefore refuses. That is the finding, not an unfinished implementation: this review did not locate a published per-synapse memory-fetch energy for any commercially available neuromorphic processor. The flattering number the literature reports is still computable, as ledger::Ledger::joules_synops_only, with its doc saying what it omits.

And the field already published the threshold that decides it. The quantity that says whether a spiking network can beat its dense equivalent is spikes per synapse per inference, and at least six papers give a number for it — every one of them below 2, several below 1. Davidson and Furber (Frontiers in Neuroscience 15:651141, 2021) derive ~1.72 and conclude that “most rate-coded spiking network implementations will not be more energy or resource efficient than the original ANN”; Steve Furber designed SpiNNaker, so this is the field auditing itself. This review located that argument in the literature and did not locate it implemented as a check in any spiking-network library, which is odd for a number that decides whether the whole approach helps. crossover makes it a check: the left-hand side is a ratio of two integer counts the simulator already keeps, so it costs nothing to run on every workload.

An event-driven claim is a measurement, not an adjective. sim::Mode::Clocked and sim::Mode::EventDriven run the same network and are required to produce the same spike train; the difference between them is ledger::Ledger::idle_fraction, a number. And an event-driven simulation is only legal for a model that can be jumped across quiet ticks, which is neuron::Neuron::EXACT_OVER_GAPS — declared per model and enforced by sim::Sim::new refusing to build rather than by a warning nobody reads.

§Quickstart

use ferromorphic::{
    ledger::TRUENORTH_2014,
    net::NetBuilder,
    neuron::Lif,
    sim::{Mode, Sim},
};

// A five-neuron chain: each cell drives the next after 2 ticks.
let mut b = NetBuilder::new(5);
for i in 0..4 {
    b.connect(i, i + 1, 20e-3, 2)?;
}
let net = b.build();

// Drive the first cell with 3 nA and run for 200 ms at 0.1 ms per tick.
let mut ext = vec![0.0; 5];
ext[0] = 3e-9;
let mut sim = Sim::new(net, vec![Lif::default(); 5], 1e-4, Mode::EventDriven)?;
let train = sim.run(2_000, &ext);
assert!(!train.is_empty());

// What it would cost on TrueNorth — and the answer is a refusal, with the reason.
let bill = sim.ledger.bill(&TRUENORTH_2014);
assert!(bill.total.is_none());
assert!(bill.unpriced.contains(&"synapse memory fetch"));
// The synaptic term alone still prices, so the refusal is informative rather than blank.
assert!(bill.synaptic.unwrap() > 0.0);

§Zero dependencies, and that is a feature

[dependencies] is empty and stays empty. It is what lets this crate be audited end to end by one person, compile to wasm32-unknown-unknown without a toolchain argument, and still build in ten years. Anything needing a dependency — a GPU driver, a power sensor, an FPGA toolchain — is a sibling crate you opt into, and deleting every sibling leaves this one intact.

§Determinism

Same seed, same spikes, every platform. rng is the only source of randomness in the crate and it takes a seed; nothing here reads a clock or the operating system’s entropy. A spike train that cannot be reproduced cannot be checked against anything, including itself.

Re-exports§

pub use crossover::Crossover;
pub use crossover::Verdict;
pub use ledger::Bill;
pub use ledger::Evidence;
pub use ledger::Ledger;
pub use ledger::Prices;
pub use net::Net;
pub use net::NetBuilder;
pub use net::NetError;
pub use neuron::AdaptiveLif;
pub use neuron::IntegrateAndFire;
pub use neuron::Izhikevich;
pub use neuron::Lif;
pub use neuron::Neuron;
pub use rng::Rng;
pub use sim::Mode;
pub use sim::Sim;
pub use sim::SimError;
pub use spike::Event;
pub use spike::Polarity;
pub use spike::Spike;
pub use spike::Train;

Modules§

aer: Address-event representation: the wire formats event sensors actually speak.
attention: Spiking attention and spiking transformers — and an honest count of what is actually spiking.
attractor: The ring attractor: a bump of activity that holds a direction after the cue has gone, with a width and a height you can write down — checked against both.
bayes: Spikes as samples: a spiking network that performs Bayesian inference by firing.
cerebellum: The cerebellum as a machine: an adaptive filter that learns by decorrelating its error from its inputs, and Albus’s CMAC, the table-lookup controller that theory became — each checked against what it must converge to and how fast.
cochlea: The silicon cochlea: sound in, spikes out, with every stage checked against its closed form.
coding: The rest of the neural codes, and the decoders that invert them.
compress: Making a trained spiking network fit the part you can actually buy.
continual: Learning without forgetting: the on-chip case, with the forgetting measured first.
control: Closing a loop with spikes: controllers, central pattern generators, and the plants to check them against.
convert: ANN-to-SNN conversion: the other way of getting a trained spiking network.
crossover: The published crossover thresholds, as a check a workload can run against itself.
delays: Delays as a resource: a neuron whose synapses arrive at different times detects a PATTERN IN TIME, a learning rule that moves the delays makes it detect the pattern it is shown, and the number of patterns a set of delays can stand for is a count — each checked exactly.
dendrite: Dendrites: a neuron with more than one compartment, and what the second compartment buys — a learning rule that needs no error signal from anywhere else, and a single cell that computes what a point neuron provably cannot.
device: Analog device non-idealities: what a weight becomes when it is a physical conductance.
distance: How different are two spike trains? The Victor–Purpura edit distance, the van Rossum distance, vector strength and the Fano factor — the four numbers a spiking experiment is most often summarised by, each checked against the cases where its value is known exactly.
encode: Turning numbers into spikes, and back.
eprop: Local learning rules: training a spiking network forward in time, without storing its past.
equilibrium: Equilibrium propagation: the gradient of a loss, read off the difference between two relaxations of the same physical network — checked against the gradient it claims to be, with the order of its error measured.
exponential: Spike initiation as a nonlinearity rather than a fiat threshold: the exponential and quadratic integrate-and-fire family.
field: The Amari neural field: a sheet of neurons with local excitation and broader inhibition, which either forgets a stimulus or holds it as a bump of a width you can compute — and the width below which a bump dies is computable too. Both are checked against the simulated field.
fusion: Multimodal fusion: more than one sense, in spikes.
graph: Graph algorithms done by spikes: a shortest path is the time a wavefront takes to arrive, and a boundary-value problem is the fraction of random walkers that leave by each door — both checked against the exact answer, with the spikes counted.
grid: Grid cells: a position held as a set of phases — a hexagonal firing map, path integration that is exact in phase space, and a modular code whose range is the PRODUCT of its periods while its size is their sum. Each is checked against the arithmetic it claims.
hardware: What actually fits on the chips: the structural limits of neuromorphic parts, checkable before anyone buys a board.
hh: Hodgkin-Huxley: the action potential derived rather than imposed.
hopfield: Associative memory as an energy landscape: the classical Hopfield network, Krotov and Hopfield’s dense associative memory, and the modern continuous Hopfield network — each with its energy function, its update as a descent on that energy, and its capacity checked against the number the theory gives rather than asserted from the paper.
ledger: The joules ledger: what a spiking workload costs, and when that question has no honest answer.
localise: Sound localisation by coincidence: the Jeffress delay-line array, which turns a time difference between two ears into a PLACE — checked against the geometry, the quantisation bound, the aliasing frequency and the coincidence probability under spike jitter.
mapping: Placing a network on cores: the problem between a model and a chip, and where the energy goes.
meanfield: Mean-field theory: what a spiking network does in aggregate, in closed form.
metrics: Benchmark metrics: what NeuroBench measures, computed here from a model and a run.
nef: The Neural Engineering Framework: representing a vector in a population of spiking neurons, computing a function of it with a weight matrix, and closing the loop into a dynamical system — with the gain, the bias, the decoder and the dynamics each checked against its closed form.
net: Sparse directed connectivity in CSR, with a per-synapse delay.
neuron: Spiking neuron models, each checked against the closed form it is supposed to reproduce.
nir: NIR, the neuromorphic intermediate representation: the graph model a trained spiking network travels in, a text serialisation of it that round-trips exactly, and a bridge into this crate.
olfaction: Neuromorphic olfaction: the olfactory bulb’s external plexiform layer, learning an odour from one presentation.
optimise: Optimisation by stochastic spiking: quadratic unconstrained binary problems, the Ising-style formulations that turn max-cut and graph colouring into them, and an annealed Glauber sampler whose fixed-temperature statistics are checked against the exact Boltzmann distribution and whose answers are checked against brute force.
oscillator: Coupled phase oscillators: synchronisation with a threshold you can write down, locomotion as a travelling wave of phase lags, and combinatorial search as the relaxation of an oscillator network — each checked against its closed form.
phasor: Phasor symbols and the spike times that carry them: the complex-valued vector symbolic architecture whose elements are phases, so that a symbol is a pattern of spike timings within a rhythm and binding is adding delays — with the algebra checked exactly and the associative memory checked against its own crosstalk.
plasticity: Synaptic plasticity: the learning rules, each with the closed form it is checked against.
predictive: Predictive coding: inference as the relaxation of prediction-error neurons, learning as the product of an error and the activity next to it — checked against the Bayesian posterior it computes and against the backpropagated gradient it approximates.
proprio: Proprioception: what a muscle tells the spinal cord about its own length, speed and force, and what happens when that report comes back late — the power-law spindle, the tendon organ, an exact rate-to-spike encoder, and a reflex loop whose delay sets the gain at which it rings.
reinforce: Reinforcement learning with three factors: a presynaptic spike leaves a synaptic eligibility trace, a postsynaptic response gates it, and a broadcast reward-prediction error turns it into a weight change — temporal-difference learning done the way a chip with a global neuromodulator does it, checked against the Bellman solution of the task.
reservoir: Reservoir computing: leave the recurrent weights alone and train one linear layer.
resonance: Noise as a resource: a threshold unit cannot see a signal that never reaches its threshold — until noise is added, and then there is a BEST amount of noise, which has a closed form. A population of identical noisy units does better still, and how much better is a sum you can evaluate exactly. Each is checked against its formula and against sampling.
resonate: Oscillatory state in a neuron: the resonate-and-fire cell, and the Legendre Memory Unit that turns a linear system into a delay line — both stepped exactly and checked against the closed forms their authors derived.
rng: Deterministic pseudorandom numbers, because a spike train has to be reproducible.
sim: The simulator, in two modes that must agree.
sparse: Sparse coding in spikes: the locally competitive algorithm, its spiking form, and the optimisation problem both of them solve — checked against that problem’s own optimality conditions rather than against a previous run.
spike: Spikes and spike trains: the one representation everything else in this crate agrees on.
spikeconv: Spiking convolutional networks: the architecture almost all deployed spiking vision runs.
surrogate: Surrogate gradients: how a spiking network is trained by backpropagation at all.
synapse: Synapse models: the four kernels, the two current conventions, and short-term plasticity.
tasks: Teaching tasks: benchmark problems generated, never downloaded.
topology: Network topology: the wiring, and the measurements that say what kind of wiring it is.
touch: Touch in spikes: the three mechanoreceptor channels of the glabrous skin as spiking afferents, each driven by the feature of the contact it actually encodes, and a fingertip’s worth of them decoding where the contact is — checked against the closed forms of this crate’s own neuron.
ttfs: Learning with spike TIMES: networks in which every neuron fires at most once, the time of that spike has a closed form, and so does its gradient — exact backpropagation through spikes, with no surrogate, checked against finite differences of the spike times themselves.
vision: Event-based vision: the algorithms that consume what an event camera emits.
vsa: Vector symbolic architectures — hyperdimensional computing — with every capacity claim checked against its closed form.

Constants§

VERSION: This crate’s version, for a run that wants to record what produced it.