CANNs: A Toolkit for Research on Continuous Attractor Neural Networks

Abstract: Continuous attractor neural networks (CANNs) are the canonical computational framework for how the brain encodes continuous variables such as spatial position, head direction, and movement direction, and explain the activity of hippocampal place cells, entorhinal grid cells, and head-direction cells. CANN research, however, is fragmented: most results rest on lab-specific implementations, general-purpose simulators lack CANN-specific abstractions, and the path from spike trains to attractor geometry in real recordings lacks a standardized toolkit. Here, we present a comprehensive open-source toolkit that unifies the full CANN research workflow. It combines three tightly integrated components: 1) canns, a Python library on BrainPy/JAX that provides standardized 1D/2D CANNs, spike-frequency-adaptation variants, grid cell networks, hierarchical path-integration models, and brain-inspired attractor architectures, together with curated datasets, task generators, an analyzer module and trainer modules for biologically plausible plasticity; 2) canns-lib, a Rust acceleration backend delivering hundreds-of-times speedups for spatial-navigation workloads and modest gains for Ripser-based persistent homology; 3) ASA (Attractor Structure Analyzer), a PySide6 pipeline applying persistent homology and cohomology to experimental neural recordings to detect ring-like and toroidal attractor signatures in real data. The toolkit ships with full-detail reproducible pipelines that recover recent CANN results including SFA-driven anticipative tracking, theta sweeps in head-direction/place/grid systems, and hierarchical path integration.

• The paper presents a comprehensive open-source toolkit that standardizes simulation, analysis, and modeling for continuous attractor neural networks.
• The paper demonstrates significant performance gains using a Rust backend, achieving up to 700× acceleration in spatial navigation simulations.
• The paper introduces an integrated Attractor Structure Analyzer that applies topological data analysis to validate and explore neural coding topology.

CANNs: A Toolkit for Research on Continuous Attractor Neural Networks

Introduction and Motivation

Continuous Attractor Neural Networks (CANNs) represent a canonical computational paradigm for neural coding of continuous variables, widely applied to the study of hippocampal place cells, entorhinal grid cells, and head-direction cells. Despite their theoretical ubiquity, practical research on CANNs has remained fragmented, primarily due to a lack of standardized, domain-specific tooling. This fragmentation impedes reproducibility, comparison, and systematic exploration, with most codebases being lab-specific and lacking integrated support for simulation, advanced data analysis, and experimental validation.

The "CANNs: A Toolkit for Research on Continuous Attractor Neural Networks" paper addresses this gap, presenting a comprehensive, open-source software ecosystem that unifies the full research workflow for CANNs—from model simulation and high-performance acceleration to topological data analysis (TDA) of neural recordings (2606.27783). The ecosystem comprises three interdependent components:

1. canns: A modular Python library built on BrainPy/JAX, implementing standardized CANN architectures, biologically inspired variants, grid-cell networks, hierarchical path-integration models, and advanced analysis/training modules.
2. canns-lib: A Rust backend delivering orders-of-magnitude acceleration for spatial navigation and persistent homology workloads.
3. ASA (Attractor Structure Analyzer): A pipeline for TDA-based detection of attractor signatures in neurophysiological data, equipped with a PySide6 GUI and reproducible result management.

This toolkit is designed for computational neuroscientists, experimentalists, and newcomers, lowering entry barriers and enabling rigorous, reproducible CANN research across theory, modeling, and empirical domains.

Architectural Overview

CANNs adopts a five-layer, strictly hierarchical architecture that mirrors best practices from domain-specialized toolkits and general neural simulation frameworks. The separation-of-concerns design spans:

• Application/Pipeline: Exposing user interfaces (CLI, GUI) and reproducible, configuration-driven workflows.
• Functional: Implementing tasks, trainers, analyzers, and utilities for modular composition.
• Core Models: Providing all CANN, SFA, grid-cell, hierarchical, and brain-inspired network variants.
• Foundation: Leveraging BrainPy/JAX for numerical performance and canns-lib for Rust-accelerated kernels.
• Hardware: Targeting CPUs, GPUs, and TPUs with device-agnostic execution.

  Figure 1: Layer hierarchy of the CANNs ecosystem, featuring five layers from hardware to application, with strictly hierarchical module interaction.

This architecture guarantees extensibility—new models, trainers, or analysis modules can be implemented with minimal code via subclassing, while maintaining stability and composability throughout the stack.

Performance Acceleration and Benchmarking

A central strength of the toolkit lies in the Rust-based canns-lib acceleration layer. Key numerical kernels are ported to Rust and exposed through PyO3 bindings, resulting in substantial computational gains:

• Persistent Homology (Ripser): 1.13× mean, up to 1.82× maximum speedup versus the Cython/C++ baseline on real and synthetic datasets, with bit-exact accuracy.
• Spatial Navigation: ∼700× speedup for long-trajectory simulation relative to the pure-Python RatInABox environment, facilitating million-step path integration workloads in under a second.

