ogym 0.1.0

Composable, type-safe reinforcement learning environments for Rust
Documentation

OGym

Crate Documentation License

OGym is a Rust-native reinforcement learning library inspired by OpenAI Gym. It provides type-safe environments, explicit action and observation spaces, and implementations backed by native Rust, Rapier, and MuJoCo.

Highlights

  • Type-safe APIs: Actions and observations are checked through strongly typed spaces instead of untyped adapters.
  • Native performance: Environments use compiled Rust implementations with minimal runtime overhead.
  • Batch execution: The BatchEnvironment abstraction supports high-throughput workloads.
  • Multiple backends: Classic Control, Toy Text, Rapier2D, and MuJoCo environments share a consistent interface.
  • Opt-in native dependencies: The default feature set does not require a MuJoCo installation.

Benchmarks

OGym and Gymnasium benchmark comparison

The chart compares OGym with equivalent Gymnasium environments. Values are mean execution times with standard deviation; lower is better. See the benchmark suite for methodology and reproduction steps.

Supported environments

Family Environments Backend
Classic Control Acrobot, CartPole, MountainCar, Pendulum Native Rust
Toy Text Blackjack, CliffWalking, FrozenLake, Taxi Native Rust
Box2D / Rapier2D BipedalWalker, LunarLander Rapier
MuJoCo Ant, HalfCheetah, Hopper, Humanoid, HumanoidStandup, InvertedDoublePendulum, InvertedPendulum, Pusher, Reacher, Swimmer, Walker2d MuJoCo

Installation

Add ogym to your Cargo.toml:

[dependencies]
ogym = "0.1.0"

MuJoCo support

MuJoCo environments are optional. Enable the mujoco feature and install the native MuJoCo library separately:

[dependencies]
ogym = { version = "0.1.0", features = ["mujoco"] }

Current limitation: The MuJoCo feature relies on OGym's repository-local patch for mujoco-rust, which crates.io packages cannot pass on to consumers. Use a source checkout for MuJoCo environments until the patched wrapper is published; the default crates.io feature set is unaffected.

MuJoCo 3.10.0

OGym targets MuJoCo 3.10.0. On Linux x86-64, install the prebuilt archive under the default path expected by the project:

mkdir -p "$HOME/.local/mujoco"
curl --fail --location \
  https://github.com/google-deepmind/mujoco/releases/download/3.10.0/mujoco-3.10.0-linux-x86_64.tar.gz \
  | tar -xz --strip-components=1 -C "$HOME/.local/mujoco"

Official prebuilt packages are also available for Linux AArch64, macOS universal, and Windows x86-64.

If MuJoCo is installed elsewhere, set MUJOCO_DIR to its root directory and make its lib directory available to the platform's dynamic linker.

Quick start

The following example runs a CartPole episode with sampled actions:

use ogym::{
    env::control::cart_pole::{CartPole, CartPoleConfig},
    env::environment::Environment,
    spaces::Space,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = CartPoleConfig::new();
    let mut env = CartPole::new(config)?;

    env.reset(None)?;

    let mut total_reward: f64 = 0.0;
    loop {
        let action = env.space.action.sample()?;
        let experience = env.step(action)?;
        total_reward += experience.reward;

        if experience.terminal.is_done() {
            break;
        }
    }

    println!("Episode finished. Total Reward: {:.2}", total_reward);
    Ok(())
}

Core abstractions

OGym uses three core traits across every backend:

Trait Responsibility
Space Defines, samples, and validates action and observation bounds.
Environment Provides reset and step semantics for a single environment.
BatchEnvironment Manages multiple environment instances for high-throughput execution.

For a detailed design overview, see the architecture documentation.

Development

Common development workflows are available from the repository root:

just --list
just validate
just build-mujoco
just test-mujoco
just benchmark cartpole
just benchmark-all

See the contributor guide for repository structure, testing expectations, and pull request guidance.

Contributing

Bug reports, feature requests, and pull requests are welcome. Discuss major architecture changes in an issue before implementation and include benchmark evidence for performance claims.

License

OGym is distributed under the MIT License.