Models API

Vectorized Urban Map Generator

class urbanmarl.models.urban_map.VectorizedUrbanMap(batch_size, volume_size, device, map_margin=5)[source]

Bases: object

Tensor-accelerated ITU-R P.1410 procedural map generator and LoS engine.

Handles procedural 3D urban heightmap generation, line-of-sight (LoS) ray tracing, collision checking, and agent coordinate transformations across parallel environments.

Parameters:

batch_size (int)
volume_size (tuple)
device (device)
map_margin (int)

batch_size

Number of parallel environment instances.

Type:: int

volume_size

3D volume dimensions (sim_x, sim_y, sim_z).

Type:: tuple

device

PyTorch compute device.

Type:: torch.device

map_margin

Margin boundary in meters for map edge buildings.

Type:: int

height_maps

Tensor heightmaps of shape (batch_size, sim_x, sim_y).

Type:: torch.Tensor

__init__(batch_size, volume_size, device, map_margin=5)[source]

Initializes the VectorizedUrbanMap generator.

Parameters:

batch_size (int) – Number of parallel environment instances.
volume_size (tuple) – Volume dimensions (X, Y, Z).
device (torch.device) – Compute device for tensor operations.
map_margin (int) – Margin buffer from volume borders. Defaults to 5.

Return type:

None

get_info_labels()[source]

Returns feature metadata column names for procedural parameters.

Returns:: List of parameter names (‘alpha’, ‘beta’, etc.).
Return type:: list[str]

create_building_faces(x, y, z, w, l, h)[source]

Constructs 3D polygon face vertices for building cuboids (Fully Vectorized).

Parameters:

x (ndarray) – np.ndarray of base coordinates.
y (ndarray) – np.ndarray of base coordinates.
z (ndarray) – np.ndarray of base coordinates.
w (ndarray) – np.ndarray of building dimensions.
l (ndarray) – np.ndarray of building dimensions.
h (ndarray) – np.ndarray of building dimensions.

Returns:

Shape (N*5, 4, 3) defining all cuboid faces for all buildings.

Return type:

np.ndarray

reset(return_urban_info=False)[source]

Resets the map environment by regenerating the height maps with new procedural parameters. Optionally returns the generated map information for analysis or observation purposes.

Parameters:: return_urban_info (bool)

reset_at(env_idx, return_urban_info=False)[source]

Parameters:

env_idx (int)
return_urban_info (bool)

get_building_polygon(urban_idx, face_color='#696969', alpha=0.3)[source]

Creates a Poly3DCollection for 3D plotting of building faces. :param urban_idx: Index of the urban environment. :type urban_idx: int :param face_color: Color of the building faces. :type face_color: str :param alpha: Transparency level of the building faces. :type alpha: float

Parameters:

urban_idx (int)
face_color (str)
alpha (float)

generate_batch_maps(alpha=None, beta=None, gamma=None)[source]

Procedurally populates building heights based on structural distribution properties. Executes on CPU/Numpy for procedural layouts, then uploads directly to device buffers.

Parameters:

alpha (Tensor)
beta (Tensor)
gamma (Tensor)

check_los_batch(p1, p2, n_steps=20, max_step_length=None)[source]

Computes line-of-sight status via dense vector projection array checking. p1: shape (batch_size, n_agents, 3) p2: shape (batch_size, n_targets, 3) max_step_length: Optional float. If provided, dynamically scales n_steps based on max ray distance. Returns: boolean tensor shape (batch_size, n_agents, n_targets)

Parameters:

p1 (Tensor)
p2 (Tensor)
n_steps (int)
max_step_length (float | None)

Return type:

Tensor

check_collision_batch(p1, p2, n_steps=20, max_step_length=None)[source]

Computes collision status via dense vector projection array checking. p1: shape (batch_size, n_agents, 3) previous positions p2: shape (batch_size, n_agents, 3) current positions Returns: boolean tensor shape (batch_size, n_agents, 1) indicating collision status

Parameters:

p1 (Tensor)
p2 (Tensor)
n_steps (int)
max_step_length (float | None)

Return type:

Tensor

sort()[source]

gen_pos(num_pos, min_z=None, max_z=None, batch_idx=None, outdoor=False, normalized=False)[source]

Generates positions for agents, optionally ensuring they are outdoors.

Parameters:

