Configuration-Space Controllers¶

Configuration-space controllers operate directly in the robot's generalized coordinates (joint angles, strains, curvatures, etc.). These controllers are suitable for applications where the desired trajectory is naturally expressed in configuration space and the actuation matrix is easily invertible (i.e., full actuation) and (preferably) configuration-independent (i.e., constant).

Overview¶

All configuration-space controllers in SoRoMoX inherit from ClosedFormModelBasedController and decompose the control action into:

\[ u = u_\mathrm{model} + u_\mathrm{feedback} \]

The controllers differ in how they compute the model-based term:

Controller	Model-Based Term	Evaluation Point
`PIDController`	None	-
`ComputedTorqueTracker`	Full inverse dynamics	Current state (q, q̇)
`FeedforwardCompensationTracker`	Full inverse dynamics	Desired state (q_d, q̇_d, q̈_d)
`MixedStateFeedbackTracker`	Mixed evaluation	Dynamic matrices at current, elastic at desired
`GravityCancellationRegulator`	G(q) + τ_el(q_des)	Gravity at current, elastic at desired
`PotentialCancellationRegulator`	G(q) + τ_el(q)	Both at current
`PotentialCompensationRegulator`	G(q_des) + τ_el(q_des)	Both at desired

Trajectory Trackers¶

Trajectory trackers are designed for dynamic trajectory tracking where the reference includes position, velocity, and acceleration profiles.

PIDController¶

Basic PID controller in configuration space without model-based feedforward.

The control law is:

\[ \tau = K_p e + K_i \int e \, dt + K_d \dot{e} \]

\[ u = A(q)^T \tau \]

where \(e = q_d - q\) is the configuration error.

soromox.control.configuration_space.PIDController ¶

PIDController(robot: SoftRobot, reference_trajectory: ReferenceTrajectory, pid_control: PIDControl)

Bases: ClosedFormModelBasedController


              flowchart TD
              soromox.control.configuration_space.PIDController[PIDController]
              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController --> soromox.control.configuration_space.PIDController
                                soromox.control.base_controller.BaseController --> soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController
                



              click soromox.control.configuration_space.PIDController href "" "soromox.control.configuration_space.PIDController"
              click soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController href "" "soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"

PID controller in configuration space for soft robots.

This controller implements PID control in the robot's configuration space, computing control inputs based on tracking errors in generalized coordinates.

The control law is

tau = Kp @ e + Ki @ integral_error + Kd @ ed u = A(q).T @ tau

where

e = q_des - q is the configuration error
ed = qd_des - qd is the velocity error
integral_error = integral of sat(e) over time
sat() is an optional saturation function for anti-windup
A(q) is the state-dependent actuation matrix of the robot
tau is the generalized force in configuration space
u is the actuator input

The integral error dynamics are

d(integral_error)/dt = sat(e)

where sat() can be the identity (no saturation), tanh, or a custom function. The saturation function provides anti-windup protection by limiting the growth of the integral term when errors are large.

Note

This base PID controller uses u = A.T @ tau, which naturally handles all actuation scenarios (full, over, and underactuation). However, subclasses that use the actuation matrix inverse require additional considerations for non-square actuation matrices.

Attributes:

Name	Type	Description
`robot`		The soft robot system to be controlled.
`reference_trajectory`		The desired trajectory to track.
`pid_control`	`PIDControl`	The PIDControl instance containing the gains and saturation.

Initialize the PID controller.

Parameters:

Name	Type	Description	Default
`robot`	`SoftRobot`	The dynamical system (robot) to be controlled. Must have an `actuation_matrix(q)` method.	required
`reference_trajectory`	`ReferenceTrajectory`	The desired trajectory to track. Must provide x_des_fn (desired configuration) and xd_des_fn (desired velocity) as functions of time.	required
`pid_control`	`PIDControl`	A PIDControl instance containing the control gains (Kp, Ki, Kd) and optional saturation function.	required

call ¶

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

Compute the combined control action.

Combines the model-based feedforward term and the error-based feedback term by summing both the control inputs and the control state derivatives.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_control`	`Array`	Combined control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Combined time derivative of the internal controller state, or None if both terms are stateless.

model_based_term ¶

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

Compute the model-based feedforward control term.

This term typically computes the control input required to achieve the desired trajectory based on the system dynamics model (e.g., inverse dynamics, gravity compensation).

The default implementation returns zero control input. Subclasses can override this method to provide model-based feedforward control.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_model`	`Array`	Model-based control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Time derivative of the internal controller state contributed by this term, or None.

error_based_feedback_term ¶

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

Compute the PID feedback control term.

This method computes the PID control action based on the tracking error between the current state and the reference trajectory.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity) - control_state: PIDControllerState containing integral error, or None if not using integral control.	required

Returns:

Name	Type	Description
`u_feedback`	`Array`	The feedback control input, shape (num_actuators,).
`control_state_dot`	`PIDControllerState \| None`	Time derivative of the PIDControllerState, or None if no control state is being tracked.

update_gains ¶

update_gains(gains: dict[str, Array]) -> PIDController

This function updates the gains of the PID controller.

Parameters:

Name	Type	Description	Default
`gains`	`dict[str, Array]`	proportional, integral, and derivative gains	required

Returns:

Name	Type	Description
`updated_self`	`PIDController`	self object with updated gains

ComputedTorqueTracker¶

Computed torque (inverse dynamics) control achieves exact input-output linearization through feedback. This is the recommended choice for fully actuated systems as it provides the strongest theoretical guarantees.

The control law is:

\[ \ddot{q}_\mathrm{ref} = \ddot{q}_d + K_p e + K_i \int e \, dt + K_d \dot{e} \]

\[ \tau = M(q) \ddot{q}_\mathrm{ref} + C(q, \dot{q}) \dot{q} + G(q) + \tau_\mathrm{el}(q) + D(q) \dot{q} \]

