# alexvoce/cortico-cerebellar_rnns architecture

> Architecture diagram of the GitHub repository alexvoce/cortico-cerebellar_rnns, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexvoce/cortico-cerebellar_rnns
- Repository: https://github.com/alexvoce/cortico-cerebellar_rnns

## Overview

Cortico-cerebellar RNNs trains recurrent models, optionally augmented with a cerebellar-inspired bias, on temporal-memory tasks and analyzes their learning and mechanisms. The principal workflow runs from task selection and sequence generation through model training, curriculum updates, and saved run artifacts. Separate analysis branches cover learning comparisons and mechanistic studies. The README establishes the product capabilities and training entry point; source-index references and excerpts support the implementation links shown. Some analysis relationships are documented at capability level because their run data and wiring were not fully sampled.

Main entry points: [`training/train.py`](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/train.py) (Training entry), [`analysis/model_stepping.py`](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/model_stepping.py) (Model dynamics), [`training/reservoir.py`](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/reservoir.py) (Reservoir curriculum), [`analysis/parity_dynamics.py`](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/parity_dynamics.py) (Parity dynamics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_task_domain["Tasks and curricula"]
  node_task_registry["Task specifications<br/>[registry.py]"]
  node_task_batches["Sequence generators<br/>[task_generators.py]"]
  node_multitask["Multitask training<br/>[multitask.py]"]
  node_task_switch["Task switching<br/>[task_switch.py]"]
  node_continual["Continual training<br/>[continual.py]"]
end

subgraph group_model_domain["Model architectures"]
  node_cb_rnn["CB-RNN<br/>[cb_rnn.py]"]
  node_cb_gru["CB-GRU<br/>[cb_gru.py]"]
end

subgraph group_training_domain["Training and runs"]
  node_train_entry["Training entry<br/>[train.py]"]
  node_base_loop["Shared train loop<br/>[base.py]"]
  node_reservoir_train["Reservoir curriculum<br/>[reservoir.py]"]
  node_curriculum_stages["Reservoir stages<br/>[variants.py]"]
  node_train_utils["Optimizer utilities<br/>[utils.py]"]
  node_run_saving["Run artifacts<br/>[save.py]"]
end

subgraph group_analysis_domain["Learning analyses"]
  node_single_task_analysis["Single-task comparisons"]
  node_learning_plots["Learning plots"]
  node_learning_metrics["Learning metrics"]
  node_scaling["Model scaling<br/>[scaling.py]"]
  node_switching_plots["Multitask comparisons"]
end

subgraph group_mechanism_domain["Mechanism analyses"]
  node_cb_ablation["CB ablation<br/>[cb_ablation.py]"]
  node_model_rebuild["Model reconstruction"]
  node_model_stepping["Model dynamics<br/>[model_stepping.py]"]
  node_dms_dynamics["DMS dynamics<br/>[dms_dynamics.py]"]
  node_dms_propagation["DMS propagation"]
  node_jacobian["Jacobian analysis<br/>[jacobian.py]"]
  node_parity_dynamics["Parity dynamics<br/>[parity_dynamics.py]"]
  node_parity_update["Parity update rules"]
  node_predictive["Predictive analysis"]
  node_cb_encoding["CB encoding"]
  node_readout_recovery["Readout recovery"]
  node_dimensionality["State dimensionality"]
  node_timescales["Timescale analysis<br/>[timescales.py]"]
  node_mechanism_plots["Mechanism figures<br/>[mechanism_plots.py]"]
end

node_researcher(("Researcher"))
node_run_artifacts[("Trained runs")]

node_researcher -->|"launches"| node_train_entry
node_train_entry -->|"selects task"| node_task_registry
node_task_registry -->|"uses batches"| node_task_batches
node_train_entry -->|"configures model"| node_cb_rnn
node_train_entry -->|"configures model"| node_cb_gru
node_cb_gru -->|"reuses CB bias"| node_cb_rnn
node_train_entry -->|"dispatches mode"| node_multitask
node_train_entry -->|"dispatches mode"| node_task_switch
node_train_entry -->|"dispatches mode"| node_continual
node_train_entry -->|"dispatches mode"| node_reservoir_train
node_reservoir_train -->|"uses stages"| node_curriculum_stages
node_reservoir_train -->|"uses optimizers"| node_train_utils
node_base_loop -->|"reads specs"| node_task_registry
node_base_loop -->|"uses utilities"| node_train_utils
node_train_entry -->|"saves runs"| node_run_saving
node_reservoir_train -->|"saves runs"| node_run_saving
node_run_saving -->|"writes artifacts"| node_run_artifacts
node_run_artifacts -->|"supplies runs"| node_single_task_analysis
node_run_artifacts -->|"supplies runs"| node_learning_metrics
node_single_task_analysis -->|"supports figures"| node_learning_plots
node_learning_plots -->|"provides plotting"| node_scaling
node_run_artifacts -->|"supplies runs"| node_switching_plots
node_run_artifacts -->|"supplies runs"| node_cb_ablation
node_cb_ablation -->|"uses reconstruction"| node_model_rebuild
node_model_stepping -->|"rebuilds models"| node_model_rebuild
node_model_stepping -->|"generates trials"| node_task_batches
node_dms_dynamics -->|"rolls out models"| node_model_stepping
node_dms_propagation -->|"uses dynamics"| node_model_stepping
node_dms_propagation -->|"uses metrics"| node_dms_dynamics
node_jacobian -->|"uses dynamics"| node_model_stepping
node_parity_dynamics -->|"uses dynamics"| node_model_stepping
node_parity_dynamics -->|"uses prediction"| node_predictive
node_parity_update -->|"uses dynamics"| node_model_stepping
node_parity_update -->|"uses trials"| node_parity_dynamics
node_predictive -->|"uses ablation data"| node_cb_ablation
node_cb_encoding -->|"uses dynamics"| node_parity_dynamics
node_cb_encoding -->|"uses update analysis"| node_parity_update
node_cb_encoding -->|"uses Jacobians"| node_jacobian
node_readout_recovery -->|"uses ablation"| node_cb_ablation
node_dimensionality -->|"rebuilds models"| node_model_rebuild
node_run_artifacts -->|"supplies runs"| node_dimensionality
node_run_artifacts -->|"supplies runs"| node_timescales
node_run_artifacts -->|"supplies runs"| node_mechanism_plots

click node_train_entry "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/train.py"
click node_task_registry "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/registry.py"
click node_task_batches "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/task_generators.py"
click node_multitask "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/multitask.py"
click node_task_switch "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/task_switch.py"
click node_continual "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/continual.py"
click node_cb_rnn "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/model/cb_rnn.py"
click node_cb_gru "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/model/cb_gru.py"
click node_base_loop "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/base.py"
click node_reservoir_train "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/reservoir.py"
click node_curriculum_stages "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/variants.py"
click node_train_utils "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/utils.py"
click node_run_saving "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/save.py"
click node_single_task_analysis "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/single_task_analysis_utils.py"
click node_learning_plots "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/single_task_plotting_utils.py"
click node_learning_metrics "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/learning_metrics.py"
click node_scaling "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/scaling.py"
click node_switching_plots "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/multitask_switching_plotting_utils.py"
click node_cb_ablation "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/cb_ablation.py"
click node_model_rebuild "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/rebuild_model_utils.py"
click node_model_stepping "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/model_stepping.py"
click node_dms_dynamics "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/dms_dynamics.py"
click node_dms_propagation "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/dms_memory_propagation.py"
click node_jacobian "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/jacobian.py"
click node_parity_dynamics "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/parity_dynamics.py"
click node_parity_update "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/parity_update_rule.py"
click node_predictive "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/predictive_analysis.py"
click node_cb_encoding "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/parity_cb_encoding.py"
click node_readout_recovery "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/readout_recovery.py"
click node_dimensionality "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/pca_dimensionality.py"
click node_timescales "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/timescales.py"
click node_mechanism_plots "https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/mechanism_plots.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_task_registry,node_task_batches,node_multitask,node_task_switch,node_continual toneBlue
class node_cb_rnn,node_cb_gru,node_run_artifacts toneAmber
class node_train_entry,node_base_loop,node_reservoir_train,node_curriculum_stages,node_train_utils,node_run_saving toneMint
class node_single_task_analysis,node_learning_plots,node_learning_metrics,node_scaling,node_switching_plots toneRose
class node_cb_ablation,node_model_rebuild,node_model_stepping,node_dms_dynamics,node_dms_propagation,node_jacobian,node_parity_dynamics,node_parity_update,node_predictive,node_cb_encoding,node_readout_recovery,node_dimensionality,node_timescales,node_mechanism_plots,node_researcher toneIndigo
```

## Components

### Tasks and curricula

- [Task specifications](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/registry.py): `tasks/registry.py`
- [Sequence generators](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/task_generators.py): `tasks/task_generators.py`
- [Multitask training](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/multitask.py): `tasks/multitask.py`
- [Task switching](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/task_switch.py): `tasks/task_switch.py`
- [Continual training](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/tasks/continual.py): `tasks/continual.py`

### Model architectures

- [CB-RNN](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/model/cb_rnn.py): `model/cb_rnn.py`
- [CB-GRU](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/model/cb_gru.py): `model/cb_gru.py`

### Training and runs

- [Training entry](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/train.py): `training/train.py`
- [Shared train loop](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/base.py): `training/base.py`
- [Reservoir curriculum](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/reservoir.py): `training/reservoir.py`
- [Reservoir stages](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/variants.py): `training/variants.py`
- [Optimizer utilities](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/utils.py): `training/utils.py`
- [Run artifacts](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/training/save.py): `training/save.py`

### Learning analyses

- [Single-task comparisons](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/single_task_analysis_utils.py): `analysis/single_task_analysis_utils.py`
- [Learning plots](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/single_task_plotting_utils.py): `analysis/single_task_plotting_utils.py`
- [Learning metrics](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/learning_metrics.py): `analysis/learning_metrics.py`
- [Model scaling](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/scaling.py): `analysis/scaling.py`
- [Multitask comparisons](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/multitask_switching_plotting_utils.py): `analysis/multitask_switching_plotting_utils.py`

### Mechanism analyses

- [CB ablation](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/cb_ablation.py): `analysis/cb_ablation.py`
- [Model reconstruction](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/rebuild_model_utils.py): `analysis/rebuild_model_utils.py`
- [Model dynamics](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/model_stepping.py): `analysis/model_stepping.py`
- [DMS dynamics](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/dms_dynamics.py): `analysis/dms_dynamics.py`
- [DMS propagation](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/dms_memory_propagation.py): `analysis/dms_memory_propagation.py`
- [Jacobian analysis](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/jacobian.py): `analysis/jacobian.py`
- [Parity dynamics](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/parity_dynamics.py): `analysis/parity_dynamics.py`
- [Parity update rules](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/parity_update_rule.py): `analysis/parity_update_rule.py`
- [Predictive analysis](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/predictive_analysis.py): `analysis/predictive_analysis.py`
- [CB encoding](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/parity_cb_encoding.py): `analysis/parity_cb_encoding.py`
- [Readout recovery](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/readout_recovery.py): `analysis/readout_recovery.py`
- [State dimensionality](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/pca_dimensionality.py): `analysis/pca_dimensionality.py`
- [Timescale analysis](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/timescales.py): `analysis/timescales.py`
- [Mechanism figures](https://github.com/alexvoce/cortico-cerebellar_rnns/blob/main/analysis/mechanism_plots.py): `analysis/mechanism_plots.py`

### Other components

- **Researcher**
- **Trained runs**

## Connections

- Researcher → Training entry: launches (evidence: `README.md`)
- Training entry → Task specifications: selects task (evidence: `training/train.py`)
- Task specifications → Sequence generators: uses batches (evidence: `tasks/registry.py`)
- Training entry → CB-RNN: configures model (evidence: `training/train.py`)
- Training entry → CB-GRU: configures model (evidence: `training/train.py`)
- CB-GRU → CB-RNN: reuses CB bias (evidence: `model/cb_gru.py`)
- Training entry → Multitask training: dispatches mode (evidence: `training/train.py`)
- Training entry → Task switching: dispatches mode (evidence: `training/train.py`)
- Training entry → Continual training: dispatches mode (evidence: `training/train.py`)
- Training entry → Reservoir curriculum: dispatches mode (evidence: `training/train.py`)
- Reservoir curriculum → Reservoir stages: uses stages (evidence: `training/reservoir.py`)
- Reservoir curriculum → Optimizer utilities: uses optimizers (evidence: `training/reservoir.py`)
- Shared train loop → Task specifications: reads specs (evidence: `training/base.py`)
- Shared train loop → Optimizer utilities: uses utilities (evidence: `training/base.py`)
- Training entry → Run artifacts: saves runs (evidence: `training/train.py`)
- Reservoir curriculum → Run artifacts: saves runs (evidence: `training/reservoir.py`)
- Run artifacts → Trained runs: writes artifacts (evidence: `README.md`)
- Trained runs → Single-task comparisons: supplies runs (evidence: `README.md`)
- Trained runs → Learning metrics: supplies runs (evidence: `README.md`)
- Single-task comparisons → Learning plots: supports figures (evidence: `README.md`)
- Learning plots → Model scaling: provides plotting (evidence: `analysis/scaling.py`)
- Trained runs → Multitask comparisons: supplies runs (evidence: `README.md`)
- Trained runs → CB ablation: supplies runs (evidence: `README.md`)
- CB ablation → Model reconstruction: uses reconstruction (evidence: `analysis/cb_ablation.py`)
- Model dynamics → Model reconstruction: rebuilds models (evidence: `analysis/model_stepping.py`)
- Model dynamics → Sequence generators: generates trials (evidence: `analysis/model_stepping.py`)
- DMS dynamics → Model dynamics: rolls out models (evidence: `analysis/dms_dynamics.py`)
- DMS propagation → Model dynamics: uses dynamics (evidence: `analysis/dms_memory_propagation.py`)
- DMS propagation → DMS dynamics: uses metrics (evidence: `analysis/dms_memory_propagation.py`)
- Jacobian analysis → Model dynamics: uses dynamics (evidence: `analysis/jacobian.py`)
- Parity dynamics → Model dynamics: uses dynamics (evidence: `analysis/parity_dynamics.py`)
- Parity dynamics → Predictive analysis: uses prediction (evidence: `analysis/parity_dynamics.py`)
- Parity update rules → Model dynamics: uses dynamics (evidence: `analysis/parity_update_rule.py`)
- Parity update rules → Parity dynamics: uses trials (evidence: `analysis/parity_update_rule.py`)
- Predictive analysis → CB ablation: uses ablation data (evidence: `analysis/predictive_analysis.py`)
- CB encoding → Parity dynamics: uses dynamics (evidence: `analysis/parity_cb_encoding.py`)
- CB encoding → Parity update rules: uses update analysis (evidence: `analysis/parity_cb_encoding.py`)
- CB encoding → Jacobian analysis: uses Jacobians (evidence: `analysis/parity_cb_encoding.py`)
- Readout recovery → CB ablation: uses ablation (evidence: `analysis/readout_recovery.py`)
- State dimensionality → Model reconstruction: rebuilds models (evidence: `analysis/pca_dimensionality.py`)
- Trained runs → State dimensionality: supplies runs (evidence: `README.md`)
- Trained runs → Timescale analysis: supplies runs (evidence: `README.md`)
- Trained runs → Mechanism figures: supplies runs (evidence: `README.md`)