num_pos (int)
min_z (float)
max_z (float)
batch_idx (int)
outdoor (bool)
normalized (bool)

Return type:

Tensor

gen_outdoor_pos(num_pos, min_z=0.0, max_z=0.0, batch_idx=None)[source]

Generate outdoor positions

Parameters:

num_pos (int)
min_z (float)
max_z (float)
batch_idx (int)

Return type:

Tensor

norm_pos(positions, min_z=None, max_z=None)[source]

Normalizes positions to [0,1] range based on the map dimensions.

Parameters:

positions (Tensor)
min_z (float)
max_z (float)

Return type:

Tensor

denorm_pos(positions, min_z=None, max_z=None)[source]

Denormalizes positions from [0,1] back to actual coordinate space.

Parameters:

positions (Tensor)
min_z (float)
max_z (float)

Return type:

Tensor

pos_to_grid(positions)[source]

Converts physical positions to grid indices for height map lookups.

Parameters:: positions (Tensor)
Return type:: Tensor

plot(batch_idx=0, title='Procedural Urban Map Height Profile', cmap='viridis', axes=None)[source]

Parameters:

batch_idx (int)
title (str)
cmap (str)

seed(seed=None)[source]: Sets the seed for the environment :param seed: Seed for the environment. Defaults to None. :type seed: int, optional

to(device)[source]

Casts the scenario to a different device.

Parameters:: device (Union[str, int, torch.device]) – the device to cast to

Radio Channel Model

UrbanMARL Radio Channel Model.

Vectorized mmWave radio channel propagation model calculating Friis path loss, LoS/NLoS attenuation exponent shifts, interference, and Shannon channel capacity.

class urbanmarl.models.channel.VectorizedChannelModel(config, device)[source]

Bases: object

Computes batched path loss, received power, interference, and data rates.

Parameters:

config (dict)
device (device)

device

Compute device for PyTorch tensor calculations.

Type:: torch.device

freq_ghz

Carrier frequency in Gigahertz (e.g. 29.0 GHz mmWave).

Type:: float

bandwidth

Transmit channel bandwidth in Hertz.

Type:: float

noise_figure_db

Receiver noise figure in decibels.

Type:: float

noise_power

Receiver thermal noise power in Watts.

Type:: float

__init__(config, device)[source]

Initializes the VectorizedChannelModel.

Parameters:

config (dict) – Channel configuration dictionary containing optional keys: - ‘frequency_ghz’: carrier frequency in GHz (default: 29.0). - ‘g2a_bandwidth’: channel bandwidth in Hz (default: 10e6). - ‘noise_figure_db’: noise figure in dB (default: 7.0).
device (torch.device) – Compute device.

Return type:

None

compute_data_rates(tx_pos, rx_pos, tx_power, los_mask)[source]

Calculates achievable transmission data rates (bps) using Shannon capacity.

Parameters:

tx_pos (torch.Tensor) – Transmitter positions (UEs) of shape (B, M, 3).
rx_pos (torch.Tensor) – Receiver positions (UAVs) of shape (B, N, 3).
tx_power (torch.Tensor) – Transmission power (Watts) of shape (B, M).
los_mask (torch.Tensor) – Line-of-sight boolean tensor of shape (B, N, M).

Returns:

Achievable channel capacity data rates in bps of shape (B, N, M).

Return type:

torch.Tensor

MEC Queue Model

UrbanMARL Mobile Edge Computing (MEC) M/M/c Queue Model.

Pure PyTorch implementation of M/M/c queuing theory calculating server utilization, queue lengths, waiting times, and total system processing delay across parallel environments.

class urbanmarl.models.mec_queue.VectorizedMECQueue(device, max_cores=64)[source]

Bases: object

PyTorch tensor M/M/c queuing model for edge servers.

Parameters:

device (device)
max_cores (int)

device

Compute device.

Type:: torch.device

max_cores

Maximum server processing core capacity.

Type:: int

log_fact

Precomputed log-factorial array for numerical stability.

Type:: torch.Tensor

__init__(device, max_cores=64)[source]

Initializes the VectorizedMECQueue model.

Parameters:

device (torch.device) – Compute device for PyTorch operations.
max_cores (int) – Maximum core count upper bound (default: 64).

Return type:

None

compute_delays(arrival_rates, service_rates, num_cores)[source]

Computes M/M/c queuing delays and utilization metrics for a batch of UAVs.

Parameters:

