Reception¶

Pulse-echo RF from point scatterers.

The core reception primitive: amplitude-weighted superposition of each scatterer's pulse-echo response v_pe ⊛ h_tx ⊛ h_rx; the single physical ∂³ stays on the band-limited excitation / impulse-response chain (e ⊛ h_e ⊛ h_r). Field II uses the same convention, so this equals Field II calc_scat (≡ calc_hhp for a unit point, corr 1.0000).

per_scatterer=True keeps each scatterer separate (PSF); False sums them. coords["t0"] is beam-axis referenced (TX bulk delays.max() subtracted) so downstream beamforming needs no per-line correction.

Parameters:

Returns:

Raises:

Pulse-echo RF for a sequence of TX events (emission basis: PW/DW/...).

Each event sets the TX delays/apodization, then pulse_echo_rf is run (summed over scatterers). Useful as the emission basis for matrix imaging.

MOVING SCATTERERS. The medium may move between emissions: give scatterer_positions_mm a (N_events, N_scat, 3) stack, one cloud per event, and each emission sees its own cloud. Blood travelling at v covers v/PRF between emissions, and the resulting round-trip path change (twice the axial step) is the inter-emission phase a Doppler estimator reads. eSDIva has no slow-time clock of its own, so the trajectory is yours to write — one line for constant flow::

t = np.arange(n_events) / prf                       # slow-time, s
pos = pos0[None] + v_mm_s[None] * t[:, None, None]  # (N_ev, N, 3)

and any pulsatile, cardiac or decorrelating trajectory is the same call. amplitudes may vary per event too, as (N_events, N_scat): the scatterer count is fixed across the sequence, so a zero amplitude is how a scatterer that has left the region of interest — or a contrast bubble that has been destroyed — is retired.

The scatterers are FROZEN during each emission. Motion is resolved only at the event rate, so the RF carries the phase shift BETWEEN emissions, not an intra-pulse Doppler frequency shift within one echo; velocities of clinical interest move a small fraction of a wavelength during a single pulse, which is why this is the standard flow model.

With out_path, the sequence is CHECKPOINTED: each event's RF is written to disk (one compressed file per event + a contents file) the moment it finishes, and re-running the same call on the same folder skips the completed events and resumes from the first missing one. The contents file fingerprints the full simulation (probe, medium, excitation, scatterers, events); re-running with anything changed raises instead of silently mixing incompatible data.

checkpoint_chunks bounds the work lost to a crash WITHIN one event: the RF is linear in the scatterers, so the cloud is split into chunks that are simulated and checkpointed one file at a time, then summed. Every chunk carries four zero-amplitude "grid sentinel" points (just nearer than the nearest scatterer and just farther than the farthest, per aperture) so all chunks of an event share one time grid and their sum is sample-exact.

Parameters:

Returns:

Raises:

Synthetic-aperture RF: each TX element/group fires alone, all RX record.

Canonical diverging-wave emission basis for matrix imaging: every group fires FLAT (zero delay, unit apodization) — this OVERRIDES any TX delays/ apodization set on the transducer. tx_groups="element" is full FMC (= Field II calc_scat_all); int N uses N-element sub-apertures; a list[list[int]] gives custom groups.

Each group is one TX event of sequence_rf, so it shares that method's checkpointing: with out_path every group (or scatterer chunk, with checkpoint_chunks) lands on disk the moment it finishes, a re-run resumes at the first missing file, and a changed setup refuses. Output Ntx_grp·Erx·Nt can be huge, hence the anti-aliased decimation (default 10×); a 10 s countdown precedes an in-RAM run so it can be aborted (a checkpointed run is always interruptible, so it starts straight away).

Parameters:

Returns:

One conventional focused scan line (Field II calc_scat match).

