Consumer types

Result, topology, geometry, transport, capability and diagnostics types returned by the propagation consumer.

These types are returned by the functions on the consumer page. All are frozen dataclasses in witwin.channel.propagation.consumer. K is the number of path rows, D the interaction width, F the number of frequency offsets and S the number of time slots.

Evaluations #

PropagationEvaluation #

Returned by evaluate.

Field	Type
`paths`	`PropagationPathBatch`
`convention`	`PropagationConvention`
`capabilities`	`PropagationCapabilities`
`diagnostics`	`PropagationDiagnostics`

FixedTopologyEvaluation #

Returned by reevaluate. The same four fields, plus row_valid: a (K,) bool CUDA mask, or None. When present it is the only authority on whether a replayed row is meaningful. Errors (ABI, capacity, device) still raise; they are never reported as row_valid=False.

TimeVaryingEvaluation #

Returned by evaluate_time_varying.

Field	Type and shape	Meaning
`slot_count`, `row_count`	`int`	`S` and `K` (rows per slot).
`times_s`	`float64`, `(S,)`	The time labels from the request.
`delay_s`, `path_length_m`	`float32`, `(S, K)`	Per-slot delay and length.
`transport`	`TimeVaryingTransport`	Per-slot transport.
`pair_count`, `pair_offsets`	`int`, `(pair_count + 1,)`	Pair segmentation of one slot; every slot repeats it.
`row_valid`	`bool`, `(S, K)`, or `None`	Row validity per slot.
`convention`, `capabilities`, `diagnostics`	records	As above.

TimeVaryingEvaluation.from_evaluation(evaluation, times_s, slot_count) builds these views from a slot-batched FixedTopologyEvaluation; evaluate_time_varying calls it for you.

TimeVaryingTransport #

Fields response, coefficient, field, direction, matrix, source_basis, sink_basis. Only the fields of the requested response are set; each is shaped (S, K, ...). TimeVaryingTransport.from_transport(transport, slot_count) creates the views without copying; the row count must be divisible by slot_count.

PropagationPathBatch #

Field	Type and shape	Meaning
`pair_count`	`int`	Number of source-sink pairs.
`path_count`	`int`	`K`.
`pair_index`	`(K,)`	Pair of every row: `sink_index * source_count + source_index`.
`pair_offsets`	`(pair_count + 1,)`	Row range of each pair: rows `pair_offsets[p]` to `pair_offsets[p + 1] - 1` belong to pair `p`.
`topology`	`PropagationTopology`	Discrete rows.
`geometry`	`PropagationGeometry`	Continuous geometry.
`transport`	`ScalarTransport`, `Complex3Transport` or `JonesTransport`	Depends on `response`.

PropagationTopology #

Field	Type and shape	Meaning
`source_index`, `sink_index`	`int32`, `(K,)`	Row in the source and sink batch.
`source_id`, `sink_id`	`int64`, `(K,)`	The `stable_ids` from the batches.
`depth`, `component_id`	`int32`, `(K,)`	Interaction count and component code.
`primitive_id`, `edge_id`, `material_id`	`int32`, `(K,)`	First interaction.
`primitive_sequence`, `material_sequence`, `interaction_type`	`int32`, `(K, D)`	Every interaction.
`provenance`	`WorldProvenance` or `None`	Scene versions at discovery.

Properties: row_count (K), device.

PropagationGeometry #

Field	Type and shape
`path_length_m`, `delay_s`	`float32`, `(K,)`
`field_direction`	`float32`, `(K, 3)`
`interaction_positions_m`, `interaction_normals`	`float32`, `(K, D, 3)`

Properties: row_count, device.

Transports #

Type	Fields	Notes
`ScalarTransport`	`coefficient` `(K,)` complex64; `coefficient_offsets` `(K, F)` or `None`; `frequency_offsets_hz` tuple or `None`	`coefficient` includes the source amplitude `sqrt(powers_w)` and the reference-frequency phase.
`Complex3Transport`	`field` `(K, 3)` complex64; `direction` `(K, 3)` float32; `field_offsets` `(K, F, 3)` or `None`; `frequency_offsets_hz`	World-frame field, including `sqrt(powers_w)`.
`JonesTransport`	`matrix` `(K, 2, 2)` complex64; `source_basis`, `sink_basis` `(K, 2, 3)` float32	`matrix[k, i, j]` maps source component `j` to sink component `i`. It is a basis map and does not include `sqrt(powers_w)`. No wideband offsets.

