Receiver stages¶

The public receiver chain is authored as typed graph nodes. There is no separate rfgen.receiver.stages plugin hierarchy: each effect registers in the open rfgen.nodes.transform role, declares its measurement plane and ordering stage, and binds ordinary typed values.

For the complete Python construction surface, see Nodes. This page collects the receiver-specific sequence and migration rules in one place.

Causal sequence¶

propagation / pathloss
  -> receiver_input_boundary
  -> equivalent-input noise
  -> receiver analog processing
  -> converter
  -> receiver digital processing

The graph checker follows this sequence through ordinary signal transforms, combiners, selects, conditionals, repeats, and subgraph calls. A stage-less transform inherits the stage of its realized complex-voltage inputs; it cannot hide a backwards edge. Cycles and unresolved container aliases fail closed.

The enforced receiver constants, in increasing order, are:

Constant	Meaning
`RECEIVER_INPUT_BOUNDARY`	The checked transition after final propagation.
`RECEIVER_EQUIVALENT_INPUT_NOISE`	Noise referred to the receiver input.
`RECEIVER_ANALOG`	Analog gain, filtering, imbalance, and protection effects.
`RECEIVER_CONVERTER`	Scale, round, clip, and reconstruct effects.
`RECEIVER_DIGITAL`	Post-converter receiver processing.

Noise before propagation, AGC before equivalent-input noise, conversion before analog processing, and a receiver-analog limiter after conversion are refused. AGC and a receiver voltage limiter share the analog interval; rfgen does not invent a relative order between them.

Receiver-input boundary¶

receiver_measurement is a PLAN node. It cites one receiver setup and authors:

receiver index and identity;
measurement_plane = "receiver_input";
nominal bandwidth and separately authored effective noise bandwidth (ENBW);
receiver noise figure; and
impedance.

Nominal bandwidth and ENBW are not aliases. Thermal noise uses ENBW. These are declared receiver facts, not a claim that a physical filter was calibrated.

receiver_input_boundary must immediately follow the final propagation or pathloss producer. Its canonical inputs are the realized signal and facts from that same upstream producer, PLAN receiver measurement facts, and PLAN posed PropagationEndpointFacts or pose-free PropagationLinkFacts for the same authoritative link. It passes the complex64-volts payload unchanged, establishes the exact receiver_input qualifier, and publishes ReceiverInputBoundaryFacts with receiver, plane, link, grid, bandwidth, noise-figure, and impedance evidence.

The checked implementation contract is ReceiverInputBoundaryProducer. An arbitrary transform cannot forge the boundary by declaring a boolean or output qualifier. Graph lineage resolves the exact checked producer through containers and requires scalar consumers to see one singleton boundary authority.

For several pose-free links terminating at one receiver, use the specialized receiver-incident seam instead of summing independent signals and choosing one link. Each ReceiverIncidentContribution atomically binds signal, link, emitter, and support evidence. ReceiverIncidentAggregate canonically orders and sums a nonempty same-receiver collection, and receiver_incident_aggregate_boundary cites that aggregate’s signal, facts, and internal custody from one producer. The boundary persists the complete ordered link/contribution relation but not member waveform copies. One noise node follows that one aggregate boundary. A mixed-receiver collection, duplicate/missing/extra/reordered row, foreign collection origin, or noisy summand is refused.

receiver_incident_reference_snr may then publish one ordered ragged row per contained contribution against the same final variance. It statically cites the exact collection and aggregate boundary and verifies full member custody at runtime. Active-support schemas retain their mean-square convention. A nominal_sample_cell_interval collection instead publishes total summed finite-vector energy divided by the union cardinality of its half-open nominal cell intervals; overlapping cells count once. Both are per-member reference SNR, not SINR, occupied-bandwidth normalization, or evidence that the superposed waveform can be separated. receiver_incident_member is available when a downstream operator genuinely needs one checked contained waveform; it establishes no new boundary and draws no noise.

Noise at the receiver input¶

