Table of Contents

Class TaxiEnv

Namespace
Gym.Environments.Envs.ToyText
Assembly
Gym.Environments.dll

Taxi-v4: drive a taxi on a 5x5 grid with walls, pick a passenger up at one of four stands (R, G, Y, B) and drop them at their destination: -1 per step, -10 for a wrong pickup or dropoff, 20 for delivering. Byte for byte what Gymnasium's Taxi computes: the 500-state transition table P (dry or rainy), the fickle passenger, the generator draws, observations, rewards, {"prob", "action_mask"} infos, ansi text and rgb_array pixels.

public class TaxiEnv : Env<NDArray, NDArray>, IEnv, IDisposable, IDynamicAttributes
Inheritance
TaxiEnv
Implements
Inherited Members
Extension Methods

Remarks

Like Gymnasium's, the env checks no action against its space: self.P[self.s][a] is a dict lookup, so any number equal to 0..5 is an action, anything else raises KeyError. Each step draws one float64 from the env's generator; a fickle passenger draws once more at the reset (random()) and once when they change their mind (choice). Observations are 0-d int64 arrays (DR-08); rewards are Gymnasium's -1, -10 and 20 as float64; the info's action_mask is Gymnasium's int8 array.

Rendering is Gymnasium's pixel art (the background with walls and stands, the house, the destination marker, the passenger and the taxi facing its last move); as in Gymnasium the taxi turns only when a render sees a movement as the last action, and the sprite is chosen with Python's list indexing by that action. ansi colours the taxi, passenger and destination with Gymnasium's escape codes. Human mode renders into the window from viewer_factory or Gymnasium.HumanViewerFactory (DR-20) at 4 frames per second. Not thread-safe.

Reference: gymnasium/envs/toy_text/taxi.py.

Its info reads typed (DR-91): TaxiInfo info = step.Info; (TaxiInfo), with the dict's own values still behind the indexer.

Constructors

TaxiEnv(TaxiEnvOptions)

Builds the instance from its options record: the properties set, the constructor's defaults for the rest.

public TaxiEnv(TaxiEnvOptions options)

Parameters

options TaxiEnvOptions

The options.

Exceptions

ArgumentNullException

Thrown when options is null.

TaxiEnv(RenderMode, bool, bool, double, double, EnvViewerFactory?)

Builds the env with the render mode given as the RenderMode enum (DR-84, DR-93), as TaxiEnv(string?, bool, bool, double, double, EnvViewerFactory?) builds it from the mode's string: new TaxiEnv(RenderMode.RgbArray) builds what new TaxiEnv(renderMode: "rgb_array") builds, the member reaching the env as Gymnasium's string (Name(RenderMode)), which its RenderMode property then holds.

public TaxiEnv(RenderMode renderMode, bool isRainy = false, bool ficklePassenger = false, double rainyProbability = 0.8, double fickleProbability = 0.3, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode RenderMode

The render mode, which the env must list in its metadata["render_modes"] as for the string; it behaves exactly as its Gymnasium string does in the other constructor.

isRainy bool

Gymnasium's is_rainy: a move goes as intended with rainyProbability, else to either side.

ficklePassenger bool

Gymnasium's fickle_passenger: the passenger may change their destination after the first move with them aboard.

rainyProbability double

Gymnasium's rainy_probability, 0.8 by default.

fickleProbability double

Gymnasium's fickle_probability, 0.3 by default: the chance, drawn at each reset, that the passenger is fickle this episode.

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Remarks

The mode is required and comes first, so new TaxiEnv() keeps meaning the other constructor, without a mode; leave the mode out there for no rendering. Every other parameter means what it means there.

Exceptions

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare (a cast integer such as (RenderMode)99).

TaxiEnv(string?, bool, bool, double, double, EnvViewerFactory?)

Creates the env.

public TaxiEnv(string? renderMode = null, bool isRainy = false, bool ficklePassenger = false, double rainyProbability = 0.8, double fickleProbability = 0.3, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode string

Gymnasium's render_mode: null, "human", "ansi" or "rgb_array".

isRainy bool

Gymnasium's is_rainy: a move goes as intended with rainyProbability, else to either side.

ficklePassenger bool

Gymnasium's fickle_passenger: the passenger may change their destination after the first move with them aboard.

rainyProbability double

Gymnasium's rainy_probability, 0.8 by default.

fickleProbability double

Gymnasium's fickle_probability, 0.3 by default: the chance, drawn at each reset, that the passenger is fickle this episode.

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Properties

BackgroundImg

Gymnasium's background_img.

public Surface? BackgroundImg { get; }

Property Value

Surface

CellSize

Gymnasium's cell_size: (88, 56) pixels.

public (int Width, int Height) CellSize { get; }

Property Value

(int Width, int Height)

ClassMetadata

Gymnasium's class attribute metadata: {"render_modes": ["human", "ansi", "rgb_array"], "render_fps": 4}. Every env starts with a copy as its instance metadata.

public static Metadata ClassMetadata { get; }

Property Value

Metadata

Remarks

A new dict on every read, so editing one env's metadata never reaches another (Python's is one shared dict).

Clock

Gymnasium's clock, null until the first image render.

public Clock? Clock { get; }

Property Value

Clock

Desc

Gymnasium's desc: the map as NumPy's (7, 11) S1 array, a new array on every read that the caller owns.

public NDArray Desc { get; }

Property Value

NDArray

DestinationImg

Gymnasium's destination_img.

public Surface? DestinationImg { get; }

Property Value

Surface

FicklePassenger

Gymnasium's fickle_passenger.

public bool FicklePassenger { get; set; }

Property Value

bool

FickleProbability

Gymnasium's fickle_probability: the chance, drawn at each reset of a fickle env, that this episode's passenger may change their mind.

public double FickleProbability { get; set; }

Property Value

double

FickleStep

Gymnasium's fickle_step: whether the passenger may still change their destination this episode.

public bool FickleStep { get; set; }

Property Value

bool

HouseImg

Gymnasium's house_img.

public Surface? HouseImg { get; }

Property Value

Surface

InitialStateDistrib

Gymnasium's initial_state_distrib, a new array on every read.

public double[] InitialStateDistrib { get; }

Property Value

double[]

LastAction

Gymnasium's lastaction: the action key of the last step, or null after a reset (Python's None).

