Symmetries and Continuous Attractors in Disordered Neural Circuits¶
Documentation for the code accompanying the paper of that name, by David G. Clark, L. F. Abbott and Haim Sompolinsky. The code is on GitHub and archived at 10.5281/zenodo.21829584.
Each figure in the paper is drawn by one of the eleven notebooks. The notebooks read
precomputed results from data/: tuning curves extracted from the recordings, and the
outputs of the slow simulations and fits. The recordings themselves are from the Peyrache
lab, published separately as
DANDI Dandiset 000939; you do not need them
to reproduce the figures.
Start here¶
Install the environment and the package.
git clone https://github.com/davidclark1/symmetries-continuous-attractors.git
cd symmetries-continuous-attractors
conda env create -f ring-local.yml
conda activate ring-local
pip install -e .
Download the cached results, 2.1 GB, from
10.5281/zenodo.21827767 and unpack the archive into
data/, so that the .npz files sit directly in data/ and tc_data.npz sits in
data/mouse_data/. Then check that the download is intact and that the package imports and
computes what it should.
cd data && md5sum -c CHECKSUMS.md5 && cd ..
python tests/test_equivalence.py
Now open any notebook and run it from top to bottom.
jupyter lab notebooks/dmft.ipynb
dmft.ipynb is a good notebook to start with, because it reads two small caches, involves no random
numbers and finishes quickly. Figure 7 of the paper appears inline as the last cell runs.
Nothing is written to disk unless you change one of the two settings described below.
What is in each notebook¶
| 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 |
The figure page goes the other way, from each figure to the notebook and cell that draws it.
Flags¶
Every notebook starts with two True/False settings, both False, so a normal run writes
nothing to disk.
SAVE_FIGURES = True writes the figure to figures/, replacing the committed image. Turn it
on when you want the figure as a file rather than inline.
REGENERATE_CACHES = True recomputes the cached inputs instead of loading them, then
overwrites the files you downloaded. Leave it off unless you specifically want to rebuild a
cache, since some of the caches take hours to rebuild.
Rebuilding cached results¶
Every file in data/ can be rebuilt with the code in this repository. Three of the files
are built directly from the raw recordings; rebuilding any of the others does not involve
the recordings at all.
Files built from the raw recordings. python -m ring.data reads the recordings and
builds the tuning curves, mouse_data/tc_data.npz. closing_the_loop.ipynb reads the
recordings and builds closing_the_loop.npz and hd_timeseries.npz. To rebuild any of
these three, download the recordings, 52 GB, from
Dandiset 000939 and point RING_DATA_DIR at
the directory holding the sub-* folders.
All other files. Each of these files is written by one of the notebooks, using
simulations and fits rather than the recordings. To rebuild one of these files, open the
notebook that writes that file
(data/README.md
says which), set REGENERATE_CACHES = True at the top, and run the notebook.
One special case. grid_search_results.npz is written by a separate command rather
than by a notebook: python -m ring.gp_opt fits the generative parameters and writes the
file, taking about 13 minutes. The command reads gamma_phi_info.npz, which the early
cells of data_and_generative_model.ipynb write, and the later cells of that same notebook
read the finished fit back in. Rebuilding this chain from scratch therefore takes three
steps: run the notebook, which writes gamma_phi_info.npz and then stops with an error
where the fit is missing; run python -m ring.gp_opt; run the notebook again.
Hardware¶
The code runs on a CPU and uses a GPU when it finds one. Two figures are sensitive to
the hardware that generates them. reservoir_rnn_dynamics.png was made on a GPU and cannot
be reproduced pixel for pixel on a CPU, because torch draws different random numbers on a
CPU than on a GPU, even from the same seed. grid_cell_eigenvalues.pdf shows a six-fold
degenerate eigenvalue spectrum, and the order in which the solver returns eigenvalues
within a degenerate cluster depends on the number of BLAS threads. Neither difference
changes what the figure shows. The figure page explains both cases on the
figures they affect.
Other pages¶
- The figure page maps every figure to the notebook, cell and caches behind it.
- The API reference documents the
ringpackage function by function. tools/check_figure_equivalence.pyandtools/check_cache_equivalence.pycompare a figure or cache you regenerated against the released version.