modurl_mujoco
Native Rust MuJoCo environments for ModuRL, using Candle tensors and mujoco-rs physics.
Implemented Gymnasium v5 environments:
AntV5— observation(105,), action(8,)HalfCheetahV5— observation(17,), action(6,)HopperV5— observation(11,), action(3,)HumanoidV5— observation(348,), action(17,)Walker2dV5— observation(17,), action(6,)
Installation
MuJoCo 3.9 is automatically downloaded by mujoco-rs on Windows and Linux. A clone of this repository works without extra configuration because .cargo/config.toml supplies a project-local cache. On Windows, this crate's build script also copies mujoco.dll next to Cargo-built executables and tests.
When adding modurl_mujoco as a dependency, Cargo does not read configuration files from dependencies. Add this to the consuming project's .cargo/config.toml:
[]
= { = "target/mujoco", = true, = false }
That limitation comes from mujoco-rs, which requires an absolute MUJOCO_DOWNLOAD_DIR while its dependency build script is running. macOS requires a manual MuJoCo installation; see the mujoco-rs installation guide.
Usage
use Device;
use *;
let mut environment = builder.device.build?;
let observation = environment.reset?.state;
let action = environment.action_space.sample?;
let transition = environment.step?;
# Ok::
Every builder defaults to the corresponding Gymnasium v5 configuration. The behavioral parameters can be overridden without constructing a separate config object:
let environment = builder
.frame_skip
.forward_reward_weight
.ctrl_cost_weight
.healthy_reward
.terminate_when_unhealthy
.healthy_z_range
.reset_noise_scale
.exclude_current_positions_from_observation
.build?;
# Ok::
The 1,000-step Gymnasium time limit is intentionally not built into the five Gymnasium-compatible environments; apply it in an environment wrapper.
Rendering
Enable the optional interactive MuJoCo viewer in your dependency:
= { = "0.1", = ["rendering"] }
Then opt an environment into rendering through its builder:
let mut environment = builder.render.build?;
environment.reset?;
# Ok::
The same .render(true) option is available on AntV5, HopperV5,
HumanoidV5, and Walker2dV5.
The viewer updates after resets, exact state changes, and simulation steps. Closing
the window stops rendering while leaving the environment usable. Interactive
viewers should be created on the application's main thread. Without the
rendering feature, the viewer dependencies and builder option are omitted.
License
modurl_mujoco is MIT-licensed and does not depend on GPL-licensed ALE code.
MuJoCo is Apache-2.0, mujoco-rs is used under its MIT option, and the
Gymnasium-derived XML models retain their upstream MIT notice in
assets/LICENSE. When available, the build places MuJoCo's
license and third-party notice files beside Cargo output automatically. Keep
those files with any binary distribution that includes the MuJoCo library.
Parity tests
The Python parity runner regenerates fixtures and executes the matching Rust tests. Pass one environment name to focus the entire workflow on it. For example, from this crate's directory:
python python_tests/parity.py ant
That command regenerates ant/trajectory.json with Gymnasium, then runs the
exact ant Rust parity test. To run the Rust test against the existing fixture
without requiring Python dependencies:
python python_tests/parity.py ant --rust-only
List the supported names or run every environment by omitting the name:
python python_tests/parity.py --list
python python_tests/parity.py
Install the pinned reference dependencies before regenerating fixtures:
python -m pip install gymnasium==1.2.1 mujoco==3.9.0
Use --generate-only when you only want to refresh fixture JSON. Ordinary
cargo test uses the committed fixtures and therefore does not require Python
or Gymnasium.
Every environment uses the same public baseline of 64 reference transitions.
The runner prints that count with --list, and the Rust tests reject fixtures
with any other length.
Each fixture follows the same procedure: Gymnasium produces a deterministic 64-step reference trajectory, then every recorded state/action pair is compared as a one-step transition from a clean solver state.
| Environment | Baseline | Observation tolerance | Reward tolerance | Additional check |
|---|---|---|---|---|
| Ant | 64 transitions | 1e-5 |
1e-5 |
Contact-force observations must be exercised |
| HalfCheetah | 64 transitions | 1e-5 |
1e-5 |
None |
| Hopper | 64 transitions | 1e-5 |
1e-5 |
None |
| Humanoid | 64 transitions | 1e-5 |
1e-5 |
Contact-force observations must be exercised |
| Walker2d | 64 transitions | 4e-3 positions; 6.6e-1 impact velocities |
2e-2 |
Includes simultaneous foot impacts |
Observation bounds also include one f32 conversion epsilon scaled by the
reference value. Walker2d keeps all impact transitions in the baseline; its
velocity-only allowance accounts for solver-order differences between the
official Python and mujoco-rs binary builds instead of shortening the fixture.