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
sizeandbatchit 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
nameis 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}.
describe
¶
describe(**where) -> dict[str, tuple[int | None, str]]
Return {name: (value, source)} for every setting.
Parameters:
-
**where–path,size,batchanddevice, as forget.
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".
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
tuneuses to skip equivalent values (not swept if None). -
doc(str) –One-line description.
-
derive(Callable[[str], int | None] | None) –device -> valuehardware 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
valueunchanged if it is None or valid for this setting'skind.
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
valueis a bool, not an int, or outside the valueskindallows.