Class PassiveChecker
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
spaceSpaceThe space.
Remarks
Reference: gymnasium/utils/passive_env_checker.py.
Exceptions
- TypeError
Thrown when
spaceis 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
actionSpaceBoxThe box.
Remarks
Reference: gymnasium/utils/passive_env_checker.py.
Exceptions
- AssertionError
Thrown when
loworhighhas another shape than the space, with Gymnasium's messages (here thelowone 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
observationSpaceBoxThe 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
loworhighhas another shape than the space, with Gymnasium's messages (thehighone 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
obsobjectThe observation.
observationSpaceSpaceThe space it should belong to.
methodNamestringresetorstep, 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 fromlen(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
spaceSpaceThe space.
Remarks
Reference: gymnasium/utils/passive_env_checker.py.
Exceptions
- TypeError
Thrown when
spaceis 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
spaceSpaceThe space; null is refused as Python refuses a non-space.
spaceTypestringobservationoraction, for the messages.checkBoxSpaceAction<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
spaceis 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
data1RetainedDataThe earlier data, retained; null shares nothing.
data2objectThe later data.
Returns
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
Returns
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_memoryraises.
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
previousObsRetainedDataThe earlier observation, retained.
previousInfoRetainedDataThe earlier info, retained.
data(object Obs, object Info)The later call's
(obs, info).previousSourcestringThe earlier call,
resetorstep.sourcestringThe 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 ofNonedoes.data(object Obs, object Info)The later call's
(obs, info).previousSourcestringThe earlier call,
resetorstep.sourcestringThe later call.
Remarks
Reference: gymnasium/utils/passive_env_checker.py.
Exceptions
- TypeError
Thrown when
previousDatais 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
envIEnvThe 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_fpsthat is not positive, a render mode set althoughrender_modesis empty, or a render moderender_modesdoes not list.- TypeError
Thrown when
render_modeshas no length (object of type 'int' has no len()), Python's error fromlen(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
envIEnvThe env.
seedBigInteger?The seed, passed on.
optionsIReadOnlyDictionary<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
envEnv<TObs, TAct>The env.
seedBigInteger?The seed, passed on.
optionsIReadOnlyDictionary<string, object>The options, passed on.
Returns
- ResetResult<TObs>
The reset's result.
Type Parameters
TObsThe observation type.
TActThe 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
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
envEnv<TObs, TAct>The env.
actionTActThe action, passed on.
Returns
- StepResult<TObs>
The step's result.
Type Parameters
TObsThe observation type.
TActThe 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.inforeturned bystep()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
dataobjectThe observation or info.
Returns
- RetainedData
The retained data; dispose it to release the views (and with them the memory they keep).