Skip to main content

Btorch

English | 简体中文

PyPI version Python versions CI Coverage Docs License Ruff

Brain-inspired differentiable PyTorch toolkit for neuromorphic and computational neuroscience research.

Use btorch if you need:

  • Recurrent SNN modelling
  • stateful neuron/synapse modules with explicit memory handling
  • practical support for sparse/connectome-style network structure
  • torch native training features (torch.compile, checkpointing, truncated BPTT)
  • solid runtime performance and ONNX export support
  • connectome import/export via SONATA, and flexible network definition coming soon

Heavily influenced by brainstate. Evolved from spikingjelly. We thank the developers of both libraries for the inspirations.

Enhancement from spikingjelly:

  • heterogenous parameters
  • enhanced check of shape and dtype of register_memory
  • torch.compile compatibility
  • gradient checkpoint and truncated BPTT
  • Sparse connectivity matrix
  • More neuron and synapse models
  • Memory state with static size and managed by torch buffer
    • onnx export is easy (note: sparse matrix is not supported by onnx)

Installation

pip/uv

Install the latest released package from PyPI:

pip install btorch

or

uv pip install btorch

conda or mamba

conda env create -n ENV_NAME -f https://github.com/Criticality-Cognitive-Computation-Lab/btorch/raw/refs/heads/main/environment.yml

Install from source control

Btorch is fast evolving. If you want the latest unreleased changes, install directly from the repository:

pip install git+https://github.com/Criticality-Cognitive-Computation-Lab/btorch.git

Gitee mirror alternative:

pip install git+https://gitee.com/alexfanqi/btorch.git

For setup instructions, see docs/installation.md.
For development workflow and contributing guidelines, see docs/development.md.

Documentation

Live docs: https://criticality-cognitive-computation-lab.github.io/btorch/

Documentation is built with Zensicle and mkdocstrings for API auto-generation from docstrings.

Build locally:

python scripts/docs.py command=build-all

The generated site is written to site/.

Preview a specific language:

python scripts/docs.py command=live language=en

If you want a clean rebuild:

rm -rf site/
python scripts/docs.py command=build-all

Skills

The skills/ directory contains usage patterns and tips for using btorch with AI agents. Install them with npx skills:

npx skills add https://github.com/Criticality-Cognitive-Computation-Lab/btorch/tree/main/skills/btorch-snn-modelling

Road Map

  • support multi-dim batch size and neuron
  • cleaner connectome import, network param management and manipulation lib
    • support full SONATA format (both BlueBrain and AIBS variants)
    • flexible like neuroarch and tiny to integrate. thinking about using DuckDB
  • verify numerical accuracy. align with Neuron and Brainstate
  • support automatic conversion between stateful and pure functions
    • similar to make_functional in torchopt
    • consider migrate to pure memory states instead of register_memory. gradient checkpointing + torch.compile struggles with mutating self
  • sparse matrix multiplication optimisation on GPU
  • large scale multi-device training and simulation
    • integrate large-scale training support with torchtitan
    • work distribution and balancing
  • compat with neurobench, Tonic
  • NIR import and export

Design and Development Principles

  • provide solid foundation of stateful Modules
  • usability over performance, simple over easy, and customizability over abstractions
    • single file/folder principle on network model
    • see Diffusers' philosophy
    • WIP to align current implementation with these principles

Contributors

alexfanqi
alexfanqi

💻
CFXTGJD
CFXTGJD

💻
gaozh0814
gaozh0814

💻
msy79lucky
msy79lucky

💻
yulaugh
yulaugh

💻

Metadata

Release files for btorch 0.1.0

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

Source distribution (sdist)

Source distribution for btorch 0.1.0
File Size Uploaded Provenance Actions
btorch-0.1.0.tar.gz 927.7 kB With provenance Details for btorch-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.2 MB

Release files / btorch-0.1.0.tar.gz

Download URL btorch-0.1.0.tar.gz
Size 927.7 kB
Tags Source
SHA-256 checksum
How to use checksums
72e55cd45999d2376dc6512dfaad2a959e637e4232a96c2f9d2f6defae9bb77c
BLAKE2b-256 checksum
How to use checksums
7c6b29e63a7a72c7072c851bd83e1ab56aadc6bcc84d52dc75a288501fbe3512
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 27, 2026.

Transparency log

Release files / btorch-0.1.0-py3-none-any.whl

Download URL btorch-0.1.0-py3-none-any.whl
Size 306.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4516cf850e835820ecd3d11d57bb66d4c8bb2a59b559f27a67eeca550e09afe4
BLAKE2b-256 checksum
How to use checksums
ed2e2cfd9c7ab954b6f552022b1ed019d609d5885f016105a4ebf360102d2471
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 27, 2026.

Transparency log

Security for btorch 0.1.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for btorch-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 27, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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