changelog.md

Release Notes

Version 0.1.2

Major Changes

Import Path Migration

• Updated dependency from brainpy to brainpy.state: Migrated all imports to use the more specific brainpy.state module
  • Updated braintrace/nn/_readout.py: Changed neuron model imports from brainpy to brainpy.state
  • Updated all documentation notebooks (12 files): Concepts, RNN/SNN online learning, batching, state management, and graph visualization tutorials
  • Updated example scripts (4 files): COBA EI RSNN, SNN evaluation, feedforward conv SNN, and SNN models
  • Updated requirements.txt and pyproject.toml to specify brainpy-state as dependency
  • Total: 19 files changed with improved module structure and consistency

New Algorithms

• Added PP-Prop (Pseudo-Prospective Propagation) algorithm: New eligibility trace algorithm in VJP-based methods
  • Added pp_prop to braintrace/_etrace_vjp/esd_rtrl.py
  • Updated docs/apis/algorithms.rst to include PP-Prop in algorithm documentation

Python 3.14 Support

• Added Python 3.14 compatibility: Updated project metadata to officially support Python 3.14
  • Updated pyproject.toml classifiers to include Python 3.14

Bug Fixes

• Fixed version info tuple creation: Corrected the version info structure in braintrace/__init__.py
  • Ensures proper version tuple formatting for compatibility checks

CI/CD Improvements

• Updated GitHub Actions workflow: Bumped actions/upload-artifact from v5 to v6
  • Modernized CI/CD pipeline with latest GitHub Actions versions
  • Improved artifact upload reliability and performance

Documentation Updates

• Updated documentation links: Refreshed links in concept documentation for better navigation
  • Updated docs/quickstart/concepts-en.ipynb (116 lines modified)
  • Updated docs/quickstart/concepts-zh.ipynb (104 lines modified)

Breaking Changes

Dependency Change:

1. Dependency name change: The project now requires brainpy-state instead of brainpy
   • Update your requirements.txt or installation commands accordingly

# Old (0.1.1)
pip install brainpy

# New (0.1.2)
pip install brainpy-state

2. Import path update: Update neuron model imports to use brainpy.state

# New (0.1.2)
from brainpy.state import IF, LIF, ALIF

Migration Guide

Update Dependencies

Replace brainpy with brainpy-state in your project dependencies:

pip uninstall brainpy
pip install brainpy-state

Update Import Statements

If you have custom code importing neuron models, update to use brainpy.state:

# Find and replace in your codebase
# from brainpy import → from brainpy.state import

Version

• Bumped version from 0.1.1 to 0.1.2

Version 0.1.1

Major Changes

Project Rename: BrainScale → BrainTrace

• Renamed the entire project from brainscale to braintrace: This change reflects the project's focus on eligibility trace-based learning algorithms
  • Package directory renamed from brainscale/ to braintrace/
  • All internal imports updated from brainscale to braintrace
  • Updated all 95 files including source code, tests, documentation, and examples
  • Updated pyproject.toml with new project name and metadata
  • Updated README with new project branding and citation information

VJP-Based Eligibility Trace Algorithms

• Added new VJP-based eligibility trace module (_etrace_vjp/): Comprehensive implementation of vector-Jacobian product based algorithms

  • base.py: Core base classes and utilities for VJP operations (671 lines)
  • d_rtrl.py: Diagonal Real-Time Recurrent Learning implementation (756 lines)
  • esd_rtrl.py: Efficient Sparse Diagonal RTRL implementation (847 lines)
  • hybrid.py: Hybrid approaches combining multiple techniques (604 lines)
  • graph_executor.py: Graph-based execution for VJP computations
  • misc.py: Miscellaneous utilities including matrix spectrum normalization

• Refactored VJP algorithm structure: Migrated from monolithic _etrace_vjp_algorithms.py (2,888 lines) to modular architecture

  • Better separation of concerns
  • Improved testability with dedicated test files (d_rtrl_test.py, esd_rtrl_test.py, graph_executor_test.py)

Logo and Branding

• Updated logo format from JPG to PNG for consistency
• Updated logo across documentation

Breaking Changes

Package Rename:

1. Import path change: All imports must now use braintrace instead of brainscale

# Old (0.1.0)
import brainscale
from brainscale import EligibilityTrace
from brainscale.nn import Linear, GRUCell

# New (0.1.1)
import braintrace
from braintrace import EligibilityTrace
from braintrace.nn import Linear, GRUCell

2. Installation: Package name changed from brainscale to braintrace

# Old
pip install brainscale

# New
pip install braintrace

Migration Guide

Update Import Statements

Replace all occurrences of brainscale with braintrace:

# Find and replace in your codebase
# brainscale → braintrace

VJP Algorithm Usage

