Config Builder API
This page documents the public classes and enums in the _config module
(C++ with pybind11 bindings).
Enums
SimMode
Simulation mode.
EM
Electromagnetic mode (duration/interval based).
RAN
RAN mode (slot/symbol based).
DBTable
Result tables that can be persisted to the database.
CIRS
Channel Impulse Response.
CFRS
Channel Frequency Response. Adding this table automatically enables wideband simulation.
RAYPATHS
Ray path data.
TELEMETRY
Telemetry data (RAN mode only).
GeoTargets
Target geometry type for material calibration operations.
BLDG
Building materials (sim.Materials section).
VEG
Vegetation materials (sim.VegetationMaterials section).
DiffusionModel
EM diffusion model for ray tracing.
LAMBERTIAN
Lambertian diffusion.
DIRECTIONAL
Directional diffusion.
Data Classes
Position
A geographic or Cartesian position.
georef
Create a georeferenced position from latitude and longitude.
alt is an altitude offset above terrain in meters. When alt
is set, the point is 3D and AODT projects z = terrain_z + alt.
When alt is None, the point is 2D and AODT
projects z to the terrain+buildings surface.
cartesian
Create a Cartesian position. z is the vertical coordinate in
meters. When z is None, the point is 2D and AODT
projects z to the terrain+buildings surface.
Waypoint
UE waypoint with position and mobility parameters.
position
- Return type
Position
speed
- Return type
float
Speed in m/s.
pauseDuration
- Return type
float
Pause duration in seconds.
azimuthOffset
- Return type
float
Azimuth offset in degrees.
S3Config
Reusable S3 connection credentials. Used by
SimConfig.set_s3_config() and
SimConfig.add_parquet_s3_config().
- Parameters
- •
bucket(str) - S3 bucket name.•provider(str) -“minio”or“aws”.•endpoint_url(str) - S3 endpoint URL (not required for AWS).•access_key(str) - Access key.•secret_key(str) - Secret key.•region(str) - AWS region (default“us-east-1”).
Domain Objects
Panel
Antenna panel configuration. Create via the static factory methods below — do not instantiate directly.
create_panel
Create a panel from antenna element names.
antenna_elements accepts built-in pattern name constants
(e.g. Panel.THREE_GPP_38901, Panel.ISOTROPIC) or custom
file paths (e.g. "path/to/pattern.csv").
Built-in constants: Panel.ISOTROPIC,
Panel.INFINITESIMAL_DIPOLE, Panel.HALFWAVE_DIPOLE,
Panel.REC_MICROSTRIP_PATCH, Panel.THREE_GPP_38901,
Panel.POLARIZED_ISOTROPIC.
- Parameters
- •
antenna_elements(list[str]) - Antenna element names or file paths.•frequency_mhz(float) - Reference frequency in MHz.•vertical_spacing(float) - Vertical spacing in wavelengths.•vertical_num(int) - Number of vertical elements.•horizontal_spacing(float) - Horizontal spacing in wavelengths.•horizontal_num(int) - Number of horizontal elements.•dual_polarized(bool) - Whether the panel is dual-polarized.•roll_first(float) - First polarization roll angle (degrees).•roll_second(float) - Second polarization roll angle (degrees). - Return type
Panel
create_panel_from_file
Create a file-based panel from a CSV or FFD file. The panel configuration is entirely defined by the file.
- Parameters
- •
panel_file_path(str) - Path to the panel definition file. - Return type
Panel
id
Return the panel ID (assigned when added to a config).
The setters below mutate an existing Panel. They are intended
for editing a config loaded via SimConfig.from_yaml_file().
For example:
None of the setters are valid on a file-based panel (one created via
Panel.create_panel_from_file()); calling any of them on such
a panel raises RuntimeError. Setters that re-run the panel
invariant check (set_antenna_elements, set_panel_size)
provide a strong exception guarantee: if validation fails, the panel
reverts to its previous state.
set_antenna_elements
set_antenna_elements(names: list[str])
Replace the antenna element list. Two forms are accepted:
- A list of :class:
AntennaElementenum values. - A list of strings: built-in pattern name constants
(
Panel.THREE_GPP_38901,Panel.ISOTROPIC, …) or custom pattern file paths. Empty strings are rejected.
Re-runs the full panel invariant check, so the new list must be
consistent with the current array shape: either a single element
(broadcast to every antenna) or exactly
vertical_num * horizontal_num * (2 if dual_polarized else 1)
entries.
- Parameters
- •
elements(list[AntennaElement]) - Antenna element enum values.•names(list[str]) - Antenna element names or file paths. - Raises
RuntimeError- If the panel is file-based, or the list
size does not match the panel shape.
set_frequency
Set the panel reference frequency in MHz.
Does not change the stored mm spacing: a real panel has a fixed
physical element spacing and only its wavelength ratio changes
with frequency. To re-derive the spacing at the new frequency,
call set_spacing_wavelengths() afterwards.
- Parameters
- •
mhz(float) - Reference frequency in MHz (must be > 0). - Raises
RuntimeError- If the panel is file-based, or mhz is
not positive.
set_spacing_wavelengths
Set the element spacings in wavelengths at the current reference frequency. Stored internally as millimeters.
- Parameters
- •
vertical_wavelengths(float) - Vertical spacing in wavelengths.•horizontal_wavelengths(float) - Horizontal spacing in wavelengths. - Raises
RuntimeError- If the panel is file-based, or either
spacing is not positive.
set_panel_size
Set the array shape (vertical x horizontal element counts) and whether the panel is dual-polarized.
Re-runs the full panel invariant check, so the current antenna element list must still be size-compatible with the new shape.
- Parameters
- •
vertical_num(int) - Number of vertical elements (must be > 0).•horizontal_num(int) - Number of horizontal elements (must be > 0).•dual_polarized(bool) - Whether the panel is dual-polarized. - Raises
RuntimeError- If the panel is file-based, the counts are
non-positive, or the antenna element list does not match the new shape.
set_roll_angles
Set the polarization roll angles in degrees.
- Parameters
- •
first_deg(float) - First polarization roll angle (degrees).•second_deg(float) - Second polarization roll angle (degrees). - Raises
RuntimeError- If the panel is file-based.
DU (Distributed Unit)
Distributed Unit. Create via Nodes.create_du().
id
Return the DU ID.
frequency
Return carrier frequency in MHz.
set_position
Set the DU position.
set_frequency
Set the DU reference frequency in MHz.
Only this DU’s emitted aerial_du_reference_freq is updated;
the frequencies of associated RUs are independent and must be
adjusted separately with RU.set_frequency() if the
deployment expects them to track.
- Parameters
- •
mhz(float) - Reference frequency in MHz (must be > 0). - Raises
ValueError- If mhz is not positive.
set_fft_size
Set FFT size.
set_max_channel_bandwidth
Set maximum channel bandwidth in MHz.
set_num_antennas
Override the number of antennas (normally auto-derived from the default RU panel).
RU (Radio Unit)
Radio Unit. Create via Nodes.create_ru().
id
Return the RU ID.
frequency
Return carrier frequency in MHz.
du_id
Return the associated DU ID.
panel_id
Return the ID of the panel assigned to this RU.
For an RU retrieved via SimConfig.get_ru() this is
always non-zero: SimConfig.add_ru() resolves an unset
(0) value to the current default RU panel before storing the
RU. The accessor only returns 0 on a freshly constructed RU
that has not yet been added to a config.
set_position
Set the RU position (georeferenced or Cartesian).
set_height
Set height in meters above ground.
set_radiated_power
Set radiated power in dBm.
set_mech_azimuth
Set mechanical azimuth in degrees.
set_mech_tilt
Set mechanical tilt in degrees.
set_frequency
Set the RU carrier frequency in MHz.
Only this RU’s emitted aerial_gnb_carrier_freq is updated;
the associated DU’s frequency is not modified.
- Parameters
- •
mhz(float) - Carrier frequency in MHz (must be > 0). - Raises
ValueError- If mhz is not positive.
assign_panel
Assign a specific panel to this RU, overriding the default.
UE (User Equipment)
User Equipment. Create via Nodes.create_ue().
id
Return the UE ID.
add_waypoint
Add a waypoint. At least one waypoint is required before calling
SimConfig.add_ue() (unless using a GPX source).
Waypoints for the same UE must all have the same dimensionality;
adding a 2D waypoint to a 3D UE, or a 3D waypoint to a 2D UE,
raises.
- Parameters
- •
position(Position) - Waypoint position.•speed(float) - Speed in m/s.•pause_duration(float) - Pause duration in seconds.•azimuth_offset(float) - Azimuth offset in degrees.
clear_waypoints
Remove all waypoints from this UE.
set_radiated_power
Set UE radiated power in dBm.
assign_panel
Assign a specific panel to this UE, overriding the default.
set_bler_target
Set the BLER target.
set_manual
Set manual mode for this UE.
Factory
Nodes
Factory for creating DU, RU, and UE objects.
create_du
Create a Distributed Unit.
- Parameters
- •
du_id(int) - DU identifier (must be > 0).•frequency_mhz(float) - Carrier frequency in MHz.•scs_khz(float) - Subcarrier spacing in kHz. - Return type
DU
create_ru
Create a Radio Unit.
- Parameters
- •
ru_id(int) - RU identifier (must be > 0).•frequency_mhz(float) - Carrier frequency in MHz.•radiated_power_dbm(float) - Radiated power in dBm.•du_id(int) - Associated DU identifier. - Return type
RU
create_ue
Create a User Equipment.
- Parameters
- •
ue_id(int) - UE identifier (must be in [1, 10000]).•radiated_power_dbm(float) - Radiated power in dBm. - Return type
UE
Configuration Builder
SimConfig
High-level configuration builder for AODT simulations.
- Parameters
- •
scene_url(str) - Scene URL — S3 key prefix or local path.•mode(SimMode) - Simulation mode (defaultEM).•asset_config_path(str) - Path toassets.yml(required). - Raises
RuntimeError- If asset_config_path is empty or cannot be loaded.
SimConfig.from_yaml_file
Load an existing complete YAML config file into an editable
:class:SimConfig.
The import path reads asset defaults from the YAML sim.*.default keys
and does not require an assets.yml path. The returned object can be
edited with the normal builder API, for example get_ru(),
get_ue(), add_ue(), etc.
Import is semantic rather than byte preserving: comments, YAML scalar style, anchors, duplicate keys, and original ordering are not preserved.
Import assumes the YAML file is generated by this client library.
- Parameters
- •
file_path(str) - Path to the YAML config file. - Raises
RuntimeError- If the file cannot be opened, parsed, or imported.
SimConfig.set_simulation_id
Set the simulation ID (used as DB name and identifier).
SimConfig.set_db
Set database connection parameters.
SimConfig.set_num_batches
Set number of simulation batches (must be > 0).
SimConfig.set_timeline
Set simulation timeline. Provide either duration/interval (EM mode) or slots_per_batch/realizations_per_slot (RAN / slot mode) — not both.
SimConfig.set_seed
Enable deterministic seeding for mobility.
SimConfig.add_tables_to_db
Add a result table to persist in the database.
SimConfig.add_table_option
Set an option for an opt-in table (e.g.
add_table_option("raypaths", "full")).
SimConfig.set_s3_config
Set the global S3 config (required). Emitted as
db.s3_config in the YAML output.
SimConfig.enable_parquet_export
Enable Parquet export to S3.
SimConfig.disable_parquet_export
Disable Parquet export.
SimConfig.add_parquet_s3_config
Add an S3 storage config for Parquet export.
SimConfig.set_parquet_iceberg
Configure an Apache Iceberg catalog for Parquet export.
SimConfig.set_ray_tracing_model
Set EM ray tracing solver parameters.
SimConfig.enable_wideband
Enable wideband simulation (automatically enabled when adding
DBTable.CFRS).
SimConfig.set_default_panel_ru
Set the default RU panel (assigns ID 2). Must be called before adding any DU, RU, or UE.
SimConfig.set_default_panel_ue
Set the default UE panel (assigns ID 1). Must be called before adding any DU, RU, or UE.
SimConfig.add_panel
Add an additional panel (auto-assigns an ID).
SimConfig.get_default_ru_panel_id
Return the ID of the panel registered as the default RU panel
(the YAML field sim_gnb_panel_type). Useful when re-editing a
config loaded via SimConfig.from_yaml_file()::
panel = config.get_panel(config.get_default_ru_panel_id()) panel.set_antenna_elements([AntennaElement.Isotropic])
The underlying field is value-initialized (2), so a non-zero
return value does not by itself imply that a Panel with that ID
has been added to the config yet. This is safe on configs loaded
via SimConfig.from_yaml_file() (the import populates real
panels and defaults), but a brand-new SimConfig() may report
an ID that does not yet correspond to any registered panel.
SimConfig.get_default_ue_panel_id
Return the ID of the panel registered as the default UE panel
(the YAML field sim_ue_panel_type). See
get_default_ru_panel_id() for caveats on default
initialization.
SimConfig.add_du
Add a DU to the configuration.
SimConfig.add_ru
Add an RU to the configuration. The referenced DU must already exist.
SimConfig.add_ue
Add a UE to the configuration. At least one waypoint or GPX source must be set.
SimConfig.get_du
Get a mutable reference to a DU by ID.
SimConfig.get_ru
Get a mutable reference to an RU by ID.
SimConfig.get_ue
Get a mutable reference to a UE by ID.
SimConfig.get_panel
Get a mutable reference to a Panel by ID.
SimConfig.get_ru_ids
Return the IDs of all RUs currently added to the config. The order reflects the underlying hash map and must be treated as unspecified.
SimConfig.get_ue_ids
Return the IDs of all UEs currently added to the config (order unspecified).
SimConfig.get_du_ids
Return the IDs of all DUs currently added to the config (order unspecified).
SimConfig.get_panel_ids
Return the IDs of all Panels currently added to the config (order unspecified).
SimConfig.remove_ue
Remove a UE from the configuration.
SimConfig.clear_waypoints
Clear all waypoints for a given UE.
SimConfig.add_ues_from_gpx
Create UEs driven by a GPX file. Use SimConfig.get_ue()
to customize individual UEs afterwards.
SimConfig.add_spawn_zone
Add a spawn zone for procedural UEs as a counter-clockwise
polygon. SimConfig.add_spawn_zone accepts only 2D points and
raises on 3D Position values.
SimConfig.set_num_procedural_ues
Set number of procedural UEs.
SimConfig.set_perc_indoor_procedural_ues
Set percentage of indoor procedural UEs (0—100).
SimConfig.set_ue_speed
Set speed range for procedural UEs in m/s.
SimConfig.enable_urban_mobility
Enable urban mobility simulation with the given number of vehicles.
SimConfig.enable_vegetation
Enable vegetation rendering from GeoJSON data. If geojson_path
is omitted, a default is derived from the scene URL as
<scene_url>/sim/vegetation.geojson. Enabled vegetation also emits
gis.vegetation.vegetation_asset_path from the required
vegetation_assets entry in assets.yml.
SimConfig.add_material_definition
Add a material calibration definition file.
SimConfig.add_material_assignment
Add a material calibration assignment file.
SimConfig.set_calibration_targets
Set the calibration target flags. Call this before the other calibration run configuration methods.
- Parameters
- •
materials(bool) - Calibrate building materials.•veg_materials(bool) - Calibrate vegetation materials.•rus(bool) - Calibrate RU angles.•rus_beams(bool) - Calibrate RU beam settings.•ues(bool) - Calibrate UE angles.
SimConfig.add_calibration_measurement
Add one measured RU/UE link used as a calibration reference. measurement_file must be non-empty. At least one measurement is required before exporting a calibration YAML.
- Parameters
- •
ru_id(int) - RU ID for the measured link.•ue_id(int) - UE ID for the measured link.•measurement_file(str) - Measurement CSV path.
SimConfig.set_calibration_timeline
Set the time indices used for calibration. step must be positive.
- Parameters
- •
start(int) - First time index.•step(int) - Time index stride.•end(int) - Optional final time index.
SimConfig.set_calibration_output
Set the calibration output S3 folder key under the configured bucket. The folder key must be non-empty and is required before exporting a calibration YAML.
SimConfig.set_calibration_execution_mode
Override the calibration execution mode. Typical calibration configs
should leave this unset; when omitted, the calibration pipeline derives
the execution mode from SimConfig.set_calibration_targets().
Use this only when an explicit training bitmask or calibration pipeline
debug mode is required. For example, "0" means debug forward pass;
positive values are calibration-group bitmasks.
SimConfig.set_calibration_keep_local_output
Set whether calibration keeps local output files.
SimConfig.set_bldg_exterior_attr
Convenience wrapper to set RF attributes for exterior buildings.
- Parameters
- •
activate_rf(bool) - Enable RF mesh for exterior surfaces.•activate_diffraction(bool) - Enable diffraction.•activate_diffusion(bool) - Enable diffusion.•activate_transmission(bool) - Enable transmission.•diffuse_surface_element_area(float) - Diffuse surface element area in m^2.•building_ids(list[str]) - Building IDs to target. Empty list = all buildings.
SimConfig.set_bldg_interior_attr
Convenience wrapper to set RF attributes for interior buildings.
- Parameters
- •
activate_rf(bool) - Enable RF mesh for interior surfaces.•activate_diffraction(bool) - Enable diffraction.•activate_transmission(bool) - Enable transmission.•building_ids(list[str]) - Building IDs to target. Empty list = all buildings.
SimConfig.set_ues_height
Set UE height for selected UEs. Empty ids = all UEs.
SimConfig.set_ues_power
Set UE radiated power for selected UEs.
SimConfig.set_rus_power
Set RU radiated power for selected RUs.
SimConfig.to_dict
Convert the configuration to a nested Python dictionary,
compatible with OmegaConf.save().