Locomotor learning model

Code for Safety prioritization shapes locomotor adaptation and performance by Inseung Kang, Kanishka Mitra and Nidhi Seethapathi. The paper refers to this implementation as InvLocAd. The preprint has the earlier title Fall risk-aware adaptation explains suboptimal locomotor performance.

Code and data (Zenodo) · Preprint · Model guide · Reproduction guide

Contents

• Python model (src/locomotor_learning_model/, command loco-simulate): the locomotor adaptation model of Seethapathi et al. (2024), in which a gradient-based learner updates a step-to-step feedback controller, with the optional fall penalty of the paper's Eq. 2. It runs, pauses and resumes simulations with the model's baseline settings.
• MATLAB manuscript engine (matlab/manuscript/): the model with fall detection and the protocol of the paper's Methods, used for the simulations of Figures 2–4 and Supplementary Figures 1 and 3; the Python model produced those of Supplementary Figures 2 and 4 and the fall-penalty comparison in the Results.
• MATLAB baseline (matlab/src/): the MATLAB version of the Python model, used to check it.
• Figure workflow (command loco-publication): recomputes the paper's figures, tables and statistics from the saved measurements and simulations on Zenodo.

Requirements: Miniforge (Conda), about 30 GB of disk space for the data, and optionally MATLAB R2021a or later for the MATLAB code. The release was tested on macOS (arm64) with MATLAB R2025a; the automated tests also run on Ubuntu.

Install

Download this repository (GitHub Code → Download ZIP, or git clone https://github.com/MIT-Motor-Control/locomotor_learning_model.git) and run from its top-level folder:

conda env create -f environment.yml
conda activate loco-ada
loco-simulate demo

The demo runs 40 learning iterations in a few seconds and writes outputs/demo/split_belt_summary.png. Activate loco-ada in each new terminal before running the commands below.

Run a simulation

loco-simulate run --seed 42 --iterations 1000 --output-dir outputs/my-run

Output	Contents
run.npz	Controller, body-state, energy and learner histories
metadata.json	Seed, condition, protocol, configuration checksum, software versions, iteration counts and summary values
checkpoint.npz, checkpoint.metadata.json	Learner state for resuming the run and its description
split_belt_summary.png	Summary figure (tied_belt_summary.png for tied walking)

The full split-belt protocol has 3,200 iterations: 6 minutes of tied walking, 45 minutes of split-belt walking and 5 minutes of tied walking. To pause after 10 of 20 iterations and resume:

loco-simulate run --seed 42 --iterations 20 --stop-after 10 --output-dir outputs/paused
loco-simulate resume outputs/paused/checkpoint.npz --output-dir outputs/resumed

A resumed run is identical to an uninterrupted run with the same seed. These simulations use the model's baseline settings, not the participant fits of the paper. The model guide maps the paper's parameters to the code and shows how to run the MATLAB manuscript engine with the paper's settings.

Reproduce the paper

1. Download the data (13 GB):

python scripts/download_data.py

This downloads locomotor_learning_model-DATA.zip from Zenodo, verifies its checksum and extracts it to data/locomotor_learning_model-DATA/. Rerun the command to resume an interrupted download. To install a ZIP you already downloaded, run python scripts/download_data.py --archive /path/to/locomotor_learning_model-DATA.zip. The data guide describes the files.

2. Prepare the inputs and reproduce the figures:

loco-publication prepare
loco-publication reproduce --strict

prepare checks all 5,166 inputs against their SHA-256 checksums and writes them to data/publication/; for a DATA folder elsewhere, add --source /path/to/locomotor_learning_model-DATA. reproduce writes outputs/publication/figures/ (PNG, PDF and SVG), outputs/publication/tables/ (CSV source data) and outputs/publication/report.md. MATLAB is not needed.

3. Compare the results with the paper:

loco-publication validate-manuscript

This checks 27 values reported in the paper, including sample sizes, test results, fit errors, fall probabilities and cross-validation results, and writes outputs/manuscript-validation/report.md.

Paper	Analysis	Figures	Tables
Figure 1C–E	figure1	figure1_cd, figure1_e	figure1_*
Figure 2B–C	figure2	figure2b_*, figure2c	figure2b_*, figure2c_*
Figure 3B–D	figure3	figure3_b, figure3_c, figure3_d	figure3_*
Figure 4	figure4	figure4	figure4_*
In-sample fit error (Results) and exponential-fit R² (Methods)	r2	r2_expfit	inverse_fit_rmse_*, r2_*
Fall-penalty comparison (Results) and Supplementary Figure 4	s4	s4_fall_penalty	s4_*
Supplementary Figure 1	s1	s1_loso	s1_*
Supplementary Figure 2	s2	s2_timeseries, s2_adapted	s2_*
Supplementary Figure 3	s3	s3_fall_risk_slices	s3_*

Select analyses with --figures, for example loco-publication reproduce --figures figure3 s1 --output outputs/selected. The workflow recomputes every analysis from saved measurements and simulations, except Supplementary Figure 1, which it replots from saved MATLAB cross-validation results (loco-publication recompute-s1 reruns them). It does not rerun the trajectory optimization, the stochastic parameter sweeps or the processing of raw motion-capture and metabolic recordings, and it does not draw schematic panels. The reproduction guide describes the inputs and methods of each analysis.

Repository map

locomotor_learning_model/
├── src/locomotor_learning_model/
│   ├── learning/             Stance dynamics, objective and learner
│   ├── initializing/         Initial conditions and treadmill speeds
│   ├── parameter_loading/    Model, learner and protocol settings
│   ├── post_processing/      Replay, energetics and summary plots
│   ├── publication/          Figure analyses, data preparation and paper comparison
│   └── cli.py, workflow.py, artifacts.py   Commands, runs and checkpoints
├── matlab/
│   ├── manuscript/           Manuscript simulation engine
│   ├── src/                  MATLAB baseline model
│   ├── run_simulation.m      Run the MATLAB baseline model
│   └── validation/           Python/MATLAB comparison and fit checks
├── scripts/                  Data download, source-data workbook and Python/MATLAB comparison
├── tests/                    Unit, regression and paper-value tests
├── docs/                     Model and reproduction guides
├── reproducibility/          Verification record of this release
├── data/                     Downloaded and prepared data (not tracked)
└── outputs/                  Generated results (not tracked)

Tests

python -m pytest -q

Tests that need the data skip when it is absent. With the data prepared, tests/test_paper_values.py reproduces all analyses and checks them against the paper; set the MATLAB environment variable to the MATLAB executable (with the Statistics and Machine Learning Toolbox) to include the MATLAB tests (manuscript-engine regression and the MATLAB versions of the Supplementary Figure 2 and 4 analyses).

Citation and license

Please cite the paper and the Zenodo record (CITATION.cff). Code is released under the MIT License and data under CC BY 4.0. Contact: Kanishka Mitra, mitra819@mit.edu.