📦 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:

pip install soromox[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
• ffmpeg - Video encoding and processing

📚 Examples Dependencies¶

To run all examples and tutorials:

pip install soromox[examples]

Includes:

• ffmpeg-python - Video encoding and processing
• 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 PlanarPCS, PlanarPCSParams

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

print("🎉 SoRoMoX installation successful!")

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

params = PlanarPCSParams(
    length=jnp.array([0.1, 0.1]),
    radius=jnp.array([0.01, 0.01]),
    density=jnp.array([1000.0, 1000.0]),
    young_modulus=jnp.array([1e6, 1e6]),
    shear_modulus=jnp.array([1e5, 1e5]),
    material_damping_coefficient=jnp.array([318.0, 318.0]),
    reference_strain=jnp.tile(jnp.array([0.0, 1.0, 0.0]), 2),
)
robot = PlanarPCS(params=params)

# 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¶