arrival_rates (torch.Tensor) – Task arrival rates (lambda) of shape (B, N).
service_rates (torch.Tensor) – Service rates per core (mu) of shape (B, N).
num_cores (torch.Tensor) – Number of allocated server cores (c) of shape (B, N).

Returns:

Dictionary containing tensors for:

’utilization’: server traffic intensity rho of shape (B, N).
’avg_queue_length’: expected number of queued tasks of shape (B, N).
’avg_waiting_time’: expected queue waiting time in seconds of shape (B, N).
’avg_system_time’: total system response time (wait + service) of shape (B, N).

Return type:

dict[str, torch.Tensor]

DTLCM Offloading Assignment

UrbanMARL Dynamic Distance-Task-Load Capacity Matching (DTLCM).

Provides continuous tensor heuristic matching for UAV-MEC task offloading assignments.

urbanmarl.models.dtlcm.compute_batched_dtlcm_assignment(uav_pos, ue_pos, uav_caps, uav_loads, task_workloads, distance_weight=0.7)[source]

Executes batched heuristic DTLCM assignment for task offloading.

Parameters:

uav_pos (torch.Tensor) – UAV 3D positions of shape (B, N, 3).
ue_pos (torch.Tensor) – UE 3D positions of shape (B, M, 3).
uav_caps (torch.Tensor) – UAV compute capacities of shape (B, N).
uav_loads (torch.Tensor) – Current UAV load levels of shape (B, N).
task_workloads (torch.Tensor) – Offloaded task workloads of shape (B, M).
distance_weight (float) – Weight assigned to spatial distance score (default: 0.7).

Returns:

Long tensor of assigned UAV indices per UE of shape (B, M).

Return type:

torch.Tensor

Network Digital Twin (NDT) & REM

UrbanMARL Network Digital Twin (NDT) Architecture & Telemetry Model.

Provides a unified, 4-layer synchronized digital twin model for 6G multi-UAV assisted Mobile Edge Computing (MEC) networks: 1. Geospatial & Structural Twin: 3D urban terrain, ITU-R P.1410 parameters, buildings. 2. Radio Environment Map (REM) Twin: Spatial SINR coverage, LoS/NLoS paths, channel capacity. 3. Computational & Queuing Twin: M/M/c server utilization, queue lengths, task latency. 4. Aerial Mobility & Energy Twin: UAV kinematics, battery state, aerodynamic energy, sojourn time.

Includes vectorized Radio Environment Map (REM) generators, live telemetry extraction, and JSON-compliant serialization for 3D digital twin visualization engines.

class urbanmarl.models.digital_twin.GeospatialTwinState(volume_size, alpha, beta, gamma, e_param, n_buildings, building_width, street_width, building_count)[source]

Bases: object

Geospatial and structural digital twin layer state.

Parameters:

volume_size (List[float])
alpha (float)
beta (float)
gamma (float)
e_param (float)
n_buildings (int)
building_width (float)
street_width (float)
building_count (int)

volume_size: List[float]

alpha: float

beta: float

gamma: float

e_param: float

n_buildings: int

building_width: float

street_width: float

building_count: int

class urbanmarl.models.digital_twin.REMTwinState(frequency_ghz, bandwidth_hz, coverage_ratio, mean_sinr_db, los_link_count, nlos_link_count, mean_data_rate_mbps)[source]

Bases: object

Radio Environment Map (REM) and wireless propagation digital twin state.

Parameters:

frequency_ghz (float)
bandwidth_hz (float)
coverage_ratio (float)
mean_sinr_db (float)
los_link_count (int)
nlos_link_count (int)
mean_data_rate_mbps (float)

frequency_ghz: float

bandwidth_hz: float

coverage_ratio: float

mean_sinr_db: float

los_link_count: int

nlos_link_count: int

mean_data_rate_mbps: float

class urbanmarl.models.digital_twin.ComputeQueuingTwinState(mean_utilization, max_utilization, mean_queue_length, mean_waiting_time_ms, mean_system_time_ms, total_completed_tasks, total_dropped_tasks)[source]

Bases: object

MEC computation and queuing dynamics digital twin state.

Parameters:

mean_utilization (float)
max_utilization (float)
mean_queue_length (float)
mean_waiting_time_ms (float)
mean_system_time_ms (float)
total_completed_tasks (int)
total_dropped_tasks (int)

