Table of Contents

Class Dict

Namespace
Gym.Spaces
Assembly
Gym.dll

A dictionary of spaces: every element is a string-keyed dict (Gym.NET's insertion-ordered Python dict, Info, DR-13's generic form) holding one element of each subspace under its key, such as a robot's {"position": …, "velocity": …}.

public class Dict : Space<Info>, IDisposable, IReadOnlyDictionary<string, Space>, IReadOnlyCollection<KeyValuePair<string, Space>>, IEnumerable<KeyValuePair<string, Space>>, IEnumerable, IEquatable<Dict>
Inheritance
Dict
Implements
Inherited Members
Extension Methods

Remarks

Keys are sorted when the space is built from an unordered mapping and sort_keys is on (Gymnasium's legacy default); an ordered mapping keeps its order. The order decides how samples flatten, so it is part of the space.

The space owns its subspaces: disposing it disposes them. Reference: gymnasium/spaces/dict.py.

Constructors

Dict(IEnumerable<KeyValuePair<string, Space>>, SpaceSeed?, bool)

A dict space from key/space pairs (Gymnasium's Dict(spaces, seed=seed)): an ordered sequence of pairs keeps its order, as Gymnasium's sequence and OrderedDict inputs do.

public Dict(IEnumerable<KeyValuePair<string, Space>> spaces, SpaceSeed? seed = null, bool sortKeys = true)

Parameters

spaces IEnumerable<KeyValuePair<string, Space>>

The pairs, in order; the space owns the subspaces from now on.

seed SpaceSeed?

An integer seed (the dict's generator then draws one int32 seed per subspace), a generator to share, or null.

sortKeys bool

Recorded as SortKeys but not applied: Gymnasium sorts only an unordered mapping. Batching (batch_space) builds a mapping and applies it then, as Gymnasium does.

Exceptions

TypeError

Thrown for a null subspace, with Gymnasium's message.

ArgumentException

Thrown for a repeated key.

ArgumentNullException

Thrown when spaces is null.

Error

Thrown when an integer seed is negative.

Dict(IReadOnlyDictionary<string, Space>, SpaceSeed?, bool)

A dict space from a mapping (Gymnasium's Dict(mapping, seed=seed, sort_keys=sort_keys)): with sortKeys (Gymnasium's default) the keys are sorted ordinally, otherwise they keep the mapping's enumeration order.

public Dict(IReadOnlyDictionary<string, Space> spaces, SpaceSeed? seed = null, bool sortKeys = true)

Parameters

spaces IReadOnlyDictionary<string, Space>

The mapping; the space owns the subspaces from now on.

seed SpaceSeed?

An integer seed, a generator to share, or null.

sortKeys bool

Whether to sort the keys, Gymnasium's legacy behavior for unordered dicts.

Exceptions

TypeError

Thrown for a null subspace.

ArgumentNullException

Thrown when spaces is null.

Error

Thrown when an integer seed is negative.

Properties

Count

The number of subspaces (Gymnasium's len(space)).

public int Count { get; }

Property Value

int

IsNpFlattenable

Whether every subspace flattens to a box.

public override bool IsNpFlattenable { get; }

Property Value

bool

this[string]

The subspace under key (Gymnasium's space[key]); assigning one adds or replaces it (Gymnasium's setitem), a new key going last.

public Space this[string key] { get; set; }

Parameters

key string

The key.

Property Value

Space

The subspace.

Exceptions

KeyError

Thrown by the getter for an unknown key, with Python's message.

TypeError

Thrown by the setter for a null space.

Keys

The keys, in the space's order (Gymnasium's keys()).

public IEnumerable<string> Keys { get; }

Property Value

IEnumerable<string>

SortKeys

Gymnasium's sort_keys as given (applied only to an unordered mapping); batching passes it on.

public bool SortKeys { get; }

Property Value

bool

Spaces

The subspaces by key, in the space's order (Gymnasium's spaces).

public IReadOnlyDictionary<string, Space> Spaces { get; }

Property Value

IReadOnlyDictionary<string, Space>

Values

The subspaces, in the space's order.

public IEnumerable<Space> Values { get; }

Property Value

IEnumerable<Space>

Methods

Contains(object?)

Whether x is an element (Gymnasium's contains): a dict with exactly the space's keys (in any order) whose every value is a member of its subspace.

public override bool Contains(object? x)

Parameters

x object

The candidate: an Info or any string-keyed dictionary.

Returns

bool

true for an element.

ContainsKey(string)

Determines whether the read-only dictionary contains an element that has the specified key.

public bool ContainsKey(string key)

Parameters

key string

The key to locate.

Returns

bool

true if the read-only dictionary contains an element that has the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

Dispose(bool)

Releases what a derived space owns (a Box's bounds); called once, by Dispose().

protected override void Dispose(bool disposing)

Parameters

disposing bool

true from Dispose(); no space has a finalizer.

Equals(Dict?)

Gymnasium's ==: the same keys in the same order with equal subspaces (an ordered comparison).

public bool Equals(Dict? other)

Parameters

other Dict

The other space.

Returns

bool

true when equal.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

FromJsonable(object)

Converts Gymnasium's dict of per-key JSON data back to dicts (Gymnasium's from_jsonable).

public override IList<Info> FromJsonable(object jsonable)

Parameters

jsonable object

The dict of per-key data.

Returns

IList<Info>

The samples.

Exceptions

ArgumentException

Thrown when the data is not a string-keyed dictionary.

GetEnumerator()

Returns an enumerator that iterates through the collection.

public IEnumerator<KeyValuePair<string, Space>> GetEnumerator()

Returns

IEnumerator<KeyValuePair<string, Space>>

An enumerator that can be used to iterate through the collection.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

Sample(object?, object?)

Draws one element (Gymnasium's sample): a dict with one sample per subspace in the space's key order, optionally under a dict of per-key masks or probability masks.

public override Info Sample(object? mask = null, object? probability = null)

Parameters

mask object

null, or a dict with the space's keys mapping to each subspace's mask.

probability object

null, or a dict with the space's keys mapping to each subspace's probability mask.

Returns

Info

A new dict; arrays in it are owned by the caller.

Exceptions

ValueError

Thrown when both masks are given.

AssertionError

Thrown for a mask that is not a dict with the space's keys, with Gymnasium's messages.

SeedCore(BigInteger?)

Gymnasium's Dict.seed for an integer or null: null seeds every subspace from entropy; an integer seeds the dict's generator, which draws one int32 seed per subspace.

protected override object SeedCore(BigInteger? seed)

Parameters

seed BigInteger?

The seed, or null.

Returns

object

The subspaces' seeds, by key.

Exceptions

Error

Thrown for a negative seed.

SeedDictCore(IReadOnlyDictionary<string, object?>)

Gymnasium's Dict.seed for a dict: one seed (of any form) per key; the keys must be the space's.

protected override object SeedDictCore(IReadOnlyDictionary<string, object?> seeds)

Parameters

seeds IReadOnlyDictionary<string, object>

The seeds.

Returns

object

The subspaces' seeds, by key.

Exceptions

ValueError

Thrown when the keys are not the space's.

SeedTypeError(object?)

Gymnasium's Dict.seed error for a seed that is not an integer, a dict or null (a list included).

protected override Exception SeedTypeError(object? seed)

Parameters

seed object

The refused seed.

Returns

Exception

TypeError: Expected seed type: dict, int or None, actual type: <class 'list'>.

ToJsonable(IEnumerable<Info>)

Converts samples to Gymnasium's JSON form: a dict with each key's to_jsonable across the batch.

public override object ToJsonable(IEnumerable<Info> samples)

Parameters

samples IEnumerable<Info>

Samples of this space.

Returns

object

The dict of per-key JSON data.

ToString()

Gymnasium's repr: Dict('position': Box(…), 'velocity': Box(…)), keys as Python string reprs.

public override string ToString()

Returns

string

The text.

TryGetValue(string, out Space)

Gets the value that is associated with the specified key.

public bool TryGetValue(string key, out Space value)

Parameters

key string

The key to locate.

value Space

When this method returns, the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.

Returns

bool

true if the object that implements the IReadOnlyDictionary<TKey, TValue> interface contains an element that has the specified key; otherwise, false.

Exceptions

ArgumentNullException

key is null.