\[ u = A(q)^{-1} \tau \]

With perfect model knowledge, the closed-loop error dynamics become linear:

\[ \ddot{e} + K_d \dot{e} + K_p e + K_i \int e \, dt = 0 \]

soromox.control.configuration_space.ComputedTorqueTracker ¶

ComputedTorqueTracker(robot: SoftRobot, reference_trajectory: ReferenceTrajectory, pid_control: PIDControl)

Bases: ClosedFormModelBasedController


              flowchart TD
              soromox.control.configuration_space.ComputedTorqueTracker[ComputedTorqueTracker]
              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController --> soromox.control.configuration_space.ComputedTorqueTracker
                                soromox.control.base_controller.BaseController --> soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController
                



              click soromox.control.configuration_space.ComputedTorqueTracker href "" "soromox.control.configuration_space.ComputedTorqueTracker"
              click soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController href "" "soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"

Computed torque trajectory tracker for soft robots.

This controller implements the computed torque control method, a model-based nonlinear control technique that achieves exact input-output linearization of robot dynamics through feedback. The method cancels all static and dynamic forces at the current robot motion (configuration and velocity) and applies a desired acceleration computed from PID feedback on the tracking error.

The computed torque method, also known as inverse dynamics control, was first developed for rigid robot manipulators. It achieves exact linearization of the nonlinear robot dynamics by computing the control torque required to produce a desired acceleration, given the current state. This transforms the closed-loop dynamics into a linear double integrator, enabling straightforward trajectory tracking through linear feedback (e.g., PID control).

The control law is

qdd_ref = qdd_des + PID(e, ed, integral_error) tau = M(q) @ qdd_ref + C(q, qd) @ qd + G(q) + tau_el(q) + D(q) @ qd u = inv(A(q)) @ tau (or pinv for overactuated systems)

where

M(q) is the inertia (mass) matrix at the current configuration
C(q, qd) is the Coriolis matrix at the current configuration and velocity
G(q) is the gravitational force at the current configuration
tau_el(q) is the elastic force at the current configuration
D(q) is the damping matrix at the current configuration
qdd_des is the desired acceleration from the reference trajectory
e = q_des - q is the configuration error
ed = qd_des - qd is the velocity error
qdd_ref is the reference acceleration that includes PID feedback
A(q) is the state-dependent actuation matrix of the robot
inv(A(q)) is the inverse of A(q) (or pseudo-inverse for overactuation)

With perfect model knowledge, the closed-loop dynamics become: qdd = qdd_des + PID(e, ed, integral_error)

which represents a linear error system. Appropriate choice of PID gains then ensures asymptotic stability and desired transient response.

Note

This controller is the recommended choice for fully actuated systems with configuration-dependent actuation matrices, as it achieves full feedback linearization. Other configuration-space controllers may have reduced theoretical guarantees when the actuation matrix depends on configuration.

The controller requires the actuation matrix to have sufficient rank: - For full actuation: A must be square and invertible. - For overactuation: A must have rank at least equal to the number of DOFs. - Underactuation is not supported as the system cannot be fully linearized.

Attributes:

Name	Type	Description
`robot`		The soft robot system to be controlled.
`reference_trajectory`		The desired trajectory to track.
`pid_control`	`PIDControl`	The PIDControl instance containing the gains and saturation.

References

Slotine, J.-J. E., & Li, W. (1987). On the Adaptive Control of Robot Manipulators. The International Journal of Robotics Research, 6(3), 49-59. https://doi.org/10.1177/027836498700600303

Spong, M. W., Hutchinson, S., & Vidyasagar, M. (2020). Robot Modeling and Control (2^nd ed.). Wiley.

Initialize the computed torque trajectory tracker.

Parameters:

Name	Type	Description	Default
`robot`	`SoftRobot`	The soft robot system to be controlled. Must have `actuation_matrix(q)`, `inertia_matrix(q)`, `coriolis_matrix(q, qd)`, `gravitational_force(q)`, `elastic_force(q)`, and `damping_matrix(q)` methods.	required
`reference_trajectory`	`ReferenceTrajectory`	The desired trajectory to track. Must provide x_des_fn (desired configuration), xd_des_fn (desired velocity), and xdd_des_fn (desired acceleration) as functions of time.	required
`pid_control`	`PIDControl`	A PIDControl instance containing the control gains (Kp, Ki, Kd) and optional saturation function. The PID output is used to compute the reference acceleration for the inverse dynamics computation.	required

Raises:

Type	Description
`ValueError`	If the system is underactuated, if the actuation matrix is singular (for full actuation), or if the rank is insufficient (for overactuation).

call ¶

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

Compute the combined control action.