Figure 2: Runtime comparison as a function of integration steps demonstrates the scalability advantage of canns-lib over pure-Python RatInABox.

Figure 3: Relative speedup of canns-lib Rust backend over baseline approaches, highlighting acceleration for both persistent homology and navigation kernels.

These accelerations directly impact practical research, enabling detailed analyses (e.g., million-step continuous-time simulations, high-dimensional TDA) that would otherwise be computationally prohibitive.

Modeling and Simulation Capabilities

The toolkit exposes well-defined CANN subclasses for 1D/2D attractors, grid-cell path-integration, spike-frequency-adaptation (SFA) networks, and theta-modulated phase-coding models. The core equations follow the Wu–Amari–Wong (WAW) model for analytically tractable bump attractors, with divisive normalization ensuring contrast-invariant steady-state tuning. Hierarchical models support spatial multi-scaling, combining grid and place cell representations.

Notable numerical results from the provided library include:

• High-accuracy path integration: $R^2 > 0.99$ and mean error $\approx 0.05$ m for grid-cell network reconstructions of 2D animal trajectories.
• Robust anticipative tracking with SFA: Phase leads scale with input velocity and SFA time constant, reproducing empirical phase-precession and theta-sweep phenomena.

  Figure 4: Anatomy of canonical CANN models. Each row demonstrates a model's connectivity, energy landscape, neuron tuning, dynamic tracking, and extracted low-dimensional activity manifold.

The toolkit supports extensive model diagnostics, visualization, and fixed-point analysis—enabling both theoretical and empirical exploration of network dynamical regimes.

Attractor Structure Analysis (ASA) Pipeline

ASA generalizes TDA-based analyses of neural data, offering persistent (co)homology computations, shuffle-controlled null models, and actionable projections from high-dimensional neural activity onto meaningful behavioral or intrinsic coordinates. These features enable direct interrogation of attractor topology present in both artificial and biological population codes.

Figure 5: Example GUI output in TDA barcode mode, showing persistent homology intervals for neural population trajectories.

ASA differentiates between time-indexed (trajectory-based) and spatial (representation-based) analyses, supporting hypotheses about ring ($S^1$) and torus ($T^2$) geometries in head-direction, grid, and place cell ensembles. Robust performance is demonstrated on real grid-cell datasets:

• Strict toroidal signature detection: In a selected high-quality cohort of 20 MEC grid-cell modules, median leading $H_1/H_2$ lifetimes were 7.88/7.63/8.57 (respectively), exceeding 99.9th percentile of the shuffle null.
• Ring attractors: Dominant $H_1$ bars identified in head-direction cell datasets, with decoded circular coordinates closely tracking behavioral orientation (mean error $\sim$24°).

Figure 6: Example barcode with a single dominant $H_1$ feature, confirming a ring-like attractor in head-direction cells.

Figure 7: EcohoMap gallery, mapping decoded cohomology phases onto the animal's physical environment in real grid-cell modules.

Figure 8: PathCompare visualization reveals that latent toroidal coordinates preserve topology and behavioral trajectory structure across sessions.

Figure 9: Population-level persistent homology in MEC modules with shuffle null controls, confirming recoverable toroidal topology in favorable cases.

The pipeline intertwines classical single-cell gridness (GridScore) with topology-aware population metrics (CohoScore), providing a principled basis for module selection and for connecting single-cell properties to collective coding topology.

Practical and Theoretical Implications

Practical implications: The CANNs toolkit represents a significant advance toward unified, end-to-end research workflows in computational neuroscience. Its API and performance unlock high-throughput simulation and reproducible TDA pipelines, facilitating direct comparisons between models and experimental results. The interoperability of Python/JAX and Rust ensures both researcher productivity and scalability to empirically relevant data volumes.

Theoretical implications: By lowering technical barriers, the toolkit encourages systematic exploration of canonical principles in attractor dynamics, neural coding geometry, and biologically plausible learning. The integrated ASA pipeline provides the tools necessary to rigorously test population-level coding hypotheses using both synthetic and experimental data, supporting deeper investigation into the geometry of neural representations.

Future Directions

Planned extensions focus on:

• Accelerated $H_2$ computation for large-scale persistent homology.
• Dedicated band-cell topology classification and expanded metrics.
• Shared-memory parallelization for batch evaluation and screening.
• Automated parameter recommendation based on empirical data statistics.
• Approximate nearest-neighbor acceleration for large navigation datasets.

These directions will further enhance the framework's utility for high-dimensional data analysis and for large-scale model benchmarking, supporting both neuroscience and AI research communities.

Conclusion

The CANNs ecosystem offers a highly modular, performance-optimized, and analysis-rich toolkit for CANN research, bridging simulation, TDA, and empirical validation in a reproducible and extensible manner. It standardizes both model development and attractor-based data analysis, facilitating rigorous interrogation of continuous neural codes in both theoretical and experimental contexts. The approach substantially reduces technical overhead, encourages best practices, and provides a robust foundation for ongoing methodological and scientific advances in the study of brain-inspired representations and dynamics.