feat(docs): add documentation and examples for BrainPy 3.x

oujago · oujago · commit 4f5ec32279ce · 2025-10-07T22:33:09.000+08:00
diff --git a/docs_version2/README.md b/docs_version2/README.md
@@ -0,0 +1,64 @@
+# BrainPy Version 2 Documentation
+
+This directory contains documentation for BrainPy 2.x, the previous major version of BrainPy.
+
+## Overview
+
+BrainPy 2.x is a highly flexible and extensible framework targeting general-purpose Brain Dynamics Programming (BDP). This documentation is maintained for users who are still using BrainPy 2.x.
+
+## Important Note
+
+**As of September 2025, BrainPy has been upgraded to version 3.x.** If you are using BrainPy 3.x, please refer to the main documentation.
+
+To use BrainPy 2.x APIs within version 3.x installations, update your imports:
+
+```python
+# Old version (v2.x standalone)
+import brainpy as bp
+import brainpy.math as bm
+
+# Using v2.x API in BrainPy 3.x
+import brainpy.version2 as bp
+import brainpy.version2.math as bm
+```
+
+## Documentation Contents
+
+- **index.rst** - Main documentation entry point
+- **core_concepts.rst** - Fundamental concepts of Brain Dynamics Programming
+- **tutorials.rst** - Step-by-step tutorials
+- **advanced_tutorials.rst** - Advanced usage patterns
+- **toolboxes.rst** - Specialized toolboxes for different applications
+- **api.rst** - Complete API reference
+- **FAQ.rst** - Frequently asked questions
+- **brainpy-changelog.md** - Version history and changes
+- **brainpylib-changelog.md** - BrainPyLib backend changes
+
+## Building Documentation
+
+This documentation is written in reStructuredText (RST) format and can be built using Sphinx:
+
+```bash
+cd docs_version2
+make html  # or use the appropriate build script
+```
+
+## Installation
+
+For BrainPy 2.x compatibility:
+
+```bash
+pip install -U brainpy[cpu]
+```
+
+## Learn More
+
+- [Core Concepts](core_concepts.rst) - Understand the fundamentals
+- [Tutorials](tutorials.rst) - Learn through examples
+- [API Documentation](api.rst) - Complete reference
+- [BrainPy Examples](https://brainpy-v2.readthedocs.io/projects/examples/) - Code examples
+- [BrainPy Ecosystem](https://brainmodeling.readthedocs.io) - Related projects
+
+## Support
+
+For questions and support, please visit the [BrainPy GitHub repository](https://github.com/brainpy/BrainPy).
diff --git a/docs_version3/README.md b/docs_version3/README.md
@@ -0,0 +1,112 @@
+# BrainPy Version 3 Documentation
+
+This directory contains documentation for BrainPy 3.x, the latest major version of BrainPy.
+
+## Overview
+
+BrainPy 3.x is a flexible, efficient, and extensible framework for computational neuroscience and brain-inspired computation. It has been completely rewritten based on [brainstate](https://github.com/chaobrain/brainstate) (since August 2025) and provides powerful capabilities for building, simulating, and training spiking neural networks.
+
+## Documentation Contents
+
+This directory contains tutorial notebooks and API documentation:
+
+### Tutorials (Bilingual: English & Chinese)
+
+#### SNN Simulation
+- **snn_simulation-en.ipynb** - Building and simulating spiking neural networks (English)
+- **snn_simulation-zh.ipynb** - 构建和模拟脉冲神经网络 (Chinese)
+
+#### SNN Training
+- **snn_training-en.ipynb** - Training spiking neural networks with surrogate gradients (English)
+- **snn_training-zh.ipynb** - 使用代理梯度训练脉冲神经网络 (Chinese)
+
+#### Checkpointing
+- **checkpointing-en.ipynb** - Saving and loading model states (English)
+- **checkpointing-zh.ipynb** - 保存和加载模型状态 (Chinese)
+
+### API Reference
+- **apis.rst** - Complete API documentation
+- **index.rst** - Main documentation entry point
+
+## Key Features in Version 3.x
+
+- Built on [brainstate](https://github.com/chaobrain/brainstate) for improved state management
+- Enhanced support for spiking neural networks
+- Streamlined API for building neural models
+- Improved performance and scalability
+- Better integration with JAX ecosystem
+- Support for GPU/TPU acceleration
+
+## Installation
+
+```bash
+# CPU version
+pip install -U brainpy[cpu]
+
+# GPU version (CUDA 12)
+pip install -U brainpy[cuda12]
+
+# GPU version (CUDA 13)
+pip install -U brainpy[cuda13]
+
+# TPU version
+pip install -U brainpy[tpu]
+
+# Full ecosystem
+pip install -U BrainX
+```
+
+## Quick Start
+
+```python
+import brainpy
+import brainstate
+import brainunit as u
+
+# Define a simple LIF neuron
+neuron = brainpy.LIF(100, V_rest=-60.*u.mV, V_th=-50.*u.mV)
+
+# Initialize and simulate
+brainstate.nn.init_all_states(neuron)
+spikes = neuron(1.*u.mA)
+```
+
+## Migration from Version 2.x
+
+If you're migrating from BrainPy 2.x, the API has changed significantly. See the migration guide in the main documentation for details.
+
+To use legacy 2.x APIs in version 3.x:
+
+```python
+import brainpy.version2 as bp
+import brainpy.version2.math as bm
+```
+
+## Running Notebooks
+
+The tutorial notebooks can be run using Jupyter:
+
+```bash
+jupyter notebook snn_simulation-en.ipynb
+```
+
+Or with JupyterLab:
+
+```bash
+jupyter lab
+```
+
+## Building Documentation
+
+If you need to build the documentation locally, this directory is part of the larger documentation system. Please refer to the main documentation build instructions.
+
+## Learn More
+
+- [Main Documentation](https://brainpy.readthedocs.io)
+- [BrainPy GitHub](https://github.com/brainpy/BrainPy)
+- [BrainState GitHub](https://github.com/chaobrain/brainstate)
+- [BrainPy Ecosystem](https://brainmodeling.readthedocs.io)
+
+## Contributing
+
+Contributions to documentation are welcome! Please submit issues or pull requests to the [BrainPy repository](https://github.com/brainpy/BrainPy).
diff --git a/examples_version2/README.md b/examples_version2/README.md
@@ -0,0 +1,119 @@
+# BrainPy Version 2 Examples
+
+This directory contains example scripts demonstrating the capabilities of BrainPy 2.x for brain dynamics programming.
+
+## Overview
+
+These examples showcase BrainPy 2.x functionality including dynamics simulation, analysis, and training. BrainPy 2.x is maintained for backward compatibility, but new projects should consider using BrainPy 3.x.
+
+## Important Note
+
+**As of September 2025, BrainPy has been upgraded to version 3.x.** To use these examples with BrainPy 3.x, update your imports:
+
+```python
+import brainpy.version2 as bp
+import brainpy.version2.math as bm
+```
+
+## Example Categories
+
+### Dynamics Simulation
+
+Network simulation examples demonstrating various neural models and dynamics:
+
+- **hh_model.py** - Hodgkin-Huxley neuron model
+- **ei_nets.py** - Excitatory-inhibitory networks
+- **COBA.py** - Conductance-based network model
+- **stdp.py** - Spike-timing-dependent plasticity
+- **decision_making_network.py** - Decision-making circuit
+- **whole_brain_simulation_with_fhn.py** - Whole-brain simulation with FitzHugh-Nagumo model
+- **whole_brain_simulation_with_sl_oscillator.py** - Whole-brain simulation with Stuart-Landau oscillator
+
+### Dynamics Analysis
+
+Phase plane and bifurcation analysis of neural models:
+
+- **1d_qif.py** - 1D Quadratic Integrate-and-Fire model analysis
+- **2d_fitzhugh_nagumo_model.py** - 2D FitzHugh-Nagumo phase plane analysis
+- **2d_mean_field_QIF.py** - 2D mean-field QIF analysis
+- **3d_reduced_trn_model.py** - 3D reduced thalamic reticular nucleus model
+- **4d_HH_model.py** - 4D Hodgkin-Huxley model analysis
+- **highdim_RNN_Analysis.py** - High-dimensional RNN dynamics analysis
+
+### Dynamics Training
+
+Training examples for recurrent networks and reservoir computing:
+
+- **echo_state_network.py** - Echo State Network (reservoir computing)
+- **integrator_rnn.py** - RNN for integration task
+- **reservoir-mnist.py** - MNIST classification with reservoir computing
+- **Sussillo_Abbott_2009_FORCE_Learning.py** - FORCE learning algorithm
+- **Song_2016_EI_RNN.py** - E/I RNN training
+- **integrate_brainpy_into_flax-lif.py** - Integration with Flax (LIF neurons)
+- **integrate_brainpy_into_flax-convlstm.py** - Integration with Flax (ConvLSTM)
+- **integrate_flax_into_brainpy.py** - Using Flax models in BrainPy
+
+### Training ANN Models
+
+Artificial neural network training examples:
+
+- **mnist-cnn.py** - CNN for MNIST classification
+- **mnist_ResNet.py** - ResNet for MNIST classification
+
+### Training SNN Models
+
+Spiking neural network training examples:
+
+- **spikebased_bp_for_cifar10.py** - Spike-based backpropagation for CIFAR-10
+- **readme.md** - Additional SNN training documentation
+
+## Requirements
+
+```bash
+pip install -U brainpy[cpu]  # or brainpy[cuda12] for GPU
+```
+
+For version 3.x with 2.x compatibility:
+
+```bash
+pip install -U brainpy[cpu]
+# Then use: import brainpy.version2 as bp
+```
+
+## Usage
+
+Run any example directly:
+
+```bash
+python dynamics_simulation/hh_model.py
+```
+
+Or with version 3.x (examples may need import updates):
+
+```bash
+# Modify imports in the script first, then run
+python dynamics_simulation/ei_nets.py
+```
+
+## Key Concepts Demonstrated
+
+- **Dynamics Simulation**: Simulating neural circuits and network dynamics
+- **Dynamics Analysis**: Phase plane analysis, bifurcation analysis, fixed points
+- **Reservoir Computing**: Echo State Networks and Liquid State Machines
+- **Network Training**: Gradient-based and FORCE learning for RNNs
+- **SNN Training**: Surrogate gradient methods for spiking networks
+- **Framework Integration**: Using BrainPy with other frameworks (Flax, JAX)
+
+## Documentation
+
+- [BrainPy 2.x Documentation](https://brainpy-v2.readthedocs.io)
+- [BrainPy 3.x Documentation](https://brainpy.readthedocs.io)
+- [BrainPy Ecosystem](https://brainmodeling.readthedocs.io)
+
+## Migrating to Version 3.x
+
+For new projects, we recommend using BrainPy 3.x which offers improved performance and a cleaner API. See the migration guide in the main documentation.
+
+## Support
+
+For questions and support, please visit the [BrainPy GitHub repository](https://github.com/brainpy/BrainPy).
diff --git a/examples_version3/README.md b/examples_version3/README.md
@@ -0,0 +1,70 @@
+# BrainPy Version 3 Examples
+
+This directory contains example scripts demonstrating the capabilities of BrainPy 3.x for simulating and training spiking neural networks.
+
+## Overview
+
+BrainPy 3.x is rewritten based on [brainstate](https://github.com/chaobrain/brainstate) and provides a powerful framework for computational neuroscience and brain-inspired computation.
+
+## Example Categories
+
+### Network Simulations (100-series)
+
+Classic network models demonstrating recurrent dynamics and emergent behaviors:
+
+- **102_EI_net_1996.py** - E/I balanced network from Brunel (1996) and Van Vreeswijk & Sompolinsky (1996)
+- **103_COBA_2005.py** - Conductance-based E/I network (COBA model)
+- **104_CUBA_2005.py** - Current-based E/I network (CUBA model)
+- **106_COBA_HH_2007.py** - COBA network with Hodgkin-Huxley neurons
+- **107_gamma_oscillation_1996.py** - Gamma oscillation generation
+- **108_synfire_chains_199.py** - Synfire chain propagation
+- **109_fast_global_oscillation.py** - Fast global oscillation dynamics
+
+### Gamma Oscillation Models (110-series)
+
+Implementations from Susin & Destexhe (2021) demonstrating different gamma oscillation mechanisms:
+
+- **110_Susin_Destexhe_2021_gamma_oscillation_AI.py** - Asynchronous-Irregular (AI) regime
+- **111_Susin_Destexhe_2021_gamma_oscillation_CHING.py** - CHING mechanism
+- **112_Susin_Destexhe_2021_gamma_oscillation_ING.py** - Interneuron Gamma (ING)
+- **113_Susin_Destexhe_2021_gamma_oscillation_PING.py** - Pyramidal-Interneuron Gamma (PING)
+
+### Spiking Neural Network Training (200-series)
+
+Examples demonstrating training of SNNs using surrogate gradient methods:
+
+- **200_surrogate_grad_lif.py** - Basic surrogate gradient learning with LIF neurons
+- **201_surrogate_grad_lif_fashion_mnist.py** - Fashion-MNIST classification with surrogate gradients
+- **202_mnist_lif_readout.py** - MNIST classification with LIF network and readout layer
+
+## Requirements
+
+```bash
+pip install -U brainpy[cpu]  # or brainpy[cuda12] for GPU support
+```
+
+## Usage
+
+Run any example directly:
+
+```bash
+python 102_EI_net_1996.py
+```
+
+## Key Features Demonstrated
+
+- Building recurrent spiking neural networks
+- Neuron models (LIF, Hodgkin-Huxley)
+- Synaptic models (exponential, conductance-based, current-based)
+- Network projection and connectivity
+- Surrogate gradient learning for SNNs
+- State management and initialization
+- Visualization of network activity
+
+## References
+
+These examples are based on influential papers in computational neuroscience. See individual script headers for specific citations.
+
+## Documentation
+
+For more information, visit the [BrainPy documentation](https://brainpy.readthedocs.io).