Combines the model-based feedforward term and the error-based feedback term by summing both the control inputs and the control state derivatives.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_control`	`Array`	Combined control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Combined time derivative of the internal controller state, or None if both terms are stateless.

model_based_term ¶

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

Compute the model-based feedforward control term for computed torque control.

This method computes the inverse dynamics torque required to cancel all static and dynamic forces at the current motion and achieve the desired acceleration from the reference trajectory.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity)	required

Returns:

Name	Type	Description
`u_model`	`Array`	The model-based control input, shape (num_actuators,).
`control_state_dot`	`Any \| None`	None (this term is stateless).

error_based_feedback_term ¶

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

Compute the PID-based feedback control term for computed torque control.

This method computes the feedback torque from the PID controller acting on the tracking error. The PID output represents an acceleration correction that is mapped through the inertia matrix and actuation matrix to obtain the actuator inputs.

The feedback term implements

qdd_fb = PID(e, ed, integral_error) tau_fb = M(q) @ qdd_fb u_fb = inv(A(q)) @ tau_fb

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity) - control_state: PIDControllerState containing integral error, or None if not using integral control.	required

Returns:

Name	Type	Description
`u_feedback`	`Array`	The feedback control input, shape (num_actuators,).
`control_state_dot`	`PIDControllerState \| None`	Time derivative of the PIDControllerState, or None if no control state is being tracked.

FeedforwardCompensationTracker¶

Feedforward compensation evaluates the complete inverse dynamics at the desired trajectory rather than the current state. This provides open-loop feedforward plus feedback correction.

The control law is:

\[ \tau_\mathrm{model} = M(q_d) \ddot{q}_d + C(q_d, \dot{q}_d) \dot{q}_d + G(q_d) + \tau_\mathrm{el}(q_d) + D(q_d) \dot{q}_d \]

\[ u = A(q)^{-1} \tau_\mathrm{model} + u_\mathrm{feedback} \]

soromox.control.configuration_space.FeedforwardCompensationTracker ¶

FeedforwardCompensationTracker(robot: SoftRobot, reference_trajectory: ReferenceTrajectory, pid_control: PIDControl)

Bases: PIDController


              flowchart TD
              soromox.control.configuration_space.FeedforwardCompensationTracker[FeedforwardCompensationTracker]
              soromox.control.configuration_space.pid_controller.PIDController[PIDController]
              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.configuration_space.pid_controller.PIDController --> soromox.control.configuration_space.FeedforwardCompensationTracker
                                soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController --> soromox.control.configuration_space.pid_controller.PIDController
                                soromox.control.base_controller.BaseController --> soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController
                




              click soromox.control.configuration_space.FeedforwardCompensationTracker href "" "soromox.control.configuration_space.FeedforwardCompensationTracker"
              click soromox.control.configuration_space.pid_controller.PIDController href "" "soromox.control.configuration_space.pid_controller.PIDController"
              click soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController href "" "soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"

Feedforward compensation trajectory tracker for soft robots.

This controller extends the PIDController by adding a model-based feedforward term that evaluates the complete inverse dynamics at the desired trajectory. It computes the inertial forces, Coriolis forces, gravitational forces, elastic forces, and damping forces all evaluated at the desired configuration, desired velocity, and desired acceleration.

The control law is

tau_model = B(q_des) @ qdd_des + C(q_des, qd_des) @ qd_des + G(q_des) + tau_el(q_des) + D(q_des) @ qd_des u_model = inv(A(q)) @ tau_model (or pinv if A is not square) u_control = u_model + u_feedback

where

B(q_des) is the inertia matrix at the desired configuration
C(q_des, qd_des) is the Coriolis matrix at the desired configuration and velocity
G(q_des) is the gravitational force at the desired configuration
tau_el(q_des) is the elastic force at the desired configuration
D(q_des) is the damping matrix at the desired configuration
qd_des is the desired velocity
qdd_des is the desired acceleration
A(q) is the state-dependent actuation matrix of the robot
inv(A(q)) is the inverse of A(q) if square, otherwise the pseudo-inverse
u_feedback is the PID feedback term from the parent class

Note

This controller is suitable for trajectory tracking but may have limited robustness to model uncertainties since all dynamics are evaluated at the desired trajectory rather than the actual state.

Warning

For full theoretical guarantees, the actuation matrix should be configuration-independent. If A(q) is configuration-dependent, consider using the ComputedTorqueTracker (with full feedback linearization) or actuation-space controllers.

Attributes:

Name	Type	Description
`robot`		The soft robot system to be controlled.
`reference_trajectory`		The desired trajectory to track.
`pid_control`		The PIDControl instance containing the gains and saturation.

References

Della Santina, C., Duriez, C., & Rus, D. (2023). Model-based control of soft robots: A survey of the state of the art and open challenges. IEEE Control Systems Magazine, 43(3), 30-65.

Kelly, R., & Salgado, R. (1994). PD control with computed feedforward of robot manipulators: A design procedure. IEEE Transactions on Robotics and Automation, 10(4), 566-571.

Initialize the feedforward compensation trajectory tracker.

Parameters:

Name	Type	Description	Default
`robot`	`SoftRobot`	The soft robot system to be controlled. Must have `actuation_matrix(q)`, `inertia_matrix(q)`, `coriolis_matrix(q, qd)`, `gravitational_force(q)`, `elastic_force(q)`, and `damping_matrix(q)` methods.	required
`reference_trajectory`	`ReferenceTrajectory`	The desired trajectory to track. Must provide x_des_fn (desired configuration), xd_des_fn (desired velocity), and xdd_des_fn (desired acceleration) as functions of time.	required
`pid_control`	`PIDControl`	A PIDControl instance containing the control gains (Kp, Ki, Kd) and optional saturation function.	required

Raises:

Type	Description
`ValueError`	If the actuation matrix is singular (for full actuation) or has insufficient rank (for overactuation).

call ¶

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

Compute the combined control action.

Combines the model-based feedforward term and the error-based feedback term by summing both the control inputs and the control state derivatives.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_control`	`Array`	Combined control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Combined time derivative of the internal controller state, or None if both terms are stateless.

error_based_feedback_term ¶

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

Compute the PID feedback control term.

This method computes the PID control action based on the tracking error between the current state and the reference trajectory.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity) - control_state: PIDControllerState containing integral error, or None if not using integral control.	required

Returns:

Name	Type	Description
`u_feedback`	`Array`	The feedback control input, shape (num_actuators,).
`control_state_dot`	`PIDControllerState \| None`	Time derivative of the PIDControllerState, or None if no control state is being tracked.

update_gains ¶

update_gains(gains: dict[str, Array]) -> PIDController

This function updates the gains of the PID controller.

Parameters:

Name	Type	Description	Default
`gains`	`dict[str, Array]`	proportional, integral, and derivative gains	required

