Tuning

stable_envs.tuning holds the settings that set chunk sizes, Triton block sizes, worker counts and memory budgets. A setting changes speed and memory use, and every value gives the same frames and states. Each setting has a default and a fixed order of sources for its value, both listed below. See Performance tuning for when to change one.

import stable_envs as snv

print(snv.tuning.get("nav_render_chunk"))               # 256
snv.tuning.set(nav_render_chunk=64)                     # for the whole process
with snv.tuning.override(nav_render_chunk=32):          # for this block only
    print(snv.tuning.describe()["nav_render_chunk"])    # (32, 'override')
print(snv.tuning.describe()["nav_render_chunk"])        # (64, 'set')
snv.tuning.set(nav_render_chunk=None)                   # clear it again
print(snv.tuning.describe()["nav_render_chunk"])        # (256, 'fallback')

How a value is chosen

The library reads a setting each time it does the work, and a change applies to the next call. large_backend_min_envs is read when the environment selects its physics backend, and large_renderer_min_rows each time it draws. workers, worker_min_envs, worker_timeout, fetch_threads and dmc_threads are read when the environment builds its worker processes or threads. The library uses the first value it finds:

Source Set by
override snv.tuning.override(...) blocks, innermost first
set snv.tuning.set(...)
env The STABLE_ENVS_<SETTING> environment variable, such as STABLE_ENVS_NAV_RENDER_CHUNK=64
cache stable-envs tune or snv.tune(env), for this device, render path, frame size and batch range
derived A rule that reads the hardware, for the settings that have one
default The call site's own value, such as the per-class cpu3d_chunk table of the DM Control body-tracking classes
fallback SETTINGS[name].fallback

describe() returns the value and the source of every setting. Overrides live in a context variable and stay in the thread that set them. Wrapping each environment's calls in its own override block gives two environments different values. Setting values are per render path, the code that draws a group of classes: every fixed-camera DM Control class shares the dmc-suite path, and a value measured with DMCCartpoleSwingup also applies to DMCReacher. The Triton block and warp settings and ogb_mjw_worlds have one value for the whole device instead.

An unknown name, a non-int value, a value that is too small, or a value of the wrong kind (a power of two or a Triton warp count) raises ValueError:

try:
    snv.tuning.set(navdot_block=3)
except ValueError as e:
    print(e)  # tuning setting 'navdot_block' takes a power of two, got 3

Settings

Values are ints, and "batch rows" means the batch rows of one call. Each hardware rule runs once per process and device: GPU rules read torch.cuda.mem_get_info and the CPU rule reads the L3 size from sysconf. When reading the hardware fails, the fallback applies.

