Environment variables¶
stable-envs reads the STABLE_ENVS_* environment variables below. Every one has a default, and setting them is optional.
STABLE_ENVS_CPU3D_CHUNK=8 STABLE_ENVS_TUNING_HINT=0 python train.py
stable-envs doctor # lists the variables that are set and flags unknown names
An unparsable value raises ValueError with the variable's name when the library reads it. stable-envs doctor flags unknown names, such as a misspelling.
Integer values take an optional K, M, G or T suffix (powers of 1024). auto or an empty value uses the default. Flags take 1 or 0.
Variables from other libraries, such as MUJOCO_GL, PYOPENGL_PLATFORM and MUJOCO_EGL_DEVICE_ID, are part of installing each family. stable-envs sets one of them, XLA_PYTHON_CLIENT_PREALLOCATE; see JAX GPU memory.
Tuning settings¶
Each variable sets one tuning setting for the whole process. How a value is chosen says when it wins.
| Variable | Sets |
|---|---|
STABLE_ENVS_WORKERS |
most worker processes |
STABLE_ENVS_LARGE_BACKEND_MIN_ENVS |
smallest batch that steps on the large-batch simulation backend with simulation_backend="auto" |
STABLE_ENVS_LARGE_RENDERER_MIN_ROWS |
smallest render batch that draws with the CUDA renderer of a class with a CPU and a CUDA renderer |
STABLE_ENVS_WORKER_MIN_ENVS |
smallest batch that uses worker processes |
STABLE_ENVS_WORKER_TIMEOUT |
seconds that a CPU simulator worker can take to answer one request |
STABLE_ENVS_FETCH_THREADS |
most simulator threads of an in-process Fetch batch |
STABLE_ENVS_DMC_THREADS |
most mujoco.batch threads of a DM Control batch |
STABLE_ENVS_CPU3D_CHUNK |
frames per chunk of the Torch CPU ray caster |
STABLE_ENVS_DMC_CPU_RAY_BUDGET |
rays per CPU render chunk of the fixed-camera DM Control classes |
STABLE_ENVS_DMC_RAY_BUDGET |
rays per CUDA render chunk of the fixed-camera DM Control classes |
STABLE_ENVS_DMC_GRAPH_ROWS |
most rows of a CUDA render chunk of the fixed-camera DM Control classes that replay one captured CUDA graph |
STABLE_ENVS_DMC_LAUNCH_RAYS |
rays per MJWarp launch of the DM Control body-tracking classes |
STABLE_ENVS_DMC_MIN_WORLDS |
fewest worlds per MJWarp launch of the DM Control body-tracking classes |
STABLE_ENVS_FETCH_MJW_WORLDS |
most worlds per MJWarp launch of the Fetch classes |
STABLE_ENVS_OGB_MJW_WORLDS |
most worlds per MJWarp launch of OGBCube and OGBScene |
STABLE_ENVS_OGB_CONTEXT_CACHE_BYTES |
GPU bytes of the OGBench MJWarp context cache |
STABLE_ENVS_OGB_GL_WORKERS |
most OpenGL worker processes of OGBCube and OGBScene |
STABLE_ENVS_RENDER_WORKERS |
most CPU render worker processes |
STABLE_ENVS_RENDER_WORKER_MIN_ROWS |
smallest CPU render batch that uses render workers |
STABLE_ENVS_NVD_BUDGET_BYTES |
GPU bytes per nvdiffrast chunk of PyFlytRocketLanding |
STABLE_ENVS_NAV_RENDER_CHUNK |
frames per render chunk of the navigation classes |
STABLE_ENVS_NAVDOT_BLOCK |
pixels per Triton tile of the navigation dot compositor |
STABLE_ENVS_NAVDOT_WARPS |
Triton warps per tile of the navigation dot compositor |
STABLE_ENVS_RASTER2D_BLOCK |
pixels per Triton program of the 2D rasterizer |
STABLE_ENVS_RASTER2D_CULL_WARPS |
Triton warps per tile of the 2D rasterizer with culling |
STABLE_ENVS_GFXDRAW_WARPS |
Triton warps per tile of the classic control rasterizer |
STABLE_ENVS_RAYCAST_BLOCK |
rays per Triton program of the analytic ray caster |
Tuning behavior¶
| Variable | Default | Effect |
|---|---|---|
STABLE_ENVS_TUNING_HINT |
1 | Set to 0 to hide the one-time log line that suggests stable-envs tune. It logs at INFO, so it shows only with STABLE_ENVS_VERBOSE=INFO or lower. |
STABLE_ENVS_AUTOTUNE |
0 | 1 tunes an untuned render path the first time it renders a large batch, then caches the values. |
Logging¶
| Variable | Default | Effect |
|---|---|---|
STABLE_ENVS_VERBOSE |
WARNING |
Default log level, with the same values as snv.set(verbose=...). snv.set overrides it. |
Environments¶
| Variable | Default | Effect |
|---|---|---|
STABLE_ENVS_MSHUMAN_HOME |
unset | Path to an existing MS-Human-700 checkout. When it's unset, stable-envs downloads the pinned commit into the cache ($XDG_CACHE_HOME/stable-envs/ms-human-700). |
STABLE_ENVS_DMC_CUDA_RENDER |
auto |
mjwarp makes the fixed-camera DM Control environments with backend="auto" on CUDA draw with the MuJoCo Warp ray tracer, as the body-tracking ones do by default. See DM Control. |
STABLE_ENVS_DMC_WARP_OPTIONS |
unset | A JSON object of default options for the DM Control MuJoCo Warp renderer, for example {"shadows": "one"}. The render_options argument overrides each key that it sets. |
JAX GPU memory¶
When JAX starts on a GPU, it reserves most of the GPU memory, and Torch then has little memory left. When stable-envs builds an environment that steps in JAX, it sets XLA_PYTHON_CLIENT_PREALLOCATE=false before JAX starts. JAX then allocates memory only when it needs it. These environments step in JAX: TwoRoom with the JAX backend, PushT with simulation_backend="jax", DMCReacher with simulation_backend="mjx", and the Craftax classes. Importing stable-envs or building another environment doesn't set the variable.
A value that you set is kept. If other code started JAX on a GPU before stable-envs built the environment, stable-envs can't change the setting. It then logs one warning that Torch can run out of GPU memory, unless you set XLA_PYTHON_CLIENT_PREALLOCATE, XLA_PYTHON_CLIENT_MEM_FRACTION or XLA_PYTHON_CLIENT_ALLOCATOR. To fix it, set the variable before Python starts, or build the environment before other code uses JAX:
XLA_PYTHON_CLIENT_PREALLOCATE=false python train.py
Development¶
| Variable | Default | Effect |
|---|---|---|
STABLE_ENVS_OGB_UNMEASURED |
0 | 1 lets a Cube or Scene class without measured visual fidelity values register with placeholder values while you measure them. OGBCube and OGBScene are measured, so it doesn't change them. Leave it unset for normal use. The library reads it once, at import. |