Limitations

EM Engine

Large EM simulations are constrained by GPU memory. The main drivers are the number of emitted rays, scattering depth, frequency samples, UEs, antenna elements, and vegetation density.

• Up to 40 million rays per RU are supported over a simulation area up to 25 square kilometers on an NVIDIA L40S GPU.
• Up to 5 scattering events per ray are supported, or up to 10 when transmission is included.
• Wideband CFR supports up to 4096 frequency samples.
• Simulations support up to 10,000 UEs.
• RU panels support up to 64 antenna elements. UE panels support up to 8 antenna elements.
• Vegetation density supports up to 50%.

If a large simulation fails due to resource limits, reduce rays, scattering events, UE density, vegetation density, or disable diffusion.

Additional EM engine constraints:

• Diffraction can occur only once per ray across the selected scattering events.
• Diffuse scattering is limited to direct diffuse paths where the diffuse vertex is line-of-sight to both the RU and UE.
• Rays with transmissions support only specular reflections.
• Built-in antenna models are limited to isotropic, polarized isotropic, infinitesimal dipole, halfwave dipole, microstrip patch, and 3GPP-type RU elements. Other models must be added through custom antenna element or panel files.
• Active Element Patterns can currently be calculated only for halfwave dipoles.
• While each RU can have its own antenna panel with its own antenna setup (antenna number, antenna spacing, antenna pattern, single/dual-polarization), all the RU panels need to have the same frequency operation parameters (carrier frequency, FFT size, subcarrier spacing).
• All UEs in one simulation run need to use the same antenna panel.

RAN Simulation

• RU antenna counts are limited to 64 or 4. UE antenna count is limited to 4.
• Only 100 MHz bandwidth with 273 PRBs is supported.
• Only 30 kHz subcarrier spacing is supported.
• When the RU has 4 antennas, only SU-MIMO is supported and beamforming is not applied.
• When the RU has 64 antennas, regularized ZF beamforming is applied.
• MMSE-IRC is applied at receivers.
• DMRS positions are fixed at symbols 2, 3, 10, and 11.
• PRBs are scheduled at PRB group level, with 4 PRBs per PRB group.
• HARQ, when enabled, operates per slot and allows up to 4 transmissions: one new transmission plus three retransmissions.
• SRS is scheduled only on S slots. S slots are dedicated to SRS.
• For SRS slots, 4-antenna RUs can allocate all 14 symbols for SRS. 64-antenna RUs can allocate only 4 symbols.
• On servers where system RAM is lower than GPU VRAM, back-to-back simulations can be unstable. In extreme cases, the system can hang and require a cold reboot.

MAC Scheduler

• HARQ retransmission is non-adaptive: retransmissions reuse the original PRB allocation, layer selection, and MCS.
• Layer selection is not fully optimized.
• MCS selection uses a SINR-to-MCS lookup table derived for single-layer AWGN transmissions, which may be inaccurate for multi-layer transmissions.

Mobility

Mobility Model

• Manual UEs cannot have waypoints that cross from indoor to outdoor space, or from outdoor to indoor space. The RRT solver fails if this is attempted.
• The RRT3 engine supports only manual users and scatterers. Procedural 3D actor generation is not implemented.
• A 3D user whose waypoints are too close to the terrain surface may fail pathfinding.
• Spawn zone footprints are convex. If input points describe a concave polygon, the mobility model samples the convex hull instead of preserving the concave outline.
• In GPX timed mode, where use_pathfinding is True, only one user ID is supported per GPX request.
• Collision detection and terrain projection use CUDA through NVIDIA Warp. A GPU is required.
• RRT distance parameters are tuned for the default scale of 100 centimeters. RRTConfig.for_scale() adjusts them for other scales, but extreme scale values may need manual tuning.
• If a user’s speed is zero at a waypoint, the trajectory is truncated at that point and the user remains stationary for the rest of the simulation.
• If a user’s trajectory is shorter than the simulation duration, the last sample is repeated to pad the output to the expected length.

Urban Mobility (SUMO)

Urban Mobility is experimental.