mean_utilization: float

max_utilization: float

mean_queue_length: float

mean_waiting_time_ms: float

mean_system_time_ms: float

total_completed_tasks: int

total_dropped_tasks: int

class urbanmarl.models.digital_twin.AerialMobilityTwinState(n_uavs, n_ues, mean_uav_altitude, mean_uav_speed, mean_battery_pct, mean_propulsion_power_w, mean_sojourn_time_steps, collision_count)[source]

Bases: object

UAV swarm kinematics, energy, and sojourn coverage digital twin state.

Parameters:

n_uavs (int)
n_ues (int)
mean_uav_altitude (float)
mean_uav_speed (float)
mean_battery_pct (float)
mean_propulsion_power_w (float)
mean_sojourn_time_steps (float)
collision_count (int)

n_uavs: int

n_ues: int

mean_uav_altitude: float

mean_uav_speed: float

mean_battery_pct: float

mean_propulsion_power_w: float

mean_sojourn_time_steps: float

collision_count: int

class urbanmarl.models.digital_twin.NDTTelemetryFrame(frame_id, timestamp_s, geospatial, rem, compute, mobility, uav_positions, ue_positions, uav_telemetry, active_links)[source]

Bases: object

Unified Network Digital Twin (NDT) telemetry snapshot for a single step.

Parameters:

frame_id (int)
timestamp_s (float)
geospatial (GeospatialTwinState)
rem (REMTwinState)
compute (ComputeQueuingTwinState)
mobility (AerialMobilityTwinState)
uav_positions (List[List[float]])
ue_positions (List[List[float]])
uav_telemetry (List[Dict[str, Any]])
active_links (List[Dict[str, Any]])

frame_id: int

timestamp_s: float

geospatial: GeospatialTwinState

rem: REMTwinState

compute: ComputeQueuingTwinState

mobility: AerialMobilityTwinState

uav_positions: List[List[float]]

ue_positions: List[List[float]]

uav_telemetry: List[Dict[str, Any]]

active_links: List[Dict[str, Any]]

to_dict()[source]

Converts telemetry frame into standard Python dictionary.

Return type:: Dict[str, Any]

to_json(indent=2)[source]

Serializes telemetry frame into JSON string.

Parameters:: indent (int | None)
Return type:: str

class urbanmarl.models.digital_twin.RadioEnvironmentMap(volume_size, grid_resolution=50, frequency_ghz=29.0, bandwidth_hz=10000000.0, noise_figure_db=7.0, sinr_threshold_db=0.0, device='cpu')[source]

Bases: object

Vectorized 2D/3D Radio Environment Map (REM) generator.

Computes spatial received signal power, interference, and Signal-to-Interference-plus-Noise Ratio (SINR) across a uniform spatial evaluation grid over the urban volume.

Parameters:

volume_size (Tuple[float, float, float])
grid_resolution (int)
frequency_ghz (float)
bandwidth_hz (float)
noise_figure_db (float)
sinr_threshold_db (float)
device (device | str)

__init__(volume_size, grid_resolution=50, frequency_ghz=29.0, bandwidth_hz=10000000.0, noise_figure_db=7.0, sinr_threshold_db=0.0, device='cpu')[source]

Initializes the RadioEnvironmentMap generator.

Parameters:

volume_size (Tuple[float, float, float]) – Urban dimensions (sim_x, sim_y, sim_z).
grid_resolution (int) – Spatial grid points along each horizontal axis. Defaults to 50.
frequency_ghz (float) – Carrier frequency in GHz. Defaults to 29.0.
bandwidth_hz (float) – Channel bandwidth in Hz. Defaults to 10e6.
noise_figure_db (float) – Receiver noise figure in dB. Defaults to 7.0.
sinr_threshold_db (float) – Minimum SINR in dB for valid coverage. Defaults to 0.0.
device (Union[torch.device, str]) – PyTorch compute device.

Return type:

None

compute_rem(uav_positions, tx_power=2.0, urban_map=None, env_idx=0)[source]

Computes spatial SINR and coverage ratio for active UAV positions.

Parameters:

uav_positions (torch.Tensor) – UAV 3D coordinates of shape (N, 3) or (B, N, 3).
tx_power (float) – Transmit power per UAV in Watts. Defaults to 2.0.
urban_map (Any | None) – Optional VectorizedUrbanMap instance for LoS ray-casting.
env_idx (int) – Batch index if uav_positions has batch dimension.

