stable_envs

import stable_envs as snv exposes every registered class, such as snv.CartPole, and the functions below. Environment methods are on Env.

import stable_envs as snv

print(snv.__version__)                    # 0.1.0
env = snv.make("CartPole", num_envs=4, device="cpu")
print(type(env).__name__, env.num_envs)   # CartPole 4
env.close()
print(snv.info("CartPole")["reference_id"])  # CartPole-v1
print(snv.get_config())  # {'verbose': 'WARNING', 'default_device': 'auto'}
Name What it does
snv.make(name, **kwargs) Build a registered environment by class name.
snv.list_envs(family=, domain=) List registered class names.
snv.list_families() List the family IDs that registered a class.
snv.info(name) Read class metadata without building anything.
snv.import_errors() Say why a family didn't register.
snv.get_field(state, name), snv.set_field(state, name, value), snv.schema_of(state) Read or write one named field of a State, also of a folded State, and find the schema of a folded State.
snv.set(...), snv.get_config() Change and read the log level and the default device.
snv.FrameLoader(env, states, batch_size) Give the frames of stored states a batch at a time, drawn ahead in large render calls.
snv.tune(env) Measure the fastest tuning setting values for an environment's render path.
snv.__version__ The installed version. Put it in bug reports next to stable-envs doctor --json.
snv.Env, snv.State, snv.StepResult, snv.VariationLike The environment base class and its types; see Env.
snv.Spec, snv.CompositeSpec Shape and dtype descriptions; see Specs and spaces.
snv.tuning The tuning settings; see Tuning.

Build an environment

snv.make("CartPole", num_envs=4) and snv.CartPole(num_envs=4) build the same thing. Use make when the class name comes from a config file or a command line. The name is the Python class name: "CartPole" works, and the upstream library's id "CartPole-v1" is an unknown name. An unknown name raises KeyError with the list of registered names. An unregistered attribute, such as snv.DMCReacher without the dmcontrol extra, raises AttributeError that points you to snv.import_errors().

make

make(name: str, **kwargs) -> Env

Construct a registered environment by class name.

make("CartPole", num_envs=64) is the same as stable_envs.CartPole(num_envs=64).

Parameters:

  • name (str) –

    Class name from list_envs, not a reference_id such as "CartPole-v1".

  • **kwargs –

    Forwarded to the constructor, such as num_envs, size, device and seed.

Raises:

  • KeyError –

    If name is not registered. import_errors shows families that didn't import.

Find environments

A family registers only if its module imports. The extras you install decide which classes appear, starting from what the core install lists. snv.info(name) reads metadata from the class, and it works for registered classes that need a GPU or an extra you haven't installed. It returns class_name, id, class, module, family, domain, render_state_dim, render_state_names, default_size, native_size, reference_id, action_dim, has_dynamics and requires_cuda. Values that depend on an instance, such as the width of a Fetch render row, are None. For shapes and dtypes, build the environment and read its specs.

list_envs

list_envs(family: str | None = None, domain: str | None = None) -> list[str]

Return sorted registered class names, optionally filtered by family or domain.

A family whose module failed to import registers no classes; see import_errors.

Parameters:

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

    Keep only this family, such as "ogbench".

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

    Keep only this domain, such as "pointmaze".

list_families

list_families() -> list[str]

Return sorted family IDs with at least one registered class.

info

info(name: str) -> dict[str, Any]

Return class metadata for name without constructing an environment.

Dimensions that depend on the instance are None.

Parameters:

  • name (str) –

    Registered class name, such as "CartPole".

Returns:

  • dict[str, Any] –

    A dict with keys such as class_name, family, domain, reference_id,

  • dict[str, Any] –

    default_size, action_dim, has_dynamics and requires_cuda.

Raises:

  • KeyError –

    If name is not registered.

import_errors

import_errors() -> dict[str, str]

Return {module name: "<ExceptionType>: <message>"} for env modules that didn't import.

Read a State field

Some families fold their State: the fixed-shape fields go into a few (N, size) arrays, one for each group of fields with the same dtype, and the State has one leaf for each group. A folded State costs less to export, copy and slice than a State with one leaf for each field. snv.get_field(state, name) returns one field as a view, on a folded State and on a State with one leaf for each field. The name joins the key parts with / or ., for example "current/body/agent/position". A write to the view changes the State. snv.schema_of(state) returns the schema of a folded State, which lists the fields (names) and where each one is (slices).

get_field

get_field(state: TensorDictBase, name: str) -> Tensor

The field name of any State, shaped (*batch, *shape).

On a folded State the result is a view of its group, so writes to it change the State. On a State with one leaf per field it is that leaf.

Parameters:

  • state (TensorDictBase) –

    A State, with any batch shape.

  • name (str) –

    Field name, with parts joined by / or ., such as "current.body.agent.position".

Raises:

  • KeyError –

    If state has no field name.

set_field

set_field(state: TensorDictBase, name: str, value) -> None

Write value into the field name of any State, broadcast to the field's shape.

