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

label

required

1 to 80 characters; slugified into the directory name

scene_mode

"geospatial"

"empty" disables every environment query

latitude, longitude

required

WGS84

radius_m

750

100 to 5,000, whole metres

receiver_height_m

1.5

0.1 to 100

voxel_pitch_m

3.0

0.5 to 25

include_buildings

true

building_source

"auto"

any registered ID (Building sources)

include_terrain

false

DEM-following ground when true, flat plane when false

material_profile

"itu"

"itu" or "uniform"; with include_terrain=false, see Buildings on flat ground

terrain_resolution_m

5.0

1 to 100; the terrain grid may not exceed 250,000 cells

antennas

null

{"source", "operator", "radio", "channels"}: take the transmitters from an antenna source

site

null

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

strategy

"random"

"fixed" uses the minimum of every range and the first entry of every list

count

8

1 to 10,000 per scene

engine

"preview"

"preview" or "sionna"

engine_config

{}

Sionna keys (Sionna RT)

transmitter_count

1 to 3

1 to 8

frequency_ghz

3.5

0.1 to 100; 1 to 10 for Sionna

power_dbm

24 to 36

-20 to 80

altitude_m

15 to 35

0 to 1,000, above ground

offset_radius_m

0 to 250

0 to the scene radius

azimuth_deg

0 to 359

0 to 360 exclusive

downtilt_deg

0 to 12

-30 to 90

antenna_patterns

["sector"]

"sector", "isotropic"

resolutions_m

[15]

1 to 200, whole metres; grid limits depend on the solver

max_depths

[3]

0 to 8

samples_per_tx

[1000000]

10,000 to 100,000,000

association_metrics

["sinr"]

"path_gain", "rss", "sinr"

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).