Returns:

‘sinr_grid’: 2D tensor of shape (grid_res, grid_res) in dB.
’coverage_mask’: 2D boolean tensor indicating SINR >= threshold.
’coverage_ratio’: Float percentage in [0.0, 1.0].
’mean_sinr_db’: Average SINR across all grid points in dB.

Return type:

Dict[str, Union[torch.Tensor, float]]

class urbanmarl.models.digital_twin.NetworkDigitalTwin(volume_size=(500.0, 500.0, 200.0), frequency_ghz=29.0, bandwidth_hz=10000000.0, noise_figure_db=7.0, rem_resolution=40, device='cpu')[source]

Bases: object

Central Network Digital Twin (NDT) manager for UrbanMARL simulations.

Synchronizes physical, wireless, computing, and mobility layers and extracts structured telemetry frames and serialization exports.

Parameters:

volume_size (Tuple[float, float, float])
frequency_ghz (float)
bandwidth_hz (float)
noise_figure_db (float)
rem_resolution (int)
device (device | str)

__init__(volume_size=(500.0, 500.0, 200.0), frequency_ghz=29.0, bandwidth_hz=10000000.0, noise_figure_db=7.0, rem_resolution=40, device='cpu')[source]

Initializes the NetworkDigitalTwin manager.

Parameters:

volume_size (Tuple[float, float, float]) – 3D urban simulation bounds.
frequency_ghz (float) – mmWave carrier frequency.
bandwidth_hz (float) – Channel bandwidth.
noise_figure_db (float) – Receiver noise figure.
rem_resolution (int) – Spatial grid resolution for Radio Environment Maps.
device (Union[torch.device, str]) – Compute device.

Return type:

None

capture_frame(env, env_idx=0, step=None, compute_rem_heatmap=False)[source]

Captures a complete digital twin telemetry frame from an active UrbanEnv.

Parameters:

env (Any) – UrbanEnv environment instance.
env_idx (int) – Environment batch index to monitor. Defaults to 0.
step (Optional[int]) – Current episode horizon step index.
compute_rem_heatmap (bool) – Whether to calculate full spatial REM SINR grid.

Returns:

Structured telemetry snapshot.

Return type:

NDTTelemetryFrame

export_telemetry_json(frame, filepath=None)[source]

Exports a single telemetry frame to JSON string or file.

Parameters:

frame (NDTTelemetryFrame) – Telemetry snapshot.
filepath (Optional[str]) – Target file path to write to.

Returns:

Serialized JSON payload string.

Return type:

str

export_telemetry_history(filepath=None)[source]

Exports all recorded telemetry frames in chronological order.

Parameters:: filepath (Optional[str]) – Target file path for JSON array.
Returns:: List of dictionary telemetry snapshots.
Return type:: List[Dict[str, Any]]

clear_history()[source]

Clears recorded frame history.

Return type:: None

Vectorized Ground User Mobility

UrbanMARL Vectorized Ground User (UE) Mobility Engine.

Provides GPU-accelerated, pure PyTorch mobility models for dynamic ground users:

Street-Constrained Manhattan Mobility: Constrains user motion to street corridors between ITU-R P.1410 building footprints.
Random Waypoint (RWP) & Gauss-Markov Mobility: Smooth continuous velocity and direction updates with boundary reflection.
Dynamic Hotspot & Crowd Migration Mobility: Models temporal crowd clustering around spatially drifting hotspot centers.

class urbanmarl.models.mobility.VectorizedUserMobility(volume_size=(500.0, 500.0, 200.0), model_type='manhattan', speed_min=0.5, speed_max=3.0, alpha_memory=0.75, device='cpu')[source]

Bases: object

Tensor-accelerated user mobility simulation engine.

Parameters:

volume_size (Tuple[float, float, float])
model_type (str)
speed_min (float)
speed_max (float)
alpha_memory (float)
device (device | str)

volume_size

Urban dimensions (sim_x, sim_y, sim_z).

Type:: Tuple[float, float, float]

device

PyTorch compute device.

Type:: torch.device

model_type

Mobility model identifier (‘manhattan’, ‘rwp’, ‘gauss_markov’, ‘hotspot’).

Type:: str

speed_min

Minimum user speed in m/s. Defaults to 0.5 (pedestrian).

Type:: float

