Scenarios API
Base Urban Scenario
UrbanMARL Base Scenario Abstract Class.
Defines the abstract interface and digital twin rendering workflow for all UrbanMARL scenarios.
- class urbanmarl.scenarios.base.UrbanScenario(config)[source]
Bases:
ABCAbstract base class for all urban environment MARL scenarios.
A scenario defines: - Environment specs (observations, actions, rewards, done flags, info). - Environment step/reset dynamics (UAV mobility, UE distribution, energy). - Reward calculations and termination criteria. - Geospatial & radio network digital twin rendering.
- Parameters:
config (dict)
- __init__(config)[source]
Initializes the UrbanScenario.
- Parameters:
config (
dict) – Configuration options dictionary.- Return type:
None
- reset(env, tensordict=None, **kwargs)[source]
Resets environment state across the whole batch or targeted environment indices.
- Parameters:
env – UrbanEnv wrapper object.
tensordict (
TensorDictBase, optional) – Input TensorDict with reset flags.**kwargs – Extra reset parameters.
- Return type:
None
- abstract process_actions(env, tensordict)[source]
Applies agent actions and updates environment positions and battery levels.
- Parameters:
tensordict (TensorDictBase)
- Return type:
None
- abstract reward(env, group)[source]
Computes reward tensor of shape (batch_size, n_agents, 1) for an agent group.
- abstract observation(env)[source]
Computes observation tensor of shape (batch_size, n_agents, obs_dim).
- Return type:
- abstract observation_spec(env, group)[source]
Returns unbatched observation spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite
- abstract action_spec(env, group)[source]
Returns unbatched action spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite
- info_global_spec(env)[source]
Returns unbatched spec for global environment info dictionary.
- Return type:
Composite | None
- info_global(env)[source]
Returns global environment info dictionary for logging.
- Return type:
dict | None
- info_agent_spec(env, group)[source]
Returns unbatched agent info spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite | None
- reward_spec(env, group)[source]
Returns unbatched reward spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite | None
Scenarios Registry & Discovery
UrbanMARL Scenarios Module Registry.
Provides dynamic, automated scenario discovery, loading, and registration
utilities for UrbanMARL environments. Scenarios in this package implementing
the UrbanScenario interface are automatically discovered and registered
at runtime without requiring manual hardcoded imports.
- class urbanmarl.scenarios.UrbanScenario(config)[source]
Bases:
ABCAbstract base class for all urban environment MARL scenarios.
A scenario defines: - Environment specs (observations, actions, rewards, done flags, info). - Environment step/reset dynamics (UAV mobility, UE distribution, energy). - Reward calculations and termination criteria. - Geospatial & radio network digital twin rendering.
- Parameters:
config (dict)
- __init__(config)[source]
Initializes the UrbanScenario.
- Parameters:
config (
dict) – Configuration options dictionary.- Return type:
None
- reset(env, tensordict=None, **kwargs)[source]
Resets environment state across the whole batch or targeted environment indices.
- Parameters:
env – UrbanEnv wrapper object.
tensordict (
TensorDictBase, optional) – Input TensorDict with reset flags.**kwargs – Extra reset parameters.
- Return type:
None
- abstract process_actions(env, tensordict)[source]
Applies agent actions and updates environment positions and battery levels.
- Parameters:
tensordict (TensorDictBase)
- Return type:
None
- abstract reward(env, group)[source]
Computes reward tensor of shape (batch_size, n_agents, 1) for an agent group.
- abstract observation(env)[source]
Computes observation tensor of shape (batch_size, n_agents, obs_dim).
- Return type:
- abstract observation_spec(env, group)[source]
Returns unbatched observation spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite
- abstract action_spec(env, group)[source]
Returns unbatched action spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite
- info_global_spec(env)[source]
Returns unbatched spec for global environment info dictionary.
- Return type:
Composite | None
- info_global(env)[source]
Returns global environment info dictionary for logging.
- Return type:
dict | None
- info_agent_spec(env, group)[source]
Returns unbatched agent info spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite | None
- reward_spec(env, group)[source]
Returns unbatched reward spec for an agent group.
- Parameters:
group (str)
- Return type:
Composite | None
- urbanmarl.scenarios.register_scenario(name, scenario_class, aliases=None)[source]
Registers a scenario class under a specific string key identifier.
- Parameters:
name (str) – Unique scenario string name.
scenario_class (Type[UrbanScenario]) – Concrete subclass of UrbanScenario.
aliases (List[str] | None) – Optional list of additional alias names for the scenario.
- Raises:
TypeError – If scenario_class is not a subclass of UrbanScenario or is abstract.
- Return type:
None
- urbanmarl.scenarios.get_scenario_class(name)[source]
Retrieves the scenario class for a given scenario name without instantiating it.
- Parameters:
name (str) – Name identifier of the scenario (case-insensitive).
- Returns:
The registered scenario class.
- Return type:
Type[UrbanScenario]
- Raises:
ValueError – If scenario name is not found in registry.
- urbanmarl.scenarios.load_scenario(name, config=None)[source]
Loads and instantiates an UrbanScenario by name.
- Parameters:
- Returns:
An initialized instance of the requested scenario class.
- Return type:
- Raises:
ValueError – If scenario name is not found in registry or cannot be loaded.
- urbanmarl.scenarios.list_scenarios()[source]
Returns a sorted list of all currently registered scenario names.
- Returns:
List of unique scenario names.
- Return type:
List[str]
- urbanmarl.scenarios.auto_register_scenarios(package_path=None)[source]
Dynamically scans and registers all concrete Scenario classes in the scenarios package.
This function automatically iterates through all python modules in the package directory, imports them, and registers any concrete subclass of
UrbanScenario(typically defined asclass Scenario(UrbanScenario)).- Parameters:
package_path (Path | None) – Optional custom Path directory to scan. Defaults to this package’s directory.
- Returns:
Dictionary of all registered scenarios.
- Return type:
Dict[str, Type[UrbanScenario]]
- urbanmarl.scenarios.__dir__()[source]
Returns directory listing of module attributes including registered scenarios.
UAV-UE Line-of-Sight
- class urbanmarl.scenarios.uav_ue_los.Scenario(config)[source]
Bases:
ScenarioScenario name: UAV_UE_LOS
Objective: Similar to UAV_NAVIGATION, but without global state information. The UAVs are trained to navigate in an urban environment with the same dynamics and constraints, and reward function.
- Reward function:
LoS ratio - collision penalty. The reward is calculated as the mean of the LoS (Line of Sight) ratio between UAVs and UEs (User Equipments) minus a penalty for collisions. The LoS ratio is computed as the mean of the uav_ue_los tensor along the last dimension, while the collision penalty is derived from the uav_collisions tensor. The final reward is returned as a tensor of shape (batch_size, n_uavs, 1).
- Parameters:
config (dict)
Coverage Scenario
- class urbanmarl.scenarios.coverage.Scenario(config)[source]
Bases:
ScenarioScenario name: COVERAGE
Objective: Similar to UAV_NAVIGATION, but without global state information. The UAVs are trained to navigate in an urban environment with the same dynamics and constraints, while the reward function has additional penality for beeing closer than a certain threshold.
- Reward function:
LoS ratio - collision penalty. The reward is calculated as the mean of the LoS (Line of Sight) ratio between UAVs and UEs (User Equipments) minus a penalty for collisions. The LoS ratio is computed as the mean of the uav_ue_los tensor along the last dimension, while the collision penalty is derived from the uav_collisions tensor. Additionally, a distance penalty is applied for UAVs that are closer than a specified threshold from each other. The final reward is returned as a tensor of shape (batch_size, n_uavs, 1).
- Parameters:
config (dict)
- reward(env, group)[source]
calculate the reward function per agent group.
- Parameters:
env (
UrbanEnv) – urbanMARL environmentgroup (
str) – the agent group for which to calculate the reward
- Returns:
reward tensor of shape (batch_size, n_uavs, 1)
- Return type:
reward (torch.Tensor)
Reward function: LoS ratio - collision penalty. The reward is calculated as the mean of the LoS (Line of Sight) ratio between UAVs and UEs (User Equipments) minus a penalty for collisions. The LoS ratio is computed as the mean of the uav_ue_los tensor along the last dimension, while the collision penalty is derived from the uav_collisions tensor. The final reward is returned as a tensor of shape (batch_size, n_uavs, 1).
UAV-MEC Task Offloading
UrbanMARL UAV MEC Offloading Scenario.
Provides a fully vectorized, closed-loop multi-agent reinforcement learning scenario for multi-UAV assisted Mobile Edge Computing (MEC) networks.
Integrates:
Vectorized mmWave radio channel propagation (Shannon transmission capacity).
Vectorized M/M/c queuing dynamics (server utilization, queue waiting time, system delay).
Dynamic Task-Distance-Load Capacity Matching (DTLCM) heuristic offloading.
Sojourn time tracking and deadline violation penalization based on Dr. Basheer Raddwan’s research (“Quantify the joint effect of mobility and urban environment on computation offloading to multi-UAV MEC network: Sojourn time”, Ad Hoc Networks, 2025).
- class urbanmarl.scenarios.uavmec_offloading.Scenario(config)[source]
Bases:
UrbanScenarioUAV MEC Offloading scenario for UrbanMARL environments.
Multi-UAV base stations collaboratively navigate a 3D urban environment to maximize task offloading completion, minimize total system latency and energy, avoid building collisions, and maintain persistent sojourn coverage over active users.
- Parameters:
config (dict)
- __init__(config)[source]
Initializes the UAV MEC Offloading scenario.
- Parameters:
config (
dict) – Scenario configuration parameters.- Return type:
None
- process_actions(env, tensordict)[source]
Executes agent actions and runs the end-to-end MEC offloading pipeline.
Steps: 1. Updates 3D UAV kinematics and collision/LoS states. 2. Computes wireless transmission data rates (Shannon capacity). 3. Matches UE tasks to UAV servers using DTLCM heuristic. 4. Calculates M/M/c queuing dynamics (utilization, waiting, response delay). 5. Tracks sojourn time and task completion within SLA deadlines.
- Parameters:
tensordict (TensorDictBase)
- Return type:
None
- observation_spec(env, group)[source]
Returns observation spec for UAV agents.
- Parameters:
group (str)
- Return type:
Composite
- action_spec(env, group)[source]
Continuous 3D velocity action spec: [v_h, phi, v_z].
- Parameters:
group (str)
- Return type:
Composite
- reward_spec(env, group)[source]
Unbounded scalar reward specification.
- Parameters:
group (str)
- Return type:
Composite
- reward(env, group)[source]
Calculates multi-objective reward balancing tasks, latency, energy, and sojourn time.
- Parameters:
env – UrbanEnv environment instance.
group (
str) – Agent group name.
- Returns:
Reward tensor of shape (batch_size, n_uavs, 1).
- Return type:
- state_spec(env)[source]
Global centralized state spec for CTDE algorithms (e.g. MAPPO).
- Return type:
Composite | None
- info_global_spec(env)[source]
Specifies keys recorded in global info dictionary.
- Return type:
Composite | None
- info_agent_spec(env, group)[source]
Specifies agent-level info dictionary if enabled.
- Parameters:
group (str)
- Return type:
Composite | None
Dynamic User Mobility
UrbanMARL Dynamic User Equipment (UE) Mobility Scenario.
NEW standalone scenario introducing dynamic ground user motion (Manhattan street-constrained, Random Waypoint, or dynamic crowd hotspots) into multi-UAV wireless coverage.
Ground users continuously move along urban corridors each time step, forcing the UAV swarm to dynamically coordinate 3D trajectories to maximize persistent Line-of-Sight (LoS) coverage and sojourn time without colliding with 3D buildings.
- class urbanmarl.scenarios.uav_mobile_ue.Scenario(config)[source]
Bases:
UrbanScenarioScenario name: UAV_MOBILE_UE.
Objective: Multi-UAV base stations collaboratively track and provide wireless coverage to dynamic, mobile ground users moving through street corridors.
- Parameters:
config (dict)
- __init__(config)[source]
Initializes the UAV Mobile UE scenario.
- Parameters:
config (
dict) – Configuration dictionary.- Return type:
None
- process_actions(env, tensordict)[source]
Applies agent actions and advances both UAVs and mobile ground UEs.
- Parameters:
tensordict (TensorDictBase)
- Return type:
None
- observation_spec(env, group)[source]
Returns observation spec for UAV agents: [x, y, z, battery, los_ratio, mean_sojourn].
- Parameters:
group (str)
- Return type:
Composite
- observation(env)[source]
Observation tensor: [x, y, z, battery, los_ratio, mean_sojourn].
- Return type:
- action_spec(env, group)[source]
Continuous velocity action spec: [v_h, phi, v_z].
- Parameters:
group (str)
- Return type:
Composite
- reward_spec(env, group)[source]
Unbounded scalar reward specification.
- Parameters:
group (str)
- Return type:
Composite
- reward(env, group)[source]
Reward balancing mobile user LoS coverage, sojourn persistence, and collision avoidance.
- state(env)[source]
Global state tensor including UAV and mobile UE states.
- Return type:
Tensor | None
- info_agent_spec(env, group)[source]
Specifies agent-level info dictionary if enabled.
- Parameters:
group (str)
- Return type:
Composite | None
Advanced Physics & Aerodynamics
UrbanMARL High-Fidelity UAV-MEC Task Offloading Scenario.
NEW standalone scenario combining: 1. High-fidelity rotary-wing UAV aerodynamic propulsion power (Zeng et al., IEEE TWC). 2. 3GPP TR 38.901 3D directional antenna radiation beamforming and elevation fading. 3. Vectorized M/M/c MEC server queuing dynamics (utilization, response latency, deadlines). 4. Dynamic task offloading assignment and sojourn time maximization.
- class urbanmarl.scenarios.uavmec_advanced_physics.Scenario(config)[source]
Bases:
UrbanScenarioScenario name: UAVMEC_ADVANCED_PHYSICS.
Objective: Multi-UAV MEC networks optimize 3D flight trajectories, offloading matching, and server allocations under realistic rotary-wing flight aerodynamics and 3D directional beamforming propagation.
- Parameters:
config (dict)
- __init__(config)[source]
Initializes the high-fidelity UAV-MEC scenario.
- Parameters:
config (
dict) – Configuration dictionary.- Return type:
None
- process_actions(env, tensordict)[source]
Executes flight dynamics, aerodynamics power, 3D channel, and MEC queues.
- Parameters:
tensordict (TensorDictBase)
- Return type:
None
- observation_spec(env, group)[source]
Observation spec for high-fidelity UAV-MEC.
- Parameters:
group (str)
- Return type:
Composite
- observation(env)[source]
Observation tensor: [x, y, z, battery, util, system_time, los_ratio, mean_sojourn].
- Return type:
- action_spec(env, group)[source]
Continuous velocity action: [v_h, phi, v_z].
- Parameters:
group (str)
- Return type:
Composite
- reward(env, group)[source]
Multi-objective reward combining completed tasks, delay, energy, and sojourn bonus.
- info_agent_spec(env, group)[source]
Agent-level info spec if enabled.
- Parameters:
group (str)
- Return type:
Composite | None