flatland.envs.observations module

Collection of environment-specific ObservationBuilder.

class flatland.envs.observations.GlobalObsForRailEnv

Bases: flatland.core.env_observation_builder.ObservationBuilder

Gives a global observation of the entire rail environment. The observation is composed of the following elements:

• transition map array with dimensions (env.height, env.width, 16), assuming 16 bits encoding of transitions.

• obs_agents_state: A 3D array (map_height, map_width, 5) with

  • first channel containing the agents position and direction
  • second channel containing the other agents positions and direction
  • third channel containing agent/other agent malfunctions
  • fourth channel containing agent/other agent fractional speeds
  • fifth channel containing number of other agents ready to depart

• obs_targets: Two 2D arrays (map_height, map_width, 2) containing respectively the position of the given agent target and the positions of the other agents targets (flag only, no counter!).

get(self, handle:int=0) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>, <class 'numpy.ndarray'>)

Called whenever an observation has to be computed for the env environment, possibly for each agent independently (agent id handle).

Parameters:

handle : int, optional

Handle of the agent for which to compute the observation vector.

Returns:

function

An observation structure, specific to the corresponding environment.

reset(self)

Called after each environment reset.

set_env(self, env:flatland.core.env.Environment)

class flatland.envs.observations.LocalObsForRailEnv(view_width, view_height, center)

Bases: flatland.core.env_observation_builder.ObservationBuilder

!!!!!!WARNING!!! THIS IS DEPRACTED AND NOT UPDATED TO FLATLAND 2.0!!!!! Gives a local observation of the rail environment around the agent. The observation is composed of the following elements:

• transition map array of the local environment around the given agent, with dimensions (view_height,2*view_width+1, 16), assuming 16 bits encoding of transitions.
• Two 2D arrays (view_height,2*view_width+1, 2) containing respectively, if they are in the agent’s vision range, its target position, the positions of the other targets.
• A 2D array (view_height,2*view_width+1, 4) containing the one hot encoding of directions of the other agents at their position coordinates, if they are in the agent’s vision range.
• A 4 elements array with one hot encoding of the direction.

Use the parameters view_width and view_height to define the rectangular view of the agent. The center parameters moves the agent along the height axis of this rectangle. If it is 0 the agent only has observation in front of it.

Deprecated since version 2.0.0.

field_of_view(self, position, direction, state=None)

get(self, handle:int=0) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>, <class 'numpy.ndarray'>, <class 'numpy.ndarray'>)

Called whenever an observation has to be computed for the env environment, possibly for each agent independently (agent id handle).

Parameters:

handle : int, optional

Handle of the agent for which to compute the observation vector.

Returns:

function

An observation structure, specific to the corresponding environment.

get_many(self, handles:Union[List[int], NoneType]=None) → Dict[int, Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]]

Called whenever an observation has to be computed for the env environment, for each agent with handle in the handles list.

reset(self)

Called after each environment reset.

class flatland.envs.observations.TreeObsForRailEnv(max_depth: int, predictor: flatland.core.env_prediction_builder.PredictionBuilder = None)

Bases: flatland.core.env_observation_builder.ObservationBuilder

TreeObsForRailEnv object.

This object returns observation vectors for agents in the RailEnv environment. The information is local to each agent and exploits the graph structure of the rail network to simplify the representation of the state of the environment for each agent.

For details about the features in the tree observation see the get() function.

class Node(dist_own_target_encountered, dist_other_target_encountered, dist_other_agent_encountered, dist_potential_conflict, dist_unusable_switch, dist_to_next_branch, dist_min_to_target, num_agents_same_direction, num_agents_opposite_direction, num_agents_malfunctioning, speed_min_fractional, num_agents_ready_to_depart, childs)

Bases: tuple

childs

Alias for field number 12

dist_min_to_target

Alias for field number 6

dist_other_agent_encountered

Alias for field number 2

dist_other_target_encountered

Alias for field number 1

dist_own_target_encountered

Alias for field number 0

dist_potential_conflict

Alias for field number 3

dist_to_next_branch

Alias for field number 5

dist_unusable_switch

Alias for field number 4

num_agents_malfunctioning

Alias for field number 9

num_agents_opposite_direction

Alias for field number 8

num_agents_ready_to_depart

Alias for field number 11

num_agents_same_direction

Alias for field number 7

speed_min_fractional

Alias for field number 10

get(self, handle:int=0) → flatland.envs.observations.Node

Computes the current observation for agent handle in env

The observation vector is composed of 4 sequential parts, corresponding to data from the up to 4 possible movements in a RailEnv (up to because only a subset of possible transitions are allowed in RailEnv). The possible movements are sorted relative to the current orientation of the agent, rather than NESW as for the transitions. The order is:

[data from 'left'] + [data from 'forward'] + [data from 'right'] + [data from 'back']

Each branch data is organized as:

[root node information] +
[recursive branch data from 'left'] +
[... from 'forward'] +
[... from 'right] +
[... from 'back']

Each node information is composed of 9 features:

#1:

if own target lies on the explored branch the current distance from the agent in number of cells is stored.

#2:

if another agents target is detected the distance in number of cells from the agents current location is stored

#3:

if another agent is detected the distance in number of cells from current agent position is stored.

#4:

possible conflict detected tot_dist = Other agent predicts to pass along this cell at the same time as the agent, we store the distance in number of cells from current agent position

0 = No other agent reserve the same cell at similar time

#5:

if an not usable switch (for agent) is detected we store the distance.

#6:

This feature stores the distance in number of cells to the next branching (current node)

#7:

minimum distance from node to the agent’s target given the direction of the agent if this path is chosen

#8:

agent in the same direction n = number of agents present same direction (possible future use: number of other agents in the same direction in this branch) 0 = no agent present same direction

#9:

agent in the opposite direction n = number of agents present other direction than myself (so conflict) (possible future use: number of other agents in other direction in this branch, ie. number of conflicts) 0 = no agent present other direction than myself

#10:

malfunctioning/blokcing agents n = number of time steps the oberved agent remains blocked

#11:

slowest observed speed of an agent in same direction 1 if no agent is observed

min_fractional speed otherwise

#12:

number of agents ready to depart but no yet active

Missing/padding nodes are filled in with -inf (truncated). Missing values in present node are filled in with +inf (truncated).

In case of the root node, the values are [0, 0, 0, 0, distance from agent to target, own malfunction, own speed] In case the target node is reached, the values are [0, 0, 0, 0, 0].

get_many(self, handles:Union[List[int], NoneType]=None) → Dict[int, flatland.envs.observations.Node]

Called whenever an observation has to be computed for the env environment, for each agent with handle in the handles list.

static print_node_features(node:flatland.envs.observations.Node, label, indent)

print_subtree(self, node, label, indent)

reset(self)

Called after each environment reset.

set_env(self, env:flatland.core.env.Environment)

tree_explored_actions_char = ['L', 'F', 'R', 'B']

util_print_obs_subtree(self, tree:flatland.envs.observations.Node)

Utility function to print tree observations returned by this object.