speed_max

Maximum user speed in m/s. Defaults to 3.0 (brisk walk/runner).

Type:: float

__init__(volume_size=(500.0, 500.0, 200.0), model_type='manhattan', speed_min=0.5, speed_max=3.0, alpha_memory=0.75, device='cpu')[source]

Initializes the VectorizedUserMobility engine.

Parameters:

volume_size (Tuple[float, float, float]) – Urban simulation boundary dimensions.
model_type (str) – Mobility algorithm name (‘manhattan’, ‘rwp’, ‘gauss_markov’, ‘hotspot’).
speed_min (float) – Minimum speed bound in m/s. Defaults to 0.5.
speed_max (float) – Maximum speed bound in m/s. Defaults to 3.0.
alpha_memory (float) – Gauss-Markov memory coefficient in [0, 1]. Defaults to 0.75.
device (Union[torch.device, str]) – PyTorch compute device.

Return type:

None

initialize_velocities(batch_size, n_ues)[source]

Initializes random 2D ground velocities for UEs.

Parameters:

batch_size (int) – Number of parallel environments.
n_ues (int) – Number of ground UEs per environment.

Returns:

Initial velocity tensor of shape (B, M, 3) with vz=0.

Return type:

torch.Tensor

initialize_hotspots(batch_size, num_hotspots=2)[source]

Initializes spatial hotspot cluster centers and drift velocities.

Parameters:

batch_size (int) – Parallel environment batch count.
num_hotspots (int) – Number of simultaneous crowd hotspots. Defaults to 2.

Return type:

None

step(ue_pos, ue_vel, dt=1.0, urban_map=None)[source]

Steps ground user positions and updates velocities.

Parameters:

ue_pos (torch.Tensor) – Current UE positions of shape (B, M, 3).
ue_vel (torch.Tensor) – Current UE velocities of shape (B, M, 3).
dt (float) – Simulation time step duration in seconds. Defaults to 1.0.
urban_map (Any | None) – Optional VectorizedUrbanMap instance for street boundary collision.

Returns:

Updated (new_positions, new_velocities).

Return type:

Tuple[torch.Tensor, torch.Tensor]

Vectorized LiDAR Proximity Rangefinder

UrbanMARL Vectorized LiDAR Rangefinder Sensor Model.

Provides GPU-accelerated, pure PyTorch ray-marching LiDAR simulations for UAVs: - Casts radial horizontal rays in 360-degree azimuth around each UAV. - Samples 3D building heightmaps along ray trajectories. - Detects distance to nearest obstacle building face. - Outputs normalized proximity vectors for collision-free decentralized POMDP navigation.

class urbanmarl.models.lidar.VectorizedLiDAR(num_beams=8, max_range=60.0, n_steps=15, device='cpu')[source]

Bases: object

Vectorized 3D LiDAR proximity rangefinder.

Simulates radial rangefinder beams around each UAV to detect building facades.

Parameters:

num_beams (int)
max_range (float)
n_steps (int)
device (device | str)

__init__(num_beams=8, max_range=60.0, n_steps=15, device='cpu')[source]

Initializes the VectorizedLiDAR sensor.

Parameters:

num_beams (int) – Number of radial azimuth beams (e.g., 8 or 16). Defaults to 8.
max_range (float) – Maximum detection range in meters. Defaults to 60.0.
n_steps (int) – Number of ray-marching sampling intervals along each beam. Defaults to 15.
device (Union[torch.device, str]) – PyTorch compute device.

Return type:

None

scan(uav_positions, urban_map)[source]

Performs ray-marching LiDAR scans for all UAVs in parallel.

Parameters:

uav_positions (torch.Tensor) – UAV 3D coordinates of shape (B, N, 3).
urban_map (Any) – VectorizedUrbanMap instance containing 3D heightmaps.

Returns:

Normalized distance readings of shape (B, N, num_beams).: Values are in [0.0, 1.0], where 1.0 represents clear/max range, and values approaching 0.0 indicate proximity to an obstacle.

Return type:

torch.Tensor

High-Fidelity Aerodynamics

UrbanMARL High-Fidelity UAV Aerodynamic Propulsion Power Model.

Implements the rotary-wing UAV flight power consumption model from: Zeng, Zhang, and Lim, “Wireless communications with unmanned aerial vehicles: driving forces, key challenges, and options,” IEEE Wireless Communications, 2016. And: Zeng and Zhang, “Energy-efficient UAV communication with trajectory optimization,” IEEE Transactions on Wireless Communications, 2017.

