Skip to main contentcanns-toolkit-attractor-networks
Comprehensive open-source toolkit unifying continuous attractor neural network (CANN) research workflow. Three co-designed components (Python/Rust/GUI) for 1D/2D attractor modeling, spike-frequency adaptation, grid cells, path integration, and persistent homology-based attractor detection in neural recordings.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/hiyenwong/ai_collection --skill canns-toolkit-attractor-networksيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
المهن ذات الصلةSOC
استنادا إلى تصنيف SOC المهني
| name | canns-toolkit-attractor-networks |
| description | Comprehensive open-source toolkit unifying continuous attractor neural network (CANN) research workflow. Three co-designed components (Python/Rust/GUI) for 1D/2D attractor modeling, spike-frequency adaptation, grid cells, path integration, and persistent homology-based attractor detection in neural recordings. |
| version | 1.0.0 |
| tags | ["neuroscience","continuous-attractor","grid-cells","place-cells","head-direction","path-integration","persistent-homology","topological-data-analysis","BrainPy","JAX","hippocampus","entorhinal-cortex"] |
| arxiv | 2606.27783 |
| authors | ["Sichao He","Aiersi Tuerhong","Shangjun She","Tianhao Chu","Yuling Wu","Junfeng Zuo","Si Wu"] |
| institution | Peking University |
| published | 2026-06-30 |
CANNs: A Toolkit for Research on Continuous Attractor Neural Networks
Core Methodology
1. What are Continuous Attractor Neural Networks (CANNs)?
Canonical computational framework for how the brain encodes continuous variables:
- Spatial position (hippocampal place cells)
- Head direction (head-direction cells)
- Movement direction (entorhinal grid cells)
Key properties:
- Recurrently connected population with localized "bump" of activity
- Bump smoothly translates along low-dimensional manifold
- Provides stability, noise robustness, and integration
- Manifold topology: ring (S¹) for 1D, torus (T²) for 2D
Biological grounding:
- Place cells (O'Keefe & Dostrovsky, 1971)
- Grid cells (Hafting et al., 2005)
- Head-direction cells (Taube et al., 1990)
2. Mathematical Core (Wu-Amari-Wong Model)
Network architecture:
- N neurons on 1D ring or 2D torus
- Translation-invariant recurrent connectivity (Gaussian kernel)
- Divisive normalization implements global inhibition
- Continuum of stable bump states parameterized by continuous variable
Dynamics:
τ du/dt = -u + ∫ J(u,v) r(v) dv + I_ext
r = [u]² / (1 + k ∫ [u]² du) # divisive normalization
Where:
- u: internal state
- r: firing rate
- J: recurrent connectivity kernel (Gaussian)
- k: global inhibition strength
- I_ext: external input
Energy landscape:
E(r) = -1/2 r^T W r + I^T r
Key behaviors:
- Bump can be moved arbitrarily by localized input
- When input disappears, bump remains (short-term memory)
- Attractor structure provides built-in integrator
3. CANNs Toolkit Architecture
Three co-designed components:
A. canns (Python library on BrainPy/JAX)
Modules:
-
Models (canns.models): Neural network dynamics
- 1D ring CANN (head-direction)
- 2D torus CANN (place fields)
Tasks (canns.task): Experimental paradigms
- Spatial navigation
- Head-direction tracking
- Grid cell firing field generation
- Parametric working memory
Analyzers (canns.analyzer): Visualization and analysis
- Energy landscape computation
- Manifold extraction (PCA, UMAP)
- Tuning curve fitting
- Topological data analysis integration
Trainers (canns.trainer): Biologically plausible learning
- Hebbian plasticity
- STDP-like rules
- Homeostatic mechanisms
Pipeline (canns.pipeline): Orchestration
- Full workflow from simulation to analysis
- Reproducible experiment scripts
B. canns-lib (Rust acceleration backend)
Performance-critical operations:
- Ripser-based persistent homology (hundreds-of-times speedup)
- Long spatial navigation trajectories
- Bulk task generation
- Python FFI for seamless integration
C. ASA (Attractor Structure Analyzer - PySide6 GUI)
Purpose: Detect attractor topology in experimental neural recordings
- Data ingestion (.npz format)
- Preprocessing (spike/rate extraction)
- Point cloud construction (time-indexed or spatially-indexed)
- Persistent homology computation
- Shuffle controls (statistical significance)
- Persistent cohomology decoding (CohoMap/EcohoMap)
- Circular coordinate extraction
- Grid score computation
- Module-level workflows
- GUI + CLI interfaces
- Ring (S¹): One dominant H₁ barcode → head-direction cells, band cells, 1D CANN
- Torus (T² = S¹×S¹): Two stable H₁ features → grid-cell modules, 2D CANN
4. Advanced CANN Variants
A. Spike-Frequency Adaptation (SFA)
Mechanism: Activity-dependent negative feedback
- Turns static bump into moving wave
- Enables anticipative tracking
- Models theta sweeps and phase precession
τ_a da/dt = -a + b * r
τ du/dt = -u + ∫ J r dv - g_a * a + I_ext
- a: adaptation current
- b: adaptation strength
- g_a: adaptation conductance
B. Theta-Rhythmic Modulation
- Theta sweeps (forward/backward)
- Phase precession
- Phase procession
theta(t) = sin(2π f_theta t + φ)
I_mod = I_baseline + A_theta * theta(t)
C. Hierarchical Path Integration
Architecture: Multiple grid-cell modules with different spatial scales
- Coarse modules: large grid spacing
- Fine modules: small grid spacing
- Hierarchical combination → precise position coding
5. Topological Data Analysis (TDA) for Attractor Detection
- Track topological features (connected components, loops, voids) across scales
- Barcode: persistence of features vs. scale parameter
- Stable features = true topology; transient = noise
Application to neural data:
from ripser import ripser
r(t) = [r₁(t), r₂(t), ..., rₙ(t)]^T ∈ ℝ^N
X_t = {r(tⱼ) : j = 1, ..., T} ⊂ ℝ^N
result = ripser(X_t, maxdim=2)
diagrams = result['dgms']
ring_signature = len(diagrams[1]) > 0 and diagrams[1][0, 1] > threshold
torus_signature = len(diagrams[1]) >= 2 and diagrams[1][1, 1] > threshold
Persistent Cohomology Decoding:
- Extract circular coordinates from cohomology generators
- Map high-dimensional activity to S¹ (ring) or T² (torus)
- Validate by alignment with behavioral variables
- Efficient cohomology computation
- Cache-aware result management
- Module-level workflows
- Surrogate data with destroyed topology
- Statistical significance testing
- Distinguish true attractor from noise
6. Reproducible Research Pipelines
Example: 1D Ring CANN (Head Direction)
from canns.models import CANN1D
from canns.task import HeadDirectionTracking
from canns.analyzer import EnergyLandscape, ManifoldAnalysis
net = CANN1D(N=512, J0=1.0, a=0.5, k=0.1)
task = HeadDirectionTracking(n_directions=4, delay=500)
inputs = task.sample()
outputs, states = net.simulate(inputs, T=2000)
energy = EnergyLandscape(net.W)
energy.plot()
manifold = ManifoldAnalysis(states)
manifold.pca(n_components=3)
manifold.umap(n_neighbors=15)
from canns.analyzer import PersistentHomology
ph = PersistentHomology()
barcode = ph.compute(states)
assert ph.is_ring_attractor(barcode)
Example: Real Neural Recording Analysis with ASA
from asa import AttractorStructureAnalyzer
data = asa.load('mec_grid_cells.npz')
rates = asa.extract_rates(data, bin_size=50)
asa_pipeline = AttractorStructureAnalyzer()
result = asa_pipeline.analyze(
rates,
method='persistent_cohomology',
maxdim=2,
shuffle_controls=100
)
if result.is_torus():
print("Grid-cell module detected: toroidal topology")
circular_coords = result.decode_circular_coordinates()
grid_score = result.compute_grid_score(circular_coords)
elif result.is_ring():
print("Head-direction or band-cell ring attractor")
phase = result.decode_ring_phase()
7. Key Capabilities
- SFA-driven anticipative tracking
- Theta sweeps in head-direction/place/grid systems
- Hierarchical path integration
- Real MEC grid-cell module analysis (heterogeneous topology)
- Head-direction cell ring attractor detection
- GridScore: quantify hexagonal firing fields
- CohoScore: topological signature strength
- PathCompare: compare trajectories across conditions
- Module-level workflows for common analyses
8. Installation and Usage
pip install canns
pip install canns[gui]
pip install asa-attractor-analyzer
import canns
net = canns.models.GridCellNetwork(module_id=1)
positions, firing_rates = net.simulate_navigation(
trajectory='random_walk',
duration=600
)
from canns.analyzer import GridFieldAnalysis
gfa = GridFieldAnalysis()
grid_score = gfa.compute_score(firing_rates, positions)
gfa.plot_firing_fields(firing_rates, positions)
Key Insights
1. Unification of CANN Research
Problem: CANN research fragmented across:
- Lab-specific implementations
- General-purpose simulators (NEURON, BRIAN) lack CANN-specific abstractions
- No standardized path from spike trains to attractor geometry
Solution: Unified toolkit covering:
- Modeling (canns)
- Acceleration (canns-lib)
- Experimental analysis (ASA)
- Reproducible pipelines
2. Topological Signatures as Biomarkers
Finding: Real MEC grid-cell modules show heterogeneous topology
- Some modules: clear toroidal signature
- Others: partial or unstable topology
- Suggests: not all grid-cell modules are perfect CANNs
Implication: Persistent homology provides quantitative biomarker for:
- Attractor quality (how "perfect" is the CANN?)
- Disease states (does Alzheimer's degrade toroidal topology?)
- Development (how does topology emerge during learning?)
3. Rust Acceleration Matters
- Persistent homology: 100-1000× speedup
- Spatial navigation: efficient long trajectories
- Enables: real-time analysis of large datasets
- Memory safety without garbage collection
- Zero-cost abstractions
- Seamless Python FFI
4. Separation of Concerns
- Models: define dynamics
- Tasks: generate inputs
- Analyzers: visualize/analyze (no state modification)
- Trainers: update parameters
- Pipeline: orchestrate
Benefit: Modular, extensible, reproducible
Experimental Validation
Predictions for Empirical Testing
-
Topology heterogeneity: Different grid-cell modules should show varying topological "perfection" (testable with large-scale MEC recordings)
-
Disease biomarkers: Neurodegenerative diseases should degrade toroidal topology (Alzheimer's → entorhinal cortex degradation)
-
Development trajectory: Toroidal topology should emerge during learning (young animals → less stable topology)
-
SFA signature: Theta sweeps and phase precession should correlate with SFA strength (testable via pharmacological manipulation)
Limitations
- Rate-based models (most implementations) → cannot capture spike timing
- Assumes translation-invariant connectivity → biological networks have variability
- Persistent homology computationally expensive for very large populations (>10,000 neurons)
- No direct spike-train analysis (requires rate conversion)
Extensions
- Spiking CANNs: Implement leaky integrate-and-fire or adaptive exponential integrate-and-fire neurons
- Learning rules: Add biologically plausible synaptic plasticity (STDP, homeostatic)
- Multi-region models: Connect hippocampus, entorhinal cortex, head-direction circuits
- Behavioral coupling: Link attractor dynamics to decision-making and navigation behavior
- GPU acceleration: JAX backend already supports GPU; extend Rust backend for CUDA
References
- arXiv:2606.27783 - Original paper
- Amari (1977a) - Lateral-inhibition neural fields
- Wu et al. (2008, 2016) - Analytically solvable CANN model
- Gardner et al. (2022) - Toroidal population geometry in grid cells
- Mi et al. (2014) - Spike-frequency adaptation in CANNs
- Chu et al. (2024, 2025) - Theta rhythms and hierarchical path integration
Activation Keywords
continuous attractor neural network, CANN, grid cells, place cells, head-direction cells, path integration, persistent homology, topological data analysis, BrainPy, JAX, hippocampus, entorhinal cortex, spatial navigation, ring attractor, torus attractor, spike-frequency adaptation, theta sweeps, phase precession, manifold learning, neural manifold, attractor analysis, ASA toolkit
