Skip to content

Release v0.12.7: Documentation Enhancements and Linux Multiprocessing Fix

Choose a tag to compare

View all tags
@Routhleck Routhleck released this 19 Jan 02:52
· 61 commits to master since this release
v0.12.7
d473dca

What's New

📖 Comprehensive Documentation Improvements

  • Enhanced docstrings across all major modules with usage examples and clearer descriptions
  • Added detailed API documentation for models, tasks, analyzers, and visualization components
  • Improved discoverability and usability for developers

🔧 Critical Bug Fix for Linux Users

  • Fixed AttributeError when using parallel rendering on Linux systems with JAX installed
  • Improved multiprocessing context handling with deterministic tests

Major Features / Key Changes

📖 Documentation Enhancements (PR #81)

Comprehensive docstring improvements across the entire codebase:

  • Package namespaces: Enhanced module-level docstrings for canns and submodules with usage examples
  • Model classes: Expanded documentation for CANN, grid cell, hierarchical, Hopfield, linear, and spiking models
  • Task modules: Added step-by-step workflows and doctest-style examples for navigation and tracking tasks
  • Analyzer modules: Added concrete usage examples for metrics, model_specific, slow_points, and visualization modules
  • Animation functions: Updated docstrings in rendering and theta_sweep_plots with clearer usage guidance

```python

Example: Improved model documentation now includes clear usage patterns

from canns.models import CANN1D

Create a 1D CANN with 100 neurons

model = CANN1D(num=100, k=1.0, tau=1.0)

Run simulation

model.step_run(duration=100.0, inputs=external_input)
```

🔧 Multiprocessing Fix for Linux (PR #82)

Fixed critical bug affecting parallel rendering on Linux systems with JAX:

  • Root cause: SpawnContext objects don't have a .method attribute, causing AttributeError
  • Solution: Modified get_multiprocessing_context() to return tuple (context, method_name)
  • Updated: All 5 call sites across visualization modules to unpack the tuple
  • Testing: Added comprehensive tests with monkeypatch for deterministic behavior

```python

Fixed API now returns both context and method name

ctx, start_method = get_multiprocessing_context(prefer_fork=True)

Handles JAX detection and falls back to spawn automatically

```

📄 Research Paper Draft

  • Added initial paper.md describing the CANNs toolkit, motivation, and design
  • Expanded docs/refs/references.bib with additional related works
  • Updated BrainPy citation with detailed metadata

Technical Improvements

  • Test coverage: Added 6 new tests for multiprocessing context handling
  • Deterministic testing: Used pytest monkeypatch for JAX-dependent behavior
  • Error handling: Improved failure path testing for unavailable multiprocessing

Files Modified

  • 36 files changed, 1754 insertions(+), 709 deletions(-)
  • New test file: tests/analyzer/visualization/test_backend.py
  • New paper draft: paper.md

Breaking Changes

None - all changes are backward compatible.

Full Changelog: v0.12.6...v0.12.7

Assets 2
Loading