Vectorized PyTorch implementation calculating instantaneous blade profile power, induced power, parasite drag power, and vertical climb/descend power.

class urbanmarl.models.aerodynamics.VectorizedAerodynamics(p0=79.86, pi=88.63, u_tip=120.0, v0=4.03, d0=0.6, rho=1.225, solidity=0.05, rotor_area=0.503, mass_kg=2.0, device='cpu')[source]

Bases: object

Calculates instantaneous aerodynamic power consumption for rotary-wing UAVs.

Parameters:

p0 (float)
pi (float)
u_tip (float)
v0 (float)
d0 (float)
rho (float)
solidity (float)
rotor_area (float)
mass_kg (float)
device (device | str)

p0

Blade profile power in hover (Watts).

Type:: float

pi

Induced power in hover (Watts).

Type:: float

u_tip

Tip speed of the rotor blade (m/s).

Type:: float

v0

Mean rotor induced velocity in hover (m/s).

Type:: float

d0

Fuselage drag ratio.

Type:: float

rho

Air density (kg/m^3).

Type:: float

s

Rotor solidity.

Type:: float

rotor_area

Rotor disc area (m^2).

Type:: float

mass_kg

UAV gross mass (kg).

Type:: float

__init__(p0=79.86, pi=88.63, u_tip=120.0, v0=4.03, d0=0.6, rho=1.225, solidity=0.05, rotor_area=0.503, mass_kg=2.0, device='cpu')[source]

Initializes aerodynamic parameters.

Parameters:

p0 (float) – Blade profile power. Defaults to 79.86 W.
pi (float) – Induced power. Defaults to 88.63 W.
u_tip (float) – Rotor tip speed in m/s. Defaults to 120.0.
v0 (float) – Mean induced velocity in m/s. Defaults to 4.03.
d0 (float) – Fuselage drag ratio. Defaults to 0.6.
rho (float) – Air density in kg/m^3. Defaults to 1.225.
solidity (float) – Rotor solidity. Defaults to 0.05.
rotor_area (float) – Rotor disc area in m^2. Defaults to 0.503.
mass_kg (float) – UAV gross mass in kg. Defaults to 2.0.
device (torch.device) – PyTorch compute device.

Return type:

None

compute_propulsion_power(velocity)[source]

Computes instantaneous aerodynamic propulsion power in Watts.

Parameters:: velocity (torch.Tensor) – UAV 3D velocity vectors (…, 3) in m/s.
Returns:: Power dissipation tensor in Watts matching batch shapes (…, 1).
Return type:: torch.Tensor

Advanced 3D Directional Channel

UrbanMARL Advanced 3D mmWave Channel Model.

Implements 3GPP TR 38.901 compliant wireless propagation modeling:

3D Directional Antenna Radiation Patterns: - Elevation beam attenuation: A_V(theta) = -min(12 * ((theta - theta_tilt) / theta_3dB)^2, SLA_V) - Azimuth beam attenuation: A_H(phi) = -min(12 * (phi / phi_3dB)^2, A_max) - Combined 3D antenna gain: G(theta, phi) = G_max - min(-(A_V + A_H), A_max)
Elevation-Dependent Rician / Rayleigh Small-Scale Fading: - Elevation-dependent Rician K-factor for LoS paths. - Rayleigh fading for NLoS paths.

class urbanmarl.models.channel_advanced.AdvancedChannelModel(frequency_ghz=29.0, bandwidth_hz=10000000.0, g_max_dbi=15.0, theta_3db_deg=65.0, phi_3db_deg=65.0, noise_figure_db=7.0, device='cpu')[source]

Bases: object

3GPP compliant 3D directional wireless channel propagation model.

Parameters:

frequency_ghz (float)
bandwidth_hz (float)
g_max_dbi (float)
theta_3db_deg (float)
phi_3db_deg (float)
noise_figure_db (float)
device (device | str)

frequency_ghz

Carrier frequency in GHz.

Type:: float

bandwidth

Transmission bandwidth in Hz.

Type:: float

g_max_dbi

Maximum boresight antenna gain in dBi.

Type:: float

theta_3db

Vertical half-power 3dB beamwidth in degrees.

Type:: float

phi_3db