Setting Type Fallback Derived default What it controls
workers int (0 or more) 8 min(value, CPUs in the process affinity, batch rows) Most worker processes of a CPU simulator batch, of a PushT, OGBCube or OGBScene reset, or of a PushT render, on Linux. The value 0 steps and resets every batch row, and draws every PushT frame, in the main process, except that a PyFlytRocketLanding batch of more than 1022 environments always uses processes.
large_backend_min_envs int none shipped per class Smallest batch that steps on the large-batch simulation backend with simulation_backend="auto", for the classes that select their backend with it (see Physics backends). Without a set value, stable-envs tune measures it per simulation path and batch range; untuned, each class uses the value it ships.
large_renderer_min_rows int none shipped per class Smallest render batch that draws with the CUDA renderer, for the classes that have a CPU and a CUDA renderer (see Renderers). Smaller batches draw on the CPU and move to the device in one copy. Without a set value, stable-envs tune measures it per render path and batch range; untuned, each class uses the value it ships.
worker_min_envs int 64 none Smallest batch that uses worker processes, or Fetch simulator threads. For PushT, the smallest number of rendered states that uses render workers.
worker_timeout int 120 none Seconds that a CPU simulator worker can take to answer one request before the batch fails. A worker can take up to the larger of this value and 300 seconds to start. Set a larger value for environments whose reset or step takes minutes in one worker, for example with snv.tuning.set(worker_timeout=600).
fetch_threads int 4 min(value, CPUs in the process affinity, batch rows) Most simulator threads of an in-process Fetch batch with simulation_backend="source".
dmc_threads int 8 min(value, CPUs in the process affinity, batch rows) Most mujoco.batch threads of a DM Control batch, for CPU and CUDA output. A batch uses at most one thread per two batch rows, and about one thread for each 0.1 ms of MuJoCo work in a step call. With MuJoCo Warp, it only sizes the reset threads of CheetahRun and QuadrupedWalk, and MJX doesn't read it.
cpu3d_chunk int 16 none (body-tracking classes use a per-class table) Frames per chunk of the Torch CPU ray caster (cpu3d, backend="torch"). The Numba kernel draws all frames in one call. The fallback was measured on a Xeon Platinum 8268.
dmc_cpu_ray_budget int, power of two 2^21 2^21 × L3 size / 35.75 MiB, rounded to a power of two, in [2^18, 2^21] Rays per CPU render chunk of the fixed-camera DM Control classes, counting supersamples.
dmc_ray_budget int, power of two 2^24 min(2^24, free GPU memory / 512), rounded down to a power of two Rays per CUDA render chunk of the fixed-camera DM Control classes.
dmc_graph_rows int 48 none Most rows of a CUDA render chunk of the fixed-camera DM Control classes that replay one captured CUDA graph. The graph draws every ray and launches once. A larger chunk launches each kernel and draws only the rays that the movers can reach. The frames are the same.
dmc_launch_rays int 256 × 224 × 224 none Rays per MJWarp launch of the DM Control body-tracking classes and of the DM Control backend="mjwarp" renderer. This value sets the worlds per launch: at most 256, unless dmc_min_worlds is larger. The worlds render option overrides it.
dmc_min_worlds int, power of two 64 none Fewest worlds per MJWarp launch of the DM Control body-tracking classes and of the DM Control backend="mjwarp" renderer.
fetch_mjw_worlds int, power of two 256 none Most worlds per MJWarp launch of the Fetch classes.
ogb_mjw_worlds int, power of two 256 none Most worlds per MJWarp launch of OGBCube and OGBScene.
ogb_gl_workers int (0 or more) 8 min(value, CPUs in the process affinity), and on CUDA also rows ÷ 8 Most OpenGL worker processes of an OGBCube or OGBScene batch on Linux. A batch that would use fewer than 2 workers draws in the main process, and so does a CPU batch with fewer states than workers. The value 0 draws every batch there.
render_workers int (0 or more) 8 min(value, CPUs in the process affinity) Most worker processes of a CPU render batch on Linux, for classic control without Numba, for Fetch with backend="opengl" (software OpenGL), for Miniworld, for Roadster, for the info.goal images of SimplePointMaze and for PyFlytRocketLanding with backend="pybullet" (TinyRenderer). Each Fetch worker has its own OpenGL context. The values 0 and 1 draw every frame in the main process.
render_worker_min_rows int 16 none Smallest CPU render batch that uses render worker processes, in every family that has them. PyFlytRocketLanding uses 2 when the setting is unset.
ogb_context_cache_bytes bytes none min(total GPU memory / 4, free GPU memory / 2), per device GPU bytes the OGBench MJWarp context cache keeps.
nvd_budget_bytes bytes 6 GiB min(6 GiB, free GPU memory / 2) GPU bytes one nvdiffrast chunk of PyFlytRocketLanding may use.
nav_render_chunk int 256 none Frames per render chunk of the navigation classes.
navdot_block int, power of two 1024 none Pixels per Triton tile of the navigation dot compositor (power of two).
navdot_warps 1, 2, 4, 8, 16 or 32 4 none Triton warps per tile of the navigation dot compositor.
raster2d_block int, power of two 128 none Pixels per Triton program of the 2D rasterizer without culling (power of two).
raster2d_cull_warps 1, 2, 4, 8, 16 or 32 4 none Triton warps per tile of the 2D rasterizer with culling.
gfxdraw_warps 1, 2, 4, 8, 16 or 32 1 none Triton warps per tile of the classic control rasterizer.
raycast_block int, power of two 256 none Rays per Triton program of the analytic ray caster (power of two).

snv.tuning.SETTINGS maps each setting name to its Setting, and snv.tuning.RENDER_PATHS maps an environment class or family name to the render and simulation paths whose measured values it shares:

setting = snv.tuning.SETTINGS["nav_render_chunk"]
print(setting.env_var, setting.fallback, setting.paths)  # STABLE_ENVS_NAV_RENDER_CHUNK 256 ('navigation',)
print(snv.tuning.RENDER_PATHS["navigation"])    # ('navigation', 'raster2d')

Read and set settings

get

get(name: str, *, path: str | None = None, size: int | None = None, batch: int | None = None, device: Any = None, default: Any = _MISSING) -> int | None

Return the current value of setting name; lookup also returns where it came from.

