中文说明请见 README_zh.md

CANNs is a Python library built on top of the Brain Simulation Ecosystem (brainstate, brainunit) that streamlines experimentation with continuous attractor neural networks and related brain-inspired models. It delivers ready-to-use models, task generators, analysis tools, and pipelines so neuroscience and AI researchers can move from ideas to reproducible simulations quickly.

• 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.spatial_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.

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

# CPU-only installation
pip install canns

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

import brainstate
from canns.models.basic import CANN1D
from canns.task.tracking import SmoothTracking1D

brainstate.environ.set(dt=0.1)

cann = CANN1D(num=512)
cann.init_state()

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=brainstate.environ.get_dt(),
)
task.get_data()

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

us, inputs = brainstate.compile.for_loop(
    step,
    task.run_steps,
    task.data,
    pbar=brainstate.compile.ProgressBar(10),
)

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

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

# 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/.

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

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).

Apache License 2.0. See LICENSE for details.