Skip to main content

BrainUnit

Physical units and unit-aware math system for general-purpose brain dynamics modeling

Header image of brainunit.

Supported Python Version LICENSE Documentation Status PyPI version PyPI Downloads

BrainUnit provides physical units and unit-aware mathematical system in JAX for brain dynamics modeling. It introduces rigoirous physical units into high-performance AI-driven abstract numerical computing.

BrainUnit is initially designed to enable unit-aware computations in brain dynamics modeling (see our BDP ecosystem). However, its features and capacities can be applied to general domains in scientific computing and AI4Science. Starting in 2025/02, BrainUnit has been fully integrated into SAIUnit (the Unit system for Scientific AI).

Functionalities are the same for both brainunit and saiunit, and their functions and data structures are interoperable, sharing the same set of APIs, and eliminating any potential conflicts. This meas that

import brainunit as u

equals to

import saiunit as u

For users primarily engaged in general scientific computing, saiunit is likely the preferred choice. However, for those focused on brain modeling, we recommend brainunit, as it is more closely aligned with our specialized brain dynamics programming ecosystem.

Documentation

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

Features

brainunit can be seamlessly integrated into every aspect of our brain modeling ecosystem, such as, the checkpointing of braintools, the event-driven operators in brainevent, the state-based JIT compilation in brainstate, online learning rules in brainscale, or event more.

A quick example for this kind of integration:

import braintools
import brainevent
import brainstate
import brainunit as u


class EINet(brainstate.nn.Module):
    def __init__(self):
        super().__init__()
        self.n_exc = 3200
        self.n_inh = 800
        self.num = self.n_exc + self.n_inh
        self.N = brainstate.nn.LIFRef(
            self.num, V_rest=-60. * u.mV, V_th=-50. * u.mV, V_reset=-60. * u.mV,
            tau=20. * u.ms, tau_ref=5. * u.ms,
            V_initializer=brainstate.init.Normal(-55., 2., unit=u.mV)
        )
        self.E = brainstate.nn.AlignPostProj(
            comm=brainstate.nn.EventFixedProb(self.n_exc, self.num, 0.02, 0.6 * u.mS),
            syn=brainstate.nn.Expon.desc(self.num, tau=5. * u.ms),
            out=brainstate.nn.COBA.desc(E=0. * u.mV),
            post=self.N
        )
        self.I = brainstate.nn.AlignPostProj(
            comm=brainstate.nn.EventFixedProb(self.n_inh, self.num, 0.02, 6.7 * u.mS),
            syn=brainstate.nn.Expon.desc(self.num, tau=10. * u.ms),
            out=brainstate.nn.COBA.desc(E=-80. * u.mV),
            post=self.N
        )

    def update(self, t, inp):
        with brainstate.environ.context(t=t):
            spk = self.N.get_spike() != 0.
            self.E(spk[:self.n_exc])
            self.I(spk[self.n_exc:])
            self.N(inp)
            return self.N.get_spike()
    
    def save_checkpoint(self):
        braintools.file.msgpack_save('states.msgpack', self.states())
    

Installation

You can install brainunit via pip:

pip install brainunit --upgrade

Citation

If you use brainunit in your research, please consider citing the following paper:

@article{wang2025integrating,
  title={Integrating physical units into high-performance AI-driven scientific computing},
  author={Wang, Chaoming and He, Sichao and Luo, Shouwei and Huan, Yuxiang and Wu, Si},
  journal={Nature Communications},
  volume={16},
  number={1},
  pages={3609},
  year={2025},
  publisher={Nature Publishing Group UK London},
  url={https://doi.org/10.1038/s41467-025-58626-4}
}

See also the ecosystem

brainunit is one part of our brain modeling ecosystem.

Metadata

Release files for brainunit 0.6.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 brainunit 0.6.0
File Size Uploaded Provenance Actions
brainunit-0.6.0.tar.gz 12.0 kB Without provenance Details for brainunit-0.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 49.0 kB

Release files / brainunit-0.6.0.tar.gz

Download URL brainunit-0.6.0.tar.gz
Size 12.0 kB
Tags Source
SHA-256 checksum
How to use checksums
870d200c1255d2fe34003956f0e52cdaad407f6f05dfe7c2ad80df3f82ddad84
BLAKE2b-256 checksum
How to use checksums
d4adcafd8b06a249eddf8461dbfdf951caf1ec2bf62b49f5d21bc69cfb9e59ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / brainunit-0.6.0-py3-none-any.whl

Download URL brainunit-0.6.0-py3-none-any.whl
Size 37.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8817ff6aa878ac9af7bc2f46e613323298fdd654705c87e78d3c40ba4d8ac543
BLAKE2b-256 checksum
How to use checksums
36ee06dfe779153fd82ba404835b0725538eb24f8b2d5ba1721d6ffefe89409d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for brainunit 0.6.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.

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.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files No 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