Install¶

Warning

Pre-implementation. The framework is not yet on PyPI. The instructions below describe the target install experience for v0; until then, install from a development branch.

Requirements¶

Requirement	Version
Python	3.11+
OS	Linux (primary), macOS (development), Windows (best-effort via WSL)
GPU	Optional. CPU is enough for quickstart and non-ray-tracing examples. Sionna ray tracing (Sionna RT) can use Dr.Jit’s LLVM backend on CPU. Linux wheels may provide a usable LLVM runtime; on macOS ARM64, install LLVM separately and set `DRJIT_LIBLLVM_PATH` as shown below. An NVIDIA GPU (CUDA / OptiX) is optional and accelerates ray tracing and large batch generation.
Memory	16 GB+ for narrowband examples; 32 GB+ for wideband examples such as 200 million samples per second (Msps), multi-second scenes.

Install¶

# Once published to PyPI (target: v0):
pip install rfgen

# During pre-release, from a development branch or pinned commit:
pip install "git+https://github.com/superpose-labs/rf-data-generation.git@<branch-or-commit>"

# SSH works too if your GitHub key is configured:
pip install "git+ssh://git@github.com/superpose-labs/rf-data-generation.git@<branch-or-commit>"

Optional extras¶

Extras install optional waveform, propagation, annotation, and distributed-compute backends. The base package is enough to inspect configs and use the minimal command surface; install extras when a preset or backend requires them.

Extra	What it pulls in	When you need it
`[sionna]`	sionna >= 2.0.1 and < 2.1, the validated Sionna PHY / RT range, plus its transitive Mitsuba / Dr.Jit ray-tracing dependencies	A channel chain whose propagation transform is `sionna_rt`, `sionna_uma`, `sionna_umi`, `sionna_rma`, `sionna_tdl`, or `sionna_cdl`
`[torchsig]`	torchsig >= 2.1.1 and < 2.2, the tested TorchSig v2.1 API range	TorchSig-backed comms emitters; HDF5 interop with `[hdf5]`
`[hdf5]`	h5py >= 3.10	HDF5 storage and TorchSig HDF5 interop
`[lora-sdr]`	No PyPI packages; requires GNU Radio plus `gr-lora_sdr` from conda or a system package manager	LoRa SDR wrapper
`[lora-phy]`	No PyPI packages; requires the LoRaPHY runtime installed separately	LoRa PHY wrapper
`[lte]`	No PyPI packages; requires `srsran` C++ runtime exposed through ZMQ	LTE emitter
`[radarsim]`	radarsimpy >= 11.0	High-fidelity radar backend
`[openai-batch]`	openai	OpenAI-hosted Phase 2 annotation and batch jobs
`[anthropic-batch]`	anthropic	Anthropic-hosted Phase 2 annotation and batch jobs
`[gcp]`	google-cloud-storage, google-cloud-aiplatform, google-auth, google-genai	Gemini, GCP storage, and Vertex Batch paths
`[aws]`	boto3	AWS-backed storage / orchestration paths
`[azure]`	azure-ai-ml, azure-identity, azure-storage-blob	Azure-backed storage and Azure ML batch paths
`[torch]`	torch >= 2.1	PyTorch dataset adapter and DataLoader integration
`[webdataset]`	webdataset >= 0.2	WebDataset storage
`[sigmf]`	sigmf >= 1.2	SigMF export
`[dev]`	pytest, mypy, ruff	Local development and validation

# Typical setup for a Phase-1 generation workstation
pip install "rfgen[torchsig,sionna]"

# HDF5/TorchSig interop needs both extras
pip install "rfgen[torchsig,hdf5]"

# Add annotation SDKs only when generating Phase-2 captions or reports
pip install "rfgen[openai-batch,anthropic-batch,gcp]"

# Local vLLM uses the OpenAI-compatible HTTP client in core
pip install rfgen

# CI / minimal
pip install rfgen

Verify¶

rfgen version
rfgen doctor --json
# rfgen 0.0.0.dev0

rfgen list-emitters | head
# comms      torchsig_adapter      bpsk, qpsk, 16qam, 64qam, ofdm, ...
# radar      pulse, fmcw, lfm
# ...

Verify signed release evidence¶

rfgen release verify is an application boundary, not a standalone evidence resolver. Before invoking it, the embedding application must install a runtime with configure_release_verification_runtime(factory). The factory receives the parsed ReleaseManifestV1, the Path | None supplied by --offline-bundle, and the integer timeout; it returns ReleasePromotionOutcomeV1.

rfgen release verify release-manifest.json --offline-bundle ./release-bundle --json --timeout 900

The embedding application resolves the offline directory into OfflineBundleIndexV1, builds ReleaseVerificationInputsV1, and configures the verifier’s policy, evidence reader, and trust boundary. The CLI does not discover an index or synthesize those inputs. If no factory is configured, it returns exit 6 with the redacted JSON error RUNTIME_UNCONFIGURED.

When a factory is installed, --offline-bundle passes its directory path to that factory. Offline verification does not fall back to network trust retrieval. --timeout accepts 1 through 3600 seconds; the default is 900. The JSON result includes the self-hashed verification report and, only after a complete offline pass, any Chapter 7 receipt and release-qualified status records.

The command returns 0 on success; 2 for invocation or schema failures; 3 for trust, signature, or transparency failures; 4 for artifact or evidence-hash failures; 5 for support or gate failures; and 6 for a deadline or internal runtime failure. See Release evidence verification for the full artifact, receipt, and offline-trust contract.

Sionna RT CPU and GPU backends¶

Sionna RT requires either a working Dr.Jit LLVM CPU backend or CUDA / OptiX. The Python extra installs Sionna, Mitsuba, and Dr.Jit, but it cannot guarantee that the operating system exposes a compatible LLVM shared library. On macOS ARM64 with a conda environment, install LLVM and point Dr.Jit at it explicitly:

conda install -n superpose_py311 -c conda-forge llvmdev
export DRJIT_LIBLLVM_PATH="$CONDA_PREFIX/lib/libLLVM.dylib"

python -c "import sionna.rt, mitsuba; print(mitsuba.variant())"
# llvm_ad_mono_polarized

Keep DRJIT_LIBLLVM_PATH set when running Sionna RT commands or tests. If sionna.rt raises an error saying libLLVM.dylib or libLLVM.so cannot be found, the top-level sionna package is installed but the RT backend is not usable yet.

GPU acceleration is optional and is most useful for production-scale or large batch generation. CUDA / OptiX moves the ray-tracing solve onto the GPU, which matters when running many scenes back-to-back rather than the single-scene examples on this page. Verify PyTorch GPU visibility:

python -c "import torch; print(torch.cuda.is_available())"
# True

If this prints False, use the LLVM setup above. A real SionnaRT test run on macOS ARM64 with Sionna 2.0.1 and the llvm_ad_mono_polarized variant produced finite RT solves without a GPU. For GPU setup, follow the PyTorch install selector, the Sionna installation notes, and the Mitsuba installation notes for CUDA / OptiX support.

Install¶

Requirements¶

Install¶

Optional extras¶

Verify¶

Verify signed release evidence¶

Sionna RT CPU and GPU backends¶

Troubleshooting¶

Next: Quickstart →¶