hetero

hetero simulates recurrent neural networks whose neurons are heterogeneous in their time constants, benchmarks them on a family of temporal tasks, and quantifies how much of the task performance is explained by heterogeneity.

Warning

This package is created for the research purposes only. No backward compatibility in API or documentation is guaranteed. Use with caution.

Note

If you use this package please cite the following article:

Golmohammadi, A., Luboeinski, J. & Tetzlaff, C. Robust and efficient enriched representation with intrinsic neuronal heterogeneity. Preprint at https://doi.org/10.48550/arXiv.2412.05126 (2025).

Installation

pip install -e .
pip install -e ".[docs]"    # to build these pages

See Detailed Installation for more info.

Quick start

# a 250-neuron rate network on a chaotic Lorenz input
hetero --stim lorenz --N 250 --task tayloramus --dyn LI

# a spiking network with a temporal-resolution readout
hetero --stim lorenz --N 250 --task tayloramus --dyn LIF \
       --readout_activation d10

# sweep first, plot once at the end
hetero --stim lorenz --noviz
hetero --stim lorenz --replot

Run hetero --help for the full flag list; the flags are grouped as input and output, heterogeneity, network, dynamics, stimulation, task, readout, optimization, dataset, and uncertainty quantification. Every flag defaults to the matching key of hetero.config.CFG.

How a run is put together

Everything is driven from a single command line entry point, hetero (hetero.cli.main()), which builds a parameter tree from the defaults in hetero.config.CFG and hands it to hetero.sim.Simulation.

  1. Stimulus – hetero.stimulus dispatches the --stim label to one of the generators in hetero.stims.processes, hetero.stims.maps or hetero.stims.elementary, and concatenates the requested timeseries into the input u.

  2. Network – hetero.networks samples the sparse topology and the excitatory/inhibitory weights.

  3. Heterogeneity – hetero.utils.sample_taus() draws one neuronal time constant per neuron; hetero.utils.make_net_ids() enumerates the (n, h) grid of mean-timescale levels n and heterogeneity levels h that the run sweeps.

  4. Task – hetero.tasks defines Taylor (Taylor expansion of the input), Nostradamus (a shifted version of it) and Tayloramus (both at once), each flattened into (dim, delta, deg) subtasks.

  5. Dynamics – hetero.dynamics.li integrates rate networks with scipy, hetero.dynamics.lif integrates spiking networks with brian2.

  6. Readout and score – hetero.fitting.Decoder fits a linear readout on the train split and scores it on the held-out split, over several trials and network realizations for uncertainty estimates.

  7. Figures – hetero.viz renders the connectivity, the time-constant distribution, the u/v/x traces, the score maps, and the angle/effective-rank summaries.

Contents

Detailed installation

Command line

API

Demo

Reproduction

Indices