Planning and generation#
The request#
A dataset request is a validated document with a name, a seed, an output option, a failure
policy (continue_on_error) and a list of scenes. Each scene carries its geometry options
and a radio map space. The Python interface, the batch page and POST /api/batches accept
the same schema. Every object in a request rejects keys it does not define, with two
exceptions. engine_config is checked only for the Sionna engine, when a radio map’s
request is built: at planning, or during generation for a scene that takes its transmitters
from an antenna source. The channels of an antenna selection ignore extra keys, as in the
antenna API.
from openworld_radio_twin.dataset import generate_dataset_sync, plan_dataset
request = {
"dataset_name": "my-radio-dataset",
"random_seed": 2026,
"scenes": [
{
"label": "Amsterdam",
"latitude": 52.3762,
"longitude": 4.8993,
"radius_m": 250,
"include_buildings": True,
"building_source": "auto",
"include_terrain": True,
"material_profile": "itu",
"terrain_resolution_m": 5.0,
"receiver_height_m": 1.5,
"voxel_pitch_m": 3.0,
"radio_maps": {
"strategy": "random", # "fixed" | "random"
"count": 8,
"engine": "sionna", # "preview" | "sionna"
"engine_config": {"device": "cuda"},
"transmitter_count": {"minimum": 1, "maximum": 3},
"frequency_ghz": {"minimum": 3.5, "maximum": 3.5},
"power_dbm": {"minimum": 24, "maximum": 36},
"altitude_m": {"minimum": 15, "maximum": 35},
"offset_radius_m": {"minimum": 0, "maximum": 250},
"azimuth_deg": {"minimum": 0, "maximum": 359},
"downtilt_deg": {"minimum": 0, "maximum": 12},
"antenna_patterns": ["sector"],
"resolutions_m": [5],
"max_depths": [3],
"samples_per_tx": [1_000_000],
"association_metrics": ["sinr"],
},
}
],
}
plan = plan_dataset(request)
print(plan.total_radio_maps, plan.total_receiver_cells, plan.total_initial_ray_samples)
result = generate_dataset_sync(request, output_root="data/generated")
print(result.output_directory, result.manifest_path)
plan_dataset expands the request without provider access or solver execution, so the exact
radio map names, solver seeds, receiver-cell count and initial ray budget can be
inspected first. generate_dataset_sync is for scripts; await generate_dataset(...)
serves notebooks and services. Both own their HTTP client and worker thread, and a request
may also be given as a BatchDatasetRequest model or a path to a JSON file. Copy
examples/generate_dataset.py for a self-contained, environment-configurable script.
Scene fields#
Field |
Default |
Range |
|---|---|---|
|
required |
1 to 80 characters; slugified into the directory name |
|
|
|
|
required |
WGS84 |
|
750 |
100 to 5,000, whole metres |
|
1.5 |
0.1 to 100 |
|
3.0 |
0.5 to 25 |
|
|
|
|
|
any registered ID (Building sources) |
|
|
DEM-following ground when |
|
|
|
|
5.0 |
1 to 100; the terrain grid may not exceed 250,000 cells |
|
|
|
|
|
1 to 80 characters; scenes with the same site share a split when the dataset is packaged (Packaging for release); fixed once the scene exists (Resume and extend) |
Radio map space#
Field |
Default |
Range |
|---|---|---|
|
|
|
|
8 |
1 to 10,000 per scene |
|
|
|
|
|
Sionna keys (Sionna RT) |
|
1 to 3 |
1 to 8 |
|
3.5 |
0.1 to 100; 1 to 10 for Sionna |
|
24 to 36 |
-20 to 80 |
|
15 to 35 |
0 to 1,000, above ground |
|
0 to 250 |
0 to the scene radius |
|
0 to 359 |
0 to 360 exclusive |
|
0 to 12 |
-30 to 90 |
|
|
|
|
|
1 to 200, whole metres; grid limits depend on the solver |
|
|
0 to 8 |
|
|
10,000 to 100,000,000 |
|
|
|
The limit of 10,000 radio maps per scene is a validation limit of the request schema. The number of scenes in a dataset is not limited.
Transmitters from an antenna source#
With antennas set, each radio map of the scene simulates one downlink channel
with the selected antennas inside the scene that transmit on it
(Antennas). The scene acquires the antennas once and stores them in
source_antennas.json, as it stores its buildings, so a resumed dataset uses the same
antennas. channels lists the channels radio maps draw from, such as
[{"low_mhz": 1805, "high_mhz": 1825}]; empty, it means every downlink channel of the
scene’s antennas that the engine supports. A source without frequencies, such as OpenCelliD,
needs the channels listed, and a listed channel no antenna transmits on stops the run.
Random radio maps draw a channel uniformly; fixed ones take the channels in turn.
The resolved channels are stored with the antennas, so a resumed dataset draws from the same
list. The channel sets the carrier and the noise bandwidth. A radio map keeps what
the source records and samples the rest from its ranges: altitude_m for a missing height,
azimuth_deg, downtilt_deg and power_dbm likewise, plus the pattern.
transmitter_count, offset_radius_m and frequency_ghz do not apply. Such radio
maps are named radio_map_0001_<pattern>_registered. The plan counts them in
registered_radio_maps, since their transmitter count, and so their ray count, is known
only once the antennas are acquired. The scene record lists the antenna source, release,
licence and attribution, and each radio map record lists the notes on its
antennas, such as defaults used or antennas assumed on the channel.
Seeded expansion#
Random plans use NumPy’s PCG64. Each radio map derives an independent stream from
SeedSequence([dataset_seed, scene_index, radio_map_index]) with one-based indices; the
fully expanded transmitter coordinates, physical parameters and solver seed are written to
its radio_map_info.json. The scene centre is the origin of every radio map. For sampled
transmitters, the stream draws the solver seed, the transmitter count, the frequency and the
pattern; then, for each transmitter in turn, its distance and bearing from the scene centre
(uniform by area in the offset_radius_m annulus), its altitude, power, azimuth and
downtilt; then the resolution, reflection depth, ray samples and association metric. The
fixed strategy places every transmitter at the inner offset radius due north of the centre.
Rebuilding a plan with the same request and software version produces the same radio maps,
and radio maps 1 to 100 stay unchanged when a scene’s count later grows to 200.
Buildings on flat ground#
The common radio map prediction setting, buildings on flat ground without terrain or surface materials, takes two scene fields:
scene["include_terrain"] = False
scene["material_profile"] = "uniform"
The ground is then a plane at height 0, and the ground, walls and roofs are all ITU concrete.
The terrain AGL height reference of the scene then means height above this plane.
The scene queries no terrain or surface data. It has no terrain/ directory and no surface
classes; its terrain_provider and surface_provider are disabled, and its licences have
no terrain or surface entry. It keeps the building meshes, the height map, the voxel slices
and depth, and on each radio grid the measurement surface, the building rasters and the path
gain (Dataset layout). In PyTorch, the ground elevation is 0 and every surface class is -1.
include_terrain=False alone is not enough: the default itu profile still acquires surface
classes and compiles them on a flat grid (Surfaces and materials).
The draws of a radio map depend on neither field nor on the dataset name. A flat version
generated with the same random_seed and otherwise the same scenes as a terrain version has
the same radio map names, solver seeds, grids and sampled transmitters (position, height above
ground and parameters), so the two versions pair radio map for radio map. Transmitters taken
from an antenna source are placed on the scene’s geometry, so they can differ between the
two versions.
Empty scenes#
scene_mode="empty" is a free-space scene. It performs no building, terrain or
surface query and writes a Sionna scene with no ground or building shapes; the coordinates
still define the local frame and transmitter positions.
{
"label": "Empty free space",
"scene_mode": "empty",
"latitude": 52.3762,
"longitude": 4.8993,
"radius_m": 250,
"radio_maps": {"engine": "sionna", "count": 1},
}
For a flat ground plane without buildings, keep scene_mode="geospatial" and set
include_buildings=False, include_terrain=False and material_profile="uniform"
(see Buildings on flat ground).
Stored arrays and previews#
Every completed radio map stores its radio_map_info.json and one array, the path gain of
each transmitter packed as 16-bit dB values (Dataset layout). RSS, SINR and the serving
transmitter are derived from it when the radio map is loaded, from the transmit powers,
noise power and association metric its record keeps. The only output option adds PNG
previews for inspection, rendered from the engine’s in-memory arrays:
request["output"] = {"previews": True} # default False
Packages leave the previews out (Packaging for release). The example script sets them with
OWRT_EXAMPLE_PREVIEWS. The option is fixed for the lifetime of a dataset (Resume and extend),
so changing it needs a new dataset. Shared scene assets, including terrain arrays and the
building rasters of each measurement surface, are written either way.
Execution model#
Radio maps of a dataset run one at a time, in one worker thread. Sionna availability is checked before any provider
access. A non-resume run never overwrites an existing dataset; a dataset directory is locked
while it is being written. A failed radio map stops the run. With continue_on_error=True
in the request, the run records the failure and continues, and the scene and the dataset end
as completed_with_errors. Progress callbacks receive the completed count, total count and a
message. OWRT_DATASET_ROOT sets the default output root (data/generated).