Returns:

Name	Type	Description
`updated_self`	`PIDController`	self object with updated gains

model_based_term ¶

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

Compute the model-based feedforward control term for trajectory tracking.

This method computes the control input required to track the desired trajectory by evaluating the complete inverse dynamics at the desired configuration, velocity, and acceleration. The generalized torques are mapped to actuator inputs using the inverse of the actuation matrix (or pseudo-inverse if A is not square).

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity)	required

Returns:

Name	Type	Description
`u_model`	`Array`	The model-based control input, shape (num_actuators,).
`control_state_dot`	`Any \| None`	None (this term is stateless).

MixedStateFeedbackTracker¶

Mixed state feedback uses a hybrid evaluation strategy: dynamic matrices (inertia, Coriolis, damping) at the current state, but desired velocities/accelerations for computing forces. Elastic forces are evaluated at the desired configuration.

The control law is:

\[ \tau_\mathrm{model} = M(q) \ddot{q}_d + C(q, \dot{q}) \dot{q}_d + G(q) + \tau_\mathrm{el}(q_d) + D(q) \dot{q}_d \]

\[ u = A(q)^{-1} \tau_\mathrm{model} + u_\mathrm{feedback} \]

This approach often provides better control performance than pure feedforward compensation since it uses the actual state for configuration-dependent matrices.

Coriolis Matrix Requirements

For theoretical stability guarantees, the Coriolis matrix \(C(q, \dot{q})\) must be derived using Christoffel symbols of the first kind, ensuring that \(N = \dot{M} - 2C\) is skew-symmetric.

soromox.control.configuration_space.MixedStateFeedbackTracker ¶

MixedStateFeedbackTracker(robot: SoftRobot, reference_trajectory: ReferenceTrajectory, pid_control: PIDControl)

Bases: PIDController


              flowchart TD
              soromox.control.configuration_space.MixedStateFeedbackTracker[MixedStateFeedbackTracker]
              soromox.control.configuration_space.pid_controller.PIDController[PIDController]
              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.configuration_space.pid_controller.PIDController --> soromox.control.configuration_space.MixedStateFeedbackTracker
                                soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController --> soromox.control.configuration_space.pid_controller.PIDController
                                soromox.control.base_controller.BaseController --> soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController
                




              click soromox.control.configuration_space.MixedStateFeedbackTracker href "" "soromox.control.configuration_space.MixedStateFeedbackTracker"
              click soromox.control.configuration_space.pid_controller.PIDController href "" "soromox.control.configuration_space.pid_controller.PIDController"
              click soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController href "" "soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"

Mixed state feedback trajectory tracker for soft robots.

This controller extends the PIDController by adding a model-based feedforward term that uses a hybrid evaluation strategy: the dynamical matrices (inertia, Coriolis, gravitational, damping) are evaluated at the current state (q, qd), while the desired acceleration and velocity are used for computing the inertial, Coriolis, and damping forces. Only the elastic forces are evaluated at the desired configuration.

This mixed strategy often provides with good model knowledge better control performance compared to pure feedforward compensation since it uses the actual state for the configuration-dependent matrices while still providing feedforward action through the desired velocities and accelerations.

The control law is

tau_model = B(q) @ qdd_des + C(q, qd) @ qd_des + G(q) + tau_el(q_des) + D(q) @ qd_des u_model = inv(A(q)) @ tau_model (or pinv if A is not square) u_control = u_model + u_feedback

where

B(q) is the inertia matrix at the current configuration
C(q, qd) is the Coriolis matrix at the current configuration and current velocity
G(q) is the gravitational force at the current configuration
tau_el(q_des) is the elastic force at the desired configuration
D(q) is the damping matrix at the current configuration
qd_des is the desired velocity
qdd_des is the desired acceleration
A(q) is the state-dependent actuation matrix of the robot
inv(A(q)) is the inverse of A(q) if square, otherwise the pseudo-inverse
u_feedback is the PID feedback term from the parent class

Note

The key difference from FeedforwardCompensationTracker is that the inertia, Coriolis, gravitational, and damping matrices are evaluated at the current state (q, qd), providing state feedback through the dynamical matrices. Only the elastic forces use the desired configuration to provide the correct equilibrium point. The Coriolis term C(q, qd) @ qd_des and the damping term D(q) @ qd_des mix current state evaluation with desired velocity.

Warning

For full theoretical guarantees, the actuation matrix should be configuration-independent. If A(q) is configuration-dependent, consider using the ComputedTorqueTracker (with full feedback linearization) or actuation-space controllers.

For the theoretical stability guarantees to hold, the Coriolis matrix C(q, qd) must be derived using the Christoffel symbols of the first kind, ensuring that the matrix N = dB/dt - 2*C is skew-symmetric. This property is essential for the passivity-based stability proofs. If the Coriolis matrix is computed using other methods (e.g., direct Jacobian time derivatives), the skew-symmetry property may not hold and the stability guarantees may be invalidated.

Attributes:

Name	Type	Description
`robot`		The soft robot system to be controlled.
`reference_trajectory`		The desired trajectory to track.
`pid_control`		The PIDControl instance containing the gains and saturation.

References

Della Santina, C., Katzschmann, R. K., Bicchi, A., & Rus, D. (2020). Model-based dynamic feedback control of a planar soft robot: trajectory tracking and interaction with the environment. The International Journal of Robotics Research, 39.

Kelly, R., & Carelli, R. (1996). A class of nonlinear PD-type controllers for robot manipulators. Journal of Robotic Systems, 13(12), 793-802.

Initialize the mixed state feedback trajectory tracker.

Parameters:

