Install¶

rfgen requires Python 3.11 or later. The examples in this documentation use Python 3.11. Create an isolated environment before installing. This repository does not document a registry install named rfgen; install a source checkout editably. Contributors who need to validate a release artifact should use Build and verify a release wheel.

Install a source checkout with uv¶

uv is the documented installer. Install it first if uv --version is not available, then let it obtain the Python version used by this guide, create an environment, and install this checkout. The core package includes native Signal Dataset persistence. The narrowband-baseline Golden Path explicitly selects a TorchSig emitter and the 3GPP TR 38.901 Urban Microcell (UMi) propagation model, an urban-microcell propagation scenario, so install both extras before running that template. Run these commands from the repository root (the directory that contains pyproject.toml). Signal Dataset 0.2 is installed by the core dependency set:

uv python install 3.11
uv venv --python 3.11 .venv-rfgen
. .venv-rfgen/bin/activate
uv pip install -e '.[torchsig,sionna]'

Verify that the command is installed and that the editable distribution is registered in this environment:

rfgen --help
python -c 'import importlib.metadata as m; print(m.version("rfgen"))'
python -c 'import rfgen; print(rfgen.__file__)'

For this editable source installation, rfgen.__file__ should point to this checkout’s src/rfgen/__init__.py; its distribution metadata is registered in .venv-rfgen. Keep this environment active for the tutorials. Do not set PYTHONPATH to make an uninstalled checkout importable.

Conda environment alternative¶

If you use Conda to manage Python environments, create a Python 3.11 environment with Conda and use uv pip to install rfgen into it:

conda create --name rfgen python=3.11
conda activate rfgen
cd /path/to/rf-data-generation
uv pip install -e .
rfgen --help

uv remains the dependency installer in this path; Conda supplies the isolated Python environment.

Extras¶

For a source checkout, install only the feature set you need by replacing the extras in the editable command; these commands do not refer to a published rfgen[...] distribution. The table lists the extras these guides use most. pyproject.toml is authoritative for the full set, and extras combine: uv pip install -e '.[torchsig,gcs]'.

Need	Install from the repository root
Native local Signal Dataset generation	`uv pip install -e .`
Native Signal Dataset on GCS	`uv pip install -e '.[gcs]'`
Narrowband classifier Golden Path	`uv pip install -e '.[torchsig,sionna]'`
Direct Gemini annotation	`uv pip install -e '.[gemini]'`
Annotating a `gs://` Signal Dataset snapshot	`uv pip install -e '.[gemini,gcs]'`
Every annotation route plus generation	`uv pip install -e '.[torchsig,sionna,gemini,remote-annotation,gcs]'`
The remote annotation route, end to end	`uv pip install -e '.[remote-annotation,gcs]'` (you generate the source dataset as well as annotate it)
Sharded Parquet publication of a derivative release	`uv pip install -e '.[parquet]'`
USD scene-plan export (`rfgen export-plan`)	`uv pip install -e '.[usd]'`
Hook-based plugins	`uv pip install -e '.[plugin-hooks]'`
Prometheus metrics sink	`uv pip install -e '.[prometheus]'`
Sionna propagation	`uv pip install -e '.[sionna]'`
ADS-B emitter	`uv pip install -e '.[adsb]'`
Radar response (default `sionna_rt` backend: ray-cast visibility, closed-form returns)	`uv pip install -e '.[sionna]'`
RadarSimPy validation-only radar oracle	no extra to install; see the RadarSimPy note below the table.

RadarSimPy is not distributed on the configured PyPI index (a plain pip install radarsimpy 404s), so it is not declared as a pyproject.toml extra at all: a Requires-Dist line is a promise to an installer that some configured index can satisfy it, and none can. First install an authorized, platform-matched RadarSimPy artifact per its provider instructions and make it importable: for example, add the directory that contains the radarsimpy package to PYTHONPATH. RadarSimPy enforces license tiers at runtime, so verify that your artifact’s tier admits your configured scene and intended use before generating; see the radar backend policy.

The version rfgen’s radar-response validation suite was actually run against (radarsimpy>=15.3,<15.4) is recorded as a checked fact instead: read radarsimpy_qualified_version under [tool.rfgen] in pyproject.toml, and run pytest tests/unit/test_radarsimpy_oracle_version.py once your artifact is on PYTHONPATH to check the installed version against it. That test skips and reports why, instead of passing, when RadarSimPy is absent, which is the ordinary case for every install that does not need the oracle.

A Java runtime for local Spark¶

remote-annotation pulls in PySpark, and pip cannot supply the JVM that PySpark needs. Local annotation starts no Spark session and needs no JVM, and execution_mode: dataproc_serverless runs Spark on the service instead.

This project pins pyspark>=3.5,<4, and Spark 3.5 supports Java 8, 11, or 17. A current default JDK (21 or newer) is outside that range and fails when the session starts, so install 17 explicitly and point JAVA_HOME at it:

brew install openjdk@17                    # macOS; use your distro's package manager on Linux
export JAVA_HOME=/opt/homebrew/opt/openjdk@17
java -version                              # expect 17.x

Point PySpark at the same interpreter the CLI runs under, in the same shell:

export PYSPARK_PYTHON="$(which python)"    # from the activated virtual environment
export PYSPARK_DRIVER_PYTHON="$PYSPARK_PYTHON"

Spark launches its Python workers as fresh processes, and it uses whatever python3 is first on PATH unless told otherwise. When that interpreter is not the one holding your rfgen install, the session starts and then fails mid-run with a long Java stack trace ending in PYTHON_VERSION_MISMATCH. The two exports above rule that out before it happens.

The lora-sdr, wifi, ble, and zigbee extras do not download their GNU Radio out-of-tree modules. Install GNU Radio plus the required module through Conda or your system package manager first, then add the corresponding empty project extra (for example, uv pip install -e '.[lora-sdr]') to declare the selected backend. lora-phy likewise requires a separately supplied loraphy package; there is no canonical PyPI release. The lte extra requires an srsRAN runtime exposed through ZMQ and does not install that runtime.

The core package does not install managed-cloud, release-signing, catalog, or telemetry integrations.