Enums

Warning

Pre-implementation. This page describes proposed contracts. Class signatures, parameter types, config field names, and behavior are subject to change before code lands. Once implementation exists, content here will be regenerated from docstrings or sourced from running tests.

Closed-set string enumerations live in rfgen.enums as StrEnum types. They appear as the type of every config field whose set of valid values is fixed and owned by the framework: placement modes, antenna geometries, model families, storage backends, and so on.

This page appears first in the API Reference because these enums are primitive vocabulary for later pages. Core Types and Config reference enum members, but the enums themselves do not depend on framework data types.

Why StrEnum and not Literal[str, ...]:

  • YAML / Hydra stays clean. A StrEnum member is a string at runtime, so record_axis: per_rx in a Hydra config deserializes correctly into RecordAxis.PER_RX.

  • Pydantic validates at the boundary. Unknown values are rejected at config load with a clear error, identical to Literal[...].

  • No magic strings inside the framework. Plugin code references RecordAxis.PER_RX symbolically. IDE autocomplete works; renaming a value is a single-file change instead of a global grep.

  • Single source of truth. Each enumeration is defined once in rfgen.enums and imported wherever it appears.

Open-set names are different: registered plugin names like the name field on ChannelConfig and ExecutorConfig are str, not enums, because anyone can ship a new plugin with pip install and the registry resolves the name at runtime. See background/design-decisions for the full rule.

YAML / Hydra usage

YAML has no enum literal syntax, so configs always use the string value of the enum member. Pydantic v2 coerces by value at validation time, and because StrEnum members are their string values at runtime, the round-trip is transparent:

# configs/storage/per_rx.yaml
storage:
  record_axis: per_rx          # the string value of RecordAxis.PER_RX
  backend: zarr                # StorageBackend.ZARR
  compression: blosc           # Compression.BLOSC

cfg = StorageConfig.model_validate(yaml_dict)
cfg.record_axis                            # RecordAxis.PER_RX
cfg.record_axis is RecordAxis.PER_RX       # True
cfg.record_axis == "per_rx"                # True (StrEnum members are strings)

Two pitfalls to avoid:

  • Do not write record_axis: PER_RX (the member name). Pydantic looks up by value, not by name, so "PER_RX" is rejected.

  • Do not wrap the enum in a Hydra _target_: block. That pattern is for instantiating classes (channels, emitters), not enum values. The plain-string form is the standard Pydantic + Hydra idiom.

In Python code and in prose, prefer the symbolic form (RecordAxis.PER_RX) over the magic string. In YAML, the string is the only form.

Scene composition

class rfgen.enums.ChannelApplicationMode

class ChannelApplicationMode(StrEnum):
    SCENE       = "scene"
    PER_EMITTER = "per_emitter"

Selects where the propagation channel runs relative to the per-emitter IQ summation in SceneConfig.

  • SCENE (default): each emitter is frequency-shifted into the wideband scene buffer, all N emitter signals are summed, and propagation runs once on the composite IQ. One propagation call per scene. Use for single-receiver or spatially co-located TX configurations.

  • PER_EMITTER: propagation is realized independently per emitter, applied per-emitter at scene SR, and the results are summed after. N propagation calls per scene. Required for distributed-TX ray-traced scenes (e.g. V2X intersections, distributed uplinks) where TX positions are spatially diverse enough that each TX has a meaningfully different propagation path.

In YAML, use the string value: channel_application: scene or channel_application: per_emitter.

See Reference / Scene Composition Algorithm § Channel application mode for the full mode-comparison table.

class rfgen.enums.DensityMode

class DensityMode(StrEnum):
    FIXED   = "fixed"
    UNIFORM = "uniform"
    POISSON = "poisson"

Selects how the DensityConfig draws an emitter count per scene. See Concepts / Scenes / Composition.

class rfgen.enums.FrequencyPlacementStrategy

class FrequencyPlacementStrategy(StrEnum):
    IID_UNIFORM    = "iid_uniform"
    STRATIFIED     = "stratified"
    CLUSTERED      = "clustered"
    ISM_REALISTIC  = "ism_realistic"
    FORCED_OVERLAP = "forced_overlap"

Selects how the scene composer places each emitter in frequency. Python code should use members such as FrequencyPlacementStrategy.IID_UNIFORM; YAML uses the value, such as iid_uniform.

class rfgen.enums.TimePlacementStrategy

class TimePlacementStrategy(StrEnum):
    IID_UNIFORM     = "iid_uniform"
    EVENT_TIMED     = "event_timed"
    PRI_PULSE_TRAIN = "pri_pulse_train"
    ADSB_CADENCE    = "adsb_cadence"
    FHSS_DWELLS     = "fhss_dwells"
    WIFI_TBTT       = "wifi_tbtt"
    BLE_ADVERTISING = "ble_advertising"