• The first run with Urban Mobility enabled requires network access to fetch OpenStreetMap data from the Overpass API. The network file is cached and reused for subsequent runs with the same bounding box.
• Manual UEs and UEs created from GPX files are not recognized by the Urban Mobility model, so collisions may occur.
• A spawn zone is required for Urban Mobility and dynamic scattering from cars.
• OSM import can produce road networks that extend beyond the spawn zone, so UE and vehicle trajectories may leave the intended area.
• Overpass API queries are limited to bounding boxes of at most 1.0 square degrees.
• If the road network cannot support the requested number of vehicles or UEs, or if SUMO actors lack enough timesteps or have trajectory points inside buildings, fewer actors may be generated.
• Vehicle and UE random trips may end before the requested duration. AODT attempts rerouting to keep actors in the simulation.
• If rerouting is not possible, actors may stay stationary after reaching their target.
• In duration/interval simulations, interval cannot exceed 100 ms because larger intervals can make vehicle motion appear jittery.
• SUMO simulates vehicles as points, not volumes. The viewer renders those points as 3D vehicle models, so two vehicles whose SUMO point positions are close together can appear to overlap or collide even though SUMO considers them separate. This is a visual artifact of the mismatch between SUMO’s point-based simulation and the volumetric rendering in the viewer.
• SUMO trajectory sampling interpolates the Z coordinate linearly between waypoints. When two consecutive waypoints lie on opposite sides of a terrain ridge or crevice, the interpolated positions can dip below the terrain surface, causing vehicles to appear partially submerged. This is more likely on maps with abrupt elevation changes. To mitigate, generate maps with higher terrain fidelity or reduce the sampling interval so waypoints are closer together.

Calibration

Calibration limitations fall into two phases:

1. Simulation before calibration — constrains the AODT simulation that must be aligned and traced before calibration: link geometry, antenna setup, scene RF interactions, and the GIS/vegetation scene.
2. Calibration process — arises from the inverse calibration run itself: the power-based, narrowband, under-constrained fit that recovers materials and orientations from the imported rays and measurements.

See Simulation setup and Calibration for the full workflow.

1. Simulation before calibration

These constrain the simulation that precedes calibration. They must be satisfied while building and tracing the aligned scene (see Simulation setup).

Trace-time requirements:

• Use GPX-driven UE samples with use_pathfinding: false, correct map georeferencing, and one measurement row per GPX sample.
• Trace calibration inputs with a 1 × 1 RU panel at the panel phase center, accurate RU position, and accurate aerial_gnb_height.
• Enable the RF interactions and scene assets that calibration must later observe, including transmission, diffuse scattering, diffraction, and vegetation when those targets matter.
• Do not rely on scatterers as calibration targets. Calibration consumes a restricted band, so avoid the full broadband grid unless the campaign requires it.

FAQ - Simulation before calibration

2. Calibration process

These limits apply after the simulation rays and measurements have already been imported. They describe what the inverse, power-based, narrowband fit can recover from those inputs (see Calibration).

UE orientation

For more on training, refer to Intro to Calibration -> 3.3 UEs.

• Calibration can correct UE orientation only; UE positions remain the positions imported from the aligned simulation input.
• Position error is absorbed as orientation or material residual, so large GPX errors or arbitrary handset motion cannot be recovered as clean tilt, azimuth, or roll corrections.
• There is roughly a 1 m uncertainty confidence range around UE positioning, but tighter measurements are still strongly recommended.
• UE orientation training is bounded to $\theta_{\mathrm{mech}}$ from 0° to 75°, $d\theta(t)$ from -30° to +30°, and $d\phi(t)$ from -45° to +45°.

RU orientation

For more on training, refer to Intro to Calibration -> 3.3 RUs.

cal.targets.RUs — bounded correction on seeded mounting angles (tilt, azimuth, panel roll):

• Calibration refines the seeded RU orientation within the -30° to +30° correction range.
• If the true mounting angle is outside that window, calibration cannot discover it from scratch. This is especially limiting for directive RU antennas because power-only observations do not uniquely identify absolute orientation when the initial angle is too far away.

RU beams

For more on training, refer to Intro to Calibration -> 3.3 RUsBeams.

cal.targets.RUsBeams — learned beam codebook on the multi-element calibration array:

• Pre-known beam codebooks cannot be supplied yet — beams are learned only when cal.targets.RUsBeams: true; support for a user-provided codebook is planned for a future release.
• Beam calibration requires measured beam indices.
• Without beam_idx columns, the active beam is unknown and the codebook cannot be identified.
• Beam errors can be ambiguous with RU orientation and material errors.
• Treat a recovered codebook as physical only after the RU orientation and material fits are also plausible.

