Source code reference

Environments

`BaseEnv`

Bases: Env

(Gymnasium) Base Environment for the simulator.

The simulator wrapped around gymnasium (gym) API.

Parameters:

Name	Type	Description	Default
`render_mode`	`str \| None`	the mode to visualize (render) the simulator. It can only be set to None or one of the following: 'human', 'rgb_array', 'file'. Defaults to `None`.	`None`
`config`	`EnvConfig \| None`	defines the configuration parameters for the gymnasium environment and the underlying simulator.	`None`

`out_sector_control` `property` `writable`

Get the flag which determine out of sector control.

`actions_gym_to_simulator(action)`

Helper method to convert gym env actions to simulator actions

Parameters:

Name	Type	Description	Default
`action`	`ActionType`	defines the gym action to convert to the simulator action(s). `int` for centralized setup and `dict` for decentralized setup.	required

Returns two-element tuple: - dict with each key-value pair representing a callsign and the corresponding action (using the integer representation of actions per aircraft). - dict with each key-value pair that represents callsign and a corresponding simulator action.

`actions_simulator_to_gym(actions_st)`

Helper method to convert simulator actions to gym actions

Parameters:

Name	Type	Description	Default
`actions_st`	`dict[str, Action]`	defines the actions to convert to gym actions. a dict, with each key-value pair representing a callsign and a corresponding simulator action as the value.	required

Returns three-element tuple: - gym action as int for centralized setup and dict for decentralized setup. - the reformatted action specific to each aircraft. - the action information specific to each aircraft.

`check_pos_information(callsign, prev_position_status, prev_incomm_status, prev_outcomm_status, prev_incorrect_exit_position)`

Check the status of an aircraft in relation to the sector.

Checks include: the position status, whether incommed, outcommed, distance to sector entry (pre-incomm), distance away from sector exit (after outcomm and exit from the sector).

Parameters:

Name	Type	Description	Default
`callsign`	`str`	the name of the aircraft.	required
`prev_position_status`	`int`	the previous step position status	required
`prev_incomm_status`	`bool`	the previous step incomm status	required
`prev_outcomm_status`	`bool`	the previous step outcomm status	required
`prev_incorrect_exit_position`	`None \| Pos2D`	the previous step tracker of the position where an aircraft incorrectly exited the ssector. If set to None, it means that the aircraft has not incorrectly exited the sector at an earlier time step.	required

Returns:

Type	Description
`ACPositionInfo`	the position information of the aircraft which contains the
`ACPositionInfo`	following information:
`ACPositionInfo`	position status
`ACPositionInfo`	incomm status
`ACPositionInfo`	outcomm status
`ACPositionInfo`	distance to sector entry (> 0 pre-incomm, set to 0.0 afterwards)
`ACPositionInfo`	distance away from sector exit (> 0 only after exiting the sector via the correct exit position on its route. set to 0.0 otherwise.).
`ACPositionInfo`	distance away from incorrect sector exit (> 0 only after exiting the sector via an incorrect position on the sector boundary (not defined on its route). set to 0.0 otherwise.).
`ACPositionInfo`	incorrect exit position: only updated once, which happens when an aircraft that was in sector at the previous time step navigates out of the sector (at the current time step) through an incorrect 'exit position' (the sector boundary). at other times, it maintains what was set in the previous step, i.e., `None` (if there was previously no incorrect sector exit) or a position in the sector (if there was an incorrect sector exit at an earlier time step).

`compute_reward(callsign, action)`

Compute reward given the current state and action.

Parameters:

Name	Type	Description	Default
`callsign`	`str`	the identifier/name of the aircraft.	required
`action`	`int`	the action taken by the agent.	required

Returns:

Type	Description
`dict[str, float]`	`dict` of the individual reward components for the aircraft.

`compute_success_metric(callsign, previous_value)`

Metric to judge whether an aircraft exit the sector correctly.

Parameters:

Name	Type	Description	Default
`callsign`	`str`	defines the aircraft's identifier.	required
`previous_value`	`int`	defines the value of the success metric at the previous time step.	required

Returns:

Type	Description
`SuccessMetric`	success metric value defined as a tenary integer: 1 => PASS: if the aircraft correctly exited the sector
`SuccessMetric`	-1 => FAIL: if the aircraft incorrectly exited the sector: either via an excursion (incorrect exit position) or the correct exit position but at a wrong flight level. 0 => PENDING: if the aircraft is still in the sector

`debug_get_actions_for_aircraft(callsign)`