Name	Type	Description	Default
`robot`	`SoftRobot`	The soft robot system to be controlled. Must have `actuation_matrix(q)`, `inertia_matrix(q)`, `coriolis_matrix(q, qd)`, `gravitational_force(q)`, `elastic_force(q)`, and `damping_matrix(q)` methods.	required
`reference_trajectory`	`ReferenceTrajectory`	The desired trajectory to track. Must provide x_des_fn (desired configuration), xd_des_fn (desired velocity), and xdd_des_fn (desired acceleration) as functions of time.	required
`pid_control`	`PIDControl`	A PIDControl instance containing the control gains (Kp, Ki, Kd) and optional saturation function.	required

Raises:

Type	Description
`ValueError`	If the actuation matrix is singular (for full actuation) or has insufficient rank (for overactuation).

call ¶

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

Compute the combined control action.

Combines the model-based feedforward term and the error-based feedback term by summing both the control inputs and the control state derivatives.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_control`	`Array`	Combined control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Combined time derivative of the internal controller state, or None if both terms are stateless.

error_based_feedback_term ¶

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

Compute the PID feedback control term.

This method computes the PID control action based on the tracking error between the current state and the reference trajectory.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity) - control_state: PIDControllerState containing integral error, or None if not using integral control.	required

Returns:

Name	Type	Description
`u_feedback`	`Array`	The feedback control input, shape (num_actuators,).
`control_state_dot`	`PIDControllerState \| None`	Time derivative of the PIDControllerState, or None if no control state is being tracked.

update_gains ¶

update_gains(gains: dict[str, Array]) -> PIDController

This function updates the gains of the PID controller.

Parameters:

Name	Type	Description	Default
`gains`	`dict[str, Array]`	proportional, integral, and derivative gains	required

Returns:

Name	Type	Description
`updated_self`	`PIDController`	self object with updated gains

model_based_term ¶

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

Compute the model-based feedforward control term for trajectory tracking.

This method computes the control input using a mixed evaluation strategy: - Dynamical matrices (B, C, G, D) are evaluated at the current state (q, qd) - The desired acceleration and velocity are used for inertial/Coriolis/damping forces - Elastic forces are evaluated at the desired configuration

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity)	required

Returns:

Name	Type	Description
`u_model`	`Array`	The model-based control input, shape (num_actuators,).
`control_state_dot`	`Any \| None`	None (this term is stateless).

Setpoint Regulators¶

Setpoint regulators are specialized for regulation tasks (constant setpoints) or quasi-static trajectories. They do not consider inertial, Coriolis, or damping forces.

GravityCancellationRegulator¶

Gravity cancellation evaluates gravity at the current configuration (for real-time compensation) and elastic forces at the desired configuration (to set the equilibrium).

The control law is:

\[ \tau_\mathrm{model} = G(q) + \tau_\mathrm{el}(q_d) \]

\[ u = A(q)^{-1} \tau_\mathrm{model} + u_\mathrm{feedback} \]

soromox.control.configuration_space.GravityCancellationRegulator ¶

GravityCancellationRegulator(robot: SoftRobot, reference_trajectory: ReferenceTrajectory, pid_control: PIDControl)

Bases: PIDController


              flowchart TD
              soromox.control.configuration_space.GravityCancellationRegulator[GravityCancellationRegulator]
              soromox.control.configuration_space.pid_controller.PIDController[PIDController]
              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.configuration_space.pid_controller.PIDController --> soromox.control.configuration_space.GravityCancellationRegulator
                                soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController --> soromox.control.configuration_space.pid_controller.PIDController
                                soromox.control.base_controller.BaseController --> soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController
                




              click soromox.control.configuration_space.GravityCancellationRegulator href "" "soromox.control.configuration_space.GravityCancellationRegulator"
              click soromox.control.configuration_space.pid_controller.PIDController href "" "soromox.control.configuration_space.pid_controller.PIDController"
              click soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController href "" "soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"

Gravity cancellation regulator for soft robots.

This controller extends the PIDController by adding a model-based feedforward term that compensates for the gravitational forces at the current configuration and elastic forces at the desired configuration. Unlike the PotentialShapingRegulator, this controller evaluates gravity at the current state rather than the desired state, providing real-time gravity compensation.

Note

This regulator is specialized for setpoint regulation or quasi-static trajectories as it does not consider the dynamical (e.g., inertial, Coriolis, damping, etc.) forces of the soft robot.

Warning

For full theoretical guarantees, the actuation matrix should be configuration-independent. If A(q) is configuration-dependent, consider using the ComputedTorqueTracker (with full feedback linearization) or actuation-space controllers.

The control law is

tau_model = G(q) + tau_el(q_des) u_model = inv(A(q)) @ tau_model (or pinv if A is not square) u_control = u_model + u_feedback

where

G(q) is the gravitational force at the current configuration
tau_el(q_des) is the elastic force at the desired configuration
A(q) is the state-dependent actuation matrix of the robot
inv(A(q)) is the inverse of A(q) if square, otherwise the pseudo-inverse
u_feedback is the PID feedback term from the parent class

Attributes:

Name	Type	Description
`robot`		The soft robot system to be controlled.
`reference_trajectory`		The desired trajectory to track.
`pid_control`		The PIDControl instance containing the gains and saturation.

References

Della Santina, C., Katzschmann, R. K., Bicchi, A., & Rus, D. (2020). Model-based dynamic feedback control of a planar soft robot: trajectory tracking and interaction with the environment. The International Journal of Robotics Research, 39.

Borja, P., Della Santina, C., & Albu-Schäffer, A. (2022). Energy-shaping control of soft continuum manipulators with in-plane disturbances. The International Journal of Robotics Research, 41(1), 62-81.

Pustina, P., Della Santina, C., & De Luca, A. (2025). Feedback regulation of elastically decoupled underactuated soft robots. IEEE Transactions on Robotics.

Initialize the gravity cancellation regulator.

Parameters:

Name	Type	Description	Default
`robot`	`SoftRobot`	The soft robot system to be controlled. Must have `actuation_matrix(q)`, `gravitational_force(q)`, and `elastic_force(q)` methods.	required
`reference_trajectory`	`ReferenceTrajectory`	The desired trajectory to track. Must provide x_des_fn (desired configuration) as a function of time.	required
`pid_control`	`PIDControl`	A PIDControl instance containing the control gains (Kp, Ki, Kd) and optional saturation function.	required

Raises:

Type	Description
`ValueError`	If the actuation matrix is singular (for full actuation) or has insufficient rank (for overactuation).

call ¶

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

Compute the combined control action.

Combines the model-based feedforward term and the error-based feedback term by summing both the control inputs and the control state derivatives.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_control`	`Array`	Combined control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Combined time derivative of the internal controller state, or None if both terms are stateless.