On a folded State, a kept field can take a new non-batch shape, as StateSchema.set says. On a State with one leaf per field, a value of a new non-batch shape replaces the leaf.

Parameters:

  • state (TensorDictBase) –

    A State, with any batch shape.

  • name (str) –

    Field name, as for get_field.

  • value –

    Tensor, array or number. Its dtype must cast to the field's dtype without loss.

Raises:

  • KeyError –

    If state has no field name.

  • TypeError –

    If value doesn't cast to the field's dtype without loss.

  • ValueError –

    If value doesn't broadcast to the field's shape, or a kept field's new value changes the batch sizes.

schema_of

schema_of(state: TensorDictBase) -> StateSchema | None

The schema of a folded state, found from its group leaves; None for a State with one leaf per field.

The lookup needs no metadata in the State: each declared group is registered by (path, size, dtype).

Raises:

  • ValueError –

    If the groups of state fit declared schemas that disagree on the layout of those groups.

Global settings

snv.set changes two process-wide settings: verbose, the lowest level the library logs, and default_device, the device a constructor uses when you omit device on a class whose default is the global setting. Env lists which classes those are. Constructors read default_device when they run. Environments you already built stay on their device when you change it. The starting log level comes from STABLE_ENVS_VERBOSE.

set

set(**kwargs: Any) -> dict[str, Any]

Update the log level or default device and return a copy of the settings.

Parameters:

  • **kwargs (Any, default: {} ) –

    verbose, the lowest level logged ("TRACE", "DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL" or "SILENT"), and default_device, used when a constructor gets device=None.

Raises:

  • KeyError –

    If any other key is passed.

  • ValueError –

    If verbose is not a known level.

get_config

get_config() -> dict[str, Any]

Return a copy of the global settings, verbose and default_device.

Draw stored states in batches

snv.FrameLoader draws stored states ahead of the caller in large env.render calls and yields batch_size frames at a time, in order. The number of states per call comes from memory only: two calls' frames and a working buffer per state fit in a quarter of the free device memory, and one call's frames stay under 1 GiB. A call draws at most the environment's render_ahead_rows states (1024 by default) and never fewer than batch_size. Building or iterating a loader times nothing. A variation= with one row per stored state is sliced with the states, so it still draws in large calls. Compact rows that use a per-environment variation draw one batch of num_envs rows per call, and a short last batch uses the variation of the first environments. Performance tuning records how render_ahead_rows was measured. Store states, render later shows an example.

FrameLoader

FrameLoader(env: Env, states: State | Tensor | ndarray, batch_size: int, *, indices=None, chunk_size: int | None = None, **render_kwargs)

Iterate over the frames of stored states, batch_size frames at a time, in order.

The loader draws a chunk of many batches with one env.render call and yields its slices, so a small batch costs the same per frame as a large one. It picks the chunk size from the free memory of env.device. Each batch has the bytes of env.render of its states, except where a renderer's bytes depend on the batch size: OGBCube and OGBScene on CUDA draw 16 or more states in OpenGL worker processes, whose frames can differ from one process by 1 level in a few pixels.

Parameters:

  • env (Env) –

    The environment that draws. Its live state doesn't change.

  • states (State | Tensor | ndarray) –

    A full State with batch (N,), or compact rows (N, state_dim) as sample_states returns them (NumPy or Torch).

  • batch_size (int) –

    Frames per yielded batch. The last batch is shorter when N is not a multiple.

  • indices –

    Optional order of the rows to draw, for example a permutation drawn ahead. A sequence or 1-D array of row indices; rows may repeat. None draws every row once in order.

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

    Rows per env.render call. None (the default) picks it from device memory.

  • **render_kwargs –

    Passed to every env.render call, for example size or variation. A variation of (N, d) rows, one per stored state, is sliced with the states (and indices). A Mapping or one shared row applies to every batch.

Yields:

  • –

    (batch_size, H, W, 3) uint8 frames on env.device.

Raises:

  • TypeError –

    If states is neither a State nor an array of rows, or out is passed.

  • ValueError –

    If batch_size or chunk_size is not positive, indices is not 1-D, a variation has more than one row but not one per stored state, or compact rows draw under a per-environment variation with a batch_size other than num_envs.

Attributes:

chunk_size property

chunk_size: int

Rows that one env.render call draws.

Tune a render path

snv.tune(env) is the Python form of stable-envs tune. Pass write=False to leave the cache untouched.

tune

tune(env: Env, *, settings=(), repeats: int = 5, write: bool = True, verbose: bool = True) -> dict[str, int]

Time the tuning settings env reads and cache the fastest values.

Parameters:

  • env (Env) –

    Environment whose device, size and num_envs define the workload.

  • settings –

    Settings to sweep (all that env reads if empty).

  • repeats (int, default: 5 ) –

    Timed calls per value.

  • write (bool, default: True ) –

    Save the results to the tuning cache.

  • verbose (bool, default: True ) –

    Print the result table.

Returns:

  • dict[str, int] –

    A dict mapping each swept setting to its chosen value.

Raises:

  • ValueError –

    If settings names an unknown setting.