Environments API

Base Environment

UrbanMARL Environment Base Wrappers.

Provides TorchRL-compatible multi-agent environment wrappers for 3D urban UAV/MEC simulations supporting batched execution across CPU and GPU devices.

class urbanmarl.envs.base_env.UrbanEnvBase(*args, **kwargs)[source]

Bases: _EnvWrapper

Base TorchRL environment wrapper for UrbanMARL environments.

Manages multi-agent grouping, scenario initialization, batch environment map allocations, tensor specifications, and vectorized step/reset mechanics.

git_url

Repository URL for UrbanMARL.

Type:: str

libname

Package library identifier name.

Type:: str

scenario_name

Name identifier of the active scenario.

Type:: str

scenario

Active UrbanScenario instance.

Type:: UrbanScenario

num_envs

Number of parallel environments in the batch.

Type:: int

n_uavs

Number of UAV agents per environment.

Type:: int

n_ues

Number of User Equipment entities per environment.

Type:: int

max_steps

Maximum episode horizon step count.

Type:: int

group_map

Multi-agent grouping configuration dictionary.

Type:: dict

git_url: str = 'https://github.com/yemenlinux/vUrbanMARL.git'

libname: str = 'urbanmarl'

property lib: Returns the imported urbanmarl module package reference.

property available_envs: Lists available environment identifiers registered in the library.

__init__(device=None, batch_size=None, scenario='navigate', **kwargs)[source]

Initializes the UrbanEnvBase environment.

Parameters:

device (DEVICE_TYPING, optional) – Computation device (e.g. ‘cpu’, ‘cuda’).
batch_size (torch.Size | None, optional) – Tensor batch size of parallel envs.
scenario (str | UrbanScenario) – Scenario name string or UrbanScenario instance.
**kwargs – Additional scenario and environment configuration parameters.

Return type:

None

property agents: list[str]: List of all active agent identifiers across groups.

property n_agents: int: Total number of agents.

property agent_names_to_indices_map: dict[str, int]: Mapping from agent name to index position.

property agent_indices_to_names_map: dict[int, str]: Mapping from index position to agent name.

property agent_names: list[str]: List of agent name strings.

read_obs(observations)[source]

Formats and unsqueezes observation data matching batch size.

Parameters:: observations (torch.Tensor | dict) – Raw observation input.
Returns:: Unsandwiched batch observation structure.
Return type:: torch.Tensor | TensorDict

info(agent)[source]

Retrieves info dictionary for a specific agent name.

Parameters:: agent (str) – Agent identifier.
Returns:: Agent-specific info payload.
Return type:: dict

to(device)[source]

Moves environment tensors to specified target device.

Parameters:: device (DEVICE_TYPING) – Target device.
Returns:: Self reference after device migration.
Return type:: EnvBase

render(mode='rgb_array', **kwargs)[source]

Renders the environment using the active scenario renderer.

Parameters:

mode (str) – Rendering mode (‘rgb_array’ or ‘human’). Defaults to ‘rgb_array’.
**kwargs – Extra arguments passed to scenario.render().

Returns:

Rendered frame (np.ndarray if ‘rgb_array’) or Matplotlib figure (if ‘human’).

class urbanmarl.envs.base_env.UrbanEnv(*args, **kwargs)[source]

Bases: UrbanEnvBase

High-level multi-agent Urban MARL environment class.

Convenience wrapper over UrbanEnvBase that accepts num_envs integer batch sizing.

__init__(num_envs, continuous_actions, seed, device, scenario='default', **kwargs)[source]

Initializes an UrbanEnv instance.

Parameters:

num_envs (int) – Number of parallel environments in the batch.
continuous_actions (bool) – Whether actions are continuous vector spaces.
seed (Optional[int]) – Random seed.
device (torch.device) – PyTorch compute device.
scenario (str | UrbanScenario) – Scenario identifier or instance.
**kwargs – Extra environment parameters.

Return type:

None

3D Renderer

UrbanMARL 3D Environment Renderer.

