Changelog
Changelog¶
All notable changes to this project are listed here. The format follows Keep a Changelog, and the project uses Semantic Versioning.
[Unreleased]¶
Breaking changes¶
- Renamed tuning names:
snv.tuning.Knobissnv.tuning.Setting,snv.tuning.KNOBSissnv.tuning.SETTINGS, theknobsargument ofsnv.tuneissettingsand the--knoboption ofstable-envs tuneis--setting. Theworker_min_lanessetting isworker_min_envs, and its variableSTABLE_ENVS_WORKER_MIN_LANESisSTABLE_ENVS_WORKER_MIN_ENVS. - The
render_rungsclass attribute ofEnvisrender_backends, and its entries areBackendPairvalues in place ofRungsvalues. - The Craftax state has three leaves, one for each dtype, such as
craftax/int32orcraftax_classic/int32, in place of one leaf for each upstream field. Each field, such asengine/player_healthorphysics/zombie/health, is a slice of one of them. Read and write a field withsnv.get_fieldandsnv.set_field. States saved before this change do not load. - The
mjwarp_min_envsargument of the DM Control classes,OGBCubeandOGBScene, thetriton_min_envsargument of PushT and thejax_min_envsargument of TwoRoom are removed, with the tables of measured cutoffs. Thelarge_backend_min_envstuning setting (STABLE_ENVS_LARGE_BACKEND_MIN_ENVS) sets the switch point for these classes. simulation_backend="auto"is the default of the DM Control classes,OGBCube,OGBSceneand PushT, and it has the same meaning in each: on CUDA, small batches step on the small-batch backend and large batches on the GPU backend."default"is no longer accepted byOGBCubeandOGBScene; None still means"auto".- The PushT state is folded: its fixed-shape fields are slices of one
(N, size)leaf for each section and dtype, and the action history keeps its own leaves. The state has about 20 leaves instead of 239, and it leaves out the goal image. Read and write fields withsnv.get_fieldandsnv.set_field. - The DM Control state has three leaves:
dmc_<task>/float64,dmc_<task>/int64anddmc_<task>/bool, such asdmc_reacher/float64. Each field, such asqposorrng/keys, is a slice of one of them. Read and write a field withsnv.get_field(state, "qpos")andsnv.set_field. States saved before this change do not load. - The
OGBCubeandOGBScenestate has one leaf for each section and dtype, such asphysics/float64. Each field, such asphysics/qposorphysics/mocap_pos, is a slice of one of them. Read and write a field withsnv.get_field(state, "physics/qpos")andsnv.set_field. States saved before this change do not load. - The navigation classes fold their state. TwoRoom, TwoRoomTarget, Piecewise and PiecewiseZones keep the agent and target positions in one
navigation/float32leaf, and SimplePointMaze keeps its fields in onesimple_point_maze/<dtype>leaf for each dtype. Read and write a field withsnv.get_field(state, "agent.position")andsnv.set_field. - The
torch_min_envsargument of the classic-control classes, thenumba_cuda_min_envsargument ofPyFlytRocketLandingand thetriton_min_envsargument ofMiniWorldMovingBlockWorldare removed, with theNUMPY_MIN_ENVS,TORCH_MIN_ENVS,NUMBA_CUDA_MIN_ENVSandTRITON_MIN_ENVSconstants.simulation_backend="auto"is the default of these classes. It uses the switch points that each class ships, or thelarge_backend_min_envssetting andstable-envs tune. - Classic control with
simulation_backend="torch"on CUDA resets with Gymnasium on the host. A seed gives Gymnasium's initial states on every backend, and therngstate fields hold the PCG64 state instead of a key and a reset count. - The classic-control and
MiniWorldMovingBlockWorldstates have one leaf for each dtype, such as("cartpole", "float64"), in place of one leaf for each field.snv.get_field(state, "physics/gravity")reads a field by name. - The
mjwarp_min_envsargument of the OGBench maze classes, the Fetch classes,MSHumanLocomotionand the Roadster classes is removed, with theMJWARP_MIN_ENVSandMAZE_MJWARP_MIN_ENVSconstants. Their defaultsimulation_backendis"auto", which uses thelarge_backend_min_envsswitch;"default"is no longer accepted. The internalmjbatch.resolve_backendis replaced bymjbatch.mujoco_backend. - The state of the OGBench maze classes, the Fetch classes,
MSHumanLocomotionand the Roadster classes has one tensor for each group of fields instead of one tensor for each field. Read and write a field by name withstable_envs.get_field(state, name)andstable_envs.set_field(state, name, value).state_specanddescribe()list the groups.
Added¶
benchmarks/speed.py,benchmarks/render_mse.pyandbenchmarks/rollout_parity.pycompare stable-envs with stable-worldmodel21446f1: speed on the same cores in one run, frame MSE, and state error. Thebenchdependency group installs stable-worldmodel.benchmarks/online_ladder.pyandbenchmarks/offline_sweep.pyare the scripts that measured the speedup tables of the paper: physics, rendering only, and both, on CPU and GPU, against stable-worldmodel21446f1.examples/lewm/throughput.pymeasures LeWM training speed and GPU use with stored frames, the stable-worldmodel renderer and stable-envs.- The Craftax classes have physics variation: the variation leaves set fields of the upstream
EnvParamsfor each environment, and the state keeps the values, soset_staterestores them. snv.FrameLoader(env, states, batch_size)yields the frames of stored States or rows a batch at a time. It draws many batches in oneenv.rendercall, with a chunk size that it picks from free device memory and caps at the environment'srender_ahead_rows, so small batches draw at the per-frame cost of a large batch. Each batch has the same bytes asenv.renderof its states, except forOGBCubeon CUDA, where a few pixels differ by 1 level.step(..., state=False)skips building the final state; the result then has nostatekey, andget_state()builds the state on demand.
Changed¶
- Craftax draws its frames in the jitted step with one texture gather per pixel, with the same bytes as upstream's renderer. A sequence of actions steps in one jitted
lax.scan. On CPU, the environments are split over one XLA host device per usable CPU, with at least 32 environments on each device. - stable-envs sets
XLA_PYTHON_CLIENT_PREALLOCATE=falsewhen it builds an environment that steps in JAX, before JAX starts, and no longer when it imports a JAX backend module. A value that you set is kept. If JAX already started on a GPU without the variable, stable-envs logs one warning with the fix. See JAX GPU memory. - CartPole and MountainCar have a
"numba"simulation backend that steps the batch in one compiled call, in place on the state, with Gymnasium's values."auto"uses it on the host at every batch size. - With
simulation_backend="auto", DM Control,OGBCube,OGBScene, PushT and TwoRoom select their CUDA physics backend from the batch size with one shared rule. The switch point comes from thelarge_backend_min_envssetting, else from the tuning cache thatstable-envs tunewrites, else from the value each class ships. Building an environment times nothing. See Physics backends. - On CUDA, the CPU physics of DM Control,
OGBCube,OGBSceneand TwoRoom moves the result of a single step to the device in one copy: the state, the outputs, thestatesand the validity masks. PushT moves the outputs and the state of a single step without frames in one copy. PushT's Numba backend keeps its state on the CPU and no longer copies it to and from the device at each step. - On CUDA, a step result that moves from the host reuses the device memory of an earlier result when no tensor uses that result any more. A single step stacks a state whose leaves share one buffer with one copy.
- TwoRoom and the other classes with reset leaves build their reset sampling tree once per environment, not at each
reset. On CUDA, a TwoRoom reset moves its state to the device in one copy. - A step that returns its state exports it with the outputs in one call, and a single step stacks its outputs without the TensorDict dispatch. This lowers the cost of each
stepcall. - With
simulation_backend="auto"on CUDA, PushT steps batches of fewer than 128 environments with Numba on the CPU and moves the outputs and the state of each step to the device, and larger batches with Triton. - PushT resets batches of 8 or more environments in worker processes (the
worker_min_envssetting still sets the size). Its Numba step does its bookkeeping in one Numba call, keeps the state layout across resets and, on CUDA, returns the outputs already on the device. - On CUDA, the
mujoco.batchphysics of Fetch, MS-Human and Roadster moves the outputs and the state of a step to the device in one copy. MS-Human converts the state to float32 before the copy.
Fixed¶
- OpenGL contexts of OGBench environments are released.
env.close()frees the shared OGBench renderers and stops the Cube and Scene OpenGL worker processes when the last environment closes, and interpreter exit frees any that remain before MuJoCo ends its EGL display. This removes theEGLErrorthatmujoco.Renderer.__del__raised at exit.
0.1.0 - 2026-11-13¶
First public release.
Added¶
- 80 batched environment classes across classic control, DM Control, Fetch, navigation, OGBench, PushT, PyFlyt Rocket Landing, Roadster, Craftax, Miniworld and MS-Human-700. Most families install as an optional extra, and a missing extra disables only its own family;
snv.import_errors()names the cause. Fetch needs MuJoCo below 3.12 and a separate Python environment from DM Control, MS-Human,OGBCubeandOGBScene, which need MuJoCo 3.17. - A class-first API:
snv.CartPole(num_envs=..., device=...), plussnv.make,snv.info,snv.list_envsandsnv.list_families. - Batched stepping on CPU or GPU. One
stepcall takes(B, A)actions for one transition or(B, T, A)for a sequence, and returns a validity mask instead of resetting finished environments. A step builds intermediate states only for the steps thatstatesselects. Env.render(x)is the one public render method. It draws frames without advancing the simulation from None (the live batch rows), a stored full state, a RenderState fromto_render_state(Cube, Scene, PushT, PyFlytRocketLanding) or compact(B, state_dim)rows fromsample_states. A state draws with its own variation, and rows draw with the current variation or withvariation=. PushT, Miniworld and Craftax have no compact rows, andPyFlytRocketLandingdraws rows on CUDA only; a refused form raises an error that gives the accepted forms.render(state)checks only the state fields that the renderer reads, andset_statechecks the full state.Env.native_sizeis the onlysizethat a class draws, the size of its upstream library. Classic control, navigation and Craftax set it, and the other classes draw any size.snv.info()and the environment pages show it.get_stateandset_statesave and restore a complete TensorDict state. When the batch runs in worker processes,set_statechecks every batch row in every worker before any worker restores. An invalid state raises and leaves every worker as it was.- Variation spaces:
sample_variation,set_variationand per-environment reset options, compatible with stable-worldmodel. Env.describe()reportsstate_fields, the shape and dtype of each state field.visual_fidelityrecords, for the classes that declare it, the per-frame MSE against the upstream library asmse_mean,mse_p95andmse_maxon the 0-255 scale, andvisual_notesays where the frames differ.snv.tuning: chunk sizes, Triton block sizes, worker counts and memory budgets are named settings that you set withsnv.tuning.set,snv.tuning.overrideorSTABLE_ENVS_<BACKEND_SETTING>variables. Some defaults come from the GPU's free memory or the CPU's L3 size. Settings never change frames or state.cpu3d.render(chunk_size=None)andraster2d.render_triton(block=None)read them too. See Performance tuning.stable-envs tune <Env>andsnv.tune(env)measure the fastest setting values for one render path on your machine and cache them.--show,--clearand--allmanage the cache.- A large render on an untuned path logs one
INFOhint to runstable-envs tune. SetSTABLE_ENVS_TUNING_HINT=0to hide it, orSTABLE_ENVS_AUTOTUNE=1to tune such a path on first use. stable-envs doctorchecks the driver, Warp and MuJoCo OpenGL setup of each family. It also reports how many render paths are tuned, lists theSTABLE_ENVS_*variables that are set, flags unknown names and checks torch's compiled GPU architectures.- Environment variables lists every
STABLE_ENVS_*variable. An unparseable value raisesValueErrornaming the variable. - The MuJoCo families (DM Control, Fetch, MS-Human and OGBench) step every environment of a batch in one call:
mujoco.batchon CPU, and MuJoCo Warp on CUDA by default, with the substeps of a step in one captured CUDA graph.simulation_backendselects either one, and"auto"uses MuJoCo Warp for CUDA batches ofmjwarp_min_envsor more. The sharedWarpBatchbackend runs the kinematics, body velocities and RNE tree passes of a substep with one thread block per environment. - A stable-envs MuJoCo rasterizer (
stable_envs.render.mujoco_raster) follows MuJoCo's OpenGL renderer, in Numba on CPU. It is the default CPU renderer ofOGBCubeandOGBScene(backend="numba", which raisesValueErroron CUDA), and it gives the Fetch and Cube/Scenerender_semantic(segmentation and planar depth).backend="opengl"draws the exact source frames. - On Linux, the families without a batched step run large CPU batches in spawned worker processes, and large render batches draw in render worker processes. The
workers,worker_min_envs,render_workersandrender_worker_min_rowssettings size the pools without changing the frames.worker_timeout(STABLE_ENVS_WORKER_TIMEOUT, default 120) sets the seconds that a worker can take to answer one request before the batch fails. - On a CUDA device, environments that step in worker processes keep the step bookkeeping on the CPU and move the outputs to the device at the end of
step. - Classic control:
simulation_backendstepsCartPole,Pendulum,Acrobot,MountainCarandMountainCarContinuousin one batched float64 operation. By default, CPU batches step in NumPy and the smallest keep the Gymnasium loop, which is faster at that size. There, Gymnasium resets the batch and owns the PCG64 streams, NumPy steps give the same state and outputs as Gymnasium, and Torch steps agree to rounding. CUDA batches step on the GPU in one Triton kernel replayed as a CUDA graph, with resets drawn on the GPU."auto","gym","numpy"and"torch"select other backends. - Classic control: on CPU, a step does not copy the state into the render rows of the environment. The rows are copied from the simulator when a reader needs them, such as
render()without a state. The Gymnasium backend builds its state and outputs without TensorDict validation. - Classic control: on CPU, a Numba kernel draws the same primitive records as the Triton kernel, in parallel over frames, and its frames are byte-identical to the Torch path. With
backend="auto", small batches of the default appearance draw with the Gymnasium renderer. - Classic control: frames equal the Gymnasium frames even at angles close to a multiple of pi/2. The rasterizer rotates as pygame's
Vector2.rotate_raddoes. - DM Control: 17 classes. On CPU, every environment steps in one
mujoco.batchcall on CPU threads (thedmc_threadssetting), and the batch copies one compiled model instead of compiling one per environment. - DM Control: on CPU, one Numba kernel draws the frames of every class, shading pixels in the float32 operation order of the Torch renderer. The frames match the Torch frames except for rare pixels where Torch's CPU square root rounds through MKL.
backend="torch"selects the Torch renderers. - DM Control:
CheetahRunruns the settling steps of its reset in themujoco.batchof the environments, andQuadrupedWalksearches the start heights of all resetting environments together. The data, state and RNG are bitwise those of dm_control's reset. - DM Control: on CUDA, MuJoCo Warp 3.17 steps all 17 classes by default (
dmcontrol-gpuextra), through the sharedWarpBatchbackend with the MuJoCo Warp step as it is. A control round is dm_control'slegacy_stepin one captured CUDA graph, and the step reads no values from the device.simulation_backend="auto"uses native physics below a measured cutoff per task, and"mjx"keeps Reacher's MJX physics. - DM Control:
backend="mjwarp"draws every class except the Manipulator classes on CUDA with the MuJoCo Warp ray tracer, withrender_optionsfor shadows, samples, geom groups and passes. On CUDA,backend="auto"selects it for the body-tracking classes,STABLE_ENVS_DMC_CUDA_RENDER=mjwarpalso selects it for the fixed-camera classes, andSTABLE_ENVS_DMC_WARP_OPTIONSsets default options. - DM Control: a mid-episode physics
set_variation()takes full effect from the next step. - DM Control:
DMCFingerTurnHarddraws the target sphere and the tip site by default, as dm_control'sfinger-turn_harddoes. Setvisibility.targetto 0 for stable-worldmodel's default, which hides both. - The
dmcontrolandogbench-manipulationextras both pin MuJoCo 3.17 and install side by side. - OGBench: 27 classes.
OGBCubeandOGBSceneuse the OGBench cube size and reset as OGBench does. On CPU, their reset and every step are bit-identical to OGBench, and MuJoCo Warp steps them on CUDA. Their frames have the look of the OGBench pixel tasks that theirreference_idnames. - OGBench:
OGBCubeandOGBScenekeep a per-environment copy of the NumPy global RNG that OGBench samples tasks from, in therng/taskleaves, which lets a seeded reset replay. The arm starts atagent.ee_start_positiononly when the reset options name that leaf orset_variationsets it. - OGBench:
OGBCubeandOGBScenedraw with the MuJoCo rasterizer by default on CPU, and with NVIDIA OpenGL on CUDA.backend="opengl"draws the source frames, in up toogb_gl_workersprocesses on Linux. On CUDA,supersample=2orbackend="mjwarp_fidelity"selects the MJWarp renderer. - OGBench: the mazes step every environment in one
mujoco.batchcall on CPU, bit-identical to OGBench, and on MuJoCo Warp on CUDA, where PointMaze integrates with Euler. A step stacks itsstatesleaf by leaf on CPU. On CUDA, MuJoCo Warp copies the state into one buffer, and thestatesof a step are one copy of these buffers. - OGBench:
PointMazeLargeNavigatetests its spotlight shadow rays only against nearby walls on CPU and draws its tracking light with Numba kernels, and renders batches of 2048 or more on CUDA. On CPU, a maze step does its Torch operations on one thread. - Fetch: 12 classes. On CPU, one batched call steps every environment, bit-identical to Gymnasium Robotics, and MuJoCo Warp steps CUDA batches by default.
simulation_backend="source"keeps Gymnasium Robotics' own step, in worker processes for large batches. - Fetch: on CPU, a Numba rasterizer draws the frames by default, with a mean per-frame MSE of about 0.15 against the source.
backend="opengl"draws them as Gymnasium Robotics does, including the translucent mocap markers, byte for byte at the tested sizes, and draws large batches in render worker processes (thefetch-opengltuning path). Each sky color uploads once per OpenGL context, and a batch with mixed sky colors renders as fast as a uniform one. - Navigation: on CPU, one Numba kernel moves every environment of
TwoRoom,TwoRoomTarget,PiecewiseandPiecewiseZones, with the same float32 rounding as the Torch step. A second kernel draws their dots.simulation_backendalso accepts"torch", andTwoRoomaccepts"jax". - Navigation: on CUDA,
TwoRoomuses JAX dynamics fromjax_min_envsup (1 by default) and needs thenavigation-gpuextra. Target distances stay on the device. - Navigation:
PiecewiseZonesandTwoRoomTargetdraw seeded resets from the same distribution tree asPiecewiseandTwoRoom, which makesreset(seed=k)start where stable-worldmodel does. - Navigation:
SimplePointMazedraws each distinctinfo.goalbackground once and returns the same goal tensor at every step. Treatinfo.goalas read-only. - PushT:
PushTandPushTDiscretedraw frames byte-identical to pygame with a Numba rasterizer on CPU and, when Triton is installed, Triton kernels on CUDA. On CPU, one Numba call draws all the frames of a batch, and action markers use the OpenCV call of the source. On CUDA, frames with action markers, unsupported shapes or a coordinate near a rounding midpoint fall back to pygame.backendtakes"auto"or"source". - PushT: a port of the Pymunk contact solver steps every environment in one call: in Numba in float64 on CPU, in Triton in float32 on CUDA, or in JAX (
simulation_backend). The state holds the solver cache, soset_staterestores without a replay. On Linux, large batches reset and render in worker processes (thepusht-simandpusht-rendertuning paths). - PushT: continuous actions outside [-1, 1] are accepted, as stable-worldmodel accepts them.
PushTDiscreteindices must be in [0, 16). - PushT: a bad
render(out=)buffer raises an error saying that the buffer must be contiguous and match the frames in shape, dtype and device. - PyFlyt Rocket Landing:
simulation_backend="numba"(the default on CPU) and"numba_cuda"(the default on CUDA) step every environment in one call of a Numba port of the PyFlyt forces and the Bullet rigid-body step, with a seeded PCG64 thrust noise for each environment."pybullet"keeps the PyFlyt and PyBullet engines with the replay-backed state that is exact to the source. - PyFlyt Rocket Landing: on CPU, a Numba port of TinyRenderer draws all the frames of a batch in one call (
backend="numba", the default).backend="pybullet"draws with PyBullet's TinyRenderer. - PyFlyt Rocket Landing: with
simulation_backend="pybullet"on CPU, the physics worker processes draw step frames with TinyRenderer, and render worker processes draw batches of stored states. One process holds at most 1022 environments, and larger batches use more processes on every platform. - PyFlyt Rocket Landing: a reset or a restore replaces the PyBullet client of one environment at a time, so a worker process holds at most one client more than its environments. A large state leaf that is all zero, such as
current/wrapper/current_goalwithout a render mode, isn't stored for each environment. A reset checks the arguments of every environment before it changes one, and a failed restore replays the states it replaced, so no environment changes. With frames on CUDA and 8 cores of an L40S machine, the peak host memory is 37.0 GB for 1024 environments and 70.0 GB for 2048, where the PyFlyt source in 8 worker processes uses 37.5 GB and 70.6 GB. - PyFlyt Rocket Landing: on CUDA, the renderer draws the fins, legs and fuel tank at the current body pose, picks ground texels as TinyRenderer does, and hides the ground when the camera is below it. The mean per-frame MSE against PyFlyt is 4.2.
- PyFlyt Rocket Landing: the flame changes color at ignition, and reset saves and restores the engine around the goal render, as the PyFlyt pixel environment does.
- Roadster:
RoadsterLoop,RoadsterMission,RoadsterTrafficJam,RoadsterRooftopandRoadsterCarHopare five planning tasks for a jet-powered car in MuJoCo (roadsterextra). They have a complete state withweather.windandweather.rainphysics leaves. - Roadster: MuJoCo's OpenGL renderer draws the world-model camera, on the GPU with its EGL driver and on the CPU otherwise. The visual variation leaf
rendering.cinematicdraws the same state on a dark-space scene with shadows and MSAA. The exhaust smoke comes from the exhaust history in state (fx), which letsrender(state)show it. - Roadster: the five classes step every environment in one batch: NumPy and
mujoco.batchon CPU, bit for bit as the source, and Torch and MuJoCo Warp on CUDA, approximately as the source (simulation_backend,roadster-gpuextra). Large CPU batches draw in render workers (theroadster-rendertuning path). - Craftax:
CraftaxClassicPixels,CraftaxClassicSymbolic,CraftaxPixelsandCraftaxSymbolicrun the upstream JAX simulator with the whole batch in one jittedvmap(craftaxandcraftax-gpuextras). - Miniworld:
MiniWorldMovingBlockWorldruns the 3D Dynamic Blockworld of Flow Equivariant World Models (MovingBlockWorldfrom the hlillemark/Miniworld fork'sflowm_releasebranch) with a complete state, and draws Miniworld's own OpenGL agent view (miniworldextra). - Miniworld:
preset="flowm"(the default) is the paper's dynamic dataset,preset="flowm-textured"its textured split andpreset="upstream"the registered environment. Each episode of the FloWM presets draws 6 to 10 blocks, and state pads them with ablocks.presentmask. - Miniworld: one batched step moves every environment, in Numba on CPU, bit-identical to the fork, and in Triton on CUDA. Large batches draw
render(state)in render workers (theminiworld-rendertuning path). - MS-Human-700:
MSHumanLocomotionwraps the whole-body musculoskeletal locomotion model (mshumanextra).mujoco.batchsteps it on CPU and MuJoCo Warp on CUDA, the float32 state lives on the environment's device, and MuJoCo's OpenGL renderer draws the frames. On CPU, a step stacks itsstateswith the shared core stack on one Torch thread. - MS-Human-700: the Apache-2.0 model downloads from LNSGroup/MS-Human-700 at a pinned commit on first use. Set
STABLE_ENVS_MSHUMAN_HOMEto use an existing checkout. - Comparison tests check each environment against its upstream library and against stable-worldmodel, for state, simulation, tasks and pixels.
- The tests compare frames with a recorded source MSE for each class (
tests/fixtures/source_mse.json) and with golden frames of the project's own renderers (tests/fixtures/golden/). stable_envs.testingmeasurement helpers, thebenchmarks/harness, includingbenchmarks/dmc_mjwarp.pyfor native and MuJoCo Warp DM Control physics, and the MkDocs documentation. The benchmarks use only the public API.benchmarks/offline_sweep.pyandbenchmarks/online_ladder.pytime stable-envs against the upstream library of each family on stored inputs and in online rollouts, and write the frame MSE against the upstream library.examples/lewm/trains and evaluates the LeWM world model of stable-worldmodel on PushT.train.pyreads states and actions from the dataset and draws the frames withenv.render(state)on the training device.
For known gaps, see the Limitations section of each environment page.