Metadata-Version: 2.1
Name: brainevent
Version: 0.0.1.post20250506
Summary: Event-driven Computation in JAX for Brain Dynamics.
Home-page: https://github.com/chaobrain/brainevent
Author: BrainEvent Developers
Author-email: BrainEvent Developers <chao.brain@qq.com>
License: Apache-2.0 license
Project-URL: homepage, http://github.com/chaobrain/brainevent
Project-URL: repository, http://github.com/chaobrain/brainevent
Keywords: computational neuroscience,brain-inspired computation,brain dynamics programming
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: brainunit (>=0.0.8)
Provides-Extra: cpu
Requires-Dist: jax ; extra == 'cpu'
Requires-Dist: absl-py ; extra == 'cpu'
Provides-Extra: cuda12
Requires-Dist: jax[cuda12] ; extra == 'cuda12'
Requires-Dist: absl-py ; extra == 'cuda12'
Provides-Extra: testing
Requires-Dist: pytest ; extra == 'testing'
Provides-Extra: tpu
Requires-Dist: jax[tpu] ; extra == 'tpu'
Requires-Dist: absl-py ; extra == 'tpu'

# Enabling Event-driven Computation in Brain Dynamics

[//]: # (<p align="center">)

[//]: # (  	<img alt="Header image of brainevent." src="https://github.com/chaobrain/brainevent/blob/main/docs/_static/brainevent.png" width=50%>)

[//]: # (</p> )



<p align="center">
	<a href="https://pypi.org/project/brainevent/"><img alt="Supported Python Version" src="https://img.shields.io/pypi/pyversions/brainevent"></a>
	<a href="https://github.com/chaobrain/brainevent/blob/main/LICENSE"><img alt="LICENSE" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a>
  	<a href='https://brainevent.readthedocs.io/en/latest/?badge=latest'>
        <img src='https://readthedocs.org/projects/brainevent/badge/?version=latest' alt='Documentation Status' />
    </a>
    <a href="https://badge.fury.io/py/brainevent"><img alt="PyPI version" src="https://badge.fury.io/py/brainevent.svg"></a>
    <a href="https://github.com/chaobrain/brainevent/actions/workflows/CI.yml"><img alt="Continuous Integration" src="https://github.com/chaobrain/brainevent/actions/workflows/CI.yml/badge.svg"></a>
    <a href="https://pepy.tech/projects/brainevent"><img src="https://static.pepy.tech/badge/brainevent" alt="PyPI Downloads"></a>
    <a href="https://doi.org/10.5281/zenodo.15324450"><img src="https://zenodo.org/badge/921610544.svg" alt="DOI"></a>
</p>




Brain is characterized by the discrete spiking events, which are the fundamental units of computation in the brain.

`BrainEvent` provides a set of data structures and algorithms for such event-driven computation on
**CPUs**, **GPUs**, **TPUs**, and maybe more, which can be used to model the brain dynamics in an
efficient and biologically plausible way.

Particularly, it provides the following class to represent binary events in the brain:

- ``EventArray``: representing array with a vector/matrix of events.

Furthermore, it implements the following commonly used data structures for event-driven computation
of the above class:

- ``COO``: a sparse matrix in COO format for sparse and event-driven computation.
- ``CSR``: a sparse matrix in CSR format for sparse and event-driven computation.
- ``CSC``: a sparse matrix in CSC format for sparse and event-driven computation.
- ``JITCHomoR``: a just-in-time connectivity matrix with homogenous weight for sparse and event-driven computation.
- ``JITCNormalR``: a just-in-time connectivity matrix with normal distribution weight for sparse and event-driven
  computation.
- ``JITCUniformR``: a just-in-time connectivity matrix with uniform distribution weight for sparse and event-driven
  computation.
- ``FixedPreNumConn``: a fixed number of pre-synaptic connections for sparse and event-driven computation.
- ``FixedPostNumConn``: a fixed number of post-synaptic connections for sparse and event-driven computation.
- ...

`BrainEvent` is fully compatible with physical units and unit-aware computations provided
in [BrainUnit](https://github.com/chaobrain/brainunit).

## Usage

If you want to take advantage of event-driven computations, you must warp your data with ``brainevent.EventArray``:

```python
import brainevent

# wrap your array with EventArray
event_array = brainevent.EventArray(your_array)
```

Then, the matrix multiplication with the following data structures, $\mathrm{event\ array} @ \mathrm{data}$,
will take advantage of event-driven computations:

- Sparse data structures provided by ``brainevent``, like:
    - ``brainevent.CSR``
    - ``brainevent.JITCHomoR``
    - ``brainevent.FixedPostNumConn``
    - ...
- Dense data structures provided by JAX/NumPy, like:
    - ``jax.numpy.ndarray``
    - ``numpy.ndarray``


```python
data = jax.random.rand(...)  # normal dense array
data = brainevent.CSR(...)  # CSR structure
data = brainevent.JITCHomoR(...)  # JIT connectivity
data = brainevent.FixedPostNumConn(...)  # fixed number of post-synaptic connections

# event-driven matrix multiplication
r = event_array @ data
r = data @ event_array
```

## Installation

You can install ``brainevent`` via pip:

```bash
pip install brainevent -U
```

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

```bash
pip install BrainX -U
```


## Documentation

The official documentation is hosted on Read the Docs: [https://brainevent.readthedocs.io/](https://brainevent.readthedocs.io/)


## See also the brain modeling ecosystem

We are building the brain modeling ecosystem: https://brainmodeling.readthedocs.io/