Both registered noise nodes require their realized signal and boundary_facts from the same checked boundary producer. Both accept only a rank-one [time] complex64-volts tensor with the exact receiver_input qualifier. Rank-zero, rank-two, mixed-receiver, missing-plane, and contradictory plane inputs are refused.

`awgn`¶

awgn is synthetic target-SNR noise, not a calibrated receiver-noise model. Its parameters are:

Parameter	Contract
`snr_db`	Finite target in the supported `[-300, 300]` dB range.
`minimum_signal_power_v2`	Sole numerical input-power floor, in V².

The node computes full-input mean-square voltage. A zero or at/below-floor input is undefined and refused. Above the floor it publishes the exact realized noise plane, variance, target SNR, receiver/link identity, and power_convention = "full_input_mean_square". The draw kernel has no hidden floor or clamp.

Shipped configurations author a low floor explicitly because their finite, post-link receiver voltages can be below the generic constructor default. Changing that parameter changes graph/record identity; it does not change the above-floor variance equation.

`receiver_thermal_noise`¶

receiver_thermal_noise computes receiver equivalent-input noise from k T B F. ENBW, noise figure, and impedance come from boundary evidence; reference temperature and the numerical power floor are node parameters. It publishes available power in watts, voltage variance in V², the exact realized noise plane, and whether the numerical floor was applied. It does not accept an SNR target or silently use nominal receiver bandwidth as ENBW.

Automatic gain control and voltage limiting¶

automatic_gain_control is AutomaticGainControl. It applies an independent causal gain loop along the final time axis and publishes the exact dimensionless gain trajectory. target_v (also accepted through the legacy parameter alias target) is a positive voltage; tau_attack and tau_decay are positive sample time constants; gain_init is nonnegative and may not exceed the positive max_gain.

max_gain limits the loop gain. It does not clip waveform magnitude.

The public limiter selectors are instance-specific:

Selector	Plane	Parameter
`transmitter_crest_limiter`	transmitter	positive absolute `rail_v`
`receiver_voltage_limiter`	receiver analog	positive absolute `rail_v`

Both radially scale an over-rail complex sample without changing phase. Neither claims dBFS: a dBFS value requires converter full-scale evidence, while these rails are physical volts. The old combined magnitude_limiter and AGC saturation_dbfs shapes are unregistered compatibility implementations and are not public selectors.

Converter effects¶

Conversion is four explicit nodes:

converter_scaling chooses volts per code from enob_bits and full_scale_v; null full scale is declared synthetic per-row normalization.
converter_rounding applies ties-to-even rounding to real and imaginary components.
converter_clipping clamps those components independently to the signed code rails.
converter_reconstruction restores complex64 volts from the cited scale.

Each downstream node requires signal and scale from one immediate producer, so the physical order is a binding contract rather than a naming convention.

Other receiver effects¶

Legacy links to the former stage hierarchy land here. The supported graph selectors are receiver_lo_error and sample_clock_offset; there is no public stage ABC or compatibility selector behind these anchors.

The registered receiver surface also includes iq_imbalance, if_fir_response, if_scalar_gain, fir_group_delay_realignment, receiver_lo_error, receiver_mixer, rational_resampler, and sample_clock_offset. Their public classes and parameter models are listed in Nodes. They use the same typed complex-voltage, sample-grid, and ordering contracts described above.

Migration¶

Insert receiver_measurement and one receiver_input_boundary after final propagation/pathloss.
For multiple pose-free links at one receiver, bind atomic contributions to receiver_incident_aggregate, then one receiver_incident_aggregate_boundary; never pick one representative link or draw receiver noise per emitter.
Bind awgn or receiver_thermal_noise from both boundary outputs.
Bind every emitter_snr numerator, measurement input, and denominator noise to that same boundary authority and receiver index.
Replace an ambiguous limiter with the transmitter crest or receiver voltage selector appropriate to that instance.
Replace AGC waveform saturation with a separately authored voltage limiter only when the modeled hardware actually has that rail.

The shipped record projections persist boundary facts, noise facts, measurement plane, power convention, receiver/link identity, and application grid so the same meaning survives codec and SDS storage.