Get the available actions for a given aircraft.

A useful debugging method

Parameters:

Name	Type	Description	Default
`callsign`	`str`	defines the identifier of the aircraft	required

Returns:

Type	Description
`dict[int, str] \| None`	the available actions for the aircraft.
`dict[int, str] \| None`	note, in centralized setup, if the aircraft was not selected in
`dict[int, str] \| None`	the generation of state for the current time step, then `None`
`dict[int, str] \| None`	is returned. this does not apply to decentralized setup.

`debug_get_actions_history()`

Returns the history of actions taken within an episode.

`disable_auto_route_following()`

Disable automatic route following for aircraft.

`enable_auto_route_following()`

Enable automatic route following for aircraft.

`get_action_parser()`

Get the action parser instance that manages the action space.

`get_active_airspace_sector()`

Get the active airspace sector in use.

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

Class method: Get the default config for an environment instance.

Defined in each child class that inherits this base class.

Parameters:

Name	Type	Description	Default
`cls`		the class	required
`view_type`	`ViewType \| str`	the type of agent view, centralized (single agent) or decentralized (multi-agent). Defaults to "centralized".	`CENTRALIZED`

Returns:

Type	Description
`EnvConfig`	dict, the default config.

`get_forward_fixes_info()`

Get the forward fixes configuration.

`get_manager()`

Get the current simulator environment manager.

`get_radar_figure()`

Get the figure and axes used to plot the simulation radar display.

`get_render_mode()`

Retrieve the render mode of the simulator.

Returns:

Name	Type	Description
`render_mode`	`str or None`	the render mode set. It contains either None or one of the following: 'human', 'rgb_array', 'file'.

`get_rollout_predictor()`

Get the predictor used for aircraft future rollout prediction.

`get_simulator()`

Get the current simulator.

`get_simulator_env()`

Get the current simulator environment.

`get_tracked_aircraft_data(callsign=None, copy_data=False)`

Returns aircraft tracked data.

Retrieves either the tracked data of all active aircraft, or the tracked data of a specific aircraft as indicated by the callsign argument.

Parameters:

Name	Type	Description	Default
`callsign`	`str`	the callsign to retrieved tracked data. Optional, if set to `None`, the tracked data for all active aircraft is returned. Defaults to `None`.	`None`
`copy_data`	`bool`	defines whether a copy of the data should be returned. Defaults to `False`.	`False`

Returns dict of tracked information for all aircraft or tracked information for a specific aircraft or None. if callsign is set, the method returns the tracked data for the specific aircraft to which the callsign belongs. if the set callsign is invalid (i.e, not in the tracker dict), then None is returned.

if `callsign` is set to None, then a `dict` containing the
tracked data for all aircraft is returned.

`get_tracked_aircraft_data_previous(callsign=None, copy_data=False)`

Returns aircraft tracked data for the previous step.

Retrieves either the tracked data of all active aircraft, or the tracked data of a specific aircraft as indicated by the callsign argument.

Parameters:

Name	Type	Description	Default
`callsign`	`str`	the callsign to retrieved tracked data. Optional, if set to `None`, the tracked data for all active aircraft is returned. Defaults to `None`.	`None`
`copy_data`	`bool`	defines whether a copy of the data should be returned. Defaults to `False`.	`False`

Returns dict of tracked information for all aircraft or tracked information for a specific aircraft or None. if callsign is set, the method returns the tracked data for the specific aircraft to which the callsign belongs. if the set callsign is invalid (i.e, not in the tracker dict), then None is returned.

if `callsign` is set to None, then a `dict` containing the
tracked data for all aircraft is returned.

`get_traffic_monitor()`

Get the traffic monitor.

`render()`

Render a frame and save to disk the current simulator state.

Render a frame based on the current state of simulator and save to disk. The rendered frame is an image that is generated using the defined radar.

`render_w_overlay_trajectory(traj_dict=None)`

Render a frame and save to disk the current simulator state.

Render a frame based on the current state of simulator and render the alternate trajectory of aircraft received from the external caller, and save the generated frame to disk. The rendered frame is an image that is generated using the defined radar.

Note, this method is for debugging purpose and should be only used when all associated gymnasium wrappers have been removed/stripped and the environment object can be accessed directly.

Also note, only "file" render mode is currently supported.

`reset(*, seed=None, options=None)`

Environment reset.

Reset the environment to an initial state, randomising the scenario.

Parameters:

