Examples¶

See Parameters, Updates, and Optimization for complete construction, immutable update, JAX, and Optax examples.

This page provides a comprehensive overview of the example scripts included with SoRoMoX. Examples are organized by application area to help you find the right starting point for your use case.

Overview¶

SoRoMoX examples are organized into two main categories:

• Simulation Examples - Dynamic simulations of various robot systems
• Control Examples - Control algorithms for different control spaces

Reproducible paper benchmarks, system identification, optimization, and application studies are catalogued separately in paper_results/README.md.

Simulation Examples¶

Simulation examples demonstrate how to model and simulate different types of robotic systems using SoRoMoX. These examples are located in examples/simulation/ and are organized by robot type.

Articulated Systems¶

Articulated systems model serial rigid-link chains. They include planar pendulum benchmarks, tendon-actuated pendulums, and spatial articulated soft robots with optional joint stiffness and damping.

N-Link Pendulum¶

python examples/simulation/pendulum/simulate_pendulum.py

What you'll learn: - Basic pendulum dynamics and numerical integration with JAX - How to visualize results and compute energy (kinetic and potential) - Working with SystemState and the rollout_to() method - End-effector trajectory computation

Key concepts: Rigid-body dynamics, state-space representation, forward kinematics

To simulate a double pendulum, modify the num_links variable in the script:

num_links = 2  # Change this line

Tendon-Actuated Pendulum¶

python examples/simulation/pendulum/simulate_tendon_actuated_pendulum.py

What you'll learn: - Cable-driven actuation modeling - Tendon routing and tension mapping - Control applications with underactuated systems

Key concepts: Actuation mapping, tendon kinematics, underactuation

Spatial Articulated Soft Robot¶

python examples/simulation/articulated/simulate_articulated_soft_robot.py

The example simulates a four-link spatial chain, plots joint states, end-effector motion, and energies, then launches a Matplotlib animation by default. Use --render open3d, --render viser, or --render all to try the optional interactive renderers.

What you'll learn: - Building a spatial serial chain with screw-axis joints - Adding passive joint stiffness and damping - Simulating with ABA-based forward dynamics through the standard rollout_to() API - Rendering with Matplotlib, Open3D, or Viser backends

Key concepts: Spatial articulated dynamics, compliant joints, ABA forward dynamics

PCS (Piecewise Constant Strain) Robots¶

PCS robots are continuum robots modeled using the Piecewise Constant Strain approach, which discretizes the robot into segments with constant strain parameters.

Planar PCS Robot¶

python examples/simulation/pcs/simulate_planar_pcs.py

What you'll learn: - Piecewise Constant Strain (PCS) kinematics for 2D continuum robots - Continuum robot dynamics using Cosserat rod theory - Forward kinematics and Jacobian computation - Visualization with Matplotlib and OpenCV renderers

Key concepts: PCS modeling, strain parameterization, planar kinematics

Spatial PCS Robot¶

python examples/simulation/pcs/simulate_pcs.py

What you'll learn: - 3D continuum robot modeling with full spatial kinematics - Six-degree-of-freedom strain representation (bending + extension + shear) - Spatial forward kinematics and workspace analysis

Key concepts: Spatial PCS, 6-DOF strains, 3D kinematics

Tendon-Actuated PCS Robots¶

# Planar version
python examples/simulation/pcs/simulate_tendon_actuated_planar_pcs.py

# Spatial version
python examples/simulation/pcs/simulate_tendon_actuated_pcs.py

# Batched simulation for performance analysis
python examples/simulation/pcs/simulate_batched_tendon_actuated_pcs.py

What you'll learn: - Tendon routing and actuation mapping for continuum robots - Cable-driven soft robot control - Batch processing for performance benchmarking

Key concepts: Tendon kinematics, actuation space, batch simulation

I-SUPPORT Manipulator¶

python examples/simulation/pcs/simulate_isupport.py

What you'll learn: - Modeling of 3D-printed pneumatic soft robotic arms - Real-world system parameter adaptation - Multi-segment pneumatic continuum robots