error_based_feedback_term ¶

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

Compute the PID feedback control term.

This method computes the PID control action based on the tracking error between the current state and the reference trajectory.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity) - control_state: PIDControllerState containing integral error, or None if not using integral control.	required

Returns:

Name	Type	Description
`u_feedback`	`Array`	The feedback control input, shape (num_actuators,).
`control_state_dot`	`PIDControllerState \| None`	Time derivative of the PIDControllerState, or None if no control state is being tracked.

update_gains ¶

update_gains(gains: dict[str, Array]) -> PIDController

This function updates the gains of the PID controller.

Parameters:

Name	Type	Description	Default
`gains`	`dict[str, Array]`	proportional, integral, and derivative gains	required

Returns:

Name	Type	Description
`updated_self`	`PIDController`	self object with updated gains

model_based_term ¶

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

Compute the model-based feedforward control term for gravity cancellation.

This method computes the control input required to compensate for the gravitational forces at the current configuration and elastic forces at the desired configuration. The generalized torques are mapped to actuator inputs using the inverse of the actuation matrix (or pseudo-inverse if A is not square).

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity)	required

Returns:

Name	Type	Description
`u_model`	`Array`	The model-based control input, shape (num_actuators,).
`control_state_dot`	`Any \| None`	None (this term is stateless).

PotentialCancellationRegulator¶

Potential cancellation evaluates both gravitational and elastic forces at the current configuration, providing real-time cancellation of all potential energy forces.

This is related to the PD+ controller in rigid robotics, which was shown to be globally asymptotically stable by Paden & Panja (1988).

The control law is:

\[ \tau_\mathrm{model} = G(q) + \tau_\mathrm{el}(q) \]

\[ u = A(q)^{-1} \tau_\mathrm{model} + u_\mathrm{feedback} \]

soromox.control.configuration_space.PotentialCancellationRegulator ¶

PotentialCancellationRegulator(robot: SoftRobot, reference_trajectory: ReferenceTrajectory, pid_control: PIDControl)

Bases: PIDController


              flowchart TD
              soromox.control.configuration_space.PotentialCancellationRegulator[PotentialCancellationRegulator]
              soromox.control.configuration_space.pid_controller.PIDController[PIDController]
              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.configuration_space.pid_controller.PIDController --> soromox.control.configuration_space.PotentialCancellationRegulator
                                soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController --> soromox.control.configuration_space.pid_controller.PIDController
                                soromox.control.base_controller.BaseController --> soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController
                




              click soromox.control.configuration_space.PotentialCancellationRegulator href "" "soromox.control.configuration_space.PotentialCancellationRegulator"
              click soromox.control.configuration_space.pid_controller.PIDController href "" "soromox.control.configuration_space.pid_controller.PIDController"
              click soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController href "" "soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"

Potential cancellation regulator for soft robots.

This controller extends the PIDController by adding a model-based feedforward term that cancels the gravitational and elastic forces at the current configuration. This provides real-time cancellation of potential energy forces.

This regulator is closely related to PD+ regulators in rigid robotics, which augment PD feedback with gravity compensation evaluated at the current configuration. The PD+ approach was shown to be globally asymptotically stable for rigid robot manipulators by Paden & Panja (1988) and Kelly & Carelli (1996).

Note

This regulator is specialized for setpoint regulation or quasi-static trajectories as it does not consider the dynamical (e.g., inertial, Coriolis, damping, etc.) forces of the soft robot.

Warning

For full theoretical guarantees, the actuation matrix should be configuration-independent. If A(q) is configuration-dependent, consider using the ComputedTorqueTracker (with full feedback linearization) or actuation-space controllers.

The control law is

tau_model = G(q) + tau_el(q) u_model = inv(A(q)) @ tau_model (or pinv if A is not square) u_control = u_model + u_feedback

where

G(q) is the gravitational force at the current configuration
tau_el(q) is the elastic force at the current configuration
A(q) is the state-dependent actuation matrix of the robot
inv(A(q)) is the inverse of A(q) if square, otherwise the pseudo-inverse
u_feedback is the PID feedback term from the parent class

Attributes:

Name	Type	Description
`robot`		The soft robot system to be controlled.
`reference_trajectory`		The desired trajectory to track.
`pid_control`		The PIDControl instance containing the gains and saturation.

References

Paden, B., & Panja, R. (1988). Globally asymptotically stable 'PD+' controller for robot manipulators. International Journal of Control, 47(6), 1697-1712.

Kelly, R., & Carelli, R. (1996). A class of nonlinear PD-type controllers for robot manipulators. Journal of Robotic Systems, 13(12), 793-802.

Patterson, Z. J., Sologuren, E., Della Santina, C., & Rus, D. (2024). Design and Control of Modular Soft-Rigid Hybrid Manipulators with Self-Contact. IEEE Transactions on Robotics.

Pustina, P. (2024). Analysis and control of the underactuation in continuum soft robots: a kinematic independent approach. PhD Thesis, Sapienza University of Rome.