Each has row_count and device properties.

Fixed-topology handles #

PreparedFixedTopology #

Field	Meaning
`topology`	The frozen `PropagationTopology`.
`buckets`	Tuple of `FixedTopologyBucket`, one per `(component, depth)`.
`prepare_d2h_copies`, `prepare_d2h_bytes`, `prepare_synchronizations`	Cost of building the handle.

Properties: row_count, device, provenance.

FixedTopologyBucket #

FixedTopologyBucket(component, depth, rows): the ascending row indices that share one component and depth. Property row_count.

WorldProvenance #

WorldProvenance(topology_version, geometry_version, material_version, assignment_version, time_s=None).

WorldProvenance.of(compiled) captures the versions of a CompiledScene.
moved_domain(current, *, allow_geometry=False) returns the first version name that differs from current, or None. With allow_geometry=True, geometry_version is ignored.

time_s is a label only and never makes a topology stale.

PropagationConvention #

The units and layout every evaluation follows.

Field	Value
`contract_version`	`6`
`pair_layout`	`sink_major_source_minor:pair_index=sink_index*source_count+source_index`
`slot_pair_layout`	Block-diagonal slot layout: `row = slot * frozen_row_count + frozen_row`
`distance_unit`, `delay_unit`	`"m"`, `"s"`
`phasor`, `time_dependence`	`exp(-jkd)`, `exp(+j2pift)`
`coefficient_reference`	`includes_reference_frequency_phase`
`narrowband_frequency_offset_law`	`H(f_ref+df) = C(f_ref)exp(-j2pidf*delay_s)`
`narrowband_frequency_offset_error_law`, `wideband_offset_layout`, `wideband_frequency_quantization_law`	Text descriptions of the approximation error and the wideband grid
`complex3_basis`	`world_cartesian`
`jones_mapping`	`source_transverse_basis_to_sink_transverse_basis`

The narrowband law is how you extrapolate a single-frequency coefficient to nearby frequencies. Wideband offsets on FixedTopologyRequest evaluate each frequency natively instead.

PropagationCapabilities #

Returned by consumer.capabilities() and attached to every evaluation.

Group	Fields
Vocabulary	`contract_version`, `components`, `responses`, `topology_modes`, `ad_modes`, `world_motions`, `world_version_domains`
Support matrices	`response_components`, `response_ad_modes`, `component_ad_modes`
Fixed topology	`fixed_topology_components`, `fixed_topology_responses`, `supports_fixed_topology`, `supports_los_jones`, `fixed_topology_row_validity_components`, `polarimetric_frozen_ad_inputs`
Slots and wideband	`supports_slot_batching`, `max_slot_count`, `supports_wideband_offsets`, `wideband_responses`, `wideband_components`, `wideband_dispersive_materials`, `wideband_rough_materials`, `max_frequency_offset_count`, `native_frequency_resolution_law`
Gradients	`component_material_leaves`, `differentiable_geometry_outputs`, `direction_differentiable_components`, `primal_only_ad_inputs`, `supports_higher_order_ad`, `ad_accounting`

Lookup methods, each raising ValueError for an unknown name:

Method	Returns
`components_for(response)`	Components available for a response
`ad_modes_for(response)`	AD modes available for a response
`ad_modes_for_component(component)`	AD modes available for a component; diffraction is `{"none"}`
`material_leaves_for(component)`	Differentiable material fields for a component
`differentiable_geometry_for(route)`	Differentiable geometry outputs of a route

PropagationDiagnostics #

Per-call counters, for auditing rather than as performance guarantees: discovery_launch_count, candidate_count, visibility_rejection_count, compact_count_d2h_copies, compact_count_d2h_bytes, compact_sync_count, validation_d2h_copies, validation_d2h_bytes, validation_sync_count, frequency_column_count (default 1), ad_companion_launches (default 0) and ad_tape_bytes (default 0).