Key concepts: Additive manufacturing, pneumatic actuation, real-world applications

Planar HSA Robot¶

Planar HSA robots are a specialized PCS family using auxetic materials that exhibit unique deformation characteristics under actuation.

# Planar HSA simulation
python examples/simulation/pcs/simulate_planar_hsa.py

What you'll learn: - Handed Shearing Auxetics (HSA) mechanics and unique deformation characteristics - Practical control applications with HSA robots

Key concepts: HSA mechanics, auxetic materials, PCS simulation

GVS (Geometric Variable Strain) Robots¶

GVS robots use flexible strain basis functions for advanced continuum robot modeling.

Basic GVS Robots¶

# Basic GVS simulation
python examples/simulation/gvs/simulate_gvs.py

What you'll learn: - Geometric Variable Strain modeling - Flexible strain basis functions - Advanced continuum robot dynamics

Key concepts: GVS modeling, basis functions, advanced kinematics

Low-Dimensional Rigid-Soft Pendulums¶

# Fixed-base affine Soft Inverted Pendulum
python examples/simulation/gvs/simulate_soft_inverted_pendulum.py

# Base-torque-actuated R-SIP
python examples/simulation/gvs/simulate_r_soft_inverted_pendulum.py

# Force-actuated cart with a passive revolute pole hinge
python examples/simulation/gvs/simulate_soft_cart_pole.py

# The same Cart-Pole with stiffness derived from E, radius, and link length
python examples/simulation/gvs/simulate_soft_cart_pole.py --stiffness-mode material_derived

# First-joint-torque-actuated two-link Pendubot
python examples/simulation/gvs/simulate_soft_pendubot.py

# First-joint-torque-actuated spatial Furuta pendulum
python examples/simulation/gvs/simulate_soft_furuta.py

Every soft link uses two dimensionless affine bending-angle coefficients, kappa(X) = (a0 + a1 X/L) / L, through scale_rotational_basis_by_length=True. The fixed SIP, R-SIP, and Cart-Pole use the explicit affine constitutive matrices and link properties from Della Santina (2020); their 1 kg link mass is distributed rather than concentrated at the tip. The R-SIP base-joint damping follows Caradonna et al. (2024).

The Cart-Pole coordinate order is [d, theta, a0, a1]. Only d is actuated, the revolute hinge is passive, and the all-zero configuration points straight upward. This differs by an angle offset from the convention in Caradonna et al. (2026): theta_model = theta_paper - pi. Its finite rigid cart/pivot link has exposed assumed length, radius, and mass parameters.

The SIP, R-SIP, and Cart-Pole support explicit_affine and material_derived soft-link stiffness modes. The backward-compatible explicit mode uses K = k H. The material mode uses K = E I/L H with I = pi r^4/4; its defaults are E = 1 MPa and r = 0.03 m, giving E I/L = 0.6362 N m. Only stiffness changes between modes: soft-link mass, inertial geometry, and damping remain the SIP defaults.

The Pendubot and Furuta use the 2026 paper's cylindrical soft-link properties (L = 1 m, R = 0.03 m, rho = 1000 kg/m^3, E = 1 MPa, and beta = 0.01 MPa s) but restrict deformation to affine bending. SoRoMoX uses G = E/3 instead of the boundary value nu = 0.5. The Pendubot splits the soft length equally between its two links. Because the paper does not report Furuta rigid-arm inertia, its default 0.5 m length, 0.02 m radius, and 0.5 kg mass are documented, configurable assumptions.

Actuation matches the cited systems: base torque for R-SIP, cart force for the Cart-Pole, and first-joint torque for Pendubot and Furuta. Metadata bounds are respectively unbounded, +/-200 N, +/-10 N m, and +/-80 N m; the model does not implicitly clip an input. Controllers are intentionally outside these open-loop examples.

Each script saves a four-panel summary figure and launches an interactive Viser rendering by default. The Cart-Pole renderer synchronizes the backbone with a moving cart, wheels, and rail. Use --record-viser to capture one playback or --no-viser --no-show for headless execution. Default ports are 8080 through 8084 in the command order above, and every script accepts --viser-port.

