Table of Contents

Class PassiveChecker

Namespace
Gym.Utils
Assembly
Gym.dll

Gymnasium's gymnasium.utils.passive_env_checker: checks of an env's spaces, observations, rewards and renders that warn (or assert, for what cannot work) without changing what the env returns. PassiveEnvChecker, which make adds unless disable_env_checker, runs them on the first reset, step and render, so a broken env is reported where it breaks rather than deep inside a training loop.

public static class PassiveChecker
Inheritance
PassiveChecker
Inherited Members

Remarks

Checks that Python needs because it is dynamically typed cannot fire here, and are left out: a step result always has five items with boolean signals, a reward is always a double, and reset always takes seed and options. What remains is what an env can still get wrong in C#: observations outside the space or of another type, a NaN or infinite reward, a null info, metadata that does not describe the render modes, render results of the wrong form, and data reused between calls.

An ObjectSpace, the view through which an Env<object?, object?> holds any space, is checked as the space it views, as Python sees only that space.

Reference: gymnasium/utils/passive_env_checker.py.

Methods

CheckActionSpace(Space?)

Checks an action space (Gymnasium's check_action_space): CheckSpace(Space?, string, Action<Box>) with the action box check.

public static void CheckActionSpace(Space? space)

Parameters

space Space

The space.

Remarks

Exceptions

TypeError

Thrown when space is null.

AssertionError

Thrown for a space that cannot work, with Gymnasium's message.

CheckBoxActionSpace(Box)

Checks a Box action space (Gymnasium's _check_box_action_space): asserts the bound shapes, then warns when a bound pair is equal, which leaves the agent no choice in that dimension.

public static void CheckBoxActionSpace(Box actionSpace)

Parameters

actionSpace Box

The box.

Remarks

Exceptions

AssertionError

Thrown when low or high has another shape than the space, with Gymnasium's messages (here the low one says "have have").

CheckBoxObservationSpace(Box)

Checks a Box observation space (Gymnasium's _check_box_observation_space): asserts that the bounds have the space's shape, then warns when a bound pair is equal or inverted, either of which makes a dimension constant or empty.

public static void CheckBoxObservationSpace(Box observationSpace)

Parameters

observationSpace Box

The box.

Remarks

The bound shapes always match for a box built by its constructor; the assertion guards against bounds replaced afterwards. Reference: gymnasium/utils/passive_env_checker.py.

Exceptions

AssertionError

Thrown when low or high has another shape than the space, with Gymnasium's messages (the high one says "have have", as Gymnasium's does).

CheckObs(object?, Space, string)

Checks that an observation matches its space (Gymnasium's check_obs): warns when it is of another type or dtype than the space's elements, recurses into tuples and dicts, and warns when it is not a member (or when the membership test throws). It never changes the observation.

public static void CheckObs(object? obs, Space observationSpace, string methodName)

Parameters

obs object

The observation.

observationSpace Space

The space it should belong to.

methodName string

reset or step, for the messages (The obs returned by the reset() method ...).

Remarks

An int here is any .NET integer or enum, as Python's int; np.int64 is a 0-d int64 array. An ObjectSpace is checked as the space it views. Reference: gymnasium/utils/passive_env_checker.py.

Exceptions

AssertionError

Thrown for a tuple observation of another length than the space, or a dict observation that is not a dict or has other keys, with Gymnasium's messages.

TypeError

Thrown when a Tuple space's observation has no length (object of type 'int' has no len()), Python's error from len(obs).

CheckObservationSpace(Space?)

Checks an observation space (Gymnasium's check_observation_space): CheckSpace(Space?, string, Action<Box>) with the observation box check.

public static void CheckObservationSpace(Space? space)

Parameters

space Space

The space.

Remarks

Exceptions

TypeError

Thrown when space is null.

AssertionError

Thrown for a space that cannot work, with Gymnasium's message.

CheckSpace(Space?, string, Action<Box>)

Checks a space of either kind (Gymnasium's check_space): what makes it unusable is asserted (a non-positive count, a shape that disagrees with nvec, an empty composite), boxes go to checkBoxSpace, and tuples and dicts are checked subspace by subspace. Other spaces pass.

public static void CheckSpace(Space? space, string spaceType, Action<Box> checkBoxSpace)

Parameters

space Space

The space; null is refused as Python refuses a non-space.

spaceType string

observation or action, for the messages.

checkBoxSpace Action<Box>

The box check of that kind: CheckBoxObservationSpace(Box) or CheckBoxActionSpace(Box).

Remarks

Gym.NET's spaces validate themselves on construction and cannot be reshaped afterwards, so the assertions only fire for a space whose state was changed by reflection or a subclass. Reference: gymnasium/utils/passive_env_checker.py.

Exceptions

TypeError

Thrown when space is null: {spaceType} space does not inherit from gymnasium.spaces.Space, actual type: <class 'NoneType'>.

AssertionError

Thrown for a space that cannot work, with Gymnasium's message.

DataSharesObjects(RetainedData?, object?)

DataSharesObjects(object?, object?) against data kept by Retain(object?), whose arrays are still alive however the caller treated the originals.

public static bool DataSharesObjects(RetainedData? data1, object? data2)

Parameters

data1 RetainedData

The earlier data, retained; null shares nothing.

data2 object

The later data.

Returns

bool

true when they share a mutable object.

Exceptions

TooHardError

Thrown when NumPy's exact overlap problem for two arrays exceeds its solver.

DataSharesObjects(object?, object?)

Whether two calls' data share a mutable object (Gymnasium's data_shares_objects): the same dict, or arrays over common memory, in matching positions of matching structures. Where DataEquivalence(object?, object?, bool) compares values, this compares identity. Immutable values (numbers, strings, NumPy scalars) and unknown ones (lists included, as in Gymnasium) never count.

public static bool DataSharesObjects(object? data1, object? data2)

Parameters

data1 object

The earlier data.

data2 object

The later data, of the same structure.

Returns

bool

true when they share a mutable object.

Remarks

Both values must be alive: comparing with arrays the caller has since disposed is meaningless, as their memory may already belong to another array. To compare with data across calls, keep it with Retain(object?) and use DataSharesObjects(RetainedData?, object?). Reference: gymnasium/utils/passive_env_checker.py.

Exceptions

TooHardError

Thrown when NumPy's exact overlap problem for two arrays exceeds its solver, as np.shares_memory raises.

EnvDataReusePassiveChecker(RetainedData, RetainedData, (object? Obs, object? Info), string, string)

EnvDataReusePassiveChecker((object? Obs, object? Info)?, (object? Obs, object? Info), string, string) against data kept by Retain(object?) since the earlier call, as PassiveEnvChecker keeps it.

public static void EnvDataReusePassiveChecker(RetainedData previousObs, RetainedData previousInfo, (object? Obs, object? Info) data, string previousSource, string source)

Parameters

previousObs RetainedData

The earlier observation, retained.

previousInfo RetainedData

The earlier info, retained.

data (object Obs, object Info)

The later call's (obs, info).

previousSource string

The earlier call, reset or step.

source string

The later call.

Exceptions

TooHardError

Thrown when NumPy's exact overlap problem for two arrays exceeds its solver.

EnvDataReusePassiveChecker((object? Obs, object? Info)?, (object? Obs, object? Info), string, string)

Warns when two calls returned observations or infos that share an object (Gymnasium's env_data_reuse_passive_checker): users keep the data of every step (replay and rollout buffers), and an env that edits and returns the same buffer corrupts what they hold.

public static void EnvDataReusePassiveChecker((object? Obs, object? Info)? previousData, (object? Obs, object? Info) data, string previousSource, string source)

Parameters

previousData (object Obs, object Info)?

The earlier call's (obs, info); null fails as Python's unpacking of None does.

data (object Obs, object Info)

The later call's (obs, info).

previousSource string

The earlier call, reset or step.

source string

The later call.

Remarks

Exceptions

TypeError

Thrown when previousData is null: cannot unpack non-iterable NoneType object.

TooHardError

Thrown when NumPy's exact overlap problem for two arrays exceeds its solver.

EnvRenderPassiveChecker(IEnv)

Checks the env's render metadata, then renders and checks the result's form against the render mode (Gymnasium's env_render_passive_checker): missing or malformed render_modes and render_fps warn, a render mode the metadata does not list asserts. The result is returned unchanged.

public static RenderResult EnvRenderPassiveChecker(IEnv env)

Parameters

env IEnv

The env.

Returns

RenderResult

The render's result, which the caller owns as from render().

Remarks

Metadata values are read as their Python counterparts: a typed array or List<T> is a list, an object[] a tuple, a string a string (whose in is a substring test, as in Python). Reference: gymnasium/utils/passive_env_checker.py.

Exceptions

AssertionError

Thrown, with Gymnasium's messages, for a render_fps that is not positive, a render mode set although render_modes is empty, or a render mode render_modes does not list.

TypeError

Thrown when render_modes has no length (object of type 'int' has no len()), Python's error from len(render_modes).

EnvResetPassiveChecker(IEnv, BigInteger?, IReadOnlyDictionary<string, object?>?)

EnvResetPassiveChecker<TObs, TAct>(Env<TObs, TAct>, BigInteger?, IReadOnlyDictionary<string, object?>?) through the untyped view, for code that holds envs of any type (check_env).

public static ResetResult<object?> EnvResetPassiveChecker(IEnv env, BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)

Parameters

env IEnv

The env.

seed BigInteger?

The seed, passed on.

options IReadOnlyDictionary<string, object>

The options, passed on.

Returns

ResetResult<object>

The reset's result.

Exceptions

AssertionError

Thrown for a malformed composite observation, or a null info.

TypeError

Thrown by CheckObs(object?, Space, string) for a tuple-space observation without a length.

EnvResetPassiveChecker<TObs, TAct>(Env<TObs, TAct>, BigInteger?, IReadOnlyDictionary<string, object?>?)

Resets the env and checks what it returned (Gymnasium's env_reset_passive_checker): the observation against the observation space, and that an info came back. The result is returned unchanged.

public static ResetResult<TObs> EnvResetPassiveChecker<TObs, TAct>(Env<TObs, TAct> env, BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)

Parameters

env Env<TObs, TAct>

The env.

seed BigInteger?

The seed, passed on.

options IReadOnlyDictionary<string, object>

The options, passed on.

Returns

ResetResult<TObs>

The reset's result.

Type Parameters

TObs

The observation type.

TAct

The action type.

Remarks

Gymnasium's checks of the reset signature (a seed and options parameter, a None default) and of the result's tuple form cannot fail in C#. Whatever the env's reset throws propagates. Reference: gymnasium/utils/passive_env_checker.py.

Exceptions

AssertionError

Thrown for a malformed composite observation (CheckObs(object?, Space, string)), or a null info: The second element returned by env.reset() was not a dictionary, actual type: <class 'NoneType'>.

TypeError

Thrown by CheckObs(object?, Space, string) for a tuple-space observation without a length.

EnvStepPassiveChecker(IEnv, object?)

EnvStepPassiveChecker<TObs, TAct>(Env<TObs, TAct>, TAct) through the untyped view: the env converts the action to its own type first.

public static StepResult<object?> EnvStepPassiveChecker(IEnv env, object? action)

Parameters

env IEnv

The env.

action object

The action, of any type the env converts.

Returns

StepResult<object>

The step's result.

Exceptions

AssertionError

Thrown for a malformed composite observation, or a null info.

TypeError

Thrown by CheckObs(object?, Space, string) for a tuple-space observation without a length.

EnvStepPassiveChecker<TObs, TAct>(Env<TObs, TAct>, TAct)

Steps the env and checks what it returned (Gymnasium's env_step_passive_checker): the observation, a NaN or infinite reward, and that an info came back. The action is not checked: some envs accept out-of-bounds actions on purpose. The result is returned unchanged.

public static StepResult<TObs> EnvStepPassiveChecker<TObs, TAct>(Env<TObs, TAct> env, TAct action)

Parameters

env Env<TObs, TAct>

The env.

action TAct

The action, passed on.

Returns

StepResult<TObs>

The step's result.

Type Parameters

TObs

The observation type.

TAct

The action type.

Remarks

Gymnasium's checks of the result's length (the 4-tuple of the old API) and of the signal and reward types cannot fail in C#. Whatever the env's step throws propagates. Reference: gymnasium/utils/passive_env_checker.py.

Exceptions

AssertionError

Thrown for a malformed composite observation (CheckObs(object?, Space, string)), or a null info: The info returned by step() must be a python dictionary, actual type: <class 'NoneType'>.

TypeError

Thrown by CheckObs(object?, Space, string) for a tuple-space observation without a length.

Retain(object?)

Keeps what DataSharesObjects(RetainedData?, object?) needs of data the caller now owns: containers by reference (for identity), every array as a view. The view keeps the array's memory alive even after the caller disposes the array, so that memory cannot be handed to the next call's fresh array and mistaken for sharing.

public static RetainedData Retain(object? data)

Parameters

data object

The observation or info.

Returns

RetainedData

The retained data; dispose it to release the views (and with them the memory they keep).