Table of Contents

Namespace Gym.Utils

Classes

Cv2

OpenCV's cv2.resize for uint8 and float32 images, bit for bit: InterArea, the interpolation Gymnasium's ResizeObservation uses, and InterLinear, the default the vector HumanRendering uses. Use it wherever Gymnasium calls cv2.resize; Gym.NET carries no native OpenCV.

Deque<T>

Python's collections.deque as the wrappers use it: a sequence that keeps the last MaxLen items, dropping the oldest as new ones are appended (RecordEpisodeStatistics's return_queue). Indexing and repr follow Python: queue[-1] is the newest, and it prints deque([1.0, 2.0], maxlen=100).

EnvChecker

Gymnasium's gymnasium.utils.env_checker: the checks an env must pass to follow the API. Today it holds DataEquivalence(object?, object?, bool), which tests and checkers use to compare observations, actions and infos; the env checks themselves arrive with the registry (P3).

EnvMatch

Gymnasium's gymnasium.utils.env_match: drives two envs with the same seed and actions and asserts they behave the same, for checking a port, a refactor or a wrapper against the original (a legacy env against its new version during a migration, for one).

FfmpegVideoWriter

An IVideoWriter that pipes raw frames to an ffmpeg process and writes an H.264 mp4, as moviepy does for Gymnasium: libx264 at the medium preset, yuv420p when both sides are even.

GymDictAttribute

Makes a partial positional record a Python dict (DR-13): the generator writes implicit conversions to and from Info (what a Dict space samples), keyed by each member's Python name ([PyName], else its snake_case), Python's == and repr.

GymOptionsAttribute

Asks Gym.NET's source generator for an options record (DR-34): on a partial env or wrapper class it writes a <Class>Options record with one property per parameter of the public constructor make binds to (a wrapper's env excepted), its ToKwargs(), and a constructor of the class that takes the record. Gymnasium.Make("CartPole-v1", new CartPoleEnvOptions { RenderMode = "rgb_array" }) is then checked by the compiler where a dictionary of kwargs is not.

GymTupleAttribute