Stölzle, M. (2025). Safe yet Precise Soft Robots: Incorporating Physics into Learned Models for Control. Dissertation, Delft University of Technology. https://doi.org/10.4233/uuid:24c1f667-8fd6-431a-bb78-11d22f8cb3da

Borja, P., Della Santina, C., & Albu-Schäffer, A. (2022). Energy-shaping control of soft continuum manipulators with in-plane disturbances. The International Journal of Robotics Research, 41(1), 62-81.

Pustina, P., Della Santina, C., & De Luca, A. (2025). Feedback regulation of elastically decoupled underactuated soft robots. IEEE Transactions on Robotics.

Initialize the potential cancellation regulator.

Parameters:

Name	Type	Description	Default
`robot`	`SoftRobot`	The soft robot system to be controlled. Must have `actuation_matrix(q)`, `gravitational_force(q)`, and `elastic_force(q)` methods.	required
`reference_trajectory`	`ReferenceTrajectory`	The desired trajectory to track. Must provide x_des_fn (desired configuration) as a function of time.	required
`pid_control`	`PIDControl`	A PIDControl instance containing the control gains (Kp, Ki, Kd) and optional saturation function.	required

Raises:

Type	Description
`ValueError`	If the actuation matrix is singular (for full actuation) or has insufficient rank (for overactuation).

call ¶

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

Compute the combined control action.