Name	Type	Description	Default
`seed`	`int`	seed for random number generator. Defaults to None.	`None`
`options`	`dict`	additional configuration for the reset. Defaults to None.	`None`

Returns:

Type	Description
`ObsType`	tuple, containing two elements, the state representation and
`InfoType`	the log information at the initial state.
`tuple[ObsType, InfoType]`	if `.config.view_config["type"]` is set as "centralized",
`tuple[ObsType, InfoType]`	then the state representation is a `numpy.ndarray` and the log
`tuple[ObsType, InfoType]`	information is a `dict`. If there are no aircraft in the airspace
`tuple[ObsType, InfoType]`	at the initial state, the state is represented using a zero
`tuple[ObsType, InfoType]`	vector.
`tuple[ObsType, InfoType]`	if `.config.view_config["type"]` is set as "decentralized",
`tuple[ObsType, InfoType]`	then the state representation is a `dict` with each element
`tuple[ObsType, InfoType]`	specific to an aircraft (aircraft callsign `str` as the key and
`tuple[ObsType, InfoType]`	`numpy.ndarray as the corresponding value). The log information
`tuple[ObsType, InfoType]`	is a `dict` with each element specific to an aircraft (the key
`tuple[ObsType, InfoType]`	is the aircraft callsign `str` and the value is a `dict`). If
`tuple[ObsType, InfoType]`	there are no aircraft in the airspace at the initial state, the
`tuple[ObsType, InfoType]`	state and log dictionaries are empty.

`save_simulation_logs()`

Save the logs of the simulation.

Save the logs of the simulation based on the history of the events and aircraft trajectory in the simulation. The operation is based on the underlying save operation defined in simulator which saves the logs to disk as csv and parquet files. The logs are saved to the simulator's log directory.

The saved files can be analyzed and used to replay the simulation (example, replay via the HMI).

`send_actions_to_simulator(actions_st)`

Send the simulator action(s) to the simulator.

Parameters:

Name	Type	Description	Default
`actions_st`	`list[Action]`	stores the action of each aircraft to be sent to the simulator. each dict item has its key as an aircraft callsign and value as the simulator action for the corresponding aircraft.	required

`set_radar()`

Configure the radar for the simulator visualisation.

`set_render_mode(render_mode)`

Set the render mode of the simulator.

Parameters:

Name	Type	Description	Default
`render_mode`	`str or None`	the render mode to set. It can only be set to None or one of the following: 'human', 'rgb_array', 'file'.	required

`step(action)`

Move simulation forward one step.

Move the simulation forward one step, performing actions and compute reward/next observation.

Parameters:

Name	Type	Description	Default
`action`	`ActionType`	action(s) for the aircraft.	required

Returns:

Name	Type	Description
	`ObsType`	A tuple containing next state, reward, done, truncated, info
`Note`	`RewardType`	if the value of the "type" key in `state_repr` config is
	`DoneType`	"centralized", then next state is `numpy.ndarray`, reward is a
	`TruncatedType`	float, done is a bool, truncated is a bool and info is a dict.
	`InfoType`	Otherwise, if "decentralized", then each item in the returned
	`tuple[ObsType, RewardType, DoneType, TruncatedType, InfoType]`	tuple is a dict, with key-value pairs as an aircraft callsign and
	`tuple[ObsType, RewardType, DoneType, TruncatedType, InfoType]`	the corresponding value for the aircraft. For example, next state
	`tuple[ObsType, RewardType, DoneType, TruncatedType, InfoType]`	is a dict with each key-value pair as aircraft callsign and
	`tuple[ObsType, RewardType, DoneType, TruncatedType, InfoType]`	`numpy.ndarray`.

`update_ac_tracker_prev_step(tracked_data, exclude=None)`

Set previous step aircraft state tracker to the current data.

`update_selected_aircraft_prev_step(value)`

Set the list of selected aircraft's callsigns in the previous step

`SectorIEnv`

Bases: BaseEnv

gymnasium environment for the I sector airspace.

Artificially generated aircraft scenarios and a configurable I sector airspace, defined in the simulation framework.

Parameters:

Name	Type	Description	Default
`render_mode`	`str \| None`	the mode to visualize (render) the simulator. It can only be set to None or one of the following: 'human', 'rgb_array', 'file'. Defaults to `None`.	`None`
`config`	`EnvConfig \| None`	defines the configuration parameters for the gymnasium environment and the underlying simulator.	`None`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

Class method: Get the default config for an environment instance.

Defined in each child class that inherits this base class.

Parameters:

Name	Type	Description	Default
`cls`		the class	required
`view_type`	`ViewType \| str`	the type of agent view, centralized (single agent) or decentralized (multi-agent). Defaults to "centralized".	`CENTRALIZED`

Returns:

Type	Description
`EnvConfig`	dict, the default config.

`SectorXEnv`

Bases: BaseEnv

gymnasium environment for the X sector airspace.

Artificially generated aircraft scenarios and a configurable X sector airspace, defined in the simulation framework.

Parameters:

Name	Type	Description	Default
`render_mode`	`str \| None`	the mode to visualize (render) the simulator. It can only be set to None or one of the following: 'human', 'rgb_array', 'file'. Defaults to `None`.	`None`
`config`	`EnvConfig \| None`	defines the configuration parameters for the gymnasium environment and the underlying simulator.	`None`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

Class method: Get the default config for an environment instance.

Defined in each child class that inherits this base class.

Parameters:

Name	Type	Description	Default
`cls`		the class	required
`view_type`	`ViewType \| str`	the type of agent view, centralized (single agent) or decentralized (multi-agent). Defaults to "centralized".	`CENTRALIZED`

Returns:

Type	Description
`EnvConfig`	dict, the default config.

`SectorXPlusEnv`

Bases: BaseEnv

gymnasium environment for the X-plus sector airspace.

Artificially generated aircraft scenarios and a configurable X-plus sector airspace, defined in the simulation framework.

Parameters:

Name	Type	Description	Default
`render_mode`	`str \| None`	the mode to visualize (render) the simulator. It can only be set to None or one of the following: 'human', 'rgb_array', 'file'. Defaults to `None`.	`None`
`config`	`EnvConfig \| None`	defines the configuration parameters for the gymnasium environment and the underlying simulator.	`None`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

Class method: Get the default config for an environment instance.

Defined in each child class that inherits this base class.

Parameters:

Name	Type	Description	Default
`cls`		the class	required
`view_type`	`ViewType \| str`	the type of agent view, centralized (single agent) or decentralized (multi-agent). Defaults to "centralized".	`CENTRALIZED`

Returns:

Type	Description
`EnvConfig`	dict, the default config.

`SectorYEnv`

Bases: BaseEnv

gymnasium environment for the Y sector airspace.

Artificially generated aircraft scenarios and a configurable Y sector airspace, defined in the simulation framework.

Parameters:

Name	Type	Description	Default
`render_mode`	`str \| None`	the mode to visualize (render) the simulator. It can only be set to None or one of the following: 'human', 'rgb_array', 'file'. Defaults to `None`.	`None`
`config`	`EnvConfig \| None`	defines the configuration parameters for the gymnasium environment and the underlying simulator.	`None`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

Class method: Get the default config for an environment instance.

Defined in each child class that inherits this base class.

Parameters:

Name	Type	Description	Default
`cls`		the class	required
`view_type`	`ViewType \| str`	the type of agent view, centralized (single agent) or decentralized (multi-agent). Defaults to "centralized".	`CENTRALIZED`

Returns:

Type	Description
`EnvConfig`	dict, the default config.

`SpringfieldEnv`

Bases: BaseEnv

gymnasium environment for the Springfield airspace.

gym environment for the Springfield training sector/airspace, defined in simulation framework. Designed to simulate challenging air traffic control scenarios. In addition, the aircraft scenarios can be based on either real-world (historical) data or artificially generated. Based on the simulator.

Parameters:

Name	Type	Description	Default
`render_mode`	`str \| None`	the mode to visualize (render) the simulator. It can only be set to None or one of the following: 'human', 'rgb_array', 'file'. Defaults to `None`.	`None`
`config`	`EnvConfig \| None`	defines the configuration parameters for the gymnasium environment and the underlying simulator.	`None`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

Class method: Get the default config for an environment instance.

Defined in each child class that inherits this base class.

Parameters:

Name	Type	Description	Default
`cls`		the class	required
`view_type`	`ViewType \| str`	the type of agent view, centralized (single agent) or decentralized (multi-agent). Defaults to "centralized".	`CENTRALIZED`

Returns:

Type	Description
`EnvConfig`	dict, the default config.

Source code reference

Environments

BaseEnv

out_sector_control property writable

actions_gym_to_simulator(action)

actions_simulator_to_gym(actions_st)

check_pos_information(callsign, prev_position_status, prev_incomm_status, prev_outcomm_status, prev_incorrect_exit_position)

compute_reward(callsign, action)

compute_success_metric(callsign, previous_value)

debug_get_actions_for_aircraft(callsign)

debug_get_actions_history()

disable_auto_route_following()

enable_auto_route_following()

get_action_parser()

get_active_airspace_sector()

get_default_env_config(view_type=ViewType.CENTRALIZED) classmethod

get_forward_fixes_info()

get_manager()

get_radar_figure()

get_render_mode()

get_rollout_predictor()

get_simulator()

get_simulator_env()

get_tracked_aircraft_data(callsign=None, copy_data=False)

get_tracked_aircraft_data_previous(callsign=None, copy_data=False)

get_traffic_monitor()

render()

render_w_overlay_trajectory(traj_dict=None)

reset(*, seed=None, options=None)

save_simulation_logs()

send_actions_to_simulator(actions_st)

set_radar()

set_render_mode(render_mode)

step(action)

update_ac_tracker_prev_step(tracked_data, exclude=None)

update_selected_aircraft_prev_step(value)

SectorIEnv

get_default_env_config(view_type=ViewType.CENTRALIZED) classmethod

SectorXEnv

get_default_env_config(view_type=ViewType.CENTRALIZED) classmethod

SectorXPlusEnv

get_default_env_config(view_type=ViewType.CENTRALIZED) classmethod

SectorYEnv

get_default_env_config(view_type=ViewType.CENTRALIZED) classmethod

SpringfieldEnv

get_default_env_config(view_type=ViewType.CENTRALIZED) classmethod

get_default_config(env_name)

get_env_cls_and_config(env_name)

Actions

ACTION_NOOP = 0 module-attribute

NUM_NOOP_ACTIONS = 1 module-attribute

DEFAULT_RELATIVE_HEADING = 10 module-attribute

DEFAULT_RELATIVE_CLIMB_DESCENT = 10 module-attribute

DEFAULT_RELATIVE_SPEED = 10 module-attribute

DEFAULT_ROUTE_DIRECT = 1 module-attribute

registry_actions = ModuleRegistry() module-attribute

Rewards

registry_reward_fn = ModuleRegistry() module-attribute

State Representation

registry_repr = ModuleRegistry() module-attribute

Wrappers

Utilities

`BaseEnv`

`out_sector_control` `property` `writable`

`actions_gym_to_simulator(action)`

`actions_simulator_to_gym(actions_st)`

`check_pos_information(callsign, prev_position_status, prev_incomm_status, prev_outcomm_status, prev_incorrect_exit_position)`

`compute_reward(callsign, action)`

`compute_success_metric(callsign, previous_value)`

`debug_get_actions_for_aircraft(callsign)`

`debug_get_actions_history()`

`disable_auto_route_following()`

`enable_auto_route_following()`

`get_action_parser()`

`get_active_airspace_sector()`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

`get_forward_fixes_info()`

`get_manager()`

`get_radar_figure()`

`get_render_mode()`

`get_rollout_predictor()`

`get_simulator()`

`get_simulator_env()`

`get_tracked_aircraft_data(callsign=None, copy_data=False)`

`get_tracked_aircraft_data_previous(callsign=None, copy_data=False)`

`get_traffic_monitor()`

`render()`

`render_w_overlay_trajectory(traj_dict=None)`

`reset(*, seed=None, options=None)`

`save_simulation_logs()`

`send_actions_to_simulator(actions_st)`

`set_radar()`

`set_render_mode(render_mode)`

`step(action)`

`update_ac_tracker_prev_step(tracked_data, exclude=None)`

`update_selected_aircraft_prev_step(value)`

`SectorIEnv`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

`SectorXEnv`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

`SectorXPlusEnv`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

`SectorYEnv`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

`SpringfieldEnv`

`get_default_env_config(view_type=ViewType.CENTRALIZED)` `classmethod`

`get_default_config(env_name)`

`get_env_cls_and_config(env_name)`

`ACTION_NOOP = 0` `module-attribute`

`NUM_NOOP_ACTIONS = 1` `module-attribute`

`DEFAULT_RELATIVE_HEADING = 10` `module-attribute`

`DEFAULT_RELATIVE_CLIMB_DESCENT = 10` `module-attribute`

`DEFAULT_RELATIVE_SPEED = 10` `module-attribute`

`DEFAULT_ROUTE_DIRECT = 1` `module-attribute`

`registry_actions = ModuleRegistry()` `module-attribute`

`registry_reward_fn = ModuleRegistry()` `module-attribute`

`registry_repr = ModuleRegistry()` `module-attribute`