Salp Simulation Python Toolkit

Overview

This repository implements numerical models, control design utilities, and workflow scripts for simulating chained salp locomotion systems using the JAX ecosystem. It provides a self-contained toolkit for designing thruster profiles, propagating system dynamics, and visualizing or analyzing simulation results.

Features

• Chain system modeling: Implements forward kinematics, differential kinematics, and viscous drag metrics for articulated chains, including helper functions to build consistent system dictionaries for downstream components. (chain_system.py)
• Control profile optimization: Provides averaged velocity estimation, quadratic-program helpers, and semidefinite relaxations for shaping periodic thruster profiles; supports both MOSEK-based semidefinite programming and SciPy-based nonlinear optimization. (control.py)
• Dynamics simulation: Wraps Diffrax integrators with JAX just-in-time compilation to evolve the augmented state, apply feedback corrections, and sample trajectories and thruster signals. (simulation.py)
• Workflow scripts: Supplies command-line entry points for single- and multi-chain simulations, along with end-to-end analysis pipelines that export plots and animations. (simulate_single_chain.py, simulate_multiple_chain.py, analysis_single_chain.py)
• Visualization: Generates Matplotlib figures and animations summarizing pose, joint, and thruster evolutions, suitable for exploratory analysis or publication-quality artifacts. (animation.py, analysis_single_chain.py)
• Comprehensive tests: Unit and workflow tests validate kinematic routines, control design helpers, simulation utilities, and analysis pipelines. (tests/)

Installation

1. Create and activate a Python 3.10+ environment.
2. Install dependencies:

   pip install -r requirements.txt

3. Obtain a MOSEK license if you plan to use the semidefinite programming workflow in control.py.

Quick Start

Simulate a Single Chain

python simulate_single_chain.py --preset landsalp --simulation-cycles 6

This command generates a pickle archive with time, state, control histories, and optional animations when --animate-result is provided.

Batch Simulations

python simulate_multiple_chain.py 6 12 18 --simulation-cycles 10 --animate

The script iterates over link counts, stores outputs in the tmp/ directory by default, and can export animations for each configuration.

Note: Batch simulation and batch analysis workflows are still under development and are not yet ready for production use.

Analyze Results

python analysis_single_chain.py path/to/result.pkl --save-directory reports

The analyzer exports SVG figures and optional GIF or MP4 animations summarizing pose, joint angles, and thruster commands.

Running Tests

Execute the automated test suite with pytest:

python -m pytest

The tests cover kinematics, control utilities, simulation accuracy, and the full single-chain workflow, including artifact generation.

Project Layout

.
├── animation.py               # Animation helpers for trajectories
├── analysis_single_chain.py   # Plotting and reporting utilities
├── analysis_multiple_chain.py # Comparative analysis for multiple chains
├── chain_system.py            # Core kinematics and metric computations
├── control.py                 # Control profile optimization routines
├── simulation.py              # Diffrax-based dynamics integrators
├── simulate_single_chain.py   # CLI for single-chain simulations
├── simulate_multiple_chain.py # CLI for batch simulations
├── utilities.py               # Linear algebra helpers and I/O utilities
├── tests/                     # Unit and workflow test suites
└── requirements.txt           # Python dependency list

Citation

If this toolkit contributes to your research, please cite the following work:

@article{yang2025geometric,
  title        = {Geometric Data-Driven Multi-Jet Locomotion Inspired by Salps},
  author       = {Yanhao Yang and Nina L. Hecht and Yousef Salaman-Maclara and Nathan Justus and Zachary A. Thomas and Farhan Rozaidi and Ross L. Hatton},
  journal      = {arXiv:2503.08817 [cs.RO]},
  year         = {2025},
  url_info     = {https://arxiv.org/abs/2503.08817},
  url_pdf      = {https://arxiv.org/pdf/2503.08817}
}

Licensing

The project is distributed under the terms of the MIT License. See LICENSE for details.