Skip to main content

BrainTrace

Eligibility Trace-based Online Learning for Brain Dynamics

Header image of braintrace.

Supported Python Version LICENSE Documentation PyPI version Continuous Integration Code Coverage

braintrace provides online learning algorithms for biological neural networks. It has been integrated into our establishing brain modeling ecosystem.

Installation

braintrace requires Python 3.11 or newer and supports Linux, macOS, and Windows. You can install braintrace via pip:

pip install braintrace --upgrade

Alternatively, you can install BrainX, which bundles braintrace with other compatible packages for a comprehensive brain modeling ecosystem:

pip install BrainX -U

Quickstart

Mark the trainable operations with an ETP primitive (here, via braintrace.nn layers, which use them internally), then compile the model into a learner and drive a sequence. There is no scan to write and no special parameter class — weights stay plain brainstate.ParamState.

import brainstate
import jax.numpy as jnp
import braintrace

class GRUNet(brainstate.nn.Module):
    def __init__(self, n_in, n_rec, n_out):
        super().__init__()
        self.rnn = braintrace.nn.GRUCell(n_in, n_rec)
        self.out = braintrace.nn.Linear(n_rec, n_out)

    def update(self, x):
        return self.out(self.rnn(x))

model = GRUNet(3, 8, 1)

# One call: initialise states, compile the eligibility-trace graph,
# return a ready learner.
learner = braintrace.compile(model, braintrace.D_RTRL, jnp.zeros((1, 3)), batch_size=1)

def step_loss(x, y):
    return jnp.mean((learner(x) - y) ** 2)

xs = brainstate.random.randn(100, 1, 3)   # (time, batch, features)
ys = brainstate.random.randn(100, 1, 1)

# Drives the sequence and accumulates online gradients -- O(1) memory in T.
grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True)

Swap braintrace.D_RTRL for pp_prop, SnAp, UORO, ThreeFactor, DNI, EProp, the OSTL variants, or an explicit braintrace.ETraceConfig to change the learning rule; nothing else in the snippet changes.

Documentation

The official documentation is hosted on Read the Docs: https://brainx.chaobrain.com/braintrace

Citation

If you use this package in your research, please cite:

@Article{Wang2026,
  author={Wang, Chaoming
          and Dong, Xingsi
          and Ji, Zilong
          and Xiao, Mingqing
          and Jiang, Jiedong
          and Liu, Xiao
          and Huan, Yuxiang
          and Wu, Si},
  title={Model-agnostic linear-memory online learning in spiking neural networks},
  journal={Nature Communications},
  year={2026},
  month={Jan},
  day={19},
  abstract={Spiking neural networks (SNNs) offer a promising paradigm for modeling brain dynamics and developing neuromorphic intelligence, yet an online learning system capable of training rich spiking dynamics over long horizons with low memory footprints has been missing. Existing online approaches either incur quadratic memory growth, sacrifice biological fidelity through oversimplified models, or lack end-to-end automated tooling. Here, we introduce BrainTrace, a model-agnostic, linear-memory, and automated online learning system for spiking neural networks. BrainTrace standardizes model specification to encompass diverse neuronal and synaptic dynamics; implements a linear-memory online learning rule by exploiting intrinsic properties of spiking dynamics; and provides a compiler that automatically generates optimized online-learning code for arbitrary user-defined models. Across diverse dynamics and tasks, BrainTrace achieves strong learning performance with a low memory footprint and high computational throughput. Critically, these properties enable online fitting of a whole-brain-scale Drosophila SNN that recapitulates region-level functional activity. By reconciling generality, efficiency, and usability, BrainTrace establishes a foundation for spiking network modeling at scale.},
  issn={2041-1723},
  doi={10.1038/s41467-026-68453-w},
  url={https://doi.org/10.1038/s41467-026-68453-w},
  publisher={Nature Publishing Group UK London}
}

See also the ecosystem

braintrace is one part of our brain simulation ecosystem: https://brainx.chaobrain.com/

Metadata

Release files for braintrace 0.2.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for braintrace 0.2.8
File Size Uploaded Provenance Actions
braintrace-0.2.8.tar.gz 727.6 kB Without provenance Details for braintrace-0.2.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for braintrace 0.2.8
File Interpreter ABI Platform Actions
braintrace-0.2.8-py3-none-any.whl Python 3 none any Details for braintrace-0.2.8-py3-none-any.whl

Total release size: 1.1 MB

Release files / braintrace-0.2.8.tar.gz

Download URL braintrace-0.2.8.tar.gz
Size 727.6 kB
Tags Source
SHA-256 checksum
How to use checksums
57c00c3be34c2dca515c77cb585fd77a4ecf07373a38d6280b594b317b405d9c
BLAKE2b-256 checksum
How to use checksums
4e10114678097d2e02f8a0edc08a68c2b1c04eb91a84f2f6038821d662a34688
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / braintrace-0.2.8-py3-none-any.whl

Download URL braintrace-0.2.8-py3-none-any.whl
Size 397.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d16d52460979626bc5822d965d61104921c2ca5c267f422d5e33835ed2781d40
BLAKE2b-256 checksum
How to use checksums
ffe6466f0218dfdaf35080746b1aa6f22ee93d8a81c41c6848d11d4dc492c568
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for braintrace 0.2.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page