[PyName("lastaction")]
public long? LastAction { get; }

Property Value

long?

Locs

Gymnasium's locs: the stands R, G, Y and B as (row, col).

public IReadOnlyList<(int Row, int Col)> Locs { get; }

Property Value

IReadOnlyList<(int X, int Y)>

LocsColors

Gymnasium's locs_colors: red, green, yellow and blue, for the stands.

public IReadOnlyList<(int R, int G, int B)> LocsColors { get; }

Property Value

IReadOnlyList<(int R, int G, int B)>

Map

Gymnasium's MAP: the grid, its walls (|) and stands, as text.

public static IReadOnlyList<string> Map { get; }

Property Value

IReadOnlyList<string>

MaxCol

Gymnasium's max_col, 4.

public int MaxCol { get; }

Property Value

int

MaxRow

Gymnasium's max_row, 4.

public int MaxRow { get; }

Property Value

int

P

Gymnasium's P: for each state and action, the possible outcomes (probability, next state, reward, terminated).

[PyName("P")]
public IReadOnlyDictionary<long, IReadOnlyDictionary<long, IReadOnlyList<ToyTextTransition>>> P { get; }

Property Value

IReadOnlyDictionary<long, IReadOnlyDictionary<long, IReadOnlyList<ToyTextTransition>>>

PassengerImg

Gymnasium's passenger_img.

public Surface? PassengerImg { get; }

Property Value

Surface

RainyLateralProbability

Gymnasium's _rainy_lateral_probability: (1 - rainy_probability) / 2.

[PyName("_rainy_lateral_probability")]
public double RainyLateralProbability { get; }

Property Value

double

RainyProbability

Gymnasium's rainy_probability, fixed at construction.

public double RainyProbability { get; }

Property Value

double

S

Gymnasium's s: the encoded state; null before the first reset. Assigning one injects a state.

[PyName("s")]
public long? S { get; set; }

Property Value

long?

TaxiFullImgs

Gymnasium's taxi_full_imgs: the taxi with the passenger, by the same orientations.

public IReadOnlyList<Surface>? TaxiFullImgs { get; }

Property Value

IReadOnlyList<Surface>

TaxiImgs

Gymnasium's taxi_imgs: the empty taxi facing south, north, east and west.

public IReadOnlyList<Surface>? TaxiImgs { get; }

Property Value

IReadOnlyList<Surface>

TaxiOrientation

Gymnasium's taxi_orientation: the sprite the taxi is drawn with (0 south, 1 north, 2 east, 3 west), set to 0 by a reset and to the last movement by a render, not by the step.

[PyName("taxi_orientation")]
public long TaxiOrientation { get; }

Property Value

long

Remarks

