openworld_radio_twin.dataset#

High-level Python interface for reproducible dataset generation.

Functions

build_index(dataset_dir)

Rebuild index.parquet of a generated dataset and return its path.

generate_dataset(source, *[, output_root, ...])

Generate a dataset without starting the web service.

generate_dataset_sync(source, *[, ...])

Generate, resume, or deterministically extend a dataset from a normal script.

load_dataset_request(source)

Validate a model, mapping, or JSON file as a batch dataset request.

load_radio_map(path)

Load a completed radio map from its directory or its radio_map_info.json.

package_dataset(dataset_dir, output_dir, *)

Package a generated dataset for release: one zstd-compressed tar per scene, splits, index and checksums.

plan_dataset(source)

Expand a dataset request without provider access or solver execution.

read_index(root)

Read the index of a generated dataset or of a package, refusing a stale one.

Classes

DatasetGenerationResult(output_directory, plan)

Completed dataset location together with its deterministic expanded plan.

RadioMap(directory, record, grid, path_gain, ...)

A generated radio map: its record and the arrays derived from its stored path gain.

class openworld_radio_twin.dataset.DatasetGenerationResult(output_directory, plan)[source]#

Bases: object

Completed dataset location together with its deterministic expanded plan.

output_directory: Path#
plan: BatchPlan#
property manifest_path: Path#
property index_path: Path#
read_manifest()[source]#

Read the completed dataset manifest.

Return type:

dict[str, Any]

class openworld_radio_twin.dataset.RadioMap(directory, record, grid, path_gain, rss, sinr, association)[source]#

Bases: object

A generated radio map: its record and the arrays derived from its stored path gain.

path_gain, rss (W) and sinr are linear float32 arrays with shape (n_tx, rows, columns), and association is the int32 serving transmitter with shape (rows, columns), -1 where no transmitter serves the cell. Rows run south to north on the grid grid. RSS, SINR and the serving transmitter follow the engine’s definition applied to the stored path gain, whose dB value is rounded to 0.01 dB steps (at most 0.005 dB off). RSS shares this bound; SINR can be off by up to twice it, because signal and interference are rounded independently. The derived values are therefore not the engine’s own values bit for bit, and a near tie can change the serving transmitter. The float32 path gain keeps that bound down to -379.3 dB, the smallest normal float32; below it float32 holds fewer digits, and stored values of -451.55 dB and below load as 0.

directory: Path#
record: dict[str, Any]#
grid: GridMapping#
path_gain: ndarray#
rss: ndarray#
sinr: ndarray#
association: ndarray#
property path_gain_db: ndarray#

Path gain in dB, -inf where it is 0.

property rss_dbm: ndarray#

Received power in dBm, -inf where it is 0.

property sinr_db: ndarray#

SINR in dB, -inf where it is 0.

openworld_radio_twin.dataset.build_index(dataset_dir)[source]#

Rebuild index.parquet of a generated dataset and return its path.

A run rebuilds the index when it ends; this rebuilds it after a run that was stopped before, for the manifest’s index_revision. It takes the generation lock, so it refuses while a run, a packaging job or another rebuild holds it, and it requires the version that created the dataset. A package is refused: packaging writes its index.

Return type:

Path

async openworld_radio_twin.dataset.generate_dataset(source, *, output_root=None, settings=None, progress=None, resume=False)[source]#

Generate a dataset without starting the web service.

The function owns and closes its HTTP client and worker thread. Use this asynchronous entry point from notebooks, services, or existing event loops. For ordinary scripts, use generate_dataset_sync(). Set resume=True to skip complete radio maps and regenerate missing ones in a compatible existing dataset.

Return type:

DatasetGenerationResult

openworld_radio_twin.dataset.generate_dataset_sync(source, *, output_root=None, settings=None, progress=None, resume=False)[source]#

Generate, resume, or deterministically extend a dataset from a normal script.

Return type:

DatasetGenerationResult

openworld_radio_twin.dataset.load_dataset_request(source)[source]#

Validate a model, mapping, or JSON file as a batch dataset request.

Return type:

BatchDatasetRequest

openworld_radio_twin.dataset.load_radio_map(path)[source]#

Load a completed radio map from its directory or its radio_map_info.json.

The path gain is unpacked from its stored uint16 dB values. RSS is the transmit power times the path gain; the SINR of a transmitter is its RSS over the sum of the other transmitters’ RSS plus the noise power, summed in float64; the serving transmitter has the largest value under the recorded association metric, the first one on a tie.

Return type:

RadioMap

openworld_radio_twin.dataset.package_dataset(dataset_dir, output_dir, *, fractions=mappingproxy({'train': 0.8, 'validation': 0.1, 'test': 0.1}), seed=0, skip_unreleasable=False, previous=None)[source]#

Package a generated dataset for release: one zstd-compressed tar per scene, splits, index and checksums.

Only complete radio maps are packaged, by the check resume uses. Scenes are assigned to the splits in groups: scenes whose squares overlap and scenes with the same site share a split. With previous, an earlier package of the dataset or its splits.json, groups with scenes of that package keep their split and only new groups are assigned; a group that joins scenes of different previous splits is refused. A scene with a layer whose licence is not recorded or does not allow redistribution, or with CC BY-SA 4.0 and ODbL layers together, is refused; with skip_unreleasable=True it is left out and named in the package’s README.md. Returns the output directory, which must not exist or be an empty directory.

Return type:

Path

openworld_radio_twin.dataset.plan_dataset(source)[source]#

Expand a dataset request without provider access or solver execution.

Return type:

BatchPlan

openworld_radio_twin.dataset.read_index(root)[source]#

Read the index of a generated dataset or of a package, refusing a stale one.

The index is stale when its recorded index_revision is not the manifest’s: a run is writing the dataset, or one stopped before it could rebuild the index. Once no run is active, owrt dataset index DATASET rebuilds the index of a generated dataset; packaging writes the index of a package.

Return type:

Table