Soft Robot Models in jaX (SoRoMoX)

📢 Note: SoRoMoX is the successor to the JSRM package. It introduces significant improvements including support for an extended set of systems (Spatial PCS, GVS, and articulated soft robots), replacement of symbolic derivations with numerical implementations for better scalability and faster JIT compilation, and migration from a functional to an object-oriented architecture using Equinox dataclasses for enhanced extendability.

SoRoMoX provides three core capabilities for soft robotics research:

• Soft Robot Models: Kinematic and dynamic models of continuum and articulated soft robots with JAX implementation
• Model-Based Control: Comprehensive suite of controllers including PID, gravity cancellation, potential shaping, impedance control, and computed torque
• Visualization: Multiple rendering backends (Matplotlib, Open3D, Viser, OpenCV) for 2D and 3D visualization

SoRoMoX includes strain-based continuum models for slender structures (Cosserat rods), planar benchmarks, and spatial articulated soft robot systems. The following systems are implemented:

We are happy to receive contributions for other soft robot models. See the Contributing Guide for more details.

Citation

Please use the following citation if you use our software in your (scientific) work:

Software Citation

@software{soromox2026,
  title = {SoRoMoX: Soft Robot Models in JAX},
  author = {Stölzle, Maximilian and Gribonval, Solange and {Feliu-Talegon}, Daniel and Perfetta, Vito Daniele and Martini, Michele and Zhang, Chuhan and Wong, Kiwan and Rus, Daniela and {Della Santina}, Cosimo},
  year = {2026},
  url = {https://github.com/tud-phi/soromox},
  version = {0.2.1},
  abstract = {Kinematic and dynamic models of continuum and articulated soft robots implemented in JAX.}
}

Planar HSA Model Citation

The model of the kinematics and dynamics of the planar HSA robot are part of the publication "An Experimental Study of Model-based Control for Planar Handed Shearing Auxetics Robots" presented at the 18th International Symposium on Experimental Robotics.

@inproceedings{stolzle2023experimental,
  title={An experimental study of model-based control for planar handed shearing auxetics robots},
  author={St{\"o}lzle, Maximilian and Rus, Daniela and Della Santina, Cosimo},
  booktitle={International Symposium on Experimental Robotics},
  pages={153--167},
  year={2023},
  organization={Springer}
}

Model-Based Controllers Citation

If you found the implementation of the model-based controllers (e.g., PID, gravity cancellation, potential shaping regulators) useful, please consider also citing the following PhD thesis:

@phdthesis{stolzle2025phdthesis,
  title = "Safe yet Precise Soft Robots: Incorporating Physics into Learned Models for Control",
  keywords = "Soft Robotics, Nonlinear Control, Machine Learning, Artificial Intelligence",
  author = "Maximilian St{\"o}lzle",
  year = "2025",
  month = "9",
  day = "15",
  language = "English",
  type = "Dissertation (TU Delft)",
  school = "Mechanical Engineering, Delft University of Technology",
  doi = "10.4233/uuid:24c1f667-8fd6-431a-bb78-11d22f8cb3da",
  isbn = "978-94-6384-836-7",
}

Installation

The package can be installed from PyPI using pip:

pip install soromox

or using uv (recommended for faster installation):

uv pip install soromox

Development Installation

For local development from the source code:

# Using pip
pip install -e .

# Using uv
uv pip install -e .

Optional Dependencies (extras)

The default install keeps the runtime dependency set small. Install one or more extras when you need development tools, examples, rendering backends, RL workflows, or the dependencies used to reproduce the paper results.

Quote extras in shell commands so shells such as zsh do not interpret the square brackets as glob patterns. Install from PyPI with:

pip install "soromox[rendering]"
pip install "soromox[rl]"

For a local editable source install, use pip or uv:

pip install -e ".[dev,docs,examples]"
uv pip install -e ".[rendering]"

To reproduce the paper results or run RL experiments from the source checkout:

uv pip install -e ".[paper_results]"
uv pip install -e ".[rl]"

Complete publication workflows, their input and generated data, and committed canonical outputs live under paper_results/. Use the paper_results extra for these workflows; the narrower rl extra remains available for reinforcement-learning-only work.

Using uv for Project Management

You can also use uv to manage the project with a virtual environment:

# Create a virtual environment and install the package
uv venv
uv pip install -e ".[dev,examples]"

# Or use uv sync for reproducible installs (creates uv.lock)
uv sync --extra dev --extra examples
uv sync --extra paper_results
uv sync --extra rl

Running Tests with Coverage

Coverage.py is included in the dev, test, and all extras. To run the test suite with the project coverage settings:

uv run --extra test make coverage

or call Coverage.py directly:

uv run --extra test python -m coverage run -m pytest
uv run --extra test python -m coverage report

For CI uploads, generate an XML report with:

uv run --extra test make coverage_xml

Usage

Simply call one of the example scripts to simulate a system. For example, to simulate the N-link pendulum:

python examples/simulation/pendulum/simulate_pendulum.py

or to simulate the planar PCS robot:

python examples/simulation/pcs/simulate_planar_pcs.py

The lightweight example catalogue and output conventions are documented in examples/README.md. Reproducible paper workflows, including the Section Vc model-based control studies, are under paper_results/:

python paper_results/secVc_model_based_control/configuration_space_comparison/code/setpoint_regulation_comparison.py
python paper_results/secVc_model_based_control/operational_space_impedance_control/code/control_pcs_with_impedance.py

Documentation

The full documentation is available at: https://tud-phi.github.io/soromox

Building Documentation Locally

To build and serve the documentation locally:

# Install documentation dependencies
uv sync --extra docs

# Serve documentation with live reload
uv run --extra docs zensical serve

The documentation will be available at http://127.0.0.1:8000.

Building Documentation for Production

# Build static documentation
uv run --extra docs zensical build --clean

# Zensical does not currently support MkDocs-style strict mode.
# The CI workflow runs the same build command.

You can also use the Makefile targets:

# Serve locally
make docs-serve

# Build documentation
make docs-build

# Build with strict mode checking
make docs-build-strict

Version Management and Releases

This project includes automated version management and release creation tools. The version bump system updates version information across all relevant files and can automatically create GitHub releases.

Version Bumping

You can bump the version using the following Makefile targets:

# Increment patch version (0.1.0 -> 0.1.1) - for bug fixes
make bump-patch

# Increment minor version (0.1.0 -> 0.2.0) - for new features
make bump-minor

# Increment major version (0.1.0 -> 1.0.0) - for breaking changes
make bump-major

# Set a specific version
make bump-version VERSION=0.2.0

Automated Releases

To create a complete release with automatic GitHub release creation:

# Create a patch release with GitHub release
make release-patch

# Create a minor release with GitHub release
make release-minor

# Create a major release with GitHub release
make release-major

# Create a specific version release
make release VERSION=1.0.0

Preview Changes (Dry Run)

Before making any changes, you can preview what would be updated using the dry run mode:

# Preview a patch version bump without making changes
python bump_version.py --patch --dry-run

# Preview a minor version bump
python bump_version.py --minor --dry-run

# Preview a specific version
python bump_version.py 0.2.0 --dry-run

The dry run mode will show you:

• Current version
• New version that would be set
• List of files that would be modified
• No actual changes are made to any files

What Gets Updated

The version bump process automatically updates:

• pyproject.toml - Main project version
• CITATION.cff - Citation version and release date
• README.md and docs/index.md - BibTeX version, year, and citation key
• docs/development/changelog.md - Moves unreleased notes into a dated release
• uv.lock - Local package version

Generated *.egg-info metadata is not tracked or edited; package builds regenerate it from pyproject.toml.

Automated Release Process

When you use the release-* commands, the following happens automatically:

1. Version numbers are updated in all relevant files
2. Changes are committed to git
3. A version tag (e.g., v0.1.1) is created
4. Changes and tags are pushed to GitHub
5. GitHub Actions verifies the tag, builds and validates the distributions once
6. The validated artifacts are attached to a GitHub release
7. The same artifacts are published to PyPI through trusted publishing

Only the release metadata files listed above are staged automatically. Other tracked or untracked worktree files are left untouched.

For more detailed information, see VERSION_BUMP_README.md.