Gymnasium wrappers

StableTested and in active use. Breaking changes will be called out. Python interop — expect Gymnasium's speed, not the native ports'.

Wrappers that drive Python Gymnasium environments from Mojo. Their primary job is validation: the native environments are faithful ports, and these let you run both from one process and compare.

from noeira.envs.gymnasium import (
    GymnasiumClassicControl,
    GymnasiumBox2D,
    GymnasiumToyText,
    GymnasiumMuJoCo,
)

Wrapper	Covers
gymnasium_classic_control	CartPole, MountainCar, Pendulum, Acrobot
gymnasium_box2d	LunarLander, BipedalWalker, CarRacing
gymnasium_toy_text	FrozenLake, Taxi, Blackjack, CliffWalking
gymnasium_mujoco	HalfCheetah, Ant, Humanoid, Walker2d, Hopper, Swimmer, …

pixi run mojo run -I . examples/gymnasium_demo.mojo

Gymnasium, Box2D and MuJoCo are pixi dependencies, so nothing extra to install.

Reference

• Gymnasium: A Standard Interface for Reinforcement Learning EnvironmentsTowers, Kwiatkowski, Terry et al. · 2024 · arXiv:2407.17032The API the native environments are ported against.

What they are for

Verifying a port. When a native environment’s dynamics look wrong, stepping both from the same state and diffing is the fastest way to find out. Several tests do exactly this, and the physics3d suite compares against live MuJoCo the same way.

Reaching environments not yet ported. Gymnasium has far more environments than noeira implements natively. If you need one of them, the wrapper gets you there today.

Sanity-checking a result. A suspiciously good score on a native environment is worth re-running on the reference.

What they are not for

Training at scale. These call into Python through interop, so you get Gymnasium’s single-environment CPU throughput plus a boundary crossing per step — precisely the cost the native environments exist to remove. They cannot be GPU-batched.

Use the native implementation for anything that matters:

Instead of	Use
GymnasiumClassicControl("CartPole-v1")	CartPoleEnv[DT]
GymnasiumMuJoCo("HalfCheetah-v5")	Phyics3dBatchedEnv[HalfCheetahModel, …]
GymnasiumBox2D("LunarLander-v3")	LunarLander[DT]

Known divergences

The native ports match Gymnasium’s dynamics, but a few observation conventions differ deliberately. Two worth knowing:

• Humanoid — 45 dimensions here versus Gymnasium’s 348–376. noeira observes position and velocity only, omitting contact forces and inertia terms.
• CarRacing — a slip-based tire model rather than Gymnasium’s simpler friction, which makes the task genuinely harder. Policies do not transfer.

Where a divergence exists it is noted on that environment’s page. Do not assume a published Gymnasium score is a target for the native version without checking.

Python interop gotchas

Two failure modes are known and unrelated to Gymnasium itself. Python temporaries created inside a Mojo function are not released until the function returns — a long-running loop holding PythonObjects leaks in a way invisible to RSS sampling, so keep hot Python loops short or move them into an exec’d block. And pyarrow crashes the embedded interpreter, so anything touching it must run in a subprocess.

Next

• Environments overview — the native catalogue
• Classic control — the ported originals