Control API¶

This module provides model-based controllers for soft robots implemented in JAX. The controllers are designed for high-performance simulation and real-time control applications.

Overview¶

SoRoMoX includes a comprehensive suite of model-based controllers organized into three control spaces:

• Configuration-Space Controllers: Controllers operating in the robot's generalized coordinates (joint angles, strains, etc.)
• Operational-Space Controllers: Controllers operating in task space (end-effector positions, orientations)
• Actuation-Space Controllers: Controllers operating in a transformed coordinate system where the actuation matrix becomes an identity structure—ideal for underactuated robots
• Utilities: Common components like PID control and reference trajectories

Choosing the Right Control Space¶

Selecting the appropriate control space is crucial for achieving good performance. The table below summarizes when to use each approach:

Configuration-Space Control¶

Use when:

• The trajectory is naturally expressed in generalized coordinates (strains, curvatures, joint angles)
• The robot is fully actuated (\(n = m\))
• The actuation matrix \(A\) is constant (configuration-independent) and easily invertible

Avoid when:

• The system is underactuated (\(m < n\))
• The actuation matrix \(A(q)\) is configuration-dependent, non-square, or poorly conditioned
• The control objective is primarily in task space

Example applications:

• Shape control of fully-actuated continuum robots
• Strain regulation in soft manipulators with identity/diagonal actuation
• Joint-level position/velocity control

Operational-Space Control¶

Use when:

• The control objective is naturally expressed in task space (end-effector position, orientation)
• You want to specify impedance behavior in Cartesian coordinates
• The robot is fully actuated and the task Jacobian is well-conditioned

Avoid when:

• Stability guarantees are strictly required
• The task space has kinematic singularities or is ill-conditioned
• You are looking for well-established, thoroughly-analyzed controllers in underactuated settings
• You need direct control over internal DOFs, not just task coordinates

Example applications:

• End-effector position tracking
• Compliant manipulation and interaction control
• Cartesian impedance control for safe human-robot interaction

Actuation-Space Control¶

Use when:

• Most importantly: a mapping from configuration- to actuation-space exists (i.e., integrability condition from (Pustina et al., 2024) is satisfied)
• The robot is underactuated (\(m < n\))
• The actuation matrix \(A(q)\) is configuration-dependent, non-square, or poorly conditioned
• You want to avoid matrix inversions in the control law
• You need clean separation between actuated and unactuated dynamics

Also works well for:

• Fully actuated systems with configuration-dependent \(A(q)\)—stability proofs remain straightforward

Avoid when:

• The zero dynamics (unactuated modes) are unstable
• The reference trajectory for unactuated coordinates is not feasible
• You need precise control over all DOFs simultaneously (impossible with underactuation)

Example applications:

• Tendon-actuated soft robots with configuration-dependent routing
• Pressure-actuated robots with fewer chambers than DOFs
• Any soft robot where underactuation or complex actuation coupling is intrinsic

Control Space Decision Flowchart¶

graph TD
    A[Start] --> B{Is the objective<br/>in task space?}
    B -->|Yes| C{Is the system<br/>fully actuated?}
    C -->|Yes| D[Operational-Space Control]
    C -->|No| E[Actuation-Space Control<br/>+ task-space mapping]
    B -->|No| F{Is integrability conditioned<br/>satisfied?}
    F -->|Yes| I[Actuation-Space Control]
    F -->|No|  G{Configuration-Space Control}

Controller Architecture¶

Most controllers in SoRoMoX follow a unified architecture that decomposes the control action into two terms:

where:

• Model-based term (\(u_\mathrm{model}\)): Computes control inputs using the robot's dynamics model to achieve desired behavior (e.g., inverse dynamics, gravity compensation, potential shaping)
• Error-based feedback term (\(u_\mathrm{feedback}\)): Provides corrective action based on tracking errors (e.g., PID control)

This decomposition is implemented in the ClosedFormModelBasedController base class, which provides a clean interface for implementing new controllers:

class MyController(ClosedFormModelBasedController):
    def model_based_term(self, system_state):
        # Compute feedforward control based on dynamics model
        # e.g., inverse dynamics, gravity compensation
        ...
        return u_model, None

    def error_based_feedback_term(self, system_state):
        # Compute feedback control based on tracking error
        # e.g., PID control
        ...
        return u_feedback, control_state_dot

Benefits of This Architecture¶

1. Modularity: Model-based and error-based feedback terms can be designed and tuned independently
2. Flexibility: Different feedback strategies (PD, PID, etc.) can be combined with various model-based terms
3. Theoretical foundation: Matches the structure used in passivity-based and Lyapunov-based control design
4. JAX compatibility: Both terms can be JIT-compiled for high-performance execution

Example: Feedforward Compensation Tracker¶

The Feedforward Compensation Tracker exemplifies this architecture:

• Model-based term: Pure feedforward inverse dynamics evaluated entirely at the desired state—no dependence on current \(q\) or \(\dot{q}\)
• Feedback term: Standard PID control on tracking error, fully independent of the model

# The model-based term computes (all at desired trajectory):
# tau_model = M(q_des) @ ydd_des + C(q_des, qd_des) @ yd_des 
#           + G(q_des) + tau_el(q_des) + D(q_des) @ yd_des

# The feedback term computes (independent of model):
# tau_fb = PID(e, ed, integral_error)

# Combined:
# u = tau_model + tau_fb

This clean separation means the two terms can be designed, tuned, and analyzed independently.

Available Controllers¶

Configuration-Space Controllers¶

Operational-Space Controllers¶

Actuation-Space Controllers¶

References and Citation¶

Base Classes¶

BaseController¶

The abstract base class for all controllers.

              flowchart TD
              soromox.control.BaseController[BaseController]

              

              click soromox.control.BaseController href "" "soromox.control.BaseController"
            

__call__(system_state: SystemState) -> tuple[Array, Any | None]

ClosedFormModelBasedController Base Class¶

This base class implements the model-based + feedback architecture described above. Subclasses override model_based_term() and/or error_based_feedback_term() to implement specific control strategies.

              flowchart TD
              soromox.control.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.base_controller.BaseController --> soromox.control.ClosedFormModelBasedController
                


              click soromox.control.ClosedFormModelBasedController href "" "soromox.control.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"
            

model_based_term(system_state: SystemState) -> tuple[Array, Any | None]

error_based_feedback_term(system_state: SystemState) -> tuple[Array, Any | None]

__call__(system_state: SystemState) -> tuple[Array, Any | None]