Selects how the scene composer places each emitter in time. EVENT_TIMED is the high-level config choice for protocol-aware timing; protocol-specific strategies are used by lower-level planners or presets when the protocol family is known.

class rfgen.enums.ScenePowerMode

class ScenePowerMode(StrEnum):
    UNIFORM_DB            = "uniform_db"
    LOG_UNIFORM           = "log_uniform"
    LOG_NORMAL_HEAVY_TAIL = "log_normal_heavy_tail"
    SIONNA_ABSOLUTE_POWER = "sionna_absolute_power"

Selects whether composition assigns target SNR-like priors or absolute TX/RX power inputs for Sionna-backed propagation.

class rfgen.enums.SceneOverlapPolicy

class SceneOverlapPolicy(StrEnum):
    REJECT = "reject"
    ALLOW  = "allow"
    FORCE  = "force"

Selects how the composer handles time-frequency overlap between placed emitters. ALLOW is the probabilistic mode; the per-draw probability lives on the SceneOverlapPolicyConfig’s p_overlap field.

class rfgen.enums.ArrayGeometry

class ArrayGeometry(StrEnum):
    ULA       = "ula"
    URA       = "ura"
    ARBITRARY = "arbitrary"

Antenna array geometry kind for MultiRXConfig.geometry. The geometry kind picks the array layout family; per-array element counts and spacings live on the sibling array-shape fields. MultiRXConfig rejects setting geometry together with a non-empty receivers list (the geometry-XOR-receivers validator).

class rfgen.enums.SceneGeometryBackend

class SceneGeometryBackend(StrEnum):
    NONE      = "none"
    SIONNA_RT = "sionna_rt"
    MITSUBA   = "mitsuba"

Scene-geometry backend selector for SceneGeometryConfig.backend. Member values are lowercase to match YAML and the rest of the framework’s closed-set config strings. Legacy "SionnaRT" and "Mitsuba" spellings still coerce for backward compatibility. Picking SIONNA_RT requires SceneConfig.assets.scene_geometry_uri; the SionnaRT-requires-assets validator on SceneConfig enforces this and raises with loc=("assets", "scene_geometry_uri").

Channels

class rfgen.enums.Group

class Group(IntEnum):
    TX          = 1
    CHANNEL     = 2
    RX_CAPTURE  = 3
    RX_HARDWARE = 4

Pipeline group tag used by ChannelPipeline to validate chain partition membership. TX and CHANNEL belong to the pre-sum partition; RX_CAPTURE and RX_HARDWARE belong to the post-sum partition. See ChannelPipeline for the validation contract.

class rfgen.enums.Transformation

class Transformation(IntEnum):
    # TX impairments
    DAC_QUANTIZATION  = 11
    PA_NONLINEARITY   = 12
    TX_PHASE_NOISE    = 13
    TX_IQ_IMBALANCE   = 14
    CFO               = 15

    # Channel propagation
    CHANNEL           = 21

    # RX capture
    RX_MIXER          = 31
    IF_FILTER         = 32
    RESAMPLER         = 33
    LNA_NOISE         = 34

    # RX hardware
    ADC_QUANTIZATION  = 41
    RX_PHASE_NOISE    = 42
    RX_IQ_IMBALANCE   = 43
    AGC               = 44

Transformation tag pinned on every concrete BaseChannel subclass as a ClassVar[Transformation]. The integer value is an implementation detail used by ChannelPipeline to validate monotonic non-decreasing ordering within each chain partition.

Emitters and channels

class rfgen.enums.Direction

class Direction(StrEnum):
    UPLINK   = "uplink"
    DOWNLINK = "downlink"

Cellular link direction for Sionna propagation backends (SionnaUMa, SionnaUMi, SionnaRMa). UPLINK means UE transmits, BS receives; DOWNLINK means BS transmits, UE receives. Passed directly to the upstream Sionna scenario class.

class rfgen.enums.EmitterFamily

class EmitterFamily(StrEnum):
    COMMS    = "comms"
    RADAR    = "radar"
    DRONE    = "drone"
    IOT      = "iot"
    ADSB     = "adsb"
    CELLULAR = "cellular"

Coarse emitter family used by EmitterFamilyConfig. New families require a framework version bump; emitter plugins within a family do not. The DRONE member is reserved for a future drone-emitter expansion; no concrete drone emitter binds to it in this release (see the Deferred for future emitter expansion catalog section).