The new VJP-based algorithms are now available through the modular interface:

Version

• Bumped version from 0.1.0 to 0.1.1

Version 0.1.0

Major Changes

State Management Refactoring

• Renamed ETraceState to HiddenState: All eligibility trace state management now uses the more general HiddenState naming convention

  • Updated across _etrace_algorithms.py, _etrace_concepts.py, _state_managment.py
  • Added deprecation warnings for ETraceState to guide users to brainstate.HiddenState
  • Updated all documentation and examples to reflect the new naming

• Renamed ETraceGroupState to HiddenGroupState: Improved consistency in hidden state handling

  • Updated in _etrace_compiler_hidden_group.py
  • Added deprecation warnings for backward compatibility

• Added deprecation handling: Implemented __getattr__ in main __init__.py to provide helpful warnings when using deprecated names:

  • ETraceState → brainstate.HiddenState
  • ETraceGroupState → brainstate.HiddenGroupState
  • ETraceTreeState → brainstate.HiddenTreeState

Neural Network Module Reorganization

• Consolidated neural network modules: Removed standalone neuron, synapse, and activation modules, migrating them to brainstate and brainpy ecosystems

  • Deleted files:
    • brainscale/nn/_neurons.py (IF, LIF, ALIF now in brainpy.state)
    • brainscale/nn/_synapses.py (Expon, Alpha, DualExpon, STP, STD now in brainpy.state)
    • brainscale/nn/_elementwise.py (activation functions now in brainstate.nn)
    • brainscale/nn/_poolings.py (pooling layers now in brainstate.nn)

• Renamed _rate_rnns.py to _rnn.py: Simplified module naming for better clarity

• Added comprehensive deprecation warnings in nn.__getattr__: Automatically redirects users to the correct modules:

  • Neuron models (IF, LIF, ALIF) → brainpy.state
  • Synapse models (Expon, Alpha, DualExpon, STP, STD) → brainpy.state
  • Activation functions (ReLU, Sigmoid, etc.) → brainstate.nn
  • Pooling layers (MaxPool, AvgPool, etc.) → brainstate.nn
  • Dropout layers → brainstate.nn

API Improvements

• Normalization parameter standardization: Renamed normalized_shape to in_size across all normalization layers for consistency

  • Updated in _normalizations.py for LayerNorm, GroupNorm, InstanceNorm, etc.
  • Improved clarity and consistency with other layer APIs

• Enhanced input dimension validation: Improved error checking in convolutional layers to catch dimension mismatches early

• Refactored imports for consistency: Updated all internal imports to use braintools for optimization and initialization utilities consistently across the codebase

Testing Infrastructure

• Added comprehensive unit tests for neural network modules:
  • _conv_test.py: 868 lines of tests for convolutional layers (Conv1d, Conv2d, Conv3d, ConvTranspose)
  • _linear_test.py: 658 lines of tests for linear layers (Linear, Identity)
  • _normalizations_test.py: 695 lines of tests for normalization layers (LayerNorm, BatchNorm, GroupNorm, etc.)
  • _readout_test.py: 763 lines of tests for readout layers (LeakyRateReadout, LeakySpikeReadout)
  • _rnn_test.py: 710 lines of tests for RNN cells (VanillaRNNCell, GRUCell, LSTMCell, MGUCell, etc.)
  • Total: 3,694 lines of new test coverage

Documentation Updates

• Streamlined API documentation: Updated docs/apis/nn.rst to remove redundant sections and enhance RNN overview
• Updated tutorials and examples: All 16 tutorial notebooks and 11 example scripts updated to reflect new APIs:
  • Concepts tutorials (en/zh)
  • RNN and SNN online learning guides
  • Batching strategies documentation
  • ETrace state management examples
  • Graph visualization tutorials

Code Quality Improvements

• Removed redundant docstrings: Cleaned up duplicate documentation in LeakyRateReadout and LeakySpikeReadout
• Improved code organization: Streamlined __all__ definitions across all modules
• Enhanced readability: Consistent import structure and better code formatting throughout

Dependency Updates

• Updated requirements.txt: Refined dependency specifications to ensure compatibility with latest brainstate and brainpy versions
• Updated pyproject.toml: Bumped version to 0.1.0 and updated project metadata

Breaking Changes

API Changes:

1. State class renaming (with deprecation warnings):

   • ETraceState → Use brainstate.HiddenState instead
   • ETraceGroupState → Use brainstate.HiddenGroupState instead
   • ETraceTreeState → Use brainstate.HiddenTreeState instead

2. Neural network component migration (with deprecation warnings):

   • Neuron models (IF, LIF, ALIF) → Use brainpy.state module
   • Synapse models (Expon, Alpha, etc.) → Use brainpy.state module
   • Activation functions → Use brainstate.nn module
   • Pooling layers → Use brainstate.nn module

