Namespace Gym.Utils
Classes
- Cv2
OpenCV's
cv2.resizefor uint8 and float32 images, bit for bit: InterArea, the interpolation Gymnasium'sResizeObservationuses, and InterLinear, the default the vectorHumanRenderinguses. Use it wherever Gymnasium callscv2.resize; Gym.NET carries no native OpenCV.
- Deque<T>
Python's
collections.dequeas the wrappers use it: a sequence that keeps the last MaxLen items, dropping the oldest as new ones are appended (RecordEpisodeStatistics'sreturn_queue). Indexing andreprfollow Python:queue[-1]is the newest, and it printsdeque([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
ffmpegprocess and writes an H.264 mp4, as moviepy does for Gymnasium:libx264at themediumpreset,yuv420pwhen both sides are even.
- GymDictAttribute
Makes a
partialpositional record a Python dict (DR-13): the generator writes implicit conversions to and fromInfo(what aDictspace samples), keyed by each member's Python name ([PyName], else its snake_case), Python's==andrepr.
- GymOptionsAttribute
Asks Gym.NET's source generator for an options record (DR-34): on a
partialenv or wrapper class it writes a<Class>Optionsrecord with one property per parameter of the public constructormakebinds to (a wrapper'senvexcepted), 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
partialpositional record a Python tuple (DR-13): the generator writes implicit conversions to and from object?[] (Gym.NET's tuple, what aTuplespace samples), Python's==member by member, and Python'srepr,(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): passkeysToAction, or give the env aget_keys_to_actionattribute.
- 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, whichmakeadds unlessdisable_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.Renderingand 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 anfps.txtholding its frame rate. Needs no external program;ffmpeg -framerate {fps} -i %06d.png out.mp4turns a folder into a video.
- PyAttributes
Python's
hasattr,getattrandsetattrfor .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:NpRandomSeedisnp_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, andrepr/str/typefor the messages of asserts and errors, which callers and tests match verbatim.
- PyCopy
Python's
copy.deepcopyfor 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
Enumclass (AutoresetMode is Gymnasium'sAutoresetMode, 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 anEnumclass, its Python name in a PyNameAttribute.
- PyEnums
Python's view of the C# enums marked PyEnumAttribute (DR-84): a member's Python
.name,.value,strandrepr, parsing a member from its value as Python'sEnum(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 comparesinfodicts, 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.makebuilds 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/maxwhose NaN results depend on argument order,roundwith half-to-even and exact decimal rounding, and NumPy'sclipandsign. 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 keywordmakebinds 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) inreprand messages. On a static method it is the Python function the method stands for where C# cannot use that name (StepApiCompatibility.Dispatchisstep_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.FullPhysicsismjtState.mjSTATE_FULLPHYSICS).
- PyValueAttribute
The Python value of a PyEnumAttribute enum's member: the
.valueof a PythonEnummember ("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 withsdraws exactly what Gymnasium's draws for seeds, 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 byinfo["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
warningsmodule that Logger depends on: its default filters, where shown warnings go, andcatch_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: whatsetattr(obj, name, value)does for a name the class does not declare. Gymnasium'sset_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
makeaccepts 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
Axesas PlayPlot uses it.
- IPlotFigure
A figure as PlayPlot draws on it: matplotlib's
Figurewithplt.pause.
- IRecordConstructorArgs
Marks a wrapper that records its constructor arguments, so its Spec can describe it completely and
makecan re-create it from an EnvSpec. A wrapper that does not implement it is recorded withkwargs=None, whichmakecannot re-create.
- IVideoWriter
Encodes one video from rendered frames (decision DR-25): what
RecordVideoand 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 ofwarnings.warn) andDeprecationWarning(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
playcallback), 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 withrowsaxes 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.