class rfgen.enums.LoRaBackend

class LoRaBackend(StrEnum):
    GR_LORA_SDR = "gr-lora-sdr"
    LORA_PHY    = "lora-phy"

LoRa-emitter backend selector consumed by the scene composer when it instantiates a LoRa emitter from the configured zoo. "gr-lora-sdr" selects the default LoRaSdrEmitter (gr-lora_sdr GNU Radio OOT module); "lora-phy" selects the pure-Python fallback LoRaPHYEmitter (loraphy library).

class rfgen.enums.PAModel

class PAModel(StrEnum):
    NONE  = "none"
    RAPP  = "rapp"
    SALEH = "saleh"

Power-amplifier nonlinearity model on FingerprintConfig. See Reference / Fingerprint Math.

class rfgen.enums.SNRDistribution

class SNRDistribution(StrEnum):
    UNIFORM               = "uniform"
    LOG_UNIFORM           = "log_uniform"
    LOG_NORMAL_HEAVY_TAIL = "log_normal_heavy_tail"

SNR sampling distribution selector on ChannelConfig. The shipped ChannelConfig.snr_distribution field is typed open str (registry-resolved); promoting it to a closed StrEnum is a deferred Layer 3+ decision.

Annotations

class rfgen.enums.AnnotationProvider

class AnnotationProvider(StrEnum):
    GEMINI    = "gemini"
    ANTHROPIC = "anthropic"
    OPENAI    = "openai"
    NONE      = "none"

Inference provider selector on AnnotatorConfig.

class rfgen.enums.AnnotationType

class AnnotationType(StrEnum):
    CAPTION      = "caption"
    QA           = "qa"
    REASONING    = "reasoning"
    SCENE_REPORT = "scene_report"
    CONTRASTIVE  = "contrastive"

Annotation kind requested from the inference client. Multi-valued: AnnotatorConfig.types is a list[AnnotationType].

Labels

class rfgen.enums.SegmentationMode

class SegmentationMode(StrEnum):
    SINGLE_LABEL = "single_label"
    MULTI_LABEL  = "multi_label"

Segmentation mask layout selector for LabelConfig.segmentation_mode and SegmentationLabeler.

class rfgen.enums.SegmentationTieBreak

class SegmentationTieBreak(StrEnum):
    LOWER_EMITTER_INDEX = "lower_emitter_index"

Single-label overlap policy for LabelConfig.segmentation_tie_break and SegmentationLabeler.

Storage

class rfgen.enums.StoreMode

class StoreMode(StrEnum):
    READ   = "read"
    WRITE  = "write"
    APPEND = "append"

Open mode for BaseStore.open. WRITE creates or truncates; READ opens read-only; APPEND opens an existing dataset for non-truncating writes while preserving prior records and schema metadata.

class rfgen.enums.StorageBackend

class StorageBackend(StrEnum):
    ZARR_LOCAL = "zarr_local"
    ZARR_GCS   = "zarr_gcs"
    ZARR_S3    = "zarr_s3"
    ZARR_AZURE = "zarr_azure"
    WEBDATASET = "webdataset"
    HDF5       = "hdf5"
    SIGMF      = "sigmf"

On-disk format selector on StorageConfig.

class rfgen.enums.RecordAxis

class RecordAxis(StrEnum):
    PER_RX = "per_rx"
    JOINT  = "joint"

Multi-RX record layout: PER_RX emits one record per receiver (default; standard single-RX shape (2, N)); JOINT emits one record per scene with a leading RX axis on the IQ tensor. See Concepts / Records, Receivers, and Assets.

class rfgen.enums.GeometryAssetKind

class GeometryAssetKind(StrEnum):
    SIONNA_BUILTIN_SCENE        = "sionna_builtin_scene"
    MITSUBA_XML_BUNDLE          = "mitsuba_xml_bundle"
    OPENGERT_MITSUBA_XML_BUNDLE = "opengert_mitsuba_xml_bundle"
    MATERIAL_DB                 = "material_db"
    ANTENNA_PATTERN             = "antenna_pattern"
    DEEPMIMO_EXPORT             = "deepmimo_export"

Typed geometry-related asset categories carried on GeometryAssetRef.kind. SIONNA_BUILTIN_SCENE and MITSUBA_XML_BUNDLE/OPENGERT_MITSUBA_XML_BUNDLE are the two kinds SionnaRT resolves into a loadable Sionna scene (see GeometryAssetRef); MATERIAL_DB and ANTENNA_PATTERN identify material-database and antenna-pattern blobs; DEEPMIMO_EXPORT identifies a DeepMIMO dataset export.

See Also