The value is the action's key: after a float movement such as 2.0 it reads 2, while every later image render raises Python's TypeError at the sprite lookup, as Gymnasium's does with the float it stored.

Window

Gymnasium's window: the frame every image render draws on, null until the first one.

public Surface? Window { get; }

Property Value

Surface

Methods

ActionMask(long)

Gymnasium's action_mask: which of the six actions change the state, as an int8 array of 0s and 1s.

public NDArray ActionMask(long state)

Parameters

state long

The state.

Returns

NDArray

A new (6,) int8 array; the caller owns it.

Exceptions

AssertionError

Thrown for a state beyond the grid.

Close()

Once a window exists, shuts the human-mode window down (pygame's display.quit()); the surface is kept.

public override void Close()

Remarks

ConvertAction(object?)

The untyped step's action conversion, with Python's order kept: the state's existence first, then the dict lookup on the action as given (its Python type is also kept for the renders' list indexing).

protected override NDArray ConvertAction(object? action)

Parameters

action object

The action as given to the untyped step.

Returns

NDArray

The action as an array: the one given, or a new one the step releases.

Exceptions

AttributeError

Thrown before the first reset.

KeyError

Thrown for an action no key equals.

TypeError

Thrown for an array of one or more dimensions.

Decode(long)

Gymnasium's decode: the state's (taxi_row, taxi_col, pass_loc, dest_idx).

public (long TaxiRow, long TaxiCol, long PassLoc, long DestIdx) Decode(long i)

Parameters

i long

The state.

Returns

(long TaxiRow, long TaxiCol, long PassLoc, long DestIdx)

The four parts.

Exceptions

AssertionError

Thrown for a state beyond the grid (Gymnasium's bare assert 0 <= i < 5 on the row).

Encode(long, long, long, long)

Gymnasium's encode: ((taxi_row * 5 + taxi_col) * 5 + pass_loc) * 4 + dest_idx.

public long Encode(long taxiRow, long taxiCol, long passLoc, long destIdx)

Parameters

taxiRow long

The taxi's row.

taxiCol long

The taxi's column.

passLoc long

The passenger's stand (0-3), or 4 in the taxi.

destIdx long

The destination stand.

Returns

long

The state.

Render()

Renders by the render mode: ansi returns the map as coloured text; any other mode draws Gymnasium's pixel art (rgb_array returns the frame).

public override RenderResult Render()

Returns

RenderResult

ansi: the text. rgb_array: the (456, 536, 3) uint8 frame, a new array the caller owns. human: nothing.

Remarks

Exceptions

AssertionError

Thrown without a render mode when the env has no spec, and for a mode other than human, ansi and rgb_array (Something went wrong with pygame. This should never happen.), as in Gymnasium.

AttributeError

Thrown before the first reset (no s; for images after the background was drawn).

TypeError

Thrown after an action Python's list indexing refuses (a float action), by the caption or the taxi sprite's lookup.

KeyError

Thrown in human mode when metadata["render_fps"] was removed.

DependencyNotInstalled

Thrown on the first human render when no viewer factory is set (DR-20).

Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)

Starts an episode: reseeds the generator when a seed is given, draws the start state (one draw), and for a fickle env draws once more whether this episode's passenger may change their mind. Renders in human mode.

public override ResetResult<NDArray> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)

Parameters

seed BigInteger?

The seed of a fresh Generator(PCG64(SeedSequence(seed))), or null to keep the generator.

options IReadOnlyDictionary<string, object>

Ignored, as in Gymnasium.

Returns

ResetResult<NDArray>

The state as a 0-d int64 array, and {"prob": 1.0, "action_mask": mask}.

Remarks

Exceptions

Error

Thrown for a negative seed, with Gymnasium's message.

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).

Step(NDArray)

Takes the action: looks up P[s][a] and draws one outcome (one float64); a fickle passenger who has just ridden their first move changes their destination (one more draw). Renders in human mode.

public override StepResult<NDArray> Step(NDArray action)

Parameters

action NDArray

A number equal to 0 (south), 1 (north), 2 (east), 3 (west), 4 (pickup) or 5 (dropoff).

Returns

StepResult<NDArray>

The new state, the reward, whether the passenger was delivered, truncated=False, and {"prob": p, "action_mask": mask}.

Remarks

Exceptions

AttributeError

Thrown before the first reset ('TaxiEnv' object has no attribute 's'), before the action is looked at.

KeyError

Thrown for an action no key equals, or an injected state outside the table, with Python's message.

TypeError

Thrown for an array action of one or more dimensions (unhashable type: 'numpy.ndarray').

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).