braintools 0.2.0__tar.gz → 0.4.0__tar.gz

{braintools-0.2.0 → braintools-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braintools
-Version: 0.2.0
+Version: 0.4.0
 Summary: Modeling tools for brain simulation.
 Author-email: BrainTools Developers <chao.brain@qq.com>
 License: 
@@ -218,26 +218,27 @@ Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: jax
 Requires-Dist: numpy>=1.15
 Requires-Dist: brainstate>=0.1.0
-Requires-Dist: brainunit>=0.0.8
+Requires-Dist: brainunit>=0.5.2
 Requires-Dist: typing_extensions
 Requires-Dist: optax
 Requires-Dist: matplotlib
 Requires-Dist: msgpack
 Requires-Dist: scipy
+Requires-Dist: brainevent
 Provides-Extra: testing
 Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
@@ -245,10 +246,35 @@ Requires-Dist: absl-py; extra == "testing"
 Requires-Dist: nevergrad; extra == "testing"
 Requires-Dist: tqdm; extra == "testing"
 Requires-Dist: rich; extra == "testing"
+Requires-Dist: pyyaml; extra == "testing"
+Requires-Dist: scikit-learn; extra == "testing"
+Requires-Dist: mne; extra == "testing"
+Requires-Dist: statsmodels; extra == "testing"
+Requires-Dist: networkx; extra == "testing"
+Requires-Dist: numba; extra == "testing"
+Requires-Dist: h5py; extra == "testing"
+Requires-Dist: pynwb; extra == "testing"
+Requires-Dist: neo; extra == "testing"
+Requires-Dist: quantities; extra == "testing"
+Provides-Extra: viz
+Requires-Dist: plotly; extra == "viz"
+Provides-Extra: progress
+Requires-Dist: tqdm; extra == "progress"
+Requires-Dist: rich; extra == "progress"
+Provides-Extra: nevergrad
+Requires-Dist: nevergrad; extra == "nevergrad"
+Provides-Extra: nwb
+Requires-Dist: pynwb; extra == "nwb"
+Provides-Extra: neo
+Requires-Dist: neo; extra == "neo"
+Requires-Dist: quantities; extra == "neo"
+Provides-Extra: hdf5
+Requires-Dist: h5py; extra == "hdf5"
 Provides-Extra: type-check
 Requires-Dist: mypy>=1.8; extra == "type-check"
 Provides-Extra: cpu
 Requires-Dist: jax[cpu]; extra == "cpu"
+Requires-Dist: brainevent[cpu]; extra == "cpu"
 Provides-Extra: cuda12
 Requires-Dist: jax[cuda12]; extra == "cuda12"
 Provides-Extra: cuda13
@@ -257,7 +283,7 @@ Provides-Extra: tpu
 Requires-Dist: jax[tpu]; extra == "tpu"
 Provides-Extra: cogtask
 Requires-Dist: brainstate>=0.1.0; extra == "cogtask"
-Requires-Dist: brainunit>=0.0.8; extra == "cogtask"
+Requires-Dist: brainunit>=0.5.2; extra == "cogtask"
 Provides-Extra: doc
 Requires-Dist: pandoc; extra == "doc"
 Requires-Dist: Jinja2; extra == "doc"
@@ -283,9 +309,6 @@ Dynamic: license-file
 <p align="center">
   <a href="https://pypi.org/project/braintools/"><img alt="Supported Python Version" src="https://img.shields.io/pypi/pyversions/braintools"></a>
   <a href="https://github.com/chaobrain/braintools/blob/main/LICENSE"><img alt="LICENSE" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a>
-  <a href='https://brainx.chaobrain.com/braintools/'>
-    <img src='https://readthedocs.org/projects/braintools/badge/?version=latest' alt='Documentation Status' />
-  </a>
   <a href="https://badge.fury.io/py/braintools"><img alt="PyPI version" src="https://badge.fury.io/py/braintools.svg"></a>
   <a href="https://github.com/chaobrain/braintools/actions/workflows/CI.yml"><img alt="Continuous Integration" src="https://github.com/chaobrain/braintools/actions/workflows/CI.yml/badge.svg"></a>
   <a href="https://codecov.io/gh/chaobrain/braintools"><img alt="Test Coverage" src="https://codecov.io/gh/chaobrain/braintools/graph/badge.svg"></a>
@@ -296,11 +319,17 @@ Dynamic: license-file
 
 ## Highlights
 
-- **Composable connectivity**: declarative builders for point, multi-compartment, and population networks with spatial kernels, degree constraints, and unit-aware metadata
-- **Cognitive task framework**: phase-based, composable trial construction (`braintools.cogtask`) for training and analyzing neural networks on classic systems-neuroscience paradigms — decision making, working memory, reasoning, motor — plus a registry of pre-built tasks
-- **Visualization suite**: publication plots, interactive dashboards, 3D viewers, and animation helpers in `braintools.visualize`
-- **Metrics and solvers**: losses, evaluation metrics, and PyTree-aware ODE/SDE/DDE integrators ready for `jit`/`vmap`
-- **Signal and optimization helpers**: reusable generators and lightweight optimizers to prototype models quickly
+- **Connectivity builders** (`braintools.conn`): declarative, unit-aware patterns for point neurons (random, fixed in-/out-degree, distance-dependent, small-world, modular, ...), multi-compartment morphologies, and convolution kernels; population networks assembled from populations and projections; vectorised, memory-bounded generation that scales to 1e5-neuron networks; export to `brainevent` sparse formats
+- **Initializers** (`braintools.init`): parameter initializers (distributions, variance scaling, orthogonal, composites) and distance profiles shared with the connectivity builders
+- **Spike data** (`braintools.spike`): the `SpikeTrains` container (a padded, `jit`/`vmap`-friendly spike-time layout with dense/event conversions), spike encoders (latency, rate, Poisson, population, ...), and bitwise spike operations
+- **Neural data analysis** (`braintools.analysis`): spike-train statistics (ISI/CV/Fano, PSTHs, correlograms, spike-train distances, synchrony), spectral and LFP analysis (multitaper and wavelet spectra, filtering, phase synchrony, cross-frequency coupling, current source density), population analysis (PCA, decoding, Granger causality, avalanches, functional connectivity), structural graph measures of connectivity, and resampling-based statistics
+- **Cognitive task framework** (`braintools.cogtask`): phase-based, composable trial construction for training and analyzing networks on classic systems-neuroscience paradigms, plus a registry of pre-built tasks
+- **Numerical integration** (`braintools.quad`): PyTree-aware ODE/SDE/DDE/IMEX one-step integrators ready for `jit`/`vmap`, a fixed-step trajectory driver (`odeint`) and a differentiable adaptive solver (`solve_ivp`)
+- **Model fitting** (`braintools.fit`): fit any JAX or `brainstate` model to data with composable objectives, summary-statistic losses, vmapped multi-start optimization, parameter sweeps, and confidence intervals
+- **Losses and metrics** (`braintools.metric`): classification, regression, ranking, and pairwise-similarity losses for training
+- **Inputs, surrogates, and visualization**: input-current generators (`braintools.input`), surrogate gradients (`braintools.surrogate`), and plotting helpers (`braintools.visualize`)
+- **Training helpers**: optimizer wrappers (`braintools.optim`), a multi-start minimizer, online readout learning (RLS, LMS, FORCE), closed-form regressions, and a lightweight training loop (`braintools.trainer`)
+- **Data files** (`braintools.file`): checkpoints, MATLAB files, and optional HDF5, NWB, and NEO formats
 
 `braintools` integrates smoothly with the broader ecosystem (e.g., `brainstate`, `brainunit`) while keeping a simple, functional style.
 
@@ -310,16 +339,25 @@ Dynamic: license-file
 pip install -U braintools
 ```
 
-Optional extras are published for hardware-specific builds:
+Optional extras select a JAX backend:
 
 ```bash
 pip install -U braintools[cpu]
-# CUDA 12.x wheels
+# CUDA 12.x / CUDA 13.x wheels
 pip install -U braintools[cuda12]
+pip install -U braintools[cuda13]
 # TPU runtime
 pip install -U braintools[tpu]
 ```
 
+and enable optional features:
+
+```bash
+pip install -U braintools[viz]        # interactive plotly figures in braintools.visualize
+pip install -U braintools[progress]   # tqdm / rich progress bars in braintools.trainer
+pip install -U braintools[nevergrad]  # gradient-free optimization in braintools.optim
+```
+
 Alternatively, install the curated BrainX bundle that ships with `braintools` and related projects:
 
 ```bash
@@ -338,9 +376,14 @@ pip install -U BrainX
 Trials are generated lazily via `task.sample(i)` / `task.batch_sample(B)`, both JIT- and `vmap`-friendly, with per-trial keys derived from `seed` so batches are fully reproducible.
 
 ```python
+import brainstate
 import brainunit as u
 from braintools.cogtask import PerceptualDecisionMaking
 
+# Phase durations are expressed in units of the environment timestep, so a
+# timestep must be set before a task is sampled.
+brainstate.environ.set(dt=1.0 * u.ms)
+
 task = PerceptualDecisionMaking(t_stimulus=1500 * u.ms, num_choices=2, seed=0)
 X, Y = task.batch_sample(32)   # X: (T, B, n_in), Y: (T, B) labels
 ```
@@ -351,6 +394,10 @@ The package also ships a registry of canonical tasks: `PerceptualDecisionMaking`
 
 The full documentation is available at https://brainx.chaobrain.com/braintools/
 
+## Upgrading to 1.0
+
+Names that moved since 0.4 (for example the `metric` analysis functions, now in `braintools.analysis`, and the top-level spike encoders, now in `braintools.spike`) still work but emit a `BraintoolsDeprecationWarning`, a `FutureWarning` shown by default. Version 1.0 removes them. The [migration guide](https://brainx.chaobrain.com/braintools/migration.html) lists every deprecated name with its replacement.
+
 ## Ecosystem
 
 `braintools` is one part of our brain simulation ecosystem: https://brainx.chaobrain.com/

braintools-0.4.0/README.md

@@ -0,0 +1,113 @@
+# Modeling tools for brain simulation
+
+<p align="center">
+  <img alt="Header image of braintools." src="https://brainx.chaobrain.com/images/braintools.webp" width=50%>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/braintools/"><img alt="Supported Python Version" src="https://img.shields.io/pypi/pyversions/braintools"></a>
+  <a href="https://github.com/chaobrain/braintools/blob/main/LICENSE"><img alt="LICENSE" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a>
+  <a href="https://badge.fury.io/py/braintools"><img alt="PyPI version" src="https://badge.fury.io/py/braintools.svg"></a>
+  <a href="https://github.com/chaobrain/braintools/actions/workflows/CI.yml"><img alt="Continuous Integration" src="https://github.com/chaobrain/braintools/actions/workflows/CI.yml/badge.svg"></a>
+  <a href="https://codecov.io/gh/chaobrain/braintools"><img alt="Test Coverage" src="https://codecov.io/gh/chaobrain/braintools/graph/badge.svg"></a>
+  <a href="https://doi.org/10.5281/zenodo.17110064"><img src="https://zenodo.org/badge/776629792.svg" alt="DOI"></a>
+</p>
+
+`braintools` is a lightweight, JAX-friendly toolbox with practical utilities for brain modeling.
+
+## Highlights
+
+- **Connectivity builders** (`braintools.conn`): declarative, unit-aware patterns for point neurons (random, fixed in-/out-degree, distance-dependent, small-world, modular, ...), multi-compartment morphologies, and convolution kernels; population networks assembled from populations and projections; vectorised, memory-bounded generation that scales to 1e5-neuron networks; export to `brainevent` sparse formats
+- **Initializers** (`braintools.init`): parameter initializers (distributions, variance scaling, orthogonal, composites) and distance profiles shared with the connectivity builders
+- **Spike data** (`braintools.spike`): the `SpikeTrains` container (a padded, `jit`/`vmap`-friendly spike-time layout with dense/event conversions), spike encoders (latency, rate, Poisson, population, ...), and bitwise spike operations
+- **Neural data analysis** (`braintools.analysis`): spike-train statistics (ISI/CV/Fano, PSTHs, correlograms, spike-train distances, synchrony), spectral and LFP analysis (multitaper and wavelet spectra, filtering, phase synchrony, cross-frequency coupling, current source density), population analysis (PCA, decoding, Granger causality, avalanches, functional connectivity), structural graph measures of connectivity, and resampling-based statistics
+- **Cognitive task framework** (`braintools.cogtask`): phase-based, composable trial construction for training and analyzing networks on classic systems-neuroscience paradigms, plus a registry of pre-built tasks
+- **Numerical integration** (`braintools.quad`): PyTree-aware ODE/SDE/DDE/IMEX one-step integrators ready for `jit`/`vmap`, a fixed-step trajectory driver (`odeint`) and a differentiable adaptive solver (`solve_ivp`)
+- **Model fitting** (`braintools.fit`): fit any JAX or `brainstate` model to data with composable objectives, summary-statistic losses, vmapped multi-start optimization, parameter sweeps, and confidence intervals
+- **Losses and metrics** (`braintools.metric`): classification, regression, ranking, and pairwise-similarity losses for training
+- **Inputs, surrogates, and visualization**: input-current generators (`braintools.input`), surrogate gradients (`braintools.surrogate`), and plotting helpers (`braintools.visualize`)
+- **Training helpers**: optimizer wrappers (`braintools.optim`), a multi-start minimizer, online readout learning (RLS, LMS, FORCE), closed-form regressions, and a lightweight training loop (`braintools.trainer`)
+- **Data files** (`braintools.file`): checkpoints, MATLAB files, and optional HDF5, NWB, and NEO formats
+
+`braintools` integrates smoothly with the broader ecosystem (e.g., `brainstate`, `brainunit`) while keeping a simple, functional style.
+
+## Installation
+
+```bash
+pip install -U braintools
+```
+
+Optional extras select a JAX backend:
+
+```bash
+pip install -U braintools[cpu]
+# CUDA 12.x / CUDA 13.x wheels
+pip install -U braintools[cuda12]
+pip install -U braintools[cuda13]
+# TPU runtime
+pip install -U braintools[tpu]
+```
+
+and enable optional features:
+
+```bash
+pip install -U braintools[viz]        # interactive plotly figures in braintools.visualize
+pip install -U braintools[progress]   # tqdm / rich progress bars in braintools.trainer
+pip install -U braintools[nevergrad]  # gradient-free optimization in braintools.optim
+```
+
+Alternatively, install the curated BrainX bundle that ships with `braintools` and related projects:
+
+```bash
+pip install -U BrainX
+```
+
+## Cognitive task framework (`braintools.cogtask`)
+
+`braintools.cogtask` lets you build cognitive tasks from composable, named **phases** (fixation, stimulus, delay, response, ...) connected by simple operators:
+
+- `a >> b` runs `b` after `a` (sequential)
+- `a * n` repeats `a` `n` times
+- `a | b` runs `a` and `b` in parallel (multi-modal stimuli)
+- `If`, `Switch`, `While` add trial-by-trial branching
+
+Trials are generated lazily via `task.sample(i)` / `task.batch_sample(B)`, both JIT- and `vmap`-friendly, with per-trial keys derived from `seed` so batches are fully reproducible.
+
+```python
+import brainstate
+import brainunit as u
+from braintools.cogtask import PerceptualDecisionMaking
+
+# Phase durations are expressed in units of the environment timestep, so a
+# timestep must be set before a task is sampled.
+brainstate.environ.set(dt=1.0 * u.ms)
+
+task = PerceptualDecisionMaking(t_stimulus=1500 * u.ms, num_choices=2, seed=0)
+X, Y = task.batch_sample(32)   # X: (T, B, n_in), Y: (T, B) labels
+```
+
+The package also ships a registry of canonical tasks: `PerceptualDecisionMaking`, `ContextDecisionMaking`, `DelayMatchSample`, `DelayComparison`, `GoNoGo`, `ReadySetGo`, `PostDecisionWager`, `Reaching1D`, `EvidenceAccumulation`, `HierarchicalReasoning`, and more — see the [API reference](https://brainx.chaobrain.com/braintools/apis/cogtask.html) for the full list.
+
+## Documentation
+
+The full documentation is available at https://brainx.chaobrain.com/braintools/
+
+## Upgrading to 1.0
+
+Names that moved since 0.4 (for example the `metric` analysis functions, now in `braintools.analysis`, and the top-level spike encoders, now in `braintools.spike`) still work but emit a `BraintoolsDeprecationWarning`, a `FutureWarning` shown by default. Version 1.0 removes them. The [migration guide](https://brainx.chaobrain.com/braintools/migration.html) lists every deprecated name with its replacement.
+
+## Ecosystem
+
+`braintools` is one part of our brain simulation ecosystem: https://brainx.chaobrain.com/
+
+## Contributing
+
+Contributions and issue reports are welcome! See `CONTRIBUTING.md` for guidelines.
+
+## License
+
+Apache 2.0. See `LICENSE` for details.
+
+## Citation
+
+If you use `braintools` in your work, please cite the Zenodo DOI: [10.5281/zenodo.17110064](https://doi.org/10.5281/zenodo.17110064)

braintools-0.4.0/braintools/__init__.py

@@ -0,0 +1,106 @@
+# Copyright 2024 BrainX Ecosystem Limited. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+
+from . import analysis
+from . import cogtask
+from . import conn
+from . import file
+from . import fit
+from . import init
+from . import input
+from . import metric
+from . import optim
+from . import quad
+from . import spike
+from . import surrogate
+from . import trainer
+from . import tree
+from . import visualize
+from ._deprecation import deprecated_class as _deprecated_class
+from ._version import __version__, __version_info__
+
+# Encoders moved to ``braintools.spike`` in 0.4.0. The top-level names are
+# deprecated aliases that warn on instantiation (never on import/access).
+LatencyEncoder = _deprecated_class(
+    spike.LatencyEncoder, 'braintools.LatencyEncoder', 'braintools.spike.LatencyEncoder')
+RateEncoder = _deprecated_class(
+    spike.RateEncoder, 'braintools.RateEncoder', 'braintools.spike.RateEncoder')
+PoissonEncoder = _deprecated_class(
+    spike.PoissonEncoder, 'braintools.PoissonEncoder', 'braintools.spike.PoissonEncoder')
+PopulationEncoder = _deprecated_class(
+    spike.PopulationEncoder, 'braintools.PopulationEncoder', 'braintools.spike.PopulationEncoder')
+BernoulliEncoder = _deprecated_class(
+    spike.BernoulliEncoder, 'braintools.BernoulliEncoder', 'braintools.spike.BernoulliEncoder')
+DeltaEncoder = _deprecated_class(
+    spike.DeltaEncoder, 'braintools.DeltaEncoder', 'braintools.spike.DeltaEncoder')
+StepCurrentEncoder = _deprecated_class(
+    spike.StepCurrentEncoder, 'braintools.StepCurrentEncoder', 'braintools.spike.StepCurrentEncoder')
+SpikeCountEncoder = _deprecated_class(
+    spike.SpikeCountEncoder, 'braintools.SpikeCountEncoder', 'braintools.spike.SpikeCountEncoder')
+TemporalEncoder = _deprecated_class(
+    spike.TemporalEncoder, 'braintools.TemporalEncoder', 'braintools.spike.TemporalEncoder')
+RankOrderEncoder = _deprecated_class(
+    spike.RankOrderEncoder, 'braintools.RankOrderEncoder', 'braintools.spike.RankOrderEncoder')
+
+# The bitwise operations moved to ``braintools.spike`` (without the ``spike_``
+# prefix). The old names stay as plain, non-warning aliases: brainstate's
+# ``nn/_elementwise.py`` binds them at import time.
+spike_bitwise_or = spike.bitwise_or
+spike_bitwise_and = spike.bitwise_and
+spike_bitwise_iand = spike.bitwise_iand
+spike_bitwise_not = spike.bitwise_not
+spike_bitwise_xor = spike.bitwise_xor
+spike_bitwise_ixor = spike.bitwise_ixor
+spike_bitwise = spike.bitwise
+
+__all__ = [
+    '__version__',
+    '__version_info__',
+    'conn',
+    'input',
+    'init',
+    'file',
+    'fit',
+    'metric',
+    'visualize',
+    'optim',
+    'trainer',
+    'tree',
+    'quad',
+    'surrogate',
+    'cogtask',
+    'analysis',
+    'spike',
+
+    'LatencyEncoder',
+    'RateEncoder',
+    'PoissonEncoder',
+    'PopulationEncoder',
+    'BernoulliEncoder',
+    'DeltaEncoder',
+    'StepCurrentEncoder',
+    'SpikeCountEncoder',
+    'TemporalEncoder',
+    'RankOrderEncoder',
+
+    'spike_bitwise_or',
+    'spike_bitwise_and',
+    'spike_bitwise_iand',
+    'spike_bitwise_not',
+    'spike_bitwise_xor',
+    'spike_bitwise_ixor',
+    'spike_bitwise',
+]