Btorch
English | 简体中文
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
- 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 💻 |
CFXTGJD 💻 |
gaozh0814 💻 |
msy79lucky 💻 |
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.