Makes a partial positional record a Python tuple (DR-13): the generator writes implicit conversions to and from object?[] (Gym.NET's tuple, what a Tuple space samples), Python's == member by member, and Python's repr, (1, 2). [GymTuple] public partial record BlackjackObservation(NDArray PlayerSum, NDArray DealerCard, NDArray UsableAce); reads a Blackjack observation by name.

MissingKeysToAction

Raised when Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?) or PlayableGame is given no key mapping and the env has none (Gymnasium's MissingKeysToAction): pass keysToAction, or give the env a get_keys_to_action attribute.

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.

Performance

Runtime benchmarks for finding performance problems (Gymnasium's gymnasium.utils.performance): how many steps, vector steps, constructions or renders an env manages per second over a target duration. Each runs until the clock passes the target, so it runs slightly over it, and reports the count divided by the time measured.

Play

Gymnasium's gymnasium.utils.play: play an env from the keyboard (Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?), play, or RunAsync(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?, CancellationToken) to await a game), and show a frame on a surface (DisplayArr(Surface, NDArray, (int Width, int Height), bool?), display_arr). The window is a PygameContext's display, Default's (the static Display) unless a context is given, made by the viewer factory (DR-20); the keys come from it through the context's event queue, or from events a program posts there.

PlayPlot

Live plots of metrics while playing (Gymnasium's PlayPlot): pass Callback(object?, object?, object?, double, bool, bool, Info) to Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?), and each step adds the points of DataCallback to one scatter plot per name, showing the last HorizonTimesteps steps.

PlayableGame

An env being played from the keyboard, as Gymnasium's PlayableGame: it opens its context's display at the size of the env's frame (times the zoom), knows which keys matter, and tracks which of them are held as ProcessEvent(Event) reads key events. Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?) builds one and drives it; build one directly to run a loop of your own.

PlotFigure

PlayPlot's default figure: matplotlib's default layout (a 640 by 480 white figure, axes at its subplot parameters, blue round markers) drawn with Gym.Rendering and shown in a window from the viewer factory at each Pause(double). No text is drawn (no titles, ticks or labels): the window's title names the plots, top to bottom.

PngVideoWriter

The default IVideoWriter: each video a folder of PNG frames (000000.png, 000001.png, ...) and an fps.txt holding its frame rate. Needs no external program; ffmpeg -framerate {fps} -i %06d.png out.mp4 turns a folder into a video.

PyAttributes

Python's hasattr, getattr and setattr for .NET objects that mirror Python classes: the declared attributes are the public instance properties and fields (named by PyNameAttribute, or the snake_case of the C# name: NpRandomSeed is np_random_seed) plus non-public members marked with PyNameAttribute; objects implementing IDynamicAttributes also hold run-time ones.

PyBuiltins

Python's built-in conversions and representations, as the Gymnasium source relies on them: float(x) for option parsing, int(x) of a float for pixel coordinates, and repr/str/type for the messages of asserts and errors, which callers and tests match verbatim.

PyCopy

Python's copy.deepcopy for the values Gymnasium deep-copies: specs (deepcopy(env.spec) before a wrapper edits it) and recorded constructor arguments (RecordConstructorArgs). The copy shares nothing mutable with the original, so editing one never shows through the other.

PyEnumAttribute

Marks a C# enum that stands for Python values (DR-84): either the members of a Python Enum class (AutoresetMode is Gymnasium's AutoresetMode, printed <AutoresetMode.NEXT_STEP: 'NextStep'>), or plain Python strings that a closed set of values takes (RenderMode, whose members are Gymnasium's render-mode strings). Each member carries its Python value in a PyValueAttribute and, for an Enum class, its Python name in a PyNameAttribute.

PyEnums

Python's view of the C# enums marked PyEnumAttribute (DR-84): a member's Python .name, .value, str and repr, parsing a member from its value as Python's Enum(value) call does, and the members in declaration order.

PyEquality

Python's == between the Python counterparts of .NET values (see PyBuiltins for the mapping), which is how Gymnasium compares info dicts, metadata, spec kwargs and the values inside them: numbers of any width compare by value (1 == 1.0 == True), dicts ignore insertion order, lists and tuples compare element by element and never equal each other. A tuple is an ITuple or an exact object?[] (Gym.NET's generic tuple, DR-13); a typed array or a list is a list.

PyKwargs

Python's keyword arguments for .NET constructors (DR-11): From(object?) turns what a caller passes (a dictionary, an options record, an anonymous object) into a dict of Python names, and Construct(Type, IReadOnlyDictionary<string, object?>) is Python's cls(**kwargs), binding each name to a constructor parameter by its Python name with Python's TypeError texts. make builds envs and wrappers through it.

PyMath

Python's and NumPy's scalar arithmetic where it differs from C#'s (port plan §3.2 and §5.3, workstream F3): floor division and modulo that follow the divisor's sign, min/max whose NaN results depend on argument order, round with half-to-even and exact decimal rounding, and NumPy's clip and sign. Gym's env math calls these wherever Gymnasium's source uses the Python operator or function, so results match Gymnasium's bit for bit; the C# operator there would drift on negative operands, NaNs and ties.

PyNameAttribute

Names a property or field by the Python attribute it stands for, where the default mapping (the snake_case form of the C# name) would not give it: [PyName("_disable_render_order_enforcing")]. A non-public member takes part in Python attribute access only when it carries this attribute. On a constructor parameter it is the keyword make binds to it (Construct(Type, IReadOnlyDictionary<string, object?>)), for the rare kwarg snake_case cannot spell. On a class it is the name Python prints for it (DR-24): the vector wrappers renamed for unique class names (NormalizeObservationVector) keep Gymnasium's (NormalizeObservation) in repr and messages. On a static method it is the Python function the method stands for where C# cannot use that name (StepApiCompatibility.Dispatch is step_api_compatibility, the class's own name). On an enum and its members it is the Python enum and constant each stands for (DR-68: MjtState.FullPhysics is mjtState.mjSTATE_FULLPHYSICS).

PyValueAttribute

The Python value of a PyEnumAttribute enum's member: the .value of a Python Enum member ("NextStep"), or the string a string member stands for ("rgb_array").

RecordConstructorArgs

The recording half of Python's RecordConstructorArgs.init, for IRecordConstructorArgs implementers.

RetainedData

The part of an observation or info that DataSharesObjects(RetainedData?, object?) compares across calls: containers by reference, arrays as views that keep their memory alive. Dispose it to release the views, which otherwise hold that memory until they are collected.

Seeding

The one way Gym.NET's envs and spaces create their random number generators. Every generator is NumPy's Generator(PCG64(SeedSequence(seed))), which NumSharp implements bit for bit, so a Gym.NET space or env seeded with s draws exactly what Gymnasium's draws for seed s, provided it makes the same calls.

StepApiCompatibility

Converts a single env's transition between the pre-0.26 "done" step API, (obs, reward, done, info), and the terminated/truncated API, (obs, reward, terminated, truncated, info). The two are told apart by info["TimeLimit.truncated"], which the old API used to mark a time-limit ending.

Video

Gymnasium's gymnasium.utils.save_video: the default recording schedule, and saving videos from a list of frames by episode and step triggers.

WarningCatcher

A Catch() block: the warnings issued while it was the innermost active catcher, in order. Dispose it (using) to end the block.

WarningMessage

One issued warning, as Python's warnings.catch_warnings(record=True) records it.

Warnings

The part of Python's warnings module that Logger depends on: its default filters, where shown warnings go, and catch_warnings(record=True) for tests. Gymnasium never throws where it only warns, so neither does Gym: a warning is text on the error stream (or a record), never an exception.

Interfaces

IDynamicAttributes

An object that, like a Python instance with a dict, can hold attributes created at run time: what setattr(obj, name, value) does for a name the class does not declare. Gymnasium's set_wrapper_attr(name, value, force=True) relies on it.

IGymOptions

An options record: an env's or wrapper's constructor arguments as typed properties (DR-11, DR-34), which make accepts in place of a dictionary of keyword arguments.

IPlotArtist

Something drawn on an IPlotAxes, which can be taken off it (matplotlib's Artist.remove).

IPlotAxes

One plot of an IPlotFigure: matplotlib's Axes as PlayPlot uses it.

IPlotFigure

A figure as PlayPlot draws on it: matplotlib's Figure with plt.pause.

IRecordConstructorArgs

Marks a wrapper that records its constructor arguments, so its Spec can describe it completely and make can re-create it from an EnvSpec. A wrapper that does not implement it is recorded with kwargs=None, which make cannot re-create.

IVideoWriter

Encodes one video from rendered frames (decision DR-25): what RecordVideo and SaveVideo(IReadOnlyList<NDArray>, string, Func<long, bool>?, Func<long, bool>?, long?, string, long, long, string?, double?, IVideoWriter?) hand their frames to, where Gymnasium hands them to moviepy. Implement it to store videos another way.

Enums

RetainedKind

What Retain(object?) kept of a value, which decides how it is compared.

WarningCategory

The Python warning classes Logger issues, as Gymnasium's logger does: UserWarning (the default of warnings.warn) and DeprecationWarning (Deprecation(string, string, int)).

Delegates

PlayCallback

What Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?) calls after every step (Gymnasium's play callback), with the transition the player caused. Callback(object?, object?, object?, double, bool, bool, Info) is one.

PlayPlot.PlotSubplots

The figure's maker: matplotlib's plt.subplots(nrows), a figure with rows axes stacked top to bottom.

PlayPlotMetrics

What PlayPlot computes its points with: a function of one transition (the arguments of PlayCallback) returning one value per plot, in the order of PlotNames.