Combines the model-based feedforward term and the error-based feedback term by summing both the control inputs and the control state derivatives.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_control`	`Array`	Combined control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Combined time derivative of the internal controller state, or None if both terms are stateless.

error_based_feedback_term ¶

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

Compute the PID feedback control term.

This method computes the PID control action based on the tracking error between the current state and the reference trajectory.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity) - control_state: PIDControllerState containing integral error, or None if not using integral control.	required

Returns:

Name	Type	Description
`u_feedback`	`Array`	The feedback control input, shape (num_actuators,).
`control_state_dot`	`PIDControllerState \| None`	Time derivative of the PIDControllerState, or None if no control state is being tracked.

update_gains ¶

update_gains(gains: dict[str, Array]) -> PIDController

This function updates the gains of the PID controller.

Parameters:

Name	Type	Description	Default
`gains`	`dict[str, Array]`	proportional, integral, and derivative gains	required

Returns:

Name	Type	Description
`updated_self`	`PIDController`	self object with updated gains

model_based_term ¶

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

Compute the model-based feedforward control term for potential cancellation.

This method computes the control input required to compensate for the gravitational and elastic forces at the current configuration. The generalized torques are mapped to actuator inputs using the inverse of the actuation matrix (or pseudo-inverse if A is not square).

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity)	required

Returns:

Name	Type	Description
`u_model`	`Array`	The model-based control input, shape (num_actuators,).
`control_state_dot`	`Any \| None`	None (this term is stateless).

PotentialCompensationRegulator¶

Potential compensation (or "potential shaping") evaluates both forces at the desired configuration, effectively reshaping the potential energy landscape to have a minimum at the setpoint.

The control law is:

\[ \tau_\mathrm{model} = G(q_d) + \tau_\mathrm{el}(q_d) \]

\[ u = A(q)^{-1} \tau_\mathrm{model} + u_\mathrm{feedback} \]

soromox.control.configuration_space.PotentialCompensationRegulator ¶

PotentialCompensationRegulator(robot: SoftRobot, reference_trajectory: ReferenceTrajectory, pid_control: PIDControl)

Bases: PIDController


              flowchart TD
              soromox.control.configuration_space.PotentialCompensationRegulator[PotentialCompensationRegulator]
              soromox.control.configuration_space.pid_controller.PIDController[PIDController]
              soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController[ClosedFormModelBasedController]
              soromox.control.base_controller.BaseController[BaseController]

                              soromox.control.configuration_space.pid_controller.PIDController --> soromox.control.configuration_space.PotentialCompensationRegulator
                                soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController --> soromox.control.configuration_space.pid_controller.PIDController
                                soromox.control.base_controller.BaseController --> soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController
                




              click soromox.control.configuration_space.PotentialCompensationRegulator href "" "soromox.control.configuration_space.PotentialCompensationRegulator"
              click soromox.control.configuration_space.pid_controller.PIDController href "" "soromox.control.configuration_space.pid_controller.PIDController"
              click soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController href "" "soromox.control.closed_form_model_based_controller.ClosedFormModelBasedController"
              click soromox.control.base_controller.BaseController href "" "soromox.control.base_controller.BaseController"

Potential compensation regulator for soft robots.

This controller extends the PIDController by adding a model-based feedforward term that compensates for the gravitational and elastic forces at the desired configuration. This is known as "potential shaping" as it effectively reshapes the potential energy landscape of the system to have a minimum at the desired configuration.

Note

This regulator is specialized for setpoint regulation or quasi-static trajectories as it does not consider the dynamical (e.g., inertial, Coriolis, damping, etc.) forces of the soft robot.

Warning

For full theoretical guarantees, the actuation matrix should be configuration-independent. If A(q) is configuration-dependent, consider using the ComputedTorqueTracker (with full feedback linearization) or actuation-space controllers.

The control law is

tau_model = G(q_des) + tau_el(q_des) u_model = inv(A(q)) @ tau_model (or pinv if A is not square) u_control = u_model + u_feedback

where

G(q_des) is the gravitational force at the desired configuration
tau_el(q_des) is the elastic force at the desired configuration
A(q) is the state-dependent actuation matrix of the robot
inv(A(q)) is the inverse of A(q) if square, otherwise the pseudo-inverse
u_feedback is the PID feedback term from the parent class

Attributes:

Name	Type	Description
`robot`		The soft robot system to be controlled.
`reference_trajectory`		The desired trajectory to track.
`pid_control`		The PIDControl instance containing the gains and saturation.

References

Kelly, R., & Salgado, R. (1994). PD control with computed feedforward of robot manipulators: A design procedure. IEEE Transactions on Robotics and Automation, 10(4), 566-571.

Borja, P., Della Santina, C., & Albu-Schäffer, A. (2022). Energy-shaping control of soft continuum manipulators with in-plane disturbances. The International Journal of Robotics Research, 41(1), 62-81.

Della Santina, C., Duriez, C., & Rus, D. (2023). Model-based control of soft robots: A survey of the state of the art and open challenges. IEEE Control Systems Magazine, 43(3), 30-65.

Pustina, P., Della Santina, C., & De Luca, A. (2025). Feedback regulation of elastically decoupled underactuated soft robots. IEEE Transactions on Robotics.

Initialize the potential compensation regulator.

Parameters:

Name	Type	Description	Default
`robot`	`SoftRobot`	The soft robot system to be controlled. Must have `actuation_matrix(q)`, `gravitational_force(q)`, and `elastic_force(q)` methods.	required
`reference_trajectory`	`ReferenceTrajectory`	The desired trajectory to track. Must provide x_des_fn (desired configuration) as a function of time.	required
`pid_control`	`PIDControl`	A PIDControl instance containing the control gains (Kp, Ki, Kd) and optional saturation function.	required

Raises:

Type	Description
`ValueError`	If the actuation matrix is singular (for full actuation) or has insufficient rank (for overactuation).

call ¶

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

Compute the combined control action.

Combines the model-based feedforward term and the error-based feedback term by summing both the control inputs and the control state derivatives.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system.	required

Returns:

Name	Type	Description
`u_control`	`Array`	Combined control input, shape (num_actuators,).
`control_state_dot`	`Optional[Any]`	Combined time derivative of the internal controller state, or None if both terms are stateless.

error_based_feedback_term ¶

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

Compute the PID feedback control term.

This method computes the PID control action based on the tracking error between the current state and the reference trajectory.

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity) - control_state: PIDControllerState containing integral error, or None if not using integral control.	required

Returns:

Name	Type	Description
`u_feedback`	`Array`	The feedback control input, shape (num_actuators,).
`control_state_dot`	`PIDControllerState \| None`	Time derivative of the PIDControllerState, or None if no control state is being tracked.

update_gains ¶

update_gains(gains: dict[str, Array]) -> PIDController

This function updates the gains of the PID controller.

Parameters:

Name	Type	Description	Default
`gains`	`dict[str, Array]`	proportional, integral, and derivative gains	required

Returns:

Name	Type	Description
`updated_self`	`PIDController`	self object with updated gains

model_based_term ¶

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

Compute the model-based feedforward control term for potential compensation.

This method computes the control input required to compensate for the gravitational and elastic forces at the desired configuration. The generalized torques are mapped to actuator inputs using the inverse of the actuation matrix (or pseudo-inverse if A is not square).

Parameters:

Name	Type	Description	Default
`system_state`	`SystemState`	The current state of the system, containing: - t: Current simulation time - y: Robot state vector [q, qd] (configuration and velocity)	required

Returns:

Name	Type	Description
`u_model`	`Array`	The model-based control input, shape (num_actuators,).
`control_state_dot`	`Any \| None`	None (this term is stateless).

Actuation Matrix Considerations¶

Configuration-Dependent Actuation Matrices

For full theoretical stability guarantees, most controllers assume the actuation matrix \(A(q)\) is configuration-independent (constant). If your system has a configuration-dependent actuation matrix, consider:

ComputedTorqueTracker: Achieves full feedback linearization regardless of \(A(q)\) dependence
Actuation-space controllers: Work directly in actuator coordinates without requiring actuation matrix inversion

The controllers handle different actuation scenarios:

Full actuation (\(n = m\), square \(A\)): Uses matrix inverse \(A^{-1}\)
Overactuation (\(m > n\)): Uses pseudo-inverse \(A^{\dagger}\) to minimize actuator effort
Underactuation (\(m < n\)): Only supported via pseudo-inverse \(A^{\dagger}\) and transpose \(A^T\); Preferably use actuation-space controllers instead

Configuration-Space Controllers¶

Overview¶

Trajectory Trackers¶

PIDController¶

soromox.control.configuration_space.PIDController ¶

__call__ ¶

model_based_term ¶

error_based_feedback_term ¶

update_gains ¶

ComputedTorqueTracker¶

soromox.control.configuration_space.ComputedTorqueTracker ¶

__call__ ¶

model_based_term ¶

error_based_feedback_term ¶

FeedforwardCompensationTracker¶

soromox.control.configuration_space.FeedforwardCompensationTracker ¶

__call__ ¶

error_based_feedback_term ¶

update_gains ¶

model_based_term ¶

MixedStateFeedbackTracker¶

soromox.control.configuration_space.MixedStateFeedbackTracker ¶

__call__ ¶

error_based_feedback_term ¶

update_gains ¶

model_based_term ¶

Setpoint Regulators¶

GravityCancellationRegulator¶

soromox.control.configuration_space.GravityCancellationRegulator ¶

__call__ ¶

error_based_feedback_term ¶

update_gains ¶

model_based_term ¶

PotentialCancellationRegulator¶

soromox.control.configuration_space.PotentialCancellationRegulator ¶

__call__ ¶

error_based_feedback_term ¶

update_gains ¶

model_based_term ¶

PotentialCompensationRegulator¶

soromox.control.configuration_space.PotentialCompensationRegulator ¶

__call__ ¶

error_based_feedback_term ¶

update_gains ¶

model_based_term ¶

Actuation Matrix Considerations¶

call ¶

call ¶

call ¶

call ¶

call ¶

call ¶

call ¶