What you'll learn: - Affine-curvature GVS construction with two bending coordinates - Hybrid rigid-joint, rigid-link, and affine soft-link topology - Signed direct force/torque routing with passive coordinates - Physically named upright and hanging configuration helpers - Interactive trajectory playback and recording with Viser

Key concepts: Affine curvature, underactuation, R-SIP, Cart-Pole, Pendubot, Furuta, Viser

Tendon-Actuated GVS Robot¶

python examples/simulation/gvs/simulate_tendon_actuated_gvs.py

What you'll learn: - Routing tendon actuation through a variable-strain continuum model - Simulating and rendering an actuated GVS robot

Key concepts: GVS modeling, tendon actuation, continuum routing

Control Examples¶

Control examples demonstrate various control algorithms for different control spaces. These examples are located in examples/control/ and are organized by control space type.

Operational-Space Controllers¶

Operational-space controllers operate on the robot's end-effector or task-space coordinates.

Synergistic Control¶

python examples/control/operational_space/control_tendon_actuated_pcs_with_synergistic.py

What you'll learn: - Operational-space control for an underactuated tendon-driven PCS robot - End-effector position tracking with actuation synergies - Task-space reference generation

Key concepts: Operational-space control, underactuation, synergistic control

Actuation-Space Controllers¶

Actuation-space controllers operate directly on the actuator inputs (e.g., tendon tensions, chamber pressures).

Setpoint Regulation¶

python examples/control/actuation_space/setpoint_regulation_comparison.py

What you'll learn: - Control in actuation space - Direct actuator command generation - Comparison of actuation-space control strategies

Key concepts: Actuation-space control, actuator mapping, direct control

Running Examples¶

Prerequisites¶

Install SoRoMoX with example dependencies:

pip install -e ".[examples]"

This installs additional packages needed for visualization and analysis: - matplotlib - Plotting and visualization - open3d - 3D visualization - opencv-python - 2D rendering for planar robots - optimistix - Optimization (for system identification examples) - plotly - Interactive plotting and visualization - seaborn - Statistical data visualization - viser - Interactive 3D visualization

Basic Workflow¶

Follow these steps to run any example:

1. Navigate to the project root (if not already there):

   cd /path/to/soromox
   

2. Run the example:

   python examples/[category]/[subcategory]/[example_name].py
   

For example:

python examples/simulation/pendulum/simulate_pendulum.py
python examples/control/actuation_space/setpoint_regulation_comparison.py

1. Analyze results in generated plots and videos

Expected outputs: - Interactive plots using Matplotlib (may require GUI backend) - Video files in the videos/ directory (if video rendering is enabled) - Console output with simulation statistics and results - Analysis plots and comparison figures (for control examples)

Customizing Examples¶

All examples are designed to be easily customizable. This section shows you how to modify parameters, outputs, and initial conditions.

Parameter Modification¶

Most examples allow easy parameter modification. Understanding parameter structure is key to adapting examples to your needs.

For PCS systems:

# Modify canonical runtime link parameters
section = robot.params.link.cross_section.replace(
    coefficients=0.9 * robot.params.link.cross_section.coefficients
)
robot = robot.update_link_params(
    length=0.2 * jnp.ones((num_segments,)),
    cross_section=section,
)

# Material variables are caller-owned and applied explicitly.
material = material.replace(
    young_modulus=1e6 * jnp.ones((num_segments,)),
    shear_modulus=5e5 * jnp.ones((num_segments,)),
)
robot = robot.with_isotropic_material(material)

For pendulum systems:

params = params.replace(
    length=jnp.array([0.5, 0.3]),
    mass=jnp.array([1.0, 0.5]),
    moment_inertia=jnp.array([0.1, 0.05]),
)
robot = robot.with_params(params)

For articulated soft robot systems:

