Skip to content

Emission

Forward pressure-field simulator. See the Emission user guide for modes and examples.

Emission 

Emission(
    transducer,
    *,
    c=1540.0,
    rho=1.0,
    fs=100000000.0,
    alpha0=None,
    freq_power=1.0,
    excitation=None,
    transfer_function=None,
    monochromatic=False,
    fast_attenuation=True,
    verbose=True,
)

Bases: SimulationBase

Compute emitted acoustic pressure fields.

Parameters:

Name Type Description Default
transducer TransducerBase

Transducer with geometry, delays, and apodization.

 required
c float

Speed of sound (m/s).

 1540.0
rho float

Medium density (kg/m^3).

 1.0
fs float

Sampling frequency (Hz).

 100e6
alpha0 float or None

Attenuation in dB/(MHz^y·cm). None = no attenuation.

 None
freq_power float

Power-law exponent y.

 1.0
excitation ndarray or None

Excitation pulse. Shape determines dispatch:

  • None — pulsed (raw SIR / attenuated SIR if alpha0 set).
  • (L,) — global excitation convolved with h_sir.
  • (L, E) — per-element excitation; each element's SIR computed separately to avoid a full (P, E, T) allocation.
 None
transfer_function callable or None

Global frequency-domain transfer function TF(freq) -> array. Applied multiplicatively in frequency domain alongside the excitation convolution (modes 3 and 4). freq is (N_freq,) float32 from scipy.fft.rfftfreq.

 None
monochromatic bool

If True, return CW amplitude at fc.

 False
fast_attenuation bool

If True (default) and alpha0 is set, use transducer-center distance for all field points (fast approximation, ignores element spatial spread). Set False to run the per-element loop using each element's center as the propagation origin (accurate near-field attenuation, much slower).

 True
verbose bool

Print diagnostic information during simulation.

 True

__call__ 

__call__(
    field_points_mm, *, method="auto"
) -> tuple[ndarray, dict]

Compute the pressure field at given field points.

Behavior is determined by instance state:

  1. monochromatic=True → CW amplitude at fc.
  2. excitation=None → pulsed transient (raw / attenuated SIR).
  3. excitation=(L,) → transient with global excitation convolution.
  4. excitation=(L, E) → transient with per-element excitation.

FieldII equivalences (same transducer geometry):

  • Mode 2 → ρ₀ · h(r, t). Equivalent to FieldII calc_h; with rho=1.0 (eSDIva default) the arrays are numerically identical up to floating-point precision.
  • Mode 1 → |H(r, ω_c)| (SIR Fourier magnitude at fc). Equivalent to FieldII calc_h → FFT → extract the fc bin.
  • Mode 3 → ρ₀ · d(e ⊛ ir_tx)/dt ⊛ h(r, t) (pulsed acoustic pressure), where ir_tx = tx.impulse_response if set, else the bare excitation e is used directly (dv_n/dt = de/dt). Equivalent to FieldII calc_hp with xdc_excitation(Th, e) and xdc_impulse(Th, ir_tx) set accordingly.
  • Mode 4 → same as mode 3, one loop iteration per element.

For modes 1–3, the per-element loop is triggered when alpha0 is not None and not fast_attenuation. When triggered, each element's h_sir is computed separately and attenuation uses the element center as propagation origin (accurate near-field model). Set fast_attenuation=True to skip the loop and use the TX center distance (faster approximation).

Mode 4 always uses the per-element loop; attenuation (if set) automatically uses element-center distances at no extra cost.

Parameters:

Name Type Description Default
field_points_mm dict or (N, 3) ndarray

Grid spec dict (mm) or raw point array (mm).

 required
method str

SIR computation method: "auto", "FST", or "sdi".

 "auto"

Returns:

Name Type Description
pressure ndarray

Monochromatic: shape (Nx, Ny, Nz) / (N_points,). Transient: shape (Nt, Nx, Ny, Nz) / (Nt, N_points).
coords dict

Keys "x", "y", "z" for structured grid; "t0", "dt" for transient.

set 

set(name: str, value)

Update a simulation parameter at runtime.

Parameters:

Name Type Description Default
name str

One of: "c", "rho", "fs", "alpha0", "freq_power", "excitation", "transfer_function", "monochromatic", "fast_attenuation", "verbose", "transducer".

 required
value object

New value for the parameter.

 required

Raises:

Type Description
ValueError

If name is not a recognized parameter.
TypeError

If value has the wrong type.

compute_deltak 

compute_deltak(field_points_mm, *, method='auto')

Per-patch trapezoid width Δk (in samples) for every field point.

SIR-accuracy diagnostic: Δk is how many time samples each patch's trapezoidal SIR spans at this geometry. The far-field/sampling approximation degrades when Δk is too small (a patch barely resolved in time), and the auto method switches FST→SDI above 8 + 2T/M. Inspect this to check a chosen no_sub_x/no_sub_y resolves every patch.

Parameters:

Name Type Description Default
field_points_mm dict or (N, 3) numpy.ndarray

Grid spec dict (mm) or raw point array (mm), as in __call__.

 required
method str

SIR method ("auto", "FST", "sdi") — only affects which patches the kernel would take the SDI path for; Δk itself is method-independent.

 "auto"

Returns:

Type Description
(P, M) numpy.ndarray

Trapezoid width in samples for each field point P and patch M.