Horizontal half-power 3dB beamwidth in degrees.

Type:: float

noise_figure_db

Receiver noise figure in dB.

Type:: float

__init__(frequency_ghz=29.0, bandwidth_hz=10000000.0, g_max_dbi=15.0, theta_3db_deg=65.0, phi_3db_deg=65.0, noise_figure_db=7.0, device='cpu')[source]

Initializes the advanced channel model.

Parameters:

frequency_ghz (float) – Carrier frequency. Defaults to 29.0 GHz.
bandwidth_hz (float) – Bandwidth. Defaults to 10 MHz.
g_max_dbi (float) – Antenna gain in dBi. Defaults to 15.0.
theta_3db_deg (float) – Vertical 3dB beamwidth. Defaults to 65 deg.
phi_3db_deg (float) – Horizontal 3dB beamwidth. Defaults to 65 deg.
noise_figure_db (float) – Receiver noise figure. Defaults to 7.0 dB.
device (Union[torch.device, str]) – PyTorch compute device.

Return type:

None

compute_3d_antenna_gain(tx_pos, rx_pos)[source]

Computes 3D directional antenna radiation pattern gain G(theta, phi) in linear scale.

Parameters:

tx_pos (torch.Tensor) – UAV transmitter coordinates of shape (…, N, 3).
rx_pos (torch.Tensor) – UE receiver coordinates of shape (…, M, 3).

Returns:

Linear antenna gain array of shape (…, N, M).

Return type:

torch.Tensor

compute_data_rates(tx_pos, rx_pos, tx_power=2.0, los_mask=None, include_fading=False)[source]

Computes Shannon data rates with 3D directional antenna patterns and fading.

Parameters:

tx_pos (torch.Tensor) – UAV 3D coordinates (…, N, 3).
rx_pos (torch.Tensor) – UE 3D coordinates (…, M, 3).
tx_power (Union[float, torch.Tensor]) – Transmit power in Watts.
los_mask (Optional[torch.Tensor]) – Boolean LoS tensor of shape (…, N, M).
include_fading (bool) – Whether to sample stochastic small-scale fading.

Returns:

Achievable transmission data rate in bits per second (…, N, M).

Return type:

torch.Tensor

GNN Message-Passing Policy

UrbanMARL Graph Neural Network (GNN) Message-Passing Policy Module.

Provides cooperative inter-agent message-passing embeddings for multi-UAV swarms:

Dynamically computes distance-thresholded inter-UAV communication graphs: A_ij = I(||p_i - p_j|| <= R_comm).
Vectorized edge-feature aggregation: m_ij = MLP([h_j, p_j - p_i, v_j - v_i]).
Permutation-invariant node feature updates: h_i’ = MLP([h_i, sum_{j in N_i} m_ij]).
Compatible with decentralized actor-critic architectures in CTDE MARL.

class urbanmarl.models.gnn_policy.VectorizedGNNMessagePassing(node_dim, hidden_dim=64, out_dim=64, r_comm=120.0)[source]

Bases: Module

Vectorized multi-agent Graph Neural Network message-passing module.

Parameters:

node_dim (int)
hidden_dim (int)
out_dim (int)
r_comm (float)

node_dim

Dimension of individual agent observation vectors.

Type:: int

hidden_dim

Hidden dimension for message and update networks.

Type:: int

out_dim

Output embedding dimension per agent.

Type:: int

r_comm

Inter-UAV communication radius in meters.

Type:: float

__init__(node_dim, hidden_dim=64, out_dim=64, r_comm=120.0)[source]

Initializes the GNN message-passing module.

Parameters:

node_dim (int) – Input agent feature dimension.
hidden_dim (int) – Hidden layer size. Defaults to 64.
out_dim (int) – Output feature embedding size. Defaults to 64.
r_comm (float) – Maximum inter-UAV communication range in meters. Defaults to 120.0.

Return type:

None

forward(node_features, positions, velocities=None)[source]

Executes vectorized graph message-passing across agents.

Parameters:

node_features (torch.Tensor) – Agent features of shape (B, N, node_dim).
positions (torch.Tensor) – Agent 3D coordinates of shape (B, N, 3).
velocities (Optional[torch.Tensor]) – Agent 3D velocities of shape (B, N, 3).

Returns:

Updated cooperative agent embeddings of shape (B, N, out_dim).

Return type:

torch.Tensor