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
optionsTaxiEnvOptionsThe options.
Exceptions
- ArgumentNullException
Thrown when
optionsis 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
renderModeRenderModeThe 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.isRainyboolGymnasium's
is_rainy: a move goes as intended withrainyProbability, else to either side.ficklePassengerboolGymnasium's
fickle_passenger: the passenger may change their destination after the first move with them aboard.rainyProbabilitydoubleGymnasium's
rainy_probability, 0.8 by default.fickleProbabilitydoubleGymnasium's
fickle_probability, 0.3 by default: the chance, drawn at each reset, that the passenger is fickle this episode.viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
renderModestringGymnasium's
render_mode: null,"human","ansi"or"rgb_array".isRainyboolGymnasium's
is_rainy: a move goes as intended withrainyProbability, else to either side.ficklePassengerboolGymnasium's
fickle_passenger: the passenger may change their destination after the first move with them aboard.rainyProbabilitydoubleGymnasium's
rainy_probability, 0.8 by default.fickleProbabilitydoubleGymnasium's
fickle_probability, 0.3 by default: the chance, drawn at each reset, that the passenger is fickle this episode.viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.HumanViewerFactory.
Properties
BackgroundImg
Gymnasium's background_img.
public Surface? BackgroundImg { get; }
Property Value
CellSize
Gymnasium's cell_size: (88, 56) pixels.
public (int Width, int Height) CellSize { get; }
Property Value
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
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
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
DestinationImg
Gymnasium's destination_img.
public Surface? DestinationImg { get; }
Property Value
FicklePassenger
Gymnasium's fickle_passenger.
public bool FicklePassenger { get; set; }
Property Value
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
FickleStep
Gymnasium's fickle_step: whether the passenger may still change their destination this episode.
public bool FickleStep { get; set; }
Property Value
HouseImg
Gymnasium's house_img.
public Surface? HouseImg { get; }
Property Value
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
Map
Gymnasium's MAP: the grid, its walls (|) and stands, as text.
public static IReadOnlyList<string> Map { get; }
Property Value
MaxCol
Gymnasium's max_col, 4.
public int MaxCol { get; }
Property Value
MaxRow
Gymnasium's max_row, 4.
public int MaxRow { get; }
Property Value
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
PassengerImg
Gymnasium's passenger_img.
public Surface? PassengerImg { get; }
Property Value
RainyLateralProbability
Gymnasium's _rainy_lateral_probability: (1 - rainy_probability) / 2.
[PyName("_rainy_lateral_probability")]
public double RainyLateralProbability { get; }
Property Value
RainyProbability
Gymnasium's rainy_probability, fixed at construction.
public double RainyProbability { get; }
Property Value
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
TaxiImgs
Gymnasium's taxi_imgs: the empty taxi facing south, north, east and west.
public IReadOnlyList<Surface>? TaxiImgs { get; }
Property Value
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
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
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
statelongThe 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
Reference: gymnasium/envs/toy_text/taxi.py.
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
actionobjectThe 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
ilongThe state.
Returns
Exceptions
- AssertionError
Thrown for a state beyond the grid (Gymnasium's bare
assert 0 <= i < 5on 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
taxiRowlongThe taxi's row.
taxiCollongThe taxi's column.
passLoclongThe passenger's stand (0-3), or 4 in the taxi.
destIdxlongThe 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
Reference: gymnasium/envs/toy_text/taxi.py.
Exceptions
- AssertionError
Thrown without a render mode when the env has no spec, and for a mode other than
human,ansiandrgb_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
seedBigInteger?The seed of a fresh
Generator(PCG64(SeedSequence(seed))), or null to keep the generator.optionsIReadOnlyDictionary<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
Reference: gymnasium/envs/toy_text/taxi.py.
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
actionNDArrayA 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
Reference: gymnasium/envs/toy_text/taxi.py.
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).