zea.simulator_time_domain

Time domain ultrasound simulator.

A time-domain alternative to zea.simulator.simulate_rf(). Instead of synthesizing every scatterer response frequency by frequency, each echo is splat in an (n_ax, n_el) map at its linear two-way delay, which is convolved once per receive channel with the transmit pulse. Attenuation is evaluated only at the pulse center frequency, so the result is an approximation.

Example usage

>>> from zea.simulator_time_domain import simulate_rf_td
>>> import numpy as np

>>> raw_data = simulate_rf_td(
...     scatterer_positions=np.array([[0, 0, 20e-3]]),
...     scatterer_magnitudes=np.array([1.0]),
...     probe_geometry=np.stack(
...         [np.linspace(-20e-3, 20e-3, 64), np.zeros(64), np.zeros(64)], axis=-1
...     ),
...     apply_lens_correction=True,
...     lens_thickness=1e-3,
...     lens_sound_speed=1000,
...     sound_speed=1540,
...     n_ax=1024,
...     center_frequency=5e6,
...     sampling_frequency=20e6,
...     t0_delays=np.zeros((1, 64)),
...     initial_times=np.zeros(1),
...     element_width=0.2e-3,
...     attenuation_coef=0.5,
...     tx_apodizations=np.ones((1, 64)),
...     t_peak=np.full(1, 1 / 5e6),
... )

Functions

get_pulse_waveform(center_frequency, ...[, ...])

Generate a real, Hann-windowed sinusoidal transmit pulse in the time domain.

simulate_rf_td(scatterer_positions, ...[, ...])

Time-domain (splat-and-convolve) RF simulator.
zea.simulator_time_domain.get_pulse_waveform(center_frequency, sampling_frequency, n_period=4, n_samples=129, scatter_exponent=0.0)[source]

Generate a real, Hann-windowed sinusoidal transmit pulse in the time domain.

This is the time-domain counterpart of zea.simulator.get_pulse_spectrum_fn(): an even, zero-centered pulse whose spectrum matches the windowed sine used by zea.simulator.simulate_rf(). The pulse length n_samples is a fixed (static) sample count so the pulse has a compile-time-known shape; the Hann window zeros any samples beyond the n_period-period support, so n_samples only needs to be large enough (and odd, to keep the pulse symmetric and delay-aligned) to contain that support.

Parameters:

  • center_frequency (float) – The center frequency of the pulse [Hz].

  • sampling_frequency (float) – The sampling frequency [Hz].

  • n_period (float) – The number of periods spanned by the Hann window.

  • n_samples (int) – The (odd) number of samples in the pulse.

  • scatter_exponent (float) – Exponent applied to the pulse spectrum relative to center_frequency.

Returns:

The pulse waveform of shape (n_samples,).

Return type:

array-like

zea.simulator_time_domain.simulate_rf_td(scatterer_positions, scatterer_magnitudes, probe_geometry, apply_lens_correction, lens_thickness, lens_sound_speed, sound_speed, n_ax, center_frequency, sampling_frequency, t0_delays, initial_times, element_width, attenuation_coef, tx_apodizations, t_peak, elevation_lens=False, element_height=None, max_chunk_gb=10.0, noise_level_db=None, tgc_max_db=0.0, noise_seed=0, noise_reference=None, scatter_exponent=2.0)[source]

Time-domain (splat-and-convolve) RF simulator.

A faster alternative to zea.simulator.simulate_rf() that produces equivalent RF data without a per-scatterer, per-frequency Fourier synthesis. Each scatterer contribution is splatted, with linear sub-sample interpolation, into an (n_ax, n_el) spike map at its two-way sample delay; the spike map is then convolved once per receive channel with a real transmit pulse.

Directivity, geometric spreading, and attenuation are evaluated at the pulse center frequency (a broadband approximation appropriate for the time domain), reusing the same helpers as zea.simulator.simulate_rf().

Parameters:

  • scatterer_positions (array-like) – The positions of the scatterers [m] of shape (n_scat, 3).

  • scatterer_magnitudes (array-like) – The magnitudes of the scatterers of shape (n_scat,).

  • probe_geometry (array-like) – The geometry of the probe [m] of shape (n_el, 3).

  • apply_lens_correction (bool) – Whether to apply lens correction.

  • lens_thickness (float) – The thickness of the lens [m].

  • lens_sound_speed (float) – The speed of sound in the lens [m/s].

  • sound_speed (float) – The speed of sound in the medium [m/s].

  • n_ax (int) – The number of samples in the RF data.

  • center_frequency (float) – The center frequency of the transmit pulse [Hz].

  • sampling_frequency (float) – The sampling frequency of the RF data [Hz].

  • t0_delays (array-like) – The transmit delays [s] of shape (n_tx, n_el).

  • initial_times (array-like) – The initial times [s] of shape (n_tx,).

  • element_width (float) – The width of the elements [m].

  • attenuation_coef (float) – The attenuation coefficient [dB/cm/MHz].

  • tx_apodizations (array-like) – The transmit apodizations of shape (n_tx, n_el).

  • t_peak (array-like) – The time of the peak of the transmit pulse [s] of shape (n_tx,).

  • elevation_lens (bool) – Whether the probe has an elevation lens: drop scatterers outside the elevation slab, and focus transmit energy directly downwards (i.e. cylindrical instead of spherical spread). For efficient pruning scatterers outside the slab, use zea.ops.Simulate rather than calling simulate_rf_td directly.

  • element_height (float) – The elevation height of the elements [m], used for the elevation directivity and the elevation slab. If None, defaults to element_width.

  • max_chunk_gb (float) – Approximate memory budget [GB] for the (chunk, n_el, n_el) tensors held at once while iterating over scatterers. Scatterers are processed in chunks sized to this budget, so peak memory no longer scales with the total scatterer count. Must be a static (Python) value, not a traced array.

  • noise_level_db (float) – Electronic noise level in dB relative to the noiseless RF maximum. None disables the noise. Must be static under jit.

  • tgc_max_db (float) – Time gain compensation in dB at the last axial sample, ramped linearly in dB from 0 at the first. 0 disables it. Must be static under jit.

  • noise_seed (int | SeedGenerator | jax.random.key, optional) – Seed for the noise. Vary it across transmit batches to keep the realisations independent.

  • noise_reference (float) – Reference amplitude for the noise level. If None, defaults to the noiseless RF maximum. Pass a fixed reference to avoid the noise level changing per transmit batch. See zea.simulator.apply_receive_chain().

  • scatter_exponent (float) – Weigh the scattered waveform spectrum by (f / center_frequency)**scatter_exponent. 2 is Rayleigh scattering (e.g. blood), myocardium is approximately 1.5, soft tissue 0.6-0.8. Must be static under jit.

Returns:

The simulated RF data of shape (n_tx, n_ax, n_el, 1).

Return type:

rf_data (array-like)