Class 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.
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
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
stepReturnsobject[]The returns tuple; the info gains the key where an episode ended.
isVectorEnvboolWhether 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
stepReturnsis 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
stepReturnsStepResult<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
TObsThe observation type.
Remarks
Reference: gymnasium/utils/step_api_compatibility.py.
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
stepReturnsobject[]The returns tuple; the info loses the key.
isVectorEnvboolWhether 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
stepReturnsis 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
stepReturnsDoneStepResult<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
TObsThe 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
stepReturnsobject[](obs, rew, done, info)or(obs, rew, terminated, truncated, info); the info is edited in place.outputTruncationBoolboolWhether the output has two flags (the new API, the default) or one.
isVectorEnvboolWhether 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
stepReturnsis 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)).