CANNs: Continuous Attractor Neural Networks Toolkit

中文说明请见 README_zh.md

CANNs is a Python library built on top of brainpy with performance‑critical modules accelerated by a dedicated Rust backend (canns-lib). It streamlines experimentation with continuous attractor neural networks and related brain‑inspired models, providing ready‑to‑use models, task generators, analysis tools, and pipelines so neuroscience and AI researchers can move from ideas to reproducible simulations quickly.

Highlights

• Model families – canns.models.basic ships 1D/2D CANNs (including SFA variants and hierarchical networks), while canns.models.brain_inspired adds Hopfield-style systems.
• Task-first API – canns.task.tracking and canns.task.open_loop_navigation generate smooth tracking inputs, population coding stimuli, or import experimental trajectories.
• Rich analysis suite – canns.analyzer covers energy landscapes, tuning curves, spike embeddings, UMAP/TDA helpers, and theta-sweep animations.
• Unified training – canns.trainer.HebbianTrainer implements generic Hebbian learning and prediction, layered on the abstract Trainer base.
• Pipelines out of the box – canns.pipeline.ThetaSweepPipeline orchestrates navigation tasks, direction/grid-cell networks, and visualisation in a single call.
• Extensible foundations – base classes (BasicModel, Task, Trainer, Pipeline) keep custom components consistent with the built-in ecosystem.

Visual Gallery

1D CANN Smooth Tracking Real-time dynamics during smooth tracking	2D CANN Population Encoding Spatial information encoding patterns
Theta Sweep Analysis Grid cell and head direction networks with theta rhythm modulation
Bump Analysis 1D bump fitting and analysis	Torus Topology Analysis 3D torus visualization and decoding

Installation

# CPU-only installation
pip install canns

# Optional accelerators (Linux only)
pip install canns[cuda12]
pip install canns[tpu]

Quick Start

import brainpy as bp
import brainpy.math as bm
from canns.models.basic import CANN1D
from canns.task.tracking import SmoothTracking1D

bm.set_dt(0.1)

cann = CANN1D(num=512)

task = SmoothTracking1D(
    cann_instance=cann,
    Iext=(0.0, 0.5, 1.0, 1.5),
    duration=(5.0, 5.0, 5.0, 5.0),
    time_step=bm.get_dt(),
)
task.get_data()

def step(t, stimulus):
    cann(stimulus)
    return cann.u.value, cann.inp.value

us, inputs = bm.for_loop(
    step,
    (
	task.run_steps,
	task.data,
    )
)

For an end-to-end theta sweep workflow, see examples/pipeline/theta_sweep_from_external_data.py or the ThetaSweepPipeline notebook in the docs.

Documentation & Notebooks

• Quick Start Guide – condensed tour of the library layout.
• Design Philosophy – detailed design rationale for each module.
• Interactive launchers:

Development Workflow

# Create the dev environment (uv-based)
make install

# Format and lint (ruff, codespell, etc.)
make lint

# Run the test suite (pytest)
make test

Additional scripts live under devtools/ and scripts/.

Repository Layout

src/canns/            Core library modules (models, tasks, analyzers, trainer, pipeline)
docs/                 Sphinx documentation and notebooks
examples/             Ready-to-run scripts for models, analysis, and pipelines
tests/                Pytest coverage for key behaviours

Citation

If you use CANNs in your research, please cite it using the information from our CITATION.cff file or use the following:

@software{he_2025_canns,
  author       = {He, Sichao},
  title        = {CANNs: Continuous Attractor Neural Networks Toolkit},
  year         = 2025,
  publisher    = {Zenodo},
  version      = {v0.9.0},
  doi          = {10.5281/zenodo.17412545},
  url          = {https://github.com/Routhleck/canns}
}

Contributing

Contributions are welcome! Please open an issue or discussion if you plan significant changes. Pull requests should follow the existing lint/test workflow (make lint && make test).

License

Apache License 2.0. See LICENSE for details.