params = params.replace(
    joint_screw=joint_screws,
    tip_position=tip_positions,
    center_of_mass_position=center_of_mass_positions,
    mass=masses,
    center_of_mass_inertia=center_of_mass_inertia,
    joint_stiffness=jnp.diag(joint_stiffness),
    joint_damping=jnp.diag(joint_damping),
)
robot = robot.with_params(params)

Output Customization¶

Control visualization and output:

# Adjust simulation time
t0 = 0.0
t1 = 10.0  # 10 seconds

# Change integration parameters
solver_dt = 0.001  # Smaller timestep for higher accuracy
save_dt = 0.01     # Output frequency

# Video settings (if using renderers)
video_width, video_height = 800, 800

Initial Conditions¶

Modify initial configurations and velocities:

# For pendulum systems
q0 = jnp.array([jnp.pi/4, jnp.pi/6])  # Initial joint angles
qd0 = jnp.zeros_like(q0)                # Initial velocities

# For articulated soft robot systems
q0 = jnp.array([0.35, -0.45, 0.28, -0.20])  # Initial joint coordinates
qd0 = jnp.zeros_like(q0)

# For PCS systems
q0 = jnp.array([0.1, 0.0, 0.0,  # Segment 1 strains
                0.2, 0.0, 0.0]) # Segment 2 strains
qd0 = jnp.zeros_like(q0)

Control Parameters¶

For control examples, you can modify controller gains:

# PID controller gains
kp = 100.0  # Proportional gain
ki = 10.0   # Integral gain
kd = 5.0    # Derivative gain

# Impedance controller parameters
K_x = 100.0 * jnp.eye(3)  # Stiffness matrix
D_x = 10.0 * jnp.eye(3)   # Damping matrix

Troubleshooting¶

Common Issues¶

Performance Tips¶

• Accuracy vs. Speed: Use smaller solver_dt for higher accuracy and improved simulation stability, larger for faster simulation
• JIT Compilation: JAX JIT compilation is automatically used in most examples for optimal performance
• GPU Acceleration: Consider using GPU acceleration for large-scale batch simulations
• Batched Simulations: For batched simulations, see simulate_batched_tendon_actuated_pcs.py as a reference
• Memory Management: Be mindful of array sizes in batch operations to avoid memory issues
• System Identification: For parameter identification, start with reasonable initial guesses and use appropriate optimization algorithms. Gradient descent will often only work locally.

Creating New Examples¶

To create a new example:

1. Choose a base example similar to your use case from the appropriate category:
2. examples/simulation/ for new robot systems

3. examples/control/ for new control algorithms

4. Copy and modify parameters and logic

5. Test thoroughly with different configurations
6. Write generated artifacts to sibling figures/ or videos/ directories

Example Template¶

Here's a minimal working example you can use as a starting point:

#!/usr/bin/env python3
"""
New Example: Description of what this example demonstrates
"""

import jax
import jax.numpy as jnp
from soromox.systems import YourSystem, SystemState

# Configure JAX (if needed)
jax.config.update("jax_enable_x64", True)  # double precision

# Parameters
params = YourSystemParams(...)

if __name__ == "__main__":
    # Initialize system
    robot = YourSystem(params=params)

    # Set initial conditions
    q0 = jnp.array([...])  # Initial configuration
    qd0 = jnp.zeros_like(q0)  # Initial velocities

    # Simulation parameters
    t0, t1 = 0.0, 5.0
    solver_dt = 1e-4
    save_dt = 0.01

    # Run simulation
    initial_state = SystemState(t=t0, y=jnp.concatenate([q0, qd0]))
    trajectory = robot.rollout_to(
        initial_state=initial_state,
        u=jnp.zeros_like(q0),  # Control inputs
        t1=t1,
        solver_dt=solver_dt,
        save_dt=save_dt,
    )

    # Analyze and visualize results
    # ...

Next Steps¶

After exploring the examples:

• Read the API documentation to understand the full capabilities of SoRoMoX
• Check the development guide for contributing new examples or features
• Explore the source code to understand implementation details
• Join the community to share your examples and get help

For more detailed information about specific systems or control methods, refer to the API documentation.