Parameters:

  • name (str) –

    A key of SETTINGS.

  • path (str | None, default: None ) –

    Render path of the call; with size and batch it selects measured values.

  • size (int | None, default: None ) –

    Frame size in pixels (0 for simulation paths).

  • batch (int | None, default: None ) –

    Number of environments in the call.

  • device (Any, default: None ) –

    Device the work runs on (the setting's own device if None).

  • default (Any, default: _MISSING ) –

    The call site's value, used instead of the setting's fallback.

lookup

lookup(name, *, path=None, size=None, batch=None, device=None, default=_MISSING, measured=True)

Return (value, source) for setting name; the arguments are those of get.

source is "override", "set", "env", "cache", "derived", "default" or "fallback".

Parameters:

  • name –

    A key of SETTINGS.

  • path –

    Render path of the call.

  • size –

    Frame size in pixels.

  • batch –

    Number of environments in the call.

  • device –

    Device the work runs on.

  • default –

    The call site's value.

  • measured –

    Read the tuning cache; False skips it.

Raises:

  • ValueError –

    If name is not a setting or its environment variable is invalid.

set

set(**settings: int | None) -> dict[str, int]

Set settings for the process and return every setting set this way; None clears a setting.

Values set here sit below override blocks and above everything else.

Parameters:

  • **settings (int | None, default: {} ) –

    {setting name: value or None}.

override

override(**settings: int) -> Iterator[None]

Set settings inside a with block, above set.

Blocks nest and the innermost wins. Other threads don't see the values, and None values are ignored.

Parameters:

  • **settings (int, default: {} ) –

    {setting name: value}.

reset

reset() -> None

Clear every setting set with set.

describe

describe(**where) -> dict[str, tuple[int | None, str]]

Return {name: (value, source)} for every setting.

Parameters:

  • **where –

    path, size, batch and device, as for get.

cache_path

cache_path(device='cpu') -> Path | None

Return the tuning cache file of device, or None for a CUDA device without CUDA.

The file is $XDG_CACHE_HOME/stable-envs/tuning/<device name>.json (~/.cache if unset).

Parameters:

  • device –

    "cpu", "cuda" or "cuda:<index>".

Time simulation backends and renderers

stable-envs tune times the simulation backends and the renderers of the environment it tunes. benchmarks/backend_switch.py uses these functions to time them over a range of batch sizes.

simulation_paths

simulation_paths(device='cuda')

Return (path, backends, measure) of the simulation paths selected for in this process on device.

Environments built in this process register them; backends has the small and large backend names.

Parameters:

  • device –

    "cpu" or "cuda".

render_paths

render_paths(device='cuda')

Return (path, renderers, measure) of the render paths that drew in this process on device.

Classes with a CPU and a GPU renderer register them when they draw; renderers has the small (CPU) and large renderer names, and time_backend times either one.

Parameters:

  • device –

    "cpu" or "cuda".

time_backend

time_backend(measure, backend: str, num_envs: int, device='cuda') -> float

Seconds per step call of backend with num_envs environments, as stable-envs tune times it.

Parameters:

  • measure –

    The measure of a simulation_paths entry.

  • backend (str) –

    A backend name of that entry.

  • num_envs (int) –

    Number of environments.

  • device –

    Device of the outputs.

Setting definitions

Setting dataclass

Setting(name: str, fallback: int | None, paths: tuple[str, ...], device: str, kind: str, unit: str | None, doc: str, derive: Callable[[str], int | None] | None = None, step: bool = False, per_path: bool = True)

One setting: its fallback, the render paths that read it, and how tune sweeps it.

Attributes:

  • name (str) –

    Setting name, a key of SETTINGS.

  • fallback (int | None) –

    Value used when nothing else sets the setting (the call site decides if None).

  • paths (tuple[str, ...]) –

    Render or simulation paths that read the setting.

  • device (str) –

    Device whose work the setting controls: "cpu", "cuda" or "any".

  • kind (str) –

    Accepted values: "n" (at least 1), "n0" (at least 0), "pow2" or "warps".

  • unit (str | None) –

    Work-split unit tune uses to skip equivalent values (not swept if None).

  • doc (str) –

    One-line description.

  • derive (Callable[[str], int | None] | None) –

    device -> value hardware rule.

  • step (bool) –

    Read at construction and timed by stepping.

  • per_path (bool) –

    Store measured values per render path instead of per device.

Methods:

  • check –

    Return value unchanged if it is None or valid for this setting's kind.

env_var property

env_var: str

The environment variable that sets this setting.

check

check(value: Any) -> int | None

Return value unchanged if it is None or valid for this setting's kind.

Parameters:

  • value (Any) –

    The value to check.

Raises:

  • ValueError –

    If value is a bool, not an int, or outside the values kind allows.