Building / surface material recovery

For more on training, refer to Intro to Calibration -> 3.3 Materials.

• Calibration only adjusts material parameters attached to interactions present in the imported ray paths. Missing transmission, diffuse scattering, or diffraction events stay missing, so their effects are pushed into whichever enabled targets remain.
• Building-material frequency exponents stay fixed. Calibration is narrowband at the carrier frequency and tunes carrier-frequency material behavior, not the full frequency-dependent material law.
• Metallic materials are currently not supported because their conductivity spans too wide a domain for the current material recovery fit.

Vegetation material recovery

For more on training, refer to Intro to Calibration -> 3.3 Vegetation Materials.

• Vegetation materials are observable only when vegetation appears in the imported ray paths.
• If the rays contain vegetation hits, reconstruction quality still depends on ray diversity and hit strength because individual vegetation interactions often carry limited energy.

Maximum trainable simulation size

The maximum supported trainable size depends mostly on active ray count and number of frequencies. The number of interactions has not shown a practical impact.

FAQ - Calibration process

Calibration is in an early alpha stage; open training behaviors are not yet fully specified.

YAML Config Builder

The YAML Config Builder is an authoring and round-trip helper for AODT simulation YAML. It is not a general-purpose editor for arbitrary YAML files. The YAML should be created either from the client library or the Viewer.

General Limitations

• UE IDs are limited to 1 through 10000. Waypoints for a single UE must all be either 2D or 3D. Spawn zones and bounding-box windows accept only 2D positions.
• When registering non-file-based panels through the builder API, panel reference frequencies must match. RU, DU, and panel frequencies are independent fields, so updating one does not update the others automatically.
• File-based panels cannot be modified with panel setters such as set_frequency, set_antenna_elements, set_spacing_wavelengths, set_panel_size, or set_roll_angles. Their panel details are read from the panel file at runtime. When using a file-based RU panel, set the DU antenna count explicitly because it cannot be derived from the panel shape.

Build YAML From Scratch

• New SimConfig(...) objects require an assets.yml file with scalar .json entries for du, ru, ue, scenario, panels, scatterers, materials, vegetation_materials, and vegetation_assets.
• Timeline configuration must use either duration/interval or slots/realizations, not both. RAN mode requires slots/realizations, and realizations_per_slot supports only 1 or 14.
• The builder enforces object relationships before export: default panels must be registered before adding DUs, RUs, or UEs; an RU must reference an existing DU and panel; and a UE must have at least one waypoint or a GPX source.

Build YAML From Importing Existing YAML

• SimConfig.from_yaml_file(...) is intended for YAML generated by the client library or Viewer. Import is semantic, not byte-preserving: comments, anchors, duplicate keys, scalar style, and original ordering are not preserved.
• Imported YAML is supposed to be valid for running a simulation. The behavior of importing manually edited YAML is undefined. Imported YAML reads asset defaults from the YAML sim.*.default entries instead of an external assets.yml.

Build YAML for Calibration

• Calibration YAML should be built by importing the exact base simulation YAML with SimConfig.from_yaml_file(...) and then calling set_calibration_targets(...). The base simulation run must export the RAYPATHS table; the builder does not infer that when adding calibration settings.
• Calibration YAML export also requires at least one calibration measurement and a non-empty output folder key.

UI

• The viewer may become temporarily unresponsive when applying a new YAML, loading data from a database, or connecting to or disconnecting from a server.
• For large scenes, placing vegetation or creating road overlays can cause EM worker heartbeat loss. Detach from the EM worker while staying in the live session, then reattach after the operation finishes.
• For large simulations, such as 100,000 slots or 1,000 UEs, the UI may lose connection with the EM Solver Worker. Use headless mode for large runs.
• When switching maps in the viewer, scenario parameters may disappear and UI console errors may appear. Restart the graphical interface and reopen the map.

GIS

• Map areas up to 25 km² are recommended. Beyond that, map processing time may become prohibitively long. Use a smaller box, or split the region across multiple prepare_map calls to cover more area.
• Cesium 3D Tiles emitted with cesium3dtiles_gzip=True (the default) require the hosting layer to set Content-Encoding: gzip. Hosts that do not set this header will return unreadable tile payloads.