Sovereign 8s.is mirror of standardgalactic/symmetries-continuous-attractors
  • Jupyter Notebook 98.8%
  • Python 1.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
David Clark 245726fa78
Some checks failed
docs / build-deploy (push) Has been cancelled
Revise the documentation and notebooks for readers
2026-08-11 11:18:11 -04:00
.github/workflows Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
data Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
docs Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
figures Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
notebooks Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
ring Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
tests Code and analysis for 'Symmetries and continuous attractors in disordered neural circuits' 2026-08-07 14:13:26 -04:00
tools Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
.gitignore Code and analysis for 'Symmetries and continuous attractors in disordered neural circuits' 2026-08-07 14:13:26 -04:00
FIGURES.md Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
LICENSE Code and analysis for 'Symmetries and continuous attractors in disordered neural circuits' 2026-08-07 14:13:26 -04:00
mkdocs.yml Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
pyproject.toml Code and analysis for 'Symmetries and continuous attractors in disordered neural circuits' 2026-08-07 14:13:26 -04:00
README.md Revise the documentation and notebooks for readers 2026-08-11 11:18:11 -04:00
ring-local.yml Code and analysis for 'Symmetries and continuous attractors in disordered neural circuits' 2026-08-07 14:13:26 -04:00

Symmetries and Continuous Attractors in Disordered Neural Circuits

Code and analysis for the paper of that name, by David G. Clark, L. F. Abbott and Haim Sompolinsky.

Documentation: davidclark1.github.io/symmetries-continuous-attractors

DOI

Abstract

A core challenge in neuroscience is reconciling idealized models with experimental data. Classical continuous-attractor models describe neural representations of continuous variables such as head direction. Symmetry in the weights generates a manifold of stable states, with tuning curves identical up to shifts. Rodent head-direction cells, by contrast, are markedly heterogeneous. Such heterogeneity, we show, is nevertheless compatible with these models. We build, directly from head-direction cell data, recurrent networks that behave as quasi-continuous attractors. A generative process then reproduces the heterogeneous tuning of these cells while making connectivity and dynamics tractable at large N. Although the weights appear disordered, they carry a circular symmetry whose eigenvalue degeneracies could signify continuous-attractor organization in connectome data. Dynamical mean-field theory recovers the ingredients of classical ring attractors, namely Mexican-hat interactions and a spontaneously broken symmetry producing bump states. Continuous-attractor mechanisms may thus operate in complex mammalian circuits.

Project structure

Every figure in the paper is drawn by one of eleven notebooks. The notebooks read precomputed results from data/: tuning curves extracted from the recordings, and the outputs of the slow simulations and fits, about 2 GB in total, released on Zenodo. The recordings themselves are head-direction data from the Peyrache lab, published separately as DANDI Dandiset 000939; you do not need them to reproduce the figures. Most notebooks run in under a minute.

Notebook Purpose Figures
data_and_generative_model.ipynb Characterizes the tuning curves measured in each mouse, tests the circular symmetry of their distribution, and fits the generative process to them 1, 3, 4, 5, S13
data_driven_attractor.ipynb Builds the ring attractor directly from the recordings and tests its closed-loop velocity integration 2
spectra.ipynb Compares the spectra and eigenvector geometry of the disordered and circulant weight matrices 6
dmft.ipynb Solves the dynamical mean-field theory of the disordered ring attractor and maps the stability of its solutions 7
grid_sims.ipynb Simulates grid cells from the disordered attractor and computes the spectrum of their connectivity 8, S15
weight_matrix_analyses.ipynb Examines the weight matrix's low-rank structure and singular vectors, compares it with spectrum-matched surrogates, and measures drift under weight noise S1, S2, S3, S4, S10
data_driven_reconstruction.ipynb Tests the reconstruction's dependence on normalization, regularization and population size, and its convergence in PC space S7, S8, S9, S14
mexican_hat_and_asymmetry.ipynb Derives the origin of the Mexican-hat connectivity profile and simulates asymmetric connectivity models S5, S6
spurious_fixed_points.ipynb Searches for spurious fixed points and simulates the attractor's breakup at small N S11, S12
reservoir_rnn.ipynb Trains a reservoir RNN to embed a ring attractor and compares its behaviour with the model's S16
closing_the_loop.ipynb Builds the closed-loop integration results that Figure 2 uses, reading the raw recordings none directly

Installation

conda env create -f ring-local.yml
conda activate ring-local
pip install -e .

These commands install the ring package that the notebooks import. The package uses a GPU when one is available and the CPU otherwise. Check the installation with python tests/test_equivalence.py.

Data

Download the cached results, 2.1 GB, and unpack them into data/:

https://doi.org/10.5281/zenodo.21827767

The .npz files should sit directly in data/, with tc_data.npz in data/mouse_data/. Verify the download with md5sum -c CHECKSUMS.md5 from inside data/. The notebooks will not run without these files. data/README.md says where each one comes from.

You only need the raw recordings from DANDI if you want to rebuild the caches from scratch rather than download them. Only two pieces of code read the raw recordings: python -m ring.data, which builds the tuning curves in mouse_data/tc_data.npz, and notebooks/closing_the_loop.ipynb, which builds closing_the_loop.npz and hd_timeseries.npz. All three output files are in the Zenodo download. Point RING_DATA_DIR at your own copy of the recordings to rerun either.

Reproducing a figure

Each figure comes from one notebook. Run it from top to bottom and the figure is recomputed and displayed inline. FIGURES.md lists every figure with its notebook, the cell that draws it, and the caches it reads.

Two variables at the top of each notebook control whether anything is written to disk. Both variables are False by default, so a normal run changes no files.

  • SAVE_FIGURES = True writes the figure to figures/, replacing the committed image.
  • REGENERATE_CACHES = True recomputes the cached inputs instead of loading them. This takes hours and overwrites the files you downloaded.

Most notebooks are quick. weight_matrix_analyses.ipynb takes about five minutes because it works through a 145 MB cache, and reservoir_rnn.ipynb trains five reservoirs from scratch.

Nearly every figure regenerates identically. A few cannot, for reasons that are properties of the computation rather than faults, such as a spectrum whose degenerate eigenvalues come back in a different order. FIGURES.md names each figure this affects and explains the difference. If you want to check a figure or a cache you regenerated against ours, tools/check_figure_equivalence.py and tools/check_cache_equivalence.py do the comparison.

Repository layout

notebooks/    the eleven analysis notebooks
ring/         the analysis code, installed as an importable package
tests/        checks on the numerical behaviour of the ring package
data/         cached results, downloaded from Zenodo (see data/README.md)
figures/      every figure image the paper uses
docs/         the figure manifest and the documentation site source
tools/        comparison utilities and the documentation generator

FIGURES.md is generated from docs/figure_manifest.yaml by python tools/gen_docs.py, so edit the manifest rather than the generated page.

Citation

If you use this code, please cite the preprint:

@article{clark2025symmetries,
  title   = {Symmetries and continuous attractors in disordered neural circuits},
  author  = {Clark, David G. and Abbott, L. F. and Sompolinsky, Haim},
  journal = {bioRxiv},
  year    = {2025},
  doi     = {10.1101/2025.01.26.634933}
}

The code itself is archived at 10.5281/zenodo.21829584 and the cached results at 10.5281/zenodo.21827767.

Licence

This repository is released under the MIT licence, in LICENSE.

Panel a of the grid-cell figure reproduces published images from Hafting et al. (2005), used with permission from Springer Nature. The Hafting et al. images are excluded from the licence, as described in figures/external/README.md.