Feature Proposal: Hydraulic cylinder actuator plugin for construction machinery simulation

[LoneWolfDog]

Hi MuJoCo team,

I'd like to propose contributing a hydraulic cylinder actuator plugin to MuJoCo. Hydraulic actuation is the backbone of construction machinery, heavy robotics, and industrial motion systems, yet MuJoCo currently has no support for fluid-power dynamics. I believe this is a significant gap that a plugin can fill without touching the core engine.

Why this matters

MuJoCo's existing actuator types (motor, position, velocity, general) are kinematic abstractions. Real hydraulic systems are governed by pressure continuity ODEs — the actuator force emerges from cavity pressure dynamics, orifice flow equations, and fluid compressibility, not from a direct torque/force command. This matters for:

• Sim-to-real transfer: position/velocity actuators produce unrealistic actuator stiffness and bandwidth limits; hydraulic dynamics introduce the true compliance characteristics that control algorithms must handle.
• Construction/mining robotics: excavators, wheel loaders, drill rigs — a growing research area (RSS, ICRA, IROS) where sim-to-real gap is a well-known pain point.
• Industrial servo-hydraulics: injection molding, press machines, flight control actuators.

What already exists: hydrasim

I've built and open-sourced hydrasim (MIT, v0.3.2), a Python-based electro-hydraulic plant simulator designed as a testbed for control algorithms (ADRC, RLS, self-calibration). It has been extensively validated and is the reference implementation for what the MuJoCo plugin would provide.

Single-joint model (5-DOF state):

State: [x, v, P_a, P_b, x_v]

Physics:

• 4/3 proportional directional valve with 4-quadrant orifice flow (turbulent √ΔP law)
• Asymmetric double-acting cylinder (A_a ≠ A_b, stroke-dependent chamber volumes)
• Pressure continuity ODE: dP/dt = β_e/V × (Q_in - Q_out - A × v) ← this is the key equation
• Stribeck friction (tanh-smoothed) + viscous damping
• Deadband, backlash hysteresis, internal leakage
• Hydraulic natural frequency ~26 Hz (mid-stroke, typical 20-ton excavator)

Multi-actuator excavator arm (21-DOF state):

• 2D planar linkage (boom/arm/bucket + swing motor) with coupled M(q) dynamics
• 4 valve-controlled actuators sharing a variable-displacement pump
• LUDV flow distribution with supply pressure capacitance
• Three pluggable integration strategies (IMEX, TLM, Constrained IMEX)

Validation (v0.3.2):

• 31 unit tests + 9-stage physical expectation checks, all passing
• Parameters calibrated to real-world Komatsu PC200-8 (20-ton excavator)
• v0.3.1 fixed 4 independent bugs (including a subtle sign error in soft-limit torque) — see CHANGELOG for details

Proposed plugin architecture

Following the pattern of the existing mujoco.pid plugin, the hydraulic cylinder plugin would be a C++ engine plugin:

plugin name: "mujoco.hydraulic_cylinder"
capability: mjPLUGIN_ACTUATOR

Plugin state (per cylinder): [P_a, P_b, x_v, hysteresis_state] — 4 floats per actuator

Configurable XML attributes:

bore, rod, stroke, beta_e, rho, Q_nom, dP_nom, tau_v,
F_coulomb, F_stiction, v_stribeck, B_viscous,
deadband_pos, deadband_neg, hysteresis, C_leak,
P_supply, P_return, n_substeps

Coupling with MuJoCo's dynamics:

This is the key design question. The hydraulic plant and MuJoCo's rigid body dynamics form a two-way coupling:

MuJoCo:  M(q)q̈ = F_hyd − C(q,q̇) − G(q) + F_contact
                     ↑                        ↓
hydrasim:  dP_a/dt = (β_e/V_a) · (Q_a − A_a·v)
           F = P_a·A_a − P_b·A_b
                     ↑
           v = J(q) · q̇   (piston velocity from joint velocity)

My proposed approach: one-step-delay decoupling

• compute() uses previous step's P_a, P_b to output F → fed to MuJoCo
• advance() uses MuJoCo's computed q̇ (this step) to sub-step integrate P_a, P_b → ready for next step
• At 1 kHz timestep with 5–10 hydraulic sub-steps, the delay error is well within stable bounds for typical hydraulic natural frequencies (~26 Hz)

MJCF usage:

<extension>
  <plugin plugin="mujoco.hydraulic_cylinder">
    <instance name="boom_cyl">
      <config key="bore" value="0.12"/>
      <config key="rod" value="0.085"/>
      <config key="stroke" value="1.334"/>
      <config key="beta_e" value="1e8"/>
      <config key="n_substeps" value="10"/>
    </instance>
  </plugin>
</extension>

<actuator>
  <plugin joint="boom" plugin="mujoco.hydraulic_cylinder" instance="boom_cyl"/>
</actuator>

What stays out (and why)

• Multi-body kinematics: MuJoCo already does this better than any hand-rolled solution. The mech/ module in hydrasim becomes unnecessary in the MuJoCo integration.
• Pump/manifold models (v2): The shared pump with LUDV distribution requires cross-actuator coupling, which is architecturally harder in the current plugin model. Single-cylinder is the right MVP.
• Controller logic: hydrasim is a plant model, not a controller. Users write their own controllers (or use mujoco.pid!).

Questions for the team

1. Is there interest in this direction? I'd like to confirm alignment before investing in the C++ porting effort.

2. Coupling approach: Does the one-step-delay approach raise concerns? The alternative would be exposing hydraulic states to MuJoCo's implicit integrator, which seems like a much larger undertaking. I'd appreciate any suggestions on a cleaner coupling mechanism.

3. Scope for MVP: Is single-cylinder MVP the right starting point, or would you prefer a different scope? I'm also considering whether a simplified "hydraulic cylinder as force generator with pressure states" (ignoring the pump dynamics initially) is the right first step.

4. Existing work: Are there any internal efforts or community projects I should be aware of that overlap with this?

About me

I work on intelligent excavator control (autonomous material handling, wire-controlled hydraulics, ADRC/RLS self-calibration). hydrasim was built as the plant model testbed for these control algorithms.

I am ready to contribute. Looking forward to your feedback!