CANNs Documentation¶

Welcome to CANNs!¶

CANNs (Continuous Attractor Neural Networks toolkit) is a research toolkit built on BrainPy and JAX, with optional Rust-accelerated canns-lib for selected performance-critical routines. It bundles model collections, task generators, analyzers, trainers, and the ASA pipeline (GUI/TUI) so you can run simulations and analyze results in a consistent workflow.

Architecture¶

Core Features¶

Model collections: basic CANNs (1D/2D, SFA), hierarchical path integration, theta-sweep models, brain-inspired models (e.g., Amari-Hopfield, linear/spiking layers)
Task generators: smooth tracking, population coding, template matching, open/closed-loop navigation
Analyzer suite: energy landscapes, tuning curves, raster/firing-rate plots, TDA and decoding utilities, cell classification
ASA pipeline & GUI/TUI: end-to-end workflow for preprocessing, TDA, decoding, and result visualization (e.g., CohoMap/CohoSpace/PathCompare/FR/FRM/GridScore)
Training & extensibility: HebbianTrainer plus base classes for consistent extension
Optional acceleration: canns-lib for selected performance-critical routines

Model Analysis Overview¶

Analyzer Display — Rich analyzer visualization results.¶

Visualizations¶

1D CANN Smooth Tracking

Real-time dynamics during smooth tracking

2D CANN Population Encoding

Spatial information encoding patterns

🔬 Theta Sweep Analysis

Theta rhythm modulation in grid and direction cell networks

Bump Analysis

1D bump fitting and analysis

Torus Topology Analysis

3D torus visualization and decoding

ASA Pipeline (GUI/TUI)¶

Quick Start¶

Install CANNs:

# CPU-only
pip install canns

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

# GUI (ASA Pipeline)
pip install canns[gui]

Optional (uv):

uv pip install canns

1D CANN smooth tracking (imports → simulation → visualization):

import brainpy.math as bm
from canns.analyzer.visualization import PlotConfigs, energy_landscape_1d_animation
from canns.models.basic import CANN1D
from canns.task.tracking import SmoothTracking1D

# simulation time step
bm.set_dt(0.1)

# build model
cann = CANN1D(num=512)

# build tracking task (Iext length = duration length + 1)
task = SmoothTracking1D(
    cann_instance=cann,
    Iext=(0.0, 0.5, 1.0, 1.5),
    duration=(5.0, 5.0, 5.0),
    time_step=bm.get_dt(),
)
task.get_data()


# one-step simulation callback
def step(t, stimulus):
    cann(stimulus)
    return cann.u.value, cann.inp.value


# run simulation loop
us, inputs = bm.for_loop(
    step,
    operands=(task.run_steps, task.data),
)

# visualize with energy landscape animation
config = PlotConfigs.energy_landscape_1d_animation(
    time_steps_per_second=int(1 / bm.get_dt()),
    fps=20,
    title="Smooth Tracking 1D",
    xlabel="State",
    ylabel="Activity",
    show=True,
)

energy_landscape_1d_animation(
    data_sets={"u": (cann.x, us), "Iext": (cann.x, inputs)},
    config=config,
)

Community and Support¶

GitHub Repository: https://github.com/routhleck/canns
Issue Tracker: https://github.com/routhleck/canns/issues
Discussions: https://github.com/routhleck/canns/discussions
Documentation: https://routhleck.com/canns/

Contributing¶

Contributions are welcome! Please check our Contribution Guidelines.

Citation¶

If you use CANNs in your research, please cite:

@software{he_2026_canns,
  author       = {He, Sichao and
                  Tuerhong, Aiersi and
                  She, Shangjun and
                  Chu, Tianhao and
                  Wu, Yuling and
                  Zuo, Junfeng and
                  Wu, Si},
  title        = {CANNs: Continuous Attractor Neural Networks Toolkit},
  month        = feb,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v1.0.0},
  doi          = {10.5281/zenodo.18453893},
  url          = {https://doi.org/10.5281/zenodo.18453893}
}