Provides high-performance, vectorized 3D/2D visualization for urban multi-agent reinforcement learning environments including buildings, UAVs, ground UEs, base stations, and radio communication links.

class urbanmarl.envs.rendering.UrbanRenderConfig(figsize=(1280, 820), dpi=100, heatmap_color='gist_yarg', heatmap_alpha=0.7, building_color='#C0C0C0', building_alpha=0.2, uav_color='#FF4444', uav_marker='^', ue_color='#4444FF', ue_marker='.', base_station_color='#FF4444', base_station_marker='v', trajectory_color='#FFA500', show_trajectory=True, trajectory_length=100, link_los_color='#00FF00', link_nlos_color='#FF0000', camera_elev=45.0, camera_azim=-120.0, show_labels=True, show_telemetry_hud=True, hud_fontsize=8, show_rem_contours=False)[source]

Bases: object

Configuration settings for urban environment rendering.

Parameters:

figsize (Tuple[int, int])
dpi (int)
heatmap_color (str)
heatmap_alpha (float)
building_color (str)
building_alpha (float)
uav_color (str)
uav_marker (str)
ue_color (str)
ue_marker (str)
base_station_color (str)
base_station_marker (str)
trajectory_color (str)
show_trajectory (bool)
trajectory_length (int)
link_los_color (str)
link_nlos_color (str)
camera_elev (float)
camera_azim (float)
show_labels (bool)
show_telemetry_hud (bool)
hud_fontsize (int)
show_rem_contours (bool)

figsize

Figure dimensions in pixels (width, height).

Type:: Tuple[int, int]

dpi

Dots per inch for figure rendering.

Type:: int

heatmap_color

Matplotlib colormap name for 2D top-view heatmap.

Type:: str

heatmap_alpha

Transparency alpha for heatmap.

Type:: float

building_color

Hex color code for building cuboids.

Type:: str

building_alpha

Transparency alpha for buildings.

Type:: float

uav_color

Hex color code for UAV markers and indicators.

Type:: str

uav_marker

Matplotlib marker style for UAVs.

Type:: str

ue_color

Hex color code for User Equipment (UE) markers.

Type:: str

ue_marker

Matplotlib marker style for UEs.

Type:: str

base_station_color

Hex color code for Base Station (BS) markers.

Type:: str

base_station_marker

Matplotlib marker style for Base Stations.

Type:: str

trajectory_color

Hex color code for UAV flight path trajectories.

Type:: str

show_trajectory

Whether to display historical trajectories.

Type:: bool

trajectory_length

Maximum number of historical points per trajectory.

Type:: int

link_los_color

Line color for Line-of-Sight (LoS) links.

Type:: str

link_nlos_color

Line color for Non-Line-of-Sight (NLoS) links.

Type:: str

camera_elev

Initial 3D camera elevation angle in degrees.

Type:: float

camera_azim

Initial 3D camera azimuth angle in degrees.

Type:: float

show_labels

Whether to display text labels on entities.

Type:: bool

figsize: Tuple[int, int] = (1280, 820)

dpi: int = 100

heatmap_color: str = 'gist_yarg'

heatmap_alpha: float = 0.7

building_color: str = '#C0C0C0'

building_alpha: float = 0.2

uav_color: str = '#FF4444'

uav_marker: str = '^'

ue_color: str = '#4444FF'

ue_marker: str = '.'

base_station_color: str = '#FF4444'

base_station_marker: str = 'v'

trajectory_color: str = '#FFA500'

show_trajectory: bool = True

trajectory_length: int = 100

link_los_color: str = '#00FF00'

link_nlos_color: str = '#FF0000'

camera_elev: float = 45.0

camera_azim: float = -120.0

show_labels: bool = True

show_telemetry_hud: bool = True

hud_fontsize: int = 8

show_rem_contours: bool = False

class urbanmarl.envs.rendering.Urban3DRenderer(config=None)[source]

Bases: object

