Development#
CONTRIBUTING.md in the repository gives the conventions for contributions and the rules every regional data source follows.
Environment and checks#
./scripts/setup.sh
conda activate owrt
ruff check .
pytest
OWRT_RELOAD=1 ./scripts/run.sh
The default suite uses synthetic inputs and needs no network access. The setup script
leaves out the large PyTorch wheels, so pytest skips the PyTorch dataset tests until the
torch extra is installed with python -m pip install -e '.[torch]'.
scripts/benchmarks/ times scene compilation from the records of a cached scene, the
provider queries behind one scene, and a cold load_scene, and measures the position error
of OpenCelliD sites against ANFR. Scene compile performance records what the compile
path costs and where the time goes.
The browser tests, the tests against live services and the package tests are opt-in. The browser tests drive the explorer in Chromium, which Playwright downloads outside the repository, and load the page’s scripts from their CDNs:
python -m pip install -e '.[ui-test]'
PLAYWRIGHT_BROWSERS_PATH=/tmp/owrt-playwright playwright install chromium
PLAYWRIGHT_BROWSERS_PATH=/tmp/owrt-playwright OWRT_RUN_GUI_TESTS=1 \
pytest tests/test_building_gui.py tests/test_antenna_gui.py
OWRT_RUN_NETWORK_TESTS=1 pytest tests/test_regional_antennas_network.py
OWRT_RUN_PACKAGE_TESTS=1 pytest tests/test_building_plugin.py
tests/test_regional_antennas_gui.py needs both variables.
Repository map#
src/openworld_radio_twin/
|-- rt.py Sionna-compatible loader and geographic helpers
|-- compiler.py Scene compilation and cache
|-- dataset.py Python dataset interface, loading, indexing and packaging
|-- batch.py Request schema, seeded expansion, generation and resume
|-- models.py Simulation request and response models
|-- antennas.py Antenna selection, channels and placement in a compiled scene
|-- spectrum.py Link direction of registered frequency ranges (3GPP bands)
|-- scenes.py Compiled scenes as the web service displays them
|-- geodesy.py WGS84 to ENU frame
|-- environment.py Terrain grid, surface classes, material profiles
|-- scene_format.py Paths of the scene files
|-- conventions.py Row orders, units, no-data values and dtypes of the written arrays
|-- radio_map_index.py The Parquet index of a dataset or package, one row per radio map
|-- torch_dataset.py PyTorch dataset of radio maps and the random crop (torch extra)
|-- licences.py Licences and credits of the data layers, the dataset LICENSE.md
|-- artifacts.py Bundle export
|-- providers/ Source registry; building sources (Overture, OSM, 3DBAG, Berlin,
| Boston), antenna sources (ANFR, ACMA, Antennebureau, UKE,
| OpenCelliD, local file), terrain, surfaces
|-- engines/ Engine registry and execution adapters
|-- simulation/ Scene builder, Sionna adapter, preview, radio-map contract
|-- main.py FastAPI application
|-- cli.py `owrt` command
`-- web/ Explorer and batch pages
tests/ Tests
examples/ Notebooks, dataset script, Slurm job, plugin example
docs/ This documentation
website/ Project page
Building the documentation#
python -m pip install -e '.[docs]'
cd docs
make html # output in docs/_build/html
The build runs with warnings as errors. Notebooks are rendered from their committed outputs
and are not executed. After executing a tutorial that calls scene.preview(), clear that
cell’s output and the notebook’s metadata.widgets before committing: the viewer’s widget
state takes tens of megabytes and needs a running kernel. make livehtml starts a rebuilding
preview when sphinx-autobuild is installed.
The GitHub Actions workflow in .github/workflows/pages.yml publishes the project page and
this documentation to GitHub Pages on every push to main: the page at the site root and
the documentation under /docs/.
Conventions#
Public behaviour is described only when it exists in the code and is covered by a test.
A change to compiled geometry or materials bumps a version in the scene cache key (scene layout, building mesh schema, geometry revision or RF material profile), and a change to Sionna radio maps bumps the radio-map contract version, so cached scenes and resumable datasets never change silently.
Provider data are kept in the caches under
.cache/and in scene and dataset directories. The repository holds provider data only in the routing boundaries ofproviders/data/, in test modules, figures and notebook outputs (Data sources and attribution).