Table of Contents

Class StepApiCompatibility

Namespace
Gym.Utils
Assembly
Gym.dll

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.

public static class StepApiCompatibility
Inheritance
StepApiCompatibility
Inherited Members

Remarks

Python's step_api_compatibility(step_returns, output_truncation_bool, is_vector_env) accepts either form and dispatches on the tuple's length: Dispatch(object?[], bool, bool) does the same over an object?[] tuple, single or vector (a list of infos, or a dict of arrays). For a typed single-env transition the argument's type already says which form it is, so the typed conversions are called directly.

As in Gymnasium, every conversion edits the given info in place: the done conversion adds "TimeLimit.truncated", the terminated/truncated conversion removes it.

Reference: gymnasium/utils/step_api_compatibility.py.

Fields

TimeLimitTruncatedKey

The info key the done API uses to mark a truncation ("TimeLimit.truncated").

public const string TimeLimitTruncatedKey = "TimeLimit.truncated"

Field Value

string

Methods

ConvertToDoneStepApi(object?[], bool)

Python's convert_to_done_step_api(step_returns, is_vector_env) over a returns tuple: four items pass through; five merge their flags into done, recording info["TimeLimit.truncated"] for the endings.

public static object?[] ConvertToDoneStepApi(object?[] stepReturns, bool isVectorEnv = false)

Parameters

stepReturns object[]

The returns tuple; the info gains the key where an episode ended.

isVectorEnv bool

Whether the returns are a vector env's.

Returns

object[]

The four returns.

Remarks

A single env's done is Python's terminated or truncated (the first truthy operand, else the second), and the recorded value truncated and not terminated. Reference: gymnasium/utils/step_api_compatibility.py.

Exceptions

ArgumentNullException

Thrown when stepReturns is null.

AssertionError

Thrown when the returns have neither four nor five items.

TypeError

Thrown for vector infos that are neither a list nor a dict.

ValueError

Thrown when a list of infos and the flags differ in length.

ConvertToDoneStepApi<TObs>(StepResult<TObs>)

Merges a transition's flags into done = terminated or truncated and, when the episode ended, records info["TimeLimit.truncated"] = truncated and not terminated, so legacy consumers can still tell a time limit from a terminal state.

public static DoneStepResult<TObs> ConvertToDoneStepApi<TObs>(StepResult<TObs> stepReturns)

Parameters

stepReturns StepResult<TObs>

The terminated/truncated transition; its info gains the key when the episode ended.

Returns

DoneStepResult<TObs>

The same transition in the done API.

Type Parameters

TObs

The observation type.

Remarks

Exceptions

ArgumentNullException

Thrown when the transition's info is null.

ConvertToTerminatedTruncatedStepApi(object?[], bool)

Python's convert_to_terminated_truncated_step_api(step_returns, is_vector_env) over a returns tuple: five items pass through; four are split by info["TimeLimit.truncated"], popped from the info (or each info of a list, or the dict of arrays).

public static object?[] ConvertToTerminatedTruncatedStepApi(object?[] stepReturns, bool isVectorEnv = false)

Parameters

stepReturns object[]

The returns tuple; the info loses the key.

isVectorEnv bool

Whether the returns are a vector env's.

Returns

object[]

The five returns.

Remarks

A single env's flags are Python's and of the operands, so a falsy done comes back as itself, and a true one as not truncated and the popped value. Reference: gymnasium/utils/step_api_compatibility.py.

Exceptions

ArgumentNullException

Thrown when stepReturns is null.

AssertionError

Thrown when the returns have neither four nor five items.

TypeError

Thrown for vector infos that are neither a list nor a dict.

ConvertToTerminatedTruncatedStepApi<TObs>(DoneStepResult<TObs>)

Splits a done-API transition's done into terminated = done and not truncated and truncated = done and truncated, where truncated is popped from info["TimeLimit.truncated"] (absent means false), so a time-limit ending stays distinguishable from a terminal state.

public static StepResult<TObs> ConvertToTerminatedTruncatedStepApi<TObs>(DoneStepResult<TObs> stepReturns)

Parameters

stepReturns DoneStepResult<TObs>

The done-API transition; its info loses the "TimeLimit.truncated" key.

Returns

StepResult<TObs>

The same transition in the terminated/truncated API.

Type Parameters

TObs

The observation type.

Remarks

Python's and returns an operand (so done of 0 stays 0); the flags here are bool, the truth value of that operand. The popped value counts by Python truthiness. Reference: gymnasium/utils/step_api_compatibility.py.

Exceptions

ArgumentNullException

Thrown when the transition's info is null.

Dispatch(object?[], bool, bool)

Python's step_api_compatibility(step_returns, output_truncation_bool, is_vector_env): converts a step's returns, whichever API they follow, to the terminated/truncated API (outputTruncationBool) or to the done API. The returns are a Python tuple, an object?[] of four or five items; the result is a new array (a returns array already in the asked form is returned as it is, as Python returns its tuple).

[PyName("step_api_compatibility")]
public static object?[] Dispatch(object?[] stepReturns, bool outputTruncationBool = true, bool isVectorEnv = false)

Parameters

stepReturns object[]

(obs, rew, done, info) or (obs, rew, terminated, truncated, info); the info is edited in place.

outputTruncationBool bool

Whether the output has two flags (the new API, the default) or one.

isVectorEnv bool

Whether the returns are a vector env's: flag arrays, and infos as a list of dicts or one dict of arrays.

Returns

object[]

The returns in the asked API.

Remarks

The class's name is taken, so the function is Dispatch in C# and step_api_compatibility by its Python name. The typed overloads of the two conversions cover a single env's StepResult<TObs> and DoneStepResult<TObs>. Reference: gymnasium/utils/step_api_compatibility.py.

Exceptions

ArgumentNullException

Thrown when stepReturns is null.

AssertionError

Thrown when the returns have neither four nor five items.

TypeError

Thrown for vector returns whose infos are neither a list nor a dict, with Gymnasium's message.

ValueError

Thrown when a list of infos and the flags differ in length (Python's zip(strict=True)).