Vectorized 3D & 2D renderer for UrbanMARL environments.

Renders: - 3D buildings as cuboid collections. - UAVs as 3D/2D flying markers with historical flight trajectories. - Ground User Equipments (UEs) on top-view and 3D maps. - Base Stations (BS) with vertical ground-projection indicators. - Vectorized communication links classified by LoS/NLoS state.

Parameters:: config (UrbanRenderConfig | None)

config

Renderer configuration parameters.

Type:: UrbanRenderConfig

__init__(config=None)[source]

Initializes the Urban3DRenderer.

Parameters:: config (Optional[UrbanRenderConfig]) – Rendering configuration. If None, uses default settings.
Return type:: None

render(state, mode='rgb_array')[source]

Renders the urban environment.

Parameters:

state (Dict) – Environment state payload containing: - ‘volume_size’: [x, y, z] environment bounds. - ‘buildings’: list of building dicts. - ‘uav_positions’: (N, 3) UAV locations. - ‘ue_positions’: (M, 3) UE locations. - ‘base_station_positions’: (K, 3) BS locations. - ‘links’: optional list of link dicts. - ‘heatmap’: optional 2D tensor/array for heatmap overlay. - ‘collisions’: optional array of collision points.
mode (str) – Rendering mode: ‘rgb_array’ returns (H, W, 3) uint8 image array, ‘human’ returns the Matplotlib figure handle. Defaults to ‘rgb_array’.

Returns:

RGB image numpy array if mode==’rgb_array’,: or matplotlib Figure handle if mode==’human’.

Return type:

Optional[Union[np.ndarray, object]]

close()[source]

Cleans up renderer resources and closes figures.

Return type:: None

PettingZoo Wrapper

UrbanMARL PettingZoo ParallelEnv Standardization Wrapper.

Provides a standard PettingZoo ParallelEnv interface for UrbanMARL:

Fully compatible with CleanRL, Ray RLlib, Stable-Baselines3 (via shimmy/SuperSuit), and standard MARL evaluation pipelines.
Supports continuous 3D velocity actions and localized agent observation spaces.

class urbanmarl.envs.pettingzoo_wrapper.UrbanPettingZooEnv(scenario='uav_navigation', render_mode='rgb_array', **env_kwargs)[source]

Bases: object

PettingZoo ParallelEnv wrapper for UrbanMARL environments.

Wraps a single-environment UrbanEnv instance into standard PettingZoo format.

Parameters:

scenario (str)
render_mode (str | None)

metadata = {'name': 'urbanmarl_v1', 'render_modes': ['rgb_array', 'human']}

__init__(scenario='uav_navigation', render_mode='rgb_array', **env_kwargs)[source]

Initializes PettingZoo wrapper.

Parameters:

scenario (str) – UrbanMARL scenario name. Defaults to ‘uav_navigation’.
render_mode (Optional[str]) – Rendering mode (‘rgb_array’ or ‘human’).
**env_kwargs – Arguments passed directly to UrbanEnv.

Return type:

None

observation_space(agent)[source]

Returns the observation space for an agent.

Parameters:: agent (str)
Return type:: Space

action_space(agent)[source]

Returns the action space for an agent.

Parameters:: agent (str)
Return type:: Space

reset(seed=None, options=None)[source]

Resets the environment.

Parameters:

seed (Optional[int]) – Random seed.
options (Optional[dict]) – Configuration options.

Returns:

(observations, infos).

Return type:

Tuple[Dict[str, np.ndarray], Dict[str, Any]]

step(actions)[source]

Steps all agents in the environment.

Parameters:: actions (Dict[str, np.ndarray]) – Dictionary of agent actions.
Returns:: Tuple of (observations, rewards, terminations, truncations, infos).
Return type:: Tuple[Dict[str, ndarray], Dict[str, float], Dict[str, bool], Dict[str, bool], Dict[str, Any]]

render()[source]

Renders environment frame.

Return type:: ndarray | None

close()[source]

Closes environment renderer.

Return type:: None