📦 Installation¶

Get started with SoRoMoX in minutes! Choose from multiple installation methods to get Soft Robot Models in jaX (SoRoMoX) running on your system.

🔧 Requirements¶

🚀 Quick Install¶

pip install soromox

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install soromox
uv pip install soromox

git clone https://github.com/tud-phi/soromox.git
cd soromox
pip install -e .

🎯 Installation Options¶

SoRoMoX provides several optional dependency groups for different use cases:

🎨 Rendering Dependencies¶

For 3D visualization and animation, install from a source checkout:

uv sync --extra rendering

Includes:

• matplotlib - For 2D plotting and simple rendering of the backbone shape
• open3d - High-quality 3D visualization
• viser - Web-based interactive rendering
• opencv-python - 2D rendering for planar robots

python -m pip install ./third_party/open3d
python -m pip install -e ".[rendering]"

📚 Examples Dependencies¶

To run all examples and tutorials:

pip install soromox[examples]

Includes:

• ipython - Enhanced interactive Python shell
• matplotlib - Publication-ready plotting and visualization
• open3d - High-quality 3D visualization
• opencv-python - Computer vision and image processing
• optimistix - Nonlinear solvers for root finding, minimization, fixed points, and least squares optimization in JAX
• plotly - Interactive plotting and visualization
• seaborn - Statistical data visualization
• viser - Web-based interactive rendering

🛠️ Development Dependencies¶

For contributing to SoRoMoX:

pip install soromox[dev]

Includes:

• pytest - Testing framework
• ruff - Fast Python linter and formatter
• mypy - Static type checking
• pre-commit - Git hooks for code quality

📖 Documentation Dependencies¶

To build documentation locally:

pip install soromox[docs]

Includes:

• zensical - Documentation site generator
• mkdocstrings-python - API documentation generation

🎉 Complete Installation¶

Get everything at once:

pip install soromox[all]

This installs all optional dependencies including rendering, examples, development tools, and documentation builders.

uv pip install soromox[rendering,examples]

✅ Verification¶

Test your installation with this quick verification script:

import jax.numpy as jnp
from soromox.systems import LinkSpec, PlanarPCS

# Create a simple 1-segment PCS robot
robot = PlanarPCS.from_links([LinkSpec.circular(
    length=0.1, radius=0.01, density=1000.0,
    young_modulus=1e6, shear_modulus=1e5,
    material_damping_coefficient=318.0,
    reference_strain=[0.0, 1.0, 0.0],
)])
robot.forward_kinematics(jnp.zeros(robot.num_coordinates), s=0.1)

print("🎉 SoRoMoX installation successful!")

import jax
import jax.numpy as jnp
from soromox.systems import LinkSpec, PlanarPCS

robot = PlanarPCS.from_links([
    LinkSpec.circular(
        length=0.1, radius=0.01, density=1000.0,
        young_modulus=1e6, shear_modulus=1e5,
        material_damping_coefficient=318.0,
        reference_strain=[0.0, 1.0, 0.0],
    )
    for _ in range(2)
])

# Test JAX compilation and differentiation. Same-shape params updates keep
# the PyTree layout fixed and avoid recompilation.
@jax.jit
def test_function(q):
    return robot.forward_kinematics(q, s=0.2)

# Test with sample configuration
q = jnp.array([0.1, 0.0, 0.0, 0.1, 0.0, 0.0])
result = test_function(q)

# Test differentiation
grad_fn = jax.grad(lambda q: jnp.sum(test_function(q)**2))
gradient = grad_fn(q)

print(f"✅ Forward kinematics: {result}")
print(f"✅ Gradient computation: {gradient}")
print("🎉 Advanced features working perfectly!")

🔧 Troubleshooting¶

python --version  # Should be >= 3.11

# For CPU only
pip install jax[cpu]

# For NVIDIA GPU
pip install jax[cuda12_pip]

# For Apple Silicon
pip install jax[metal]

🆘 Getting Help¶