Recomputes the TX and RX focus + apodization FROM focus_mm (reusing each transducer's compute_delays / compute_apodization), then beamforms ON RECEIVE INSIDE THE SIR KERNEL via _focused_sum_rf (focused_sum=True): every RX patch carries its focusing delay + apodization and the kernel sums them into one line — exactly Field II calc_scat's internal receive beamforming. This replaces the old per-element-RF + external DAS_focused_scanline path, so it is ~E_rx× cheaper (one FFT pair, no per-channel loop) and applies the receive focus at corner-time resolution (no sample-interpolation loss). Loop focus_mm externally to build a B-mode, e.g. img[i] = sim.scan_focusline(...)[0].

By default the RX aperture mirrors the TX focus + apodization (the usual focused-imaging case, and what Field II's sesr.m does: identical xdc_apodization on emit and receive). Pass rx_FoverD / rx_apodization_type to give the receive aperture a different profile.

Parameters:

Returns:

Interactive 3-D preview of the pulse-echo setup (TX, RX, scatterers).

Renders the transmit and receive apertures (their patch meshes, in mm) and the scatterer cloud, each point coloured by its scattering amplitude and faded in proportion to it — a quick visual check that positions, units and aperture poses are what the simulation will see. When TX and RX are the same object the aperture is drawn once.

Parameters:

Returns:

Update a parameter at runtime, then invalidate the conventional delegate.

Extends ReceptionBase.set with validation of the "method" selector and by dropping the cached ReceptionConventional (rebuilt on the next conventional call, picking up the new tx/rx/medium/excitation state).

Parameters:

Pulse-echo RF from point scatterers.

The core reception primitive. The recorded pulse-echo signal is the amplitude-weighted superposition of each scatterer's pulse-echo response::

rf = (ρ₀/2c₀²) Σ_i a_i (exc ⊛ ir_tx ⊛ ir_rx ⊛ h_pe)|_{r_i}

The three physical excitation derivatives are carried by the band-limited exc ⊛ ir_tx ⊛ ir_rx chain, so NO extra explicit ∂/∂t is applied. Field II uses the same convention, so this equals its calc_scat (≡ calc_hhp for a unit point, corr 1.0000).

per_scatterer=True keeps each scatterer separate — the point-spread function (PSF) use; False sums them (the recorded echo).

coords["t0"] is referenced to the beam axis (the TX focusing bulk tx.delays.max() is subtracted), so downstream beamforming needs no per-line bulk correction.

Parameters:

Returns:

Raises:

Pulse-echo RF for a sequence of TX events (emission basis: PW/DW/...).

Each event sets the TX delays/apodization, then pulse_echo_rf is run (summed over scatterers). Useful as the emission basis for matrix imaging.

MOVING SCATTERERS. The medium may move between emissions: give scatterer_positions_mm a (N_events, N_scat, 3) stack, one cloud per event, and each emission sees its own cloud. Blood travelling at v covers v/PRF between emissions, and the resulting round-trip path change (twice the axial step) is the inter-emission phase a Doppler estimator reads. eSDIva has no slow-time clock of its own, so the trajectory is yours to write — one line for constant flow::

t = np.arange(n_events) / prf                       # slow-time, s
pos = pos0[None] + v_mm_s[None] * t[:, None, None]  # (N_ev, N, 3)

and any pulsatile, cardiac or decorrelating trajectory is the same call. amplitudes may vary per event too, as (N_events, N_scat): the scatterer count is fixed across the sequence, so a zero amplitude is how a scatterer that has left the region of interest — or a contrast bubble that has been destroyed — is retired.

The scatterers are FROZEN during each emission. Motion is resolved only at the event rate, so the RF carries the phase shift BETWEEN emissions, not an intra-pulse Doppler frequency shift within one echo; velocities of clinical interest move a small fraction of a wavelength during a single pulse, which is why this is the standard flow model.

With out_path, the sequence is CHECKPOINTED: each event's RF is written to disk (one compressed file per event + a contents file) the moment it finishes, and re-running the same call on the same folder skips the completed events and resumes from the first missing one. The contents file fingerprints the full simulation (probe, medium, excitation, scatterers, events); re-running with anything changed raises instead of silently mixing incompatible data.

checkpoint_chunks bounds the work lost to a crash WITHIN one event: the RF is linear in the scatterers, so the cloud is split into chunks that are simulated and checkpointed one file at a time, then summed. Every chunk carries four zero-amplitude "grid sentinel" points (just nearer than the nearest scatterer and just farther than the farthest, per aperture) so all chunks of an event share one time grid and their sum is sample-exact.

Parameters:

Returns:

Raises:

Synthetic-aperture RF: each TX element/group fires alone, all RX record.

Canonical diverging-wave emission basis for matrix imaging: every group fires FLAT (zero delay, unit apodization) — this OVERRIDES any TX delays/ apodization set on the transducer. tx_groups="element" is full FMC (= Field II calc_scat_all); int N uses N-element sub-apertures; a list[list[int]] gives custom groups.

Each group is one TX event of sequence_rf, so it shares that method's checkpointing: with out_path every group (or scatterer chunk, with checkpoint_chunks) lands on disk the moment it finishes, a re-run resumes at the first missing file, and a changed setup refuses. Output Ntx_grp·Erx·Nt can be huge, hence the anti-aliased decimation (default 10×); a 10 s countdown precedes an in-RAM run so it can be aborted (a checkpointed run is always interruptible, so it starts straight away).

Parameters:

Returns:

One conventional focused scan line (Field II calc_scat match).

Recomputes the TX and RX focus + apodization FROM focus_mm (reusing each transducer's compute_delays / compute_apodization), then beamforms ON RECEIVE INSIDE THE SIR KERNEL via _focused_sum_rf (focused_sum=True): every RX patch carries its focusing delay + apodization and the kernel sums them into one line — exactly Field II calc_scat's internal receive beamforming. This replaces the old per-element-RF + external DAS_focused_scanline path, so it is ~E_rx× cheaper (one FFT pair, no per-channel loop) and applies the receive focus at corner-time resolution (no sample-interpolation loss). Loop focus_mm externally to build a B-mode, e.g. img[i] = sim.scan_focusline(...)[0].

By default the RX aperture mirrors the TX focus + apodization (the usual focused-imaging case, and what Field II's sesr.m does: identical xdc_apodization on emit and receive). Pass rx_FoverD / rx_apodization_type to give the receive aperture a different profile.

Parameters:

Returns:

Interactive 3-D preview of the pulse-echo setup (TX, RX, scatterers).

Renders the transmit and receive apertures (their patch meshes, in mm) and the scatterer cloud, each point coloured by its scattering amplitude and faded in proportion to it — a quick visual check that positions, units and aperture poses are what the simulation will see. When TX and RX are the same object the aperture is drawn once.

Parameters:

Returns:

Validate value against _SETTABLE[name] and assign it.

The shared tail of every set(): checks the name is known and the type matches, casts an excitation to float32, and stores the attribute. Subclasses handle their structural keys ("transducer"/"tx"/ "rx") first, then delegate the plain parameters here.

Raises:

Effective excitation pulse: self.excitation else tx.excitation.

Returns a float32 array or None. A global pulse is (L,); a per-transmit-element pulse is (L, E) (one column per element) and is preserved as 2-D — only a transducer-stored 1-D pulse is ravelled.

Align one depth bin's time grid with the shared global time axis.

All depth bins must land on ONE common time axis (origin t0_global, step dt), but a bin's natural start t0_nat generally falls between two of its samples. This rounds t0_nat DOWN to the nearest sample of the shared axis. Time-domain paths build the bin's grid from t0_snap; a spectral path can instead reference its phase to t0_snap (or apply shift as a phase ramp).

Returns:

Refuse baffle="soft" in a core that models the rigid baffle only.

Split flat per-patch arrays into one tuple per element.

arrays is the 7-tuple (centers, wx, wy, apod, delays, eu, ev) of per-patch quantities; this returns a list of n_elements such tuples, each holding only the patches belonging to that element (sub_el_idx == e). Used to compute one element's SIR at a time (per-element excitation, per-element attenuation, raw per-channel RF).

Pulse-echo RF from point scatterers.

The core reception primitive: amplitude-weighted superposition of each scatterer's pulse-echo response v_pe ⊛ h_tx ⊛ h_rx; the single physical ∂³ stays on the band-limited excitation / impulse-response chain (e ⊛ h_e ⊛ h_r). Field II uses the same convention, so this equals Field II calc_scat (≡ calc_hhp for a unit point, corr 1.0000).

per_scatterer=True keeps each scatterer separate (PSF); False sums them. coords["t0"] is beam-axis referenced (TX bulk delays.max() subtracted) so downstream beamforming needs no per-line correction.

Parameters:

Returns:

Raises:

Receive-beamformed line via in-kernel focused sum.

Backend hook for ReceptionBase.scan_focusline: the pulse-echo RF with focused_sum=True. Returns the single line (Nt,) and its coords. Field II's calc_scat builds its line the same way (focused, apodized, summed on receive).

Zero the per-phase wall-clock log at the start of an RF computation.

Add the wall-clock time of the enclosed block to self.time_log[key].

compute_h_sir timed into time_log["sir_s"] (the SIR kernel cost).

One-line time_grid/sir/fft breakdown of the last RF computation.

Extract patch arrays from both TX and RX transducers.

Update a parameter at runtime, then invalidate the conventional delegate.

Extends ReceptionBase.set with validation of the "method" selector and by dropping the cached ReceptionConventional (rebuilt on the next conventional call, picking up the new tx/rx/medium/excitation state).

Parameters:

Pre-extract per-RX-element patch arrays.

Receive patch groups feeding the per-element / per-line SIR.

focused_sum → ONE group holding every RX patch (the kernel sums it into a single beamformed line, Field II calc_scat's internal receive sum); else one group per receive element → raw per-channel RF. Each group is the tuple (centers, wx, wy, apod, delays, eu, ev) of that group's patch arrays.

Far-field SIR sample grid for one aperture ("tx" or "rx").

Wraps compute_time_grid with that aperture's patch centres, largest patch dimensions and focusing delays. Returns (time_grid, t0, dt, T): the sampled time axis and its origin t0 (s), step dt (s) and length T (samples), sized to cover the trapezoidal SIR of every scatterer.

Beamforming t0, coords dict, and optional anti-aliased decimation.

coords["t0"] is the beamforming time reference, not the literal instant of the first RF sample: it is set so that a scatterer's echo peaks at its geometric round-trip time (|p − r_tx| + |p − r_rx|)/c. A delay-and-sum can then read the sample at (t_tx + t_rx − t0)/dt with no further correction — the convention Field II users reach through USTB, and the one MUST gets for free from a zero-phase pulse. Three shifts build it:

• TX/RX focusing bulk. pe_t0 counts from the first-firing element, so the transmit bulk tx.delays.max() (the last-firing element's delay) is subtracted to put the origin on the beam axis; the RX bulk likewise.
• Elevation lens transit. A cylindrical lens is a RECESSED surface: its patches lie on an arc whose centre sits at z = −sag, behind the rim plane the beamformer measures depth from. Every patch is therefore farther from an on-axis target than the face plane suggests — at the lens focus, uniformly by one sag R − √(R² − (h/2)²), which is exactly the condition that makes rim and centre equidistant and focuses the beam. The echo thus arrives one lens transit LATE relative to the 2z/c a beamformer assumes, so the sag is SUBTRACTED from t0 (TX once, RX once) to put the echo back at its geometric depth. Flat apertures have zero sag. Measured on a point target at the lens focus: with the term subtracted the target lands within 0.005 mm of truth; adding it instead places the image 2 sags (0.34 mm here) too deep, and omitting it altogether 1 sag too deep.
• Two-way pulse centre. The band-limited echo peaks half a pulse after the geometric arrival (see _pulse_center_lag_s); subtracting that lag here is what makes the naive delay-and-sum land on the peak. The value stays in coords["pulse_center_lag_s"] as provenance — it is already applied, so a beamformer must NOT add it again.

Envelope-centre lag of the two-way pulse (seconds), removed from t0.

The received waveform is the electric drive convolved with the transmit and receive element impulse responses, e ⊛ h_tx ⊛ h_rx. Three bursts of lengths L_e, L_tx, L_rx convolve to N = L_e + L_tx + L_rx − 2 samples; each factor has a symmetric envelope, so the two-way envelope peaks at the centre of that support, (N − 1)/2 samples after the geometric arrival. A delay-and-sum reads samples at the geometric round-trip time, so it would land this lag BEFORE the echo peak — an axial bias of c·lag/2 (0.5 mm for a 5 MHz two-cycle pulse model). _finalize subtracts it from coords["t0"] so the naive lookup is already correct. It depends only on the pulse model and fs — never on the phantom.

Compute the RF one depth bin at a time and sum onto one shared time axis.

Scatterers are sorted by distance to the transmit aperture centroid (a proxy for their echo arrival time) and split into n_bins groups of equal size. per_bin_fn(idx) computes one group's RF on a time grid just long enough for that group's arrivals, and returns (rf_bin, n0) where n0 is the integer sample index at which that grid starts on the shared global time axis (see _snap_to_lattice). Because every bin's samples land exactly on that shared axis, recombining is a plain addition into rf[:, n0:n0+len] — no interpolation or resampling anywhere.

Choose how many depth bins to split the scatterers into (1 = no binning).

Why bin at all: each scatterer's echo occupies a short time window around its round-trip arrival 2·|r|/c, but a single computation over ALL scatterers must use a time grid spanning from the earliest to the latest arrival. With scatterers spread over centimetres of depth that grid is long and mostly empty, and its FFT length nfft (and, for the spectral form, the number of in-band frequency bins ∝ nfft) grows with the depth span. Splitting the scatterers into depth-ordered groups lets each group use a grid only as long as its own arrival window — much shorter transforms, same summed RF.

How the count is chosen:

1. Don't bin when it cannot pay: fewer than _MIN_SCATTERERS_PER_BIN scatterers, fewer than 2 output channels, or all scatterers at the same depth (arrival spread under one sample).
2. Otherwise target ~_MIN_SCATTERERS_PER_BIN scatterers per bin (P // _MIN_SCATTERERS_PER_BIN). More bins mean shorter windows but also more fixed per-bin overhead (SIR rebuild + FFT setup), and nfft can never drop below the excitation length — so past this occupancy, extra bins are pure overhead. This target is the empirical balance.
3. Never more bins than the arrival spread in samples: a bin thinner than one sample cannot shrink its window any further.

Normalise and validate positions + amplitudes, return (points_m, amps).

positions_mm may also be a grid dict (x_extent/dx/… keys in mm, exactly as Emission takes): the regular lattice of point targets it describes is built automatically — handy with per_scatterer=True to map the PSF across the field. A regular lattice is NOT a tissue phantom (its periodicity returns coherent lattice echoes, not speckle); for phantoms draw random scatterers, e.g. with [make_phantom][esdiva.utilities.phantom.make_phantom].

A single acquisition sees ONE cloud, so a per-event (N_events, N_scat, 3) stack of moving scatterers is refused here — that shape belongs to sequence_rf, which fires one emission per event.

Resolve a static or per-event scatterer cloud into an event indexer.

A sequence may hold the medium still (one cloud, reused every emission) or let it move: blood in a vessel travels v/PRF between emissions, and it is exactly that inter-emission displacement — a round-trip path change of twice the axial step — that a Doppler estimator reads as phase. Both are expressed by the shape of the input: (N_scat, 3) holds still, (N_events, N_scat, 3) gives each emission its own cloud. Amplitudes follow the same rule, so a scatterer that leaves the region of interest (or a contrast bubble that is destroyed) is retired by setting its amplitude to zero for the later events.

Parameters:

Returns:

Raises:

Interactive 3-D preview of the pulse-echo setup (TX, RX, scatterers).

Renders the transmit and receive apertures (their patch meshes, in mm) and the scatterer cloud, each point coloured by its scattering amplitude and faded in proportion to it — a quick visual check that positions, units and aperture poses are what the simulation will see. When TX and RX are the same object the aperture is drawn once.

Parameters:

Returns:

Pulse-echo RF for a sequence of TX events (emission basis: PW/DW/...).

Each event sets the TX delays/apodization, then pulse_echo_rf is run (summed over scatterers). Useful as the emission basis for matrix imaging.

MOVING SCATTERERS. The medium may move between emissions: give scatterer_positions_mm a (N_events, N_scat, 3) stack, one cloud per event, and each emission sees its own cloud. Blood travelling at v covers v/PRF between emissions, and the resulting round-trip path change (twice the axial step) is the inter-emission phase a Doppler estimator reads. eSDIva has no slow-time clock of its own, so the trajectory is yours to write — one line for constant flow::

t = np.arange(n_events) / prf                       # slow-time, s
pos = pos0[None] + v_mm_s[None] * t[:, None, None]  # (N_ev, N, 3)

and any pulsatile, cardiac or decorrelating trajectory is the same call. amplitudes may vary per event too, as (N_events, N_scat): the scatterer count is fixed across the sequence, so a zero amplitude is how a scatterer that has left the region of interest — or a contrast bubble that has been destroyed — is retired.

The scatterers are FROZEN during each emission. Motion is resolved only at the event rate, so the RF carries the phase shift BETWEEN emissions, not an intra-pulse Doppler frequency shift within one echo; velocities of clinical interest move a small fraction of a wavelength during a single pulse, which is why this is the standard flow model.

With out_path, the sequence is CHECKPOINTED: each event's RF is written to disk (one compressed file per event + a contents file) the moment it finishes, and re-running the same call on the same folder skips the completed events and resumes from the first missing one. The contents file fingerprints the full simulation (probe, medium, excitation, scatterers, events); re-running with anything changed raises instead of silently mixing incompatible data.

checkpoint_chunks bounds the work lost to a crash WITHIN one event: the RF is linear in the scatterers, so the cloud is split into chunks that are simulated and checkpointed one file at a time, then summed. Every chunk carries four zero-amplitude "grid sentinel" points (just nearer than the nearest scatterer and just farther than the farthest, per aperture) so all chunks of an event share one time grid and their sum is sample-exact.

Parameters:

Returns:

Raises:

Checkpointed single-shot pulse-echo = a one-event sequence.

Backend for pulse_echo_rf(out_path=...): the current TX delays/apodization become an explicit event so the dataset fingerprint captures the focus state (sequence_rf fingerprints its events; bare transducer state would go unchecked and a resume could silently mix two different focus settings).

Open/create the checkpoint folder for sequence_rf.

The fingerprint covers everything that determines the RF: probe geometries (via their repr), medium, sampling, excitation, scatterer cloud and the per-event delays/apodization. Any bit-level change in these makes the resume refuse, so a checkpoint can never be silently continued with different physics. The chunk count is part of the fingerprint too (chunk files are indexed by it), but only when chunking is on, so unchunked datasets keep their original fingerprint.

Four zero-amplitude points that pin the pulse-echo time grid.

The RF time window is sized from the min/max patch-centre-to-scatterer distance of the simulated point set, so two different chunks of one phantom would get slightly different (non-sample-aligned) windows and their partial RFs could not be summed. Adding to EVERY chunk one point 0.2 mm nearer than the nearest scatterer and one 0.2 mm farther than the farthest (for the TX and the RX aperture) forces one common window; with zero scattering amplitude they contribute nothing to the physics.

Parameters:

Returns:

Build the list of TX element-index groups for synthetic_aperture_rf.

Synthetic-aperture RF: each TX element/group fires alone, all RX record.

Canonical diverging-wave emission basis for matrix imaging: every group fires FLAT (zero delay, unit apodization) — this OVERRIDES any TX delays/ apodization set on the transducer. tx_groups="element" is full FMC (= Field II calc_scat_all); int N uses N-element sub-apertures; a list[list[int]] gives custom groups.

Each group is one TX event of sequence_rf, so it shares that method's checkpointing: with out_path every group (or scatterer chunk, with checkpoint_chunks) lands on disk the moment it finishes, a re-run resumes at the first missing file, and a changed setup refuses. Output Ntx_grp·Erx·Nt can be huge, hence the anti-aliased decimation (default 10×); a 10 s countdown precedes an in-RAM run so it can be aborted (a checkpointed run is always interruptible, so it starts straight away).

Parameters:

Returns:

Set focusing delays + apodization on trans from focus (mm).

One conventional focused scan line (Field II calc_scat match).

Recomputes the TX and RX focus + apodization FROM focus_mm (reusing each transducer's compute_delays / compute_apodization), then beamforms ON RECEIVE INSIDE THE SIR KERNEL via _focused_sum_rf (focused_sum=True): every RX patch carries its focusing delay + apodization and the kernel sums them into one line — exactly Field II calc_scat's internal receive beamforming. This replaces the old per-element-RF + external DAS_focused_scanline path, so it is ~E_rx× cheaper (one FFT pair, no per-channel loop) and applies the receive focus at corner-time resolution (no sample-interpolation loss). Loop focus_mm externally to build a B-mode, e.g. img[i] = sim.scan_focusline(...)[0].

By default the RX aperture mirrors the TX focus + apodization (the usual focused-imaging case, and what Field II's sesr.m does: identical xdc_apodization on emit and receive). Pass rx_FoverD / rx_apodization_type to give the receive aperture a different profile.

Parameters:

Returns:

Time grid covering both TX and RX propagation paths.

Returns the combined pulse-echo window (pe_t0, dt, pe_T) and the two one-way windows (tx_t0, tx_T, rx_t0, rx_T). The spectral form references its TX and RX spectra to tx_t0 / rx_t0 so their product lands at pe_t0 = tx_t0 + rx_t0.

Lazily build (and cache) the ReceptionConventional used for the conventional branch, with its SIR-sampling kernel set to sir_method ("fst"/"sdi"/ "auto").

Shares the same tx/rx objects (so focusing state set by sequence_rf/scan_focusline/synthetic_aperture_rf is seen) and mirrors the medium params. The RX-non-default warning already fired at this object's construction, so suppress the duplicate here.

In-band frequency slice [b0, b1) where the pulse filter is non-negligible.

The received signal is shaped by the excitation × impulse-response magnitude band_mag; outside the band where it exceeds tol of its peak the result is ~0, so the spectral form's spectra need not be evaluated there. Returns the contiguous span covering every significant bin (the whole range if the drive is wideband).

Common time-grid, FFT-filter and band-range setup for the spectral core.

Returns a dict of everything the spectral (and ReceptionPaired) cores share.

grid_override (a (pe_t0, dt, pe_T, tx_t0, rx_t0) tuple) bypasses the natural time grid — used by the depth-binned spectral path, where each bin's window is snapped to the global sample lattice so per-bin results add back at an integer offset. pe_T (and hence nfft, the band-bin count) is then the SHORT per-bin window, not the whole-field span.

Spectral PE core: closed-form one-way SIR spectra, multiplied — no forward FFT.

H_TX and each receive element's H_RX are evaluated only on the in-band frequencies; their product is the two-way SIR spectrum. For the summed RF the scatterers are amplitude-summed in the frequency domain (amps @ H_TX·H_RX), the shared filter G = fs·IR is applied per bin (the excitation weights each TX element's H_TX,t, so global and per-element drives share one path), and one inverse FFT per element returns the RF. Attenuation multiplies each (scatterer, element) product by H_att over the round trip TX centre → scatterer → element centre.

Depth binning. The in-band bin count is N_band = (BW/fs)·nfft and nfft ≈ next_pow2(pe_T) spans the arrival window of ALL scatterers, so a deep or wide field inflates N_band — and the spectrum build costs P·M·N_band, the dominant term. Grouping scatterers by depth lets each bin use a SHORT window (small nfft → small N_band), cutting both the build and the per-element product-sum by nfft_full/nfft_bin. Each bin shares one global sample lattice, so its RF adds back at an integer sample offset (no resampling). Used only for the summed RF (per_scatterer=False); the per-scatterer PSF keeps one window.

Number of output channels the spectral core produces (1 if focused_sum).

Lay per-element patch arrays out element-by-element, CSR-style.

The fused two-way kernel reads an aperture as one set of patch arrays in which element e occupies the contiguous block ptr[e]:ptr[e+1]. This concatenates the per-element groups into that layout and returns the patch arrays, their tangent frames, and the offsets ptr.

TX patch arrays + element offsets ptr: one block per element when each element has its own drive (n_drives > 1), else the whole aperture as one.

Shared filter G = fs·ir_tx·ir_rx, TX drives and the attenuation spec.

fs turns the product of two continuous SIR spectra into the sampled-RF scale (rfft(h[n]) ≈ fs·H per SIR, and the discrete convolution carries one dt). The drive spectra (E_tx or 1, N_band) weight each TX element's H_TX,t (one row of ones without excitation). Attenuation (None when alpha0 is unset) is referenced to the TX aperture centre and each receive element centre (the aperture centroid for a focused sum).

One receive element's closed-form SIR spectrum H_RX → (P, N_band).

Summed spectral RF for one (sub-field, window) → (n_out, pe_T) float32.

Forms the two-way SIR spectrum H_TX·H_RX for every receive element and amplitude-sums it over scatterers in a single fused parallel pass (the analogue of conventional's amps @ H_pe): the transmit one-way spectrum is built once per scatterer and reused across all receive elements, with nothing of size (P, N_band) materialised. The shared filter G = fs·IR is then applied per bin and one inverse FFT per element returns the RF. Reused for the single-window path and for each depth bin (the window — hence nfft and the band-bin count — comes from s); rx_csr is the receive aperture laid out element-by-element.

The fused kernel accumulates the scatterer sum in complex128 internally — cheap because N_band is the small in-band bin count.

Summed spectral RF, split into depth bins for short per-bin windows.

Same physical result as the single-window spectral path, but scatterers are grouped by depth so each bin spans a tight arrival window → small nfft → small in-band bin count N_band (the spectral form's dominant cost factor). All bins share one global sample lattice (t0_g, the reported t0): each bin's window is snapped to that lattice and its RF added back at the integer sample offset n0 — no resampling. Only the summed RF uses this; per-scatterer does not.