3. Normalization parameter rename:

   • normalized_shape → in_size (for LayerNorm, GroupNorm, etc.)

4. Module file reorganization:

   • nn/_rate_rnns.py → nn/_rnn.py
   • Removed: _neurons.py, _synapses.py, _elementwise.py, _poolings.py

Migration Guide

For State Management:

# Old (0.0.11)
from brainscale import ETraceState, ETraceGroupState

# New (0.1.0)
from brainstate import HiddenState, HiddenGroupState

For Neural Network Components:

# Old (0.0.11)
from brainscale.nn import IF, LIF, Expon, ReLU, MaxPool2d

# New (0.1.0)
from brainpy.state import IF, LIF, Expon
from brainstate.nn import ReLU, MaxPool2d

For Normalization Layers:

# Old (0.0.11)
norm = LayerNorm(normalized_shape=(128,))

# New (0.1.0)
norm = LayerNorm(in_size=128)

Note: All deprecated APIs include automatic warnings that will guide you to the correct replacements. The old APIs will continue to work in 0.1.0 but will be removed in a future release.

Version

• Bumped version from 0.0.11 to 0.1.0

Version 0.0.11

Major Changes

Import Refactoring

• Migrated imports from brainstate to braintools: All initialization-related imports now use braintools.init instead of brainstate.init

  • Updated imports in:
    • brainscale/nn/_neurons.py: Changed from brainstate import init to from braintools import init
    • brainscale/nn/_linear.py: Changed from brainstate import init to from braintools import init
    • brainscale/nn/_conv.py: Updated initialization imports
    • brainscale/nn/_synapses.py: Updated initialization imports
    • brainscale/nn/_readout.py: Updated initialization imports

• Migrated neural network model imports from brainstate.nn to brainpy: Updated base classes for neuron models

  • IF, LIF, ALIF now inherit from brainpy instead of brainstate.nn
  • Maintained API compatibility while using the new brainpy backend

• Updated functional API calls: Changed from brainstate.functional.sigmoid to brainstate.nn.sigmoid in RNN cells

Dependency Updates

• Added brainpy as a required dependency in requirements.txt

Documentation Enhancements

• Improved docstring formatting across the codebase:
  • Enhanced parameter documentation with proper type annotations using NumPy-style docstrings
  • Added missing "Returns" sections to property and method docstrings
  • Converted inline examples to proper "Examples" sections with code blocks
  • Updated documentation in:
    • brainscale/_etrace_algorithms.py: Enhanced EligibilityTrace and ETraceAlgorithm documentation
    • brainscale/_etrace_compiler_base.py: Improved parameter and return type documentation
    • brainscale/_etrace_compiler_module_info.py: Enhanced module documentation

Core Algorithm Updates

• RNN State Management: Updated all RNN cells to use braintools.init.param for state initialization and reset
  • ValinaRNNCell: Updated init_state() and reset_state() methods
  • GRUCell: Updated state management and activation functions
  • CFNCell: Updated forget and input gate implementations
  • MGUCell: Updated minimal gated unit state handling

Test Updates

• Refactored test imports: Updated test files to use new import paths
  • brainscale/_etrace_model_test.py: Updated with new import structure
  • brainscale/_etrace_vjp_algorithms_test.py: Aligned with new API

Version

• Bumped version from 0.0.10 to 0.0.11

Files Changed (17 files)

• .gitignore: Added new patterns
• brainscale/__init__.py: Updated version number
• brainscale/_etrace_algorithms.py: Enhanced documentation and imports
• brainscale/_etrace_compiler_base.py: Improved documentation
• brainscale/_etrace_compiler_graph.py: Minor updates
• brainscale/_etrace_compiler_hidden_group.py: Minor updates
• brainscale/_etrace_compiler_module_info.py: Enhanced documentation
• brainscale/_etrace_model_test.py: Updated test imports
• brainscale/_etrace_vjp_algorithms_test.py: Updated test imports
• brainscale/_etrace_vjp_graph_executor.py: Updated imports
• brainscale/nn/_conv.py: Migrated to braintools imports
• brainscale/nn/_linear.py: Migrated to braintools imports
• brainscale/nn/_neurons.py: Migrated to brainpy and braintools
• brainscale/nn/_rate_rnns.py: Migrated to braintools and updated functional APIs
• brainscale/nn/_readout.py: Updated imports
• brainscale/nn/_synapses.py: Updated imports
• requirements.txt: Added brainpy dependency

Breaking Changes

None. All changes maintain backward compatibility at the API level.

Migration Guide

If you have custom code using brainscale:

• No changes required for end users
• If extending brainscale internally, note that initialization utilities now come from braintools instead of brainstate