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 areference_idsuch as"CartPole-v1". -
**kwargs–Forwarded to the constructor, such as
num_envs,size,deviceandseed.
Raises:
-
KeyError–If
nameis not registered.import_errorsshows 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:
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_dynamicsandrequires_cuda.
Raises:
-
KeyError–If
nameis 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
statehas no fieldname.
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
statehas no fieldname. -
TypeError–If
valuedoesn't cast to the field's dtype without loss. -
ValueError–If
valuedoesn'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
statefit 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"), anddefault_device, used when a constructor getsdevice=None.
Raises:
-
KeyError–If any other key is passed.
-
ValueError–If
verboseis 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)assample_statesreturns them (NumPy or Torch). -
batch_size(int) –Frames per yielded batch. The last batch is shorter when
Nis 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.rendercall. None (the default) picks it from device memory. -
**render_kwargs–Passed to every
env.rendercall, for examplesizeorvariation. Avariationof(N, d)rows, one per stored state, is sliced with the states (andindices). A Mapping or one shared row applies to every batch.
Yields:
-
–
(batch_size, H, W, 3)uint8 frames onenv.device.
Raises:
-
TypeError–If
statesis neither a State nor an array of rows, oroutis passed. -
ValueError–If
batch_sizeorchunk_sizeis not positive,indicesis not 1-D, avariationhas more than one row but not one per stored state, or compact rows draw under a per-environment variation with abatch_sizeother thannum_envs.
Attributes:
-
chunk_size(int) –Rows that one
env.rendercall 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,
sizeandnum_envsdefine the workload. -
settings–Settings to sweep (all that
envreads 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:
Raises:
-
ValueError–If
settingsnames an unknown setting.