esdiva 0.1.0__py3-none-any.whl

esdiva/__init__.py

@@ -0,0 +1,142 @@
+"""Acoustic field simulator based on the spatial impulse response method (eSDIva)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+import esdiva.attenuation as attenuation
+import esdiva.beamforming as beamforming
+import esdiva.emission as emission
+import esdiva.plotting as plotting
+import esdiva.reception as reception
+import esdiva.transducers as transducers
+import esdiva.utilities as utilities
+from esdiva.beamforming import DAS_focused_scanline, envelope_db
+from esdiva.emission import Emission
+from esdiva.plotting import plot2D_pressure_slices
+from esdiva.reception import Reception, ReceptionConventional
+from esdiva.utilities import align_to_common_time, to_dB
+
+
+# backward-compat alias (old signature was x, y, z, p; new is p, x, y, z)
+def plot_pressure_planes(x, y, z, pressure_field, **kwargs):
+    """Plot pressure planes (deprecated, use `plot2D_pressure_slices`).
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        Lateral coordinates.
+    y : numpy.ndarray
+        Elevation coordinates.
+    z : numpy.ndarray
+        Axial coordinates.
+    pressure_field : numpy.ndarray
+        Pressure data.
+    **kwargs
+        Forwarded to `plot2D_pressure_slices`.
+
+    Returns
+    -------
+    None
+        No return value; displays the plot.
+    """
+    return plot2D_pressure_slices(pressure_field, x=x, y=y, z=z, **kwargs)
+
+
+__all__ = [
+    "Emission",
+    "Reception",
+    "ReceptionConventional",
+    "attenuation",
+    "beamforming",
+    "DAS_focused_scanline",
+    "emission",
+    "envelope_db",
+    "reception",
+    "transducers",
+    "utilities",
+    "plotting",
+    "plot2D_pressure_slices",
+    "align_to_common_time",
+    "plot_pressure_planes",
+    "to_dB",
+]
+
+try:
+    __version__ = version("esdiva")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+
+def main() -> None:
+    """Greet the user and run a small timed demo field, then show it in 3-D.
+
+    Entry point for ``uv run esdiva`` / the ``esdiva`` console script. Prints a
+    banner, focuses a 17x17 matrix array at 3 mm, computes one monochromatic
+    (CW) pressure volume around the focus, reports how long the SIR took, and
+    opens a PyVista window with the transducer mesh and the normalized pressure
+    volume — a few-second "it works" that shows the 3-D field for new users.
+    """
+    import time
+
+    import numpy as np
+    import pyvista as pv
+
+    from .plotting import add_pressure_vol, add_transducer_mesh, create_3Dvol_mesh
+
+    banner = rf"""
+  ___   ____    ____    ___            __ _
+ / _ \ / ___|  |  _ \  |_ _| __   __  / _` |
+|  __/ \___ \  | | | |  | |  \ \ / / | (_| |
+ \___|  ___) | | |_| |  | |   \ V /   \__,_|
+       |____/  |____/  |___|   \_/            v{__version__}
+
+  Efficient Sparse Delta Integration for Vectorized Acoustics.
+  A friendly, fast, exact ultrasound field simulator.
+"""
+    print(banner)
+
+    # 17x17 matrix array at 10 MHz, geometrically focused at 3 mm depth.
+    probe = transducers.MatrixArrayTransducer(
+        n_elements_x=17,
+        n_elements_y=17,
+        element_width_mm=0.2,
+        element_height_mm=0.2,
+        kerf_x_mm=0.05,
+        kerf_y_mm=0.05,
+        no_sub_x=2,
+        no_sub_y=2,
+        frequency_Hz=10e6,
+    )
+    focus_mm = np.array([0, 0, 3])
+    probe.compute_delays(focus_mm=focus_mm)
+    probe.compute_apodization(focus_mm=focus_mm, FoverD=1.0)
+
+    # Coarse grid around the focus (0.5 x 0.5 x 1.5 mm box) — kept coarse so the
+    # volume renders in seconds; drop the step sizes for a finer field.
+    field_points = {
+        "x_extent": [focus_mm[0] - 0.5, focus_mm[0] + 0.5],
+        "y_extent": [focus_mm[1] - 0.5, focus_mm[1] + 0.5],
+        "z_extent": [focus_mm[2] - 1.5, focus_mm[2] + 1.5],
+        "dx": 0.03,
+        "dy": 0.03,
+        "dz": 0.05,
+    }
+
+    print("Simulating a CW field at 10 MHz around the 3 mm focus ...")
+    sim = emission.Emission(probe, monochromatic=True)
+    t0 = time.perf_counter()
+    p, coords = sim(field_points, method="auto")
+    dt = time.perf_counter() - t0
+    print(f"  done in {dt:.2f} s  (peak |p| = {float(np.abs(p).max()):.3g})")
+    print("  opening the 3-D field - close the window to exit.")
+
+    # Build the transducer + normalized-pressure meshes and render both.
+    tx_mesh = probe.get_mesh()
+    pressure_mesh = create_3Dvol_mesh(
+        p / p.max(), coords["x"], coords["y"], coords["z"], scalars="Pressure"
+    )
+    plotter = pv.Plotter(window_size=(700, 700), notebook=False)
+    plotter = add_pressure_vol(pressure_mesh, plotter=plotter, ambient=0.6)
+    plotter = add_transducer_mesh(tx_mesh, plotter=plotter, ambient=1.0)
+    plotter.add_axes(label_size=(0.1, 0.1))
+    plotter.camera.up = (0, 0, -1)
+    plotter.show()

esdiva/attenuation/__init__.py

@@ -0,0 +1,17 @@
+"""Causal power-law attenuation transfer functions and distance utilities."""
+
+from .attenuation import (
+    causal_attenuation_tf,
+    compute_attenuation_distances,
+    compute_reception_distances,
+    convert_alpha0_to_nepers,
+    reduce_patch_distances_to_element,
+)
+
+__all__ = [
+    "causal_attenuation_tf",
+    "compute_attenuation_distances",
+    "compute_reception_distances",
+    "convert_alpha0_to_nepers",
+    "reduce_patch_distances_to_element",
+]

esdiva/attenuation/attenuation.py

@@ -0,0 +1,376 @@
+"""Causal power-law attenuation transfer functions and distance helpers.
+
+Standalone module — no dependency on Emission or Reception.  Both import
+from here.
+
+Models frequency-dependent tissue attenuation as a power law ``α(ω) = α₀·|ω|^y``
+together with its causal Kramers-Kronig phase dispersion (Szabo 1994; Holm 2019), so
+the transfer function both damps and correctly delays each frequency — a non-causal
+amplitude-only form would produce pre-echo precursors.
+
+Notes
+-----
+**Unit convention**
+
+* User-facing: ``alpha0`` in dB/(MHz^y·cm) — matches clinical literature.
+* Internal: ``alpha0`` in Np/(Hz^y·m) — convert via ``convert_alpha0_to_nepers``.
+
+**Attenuation model**
+
+Causal power-law (Szabo 1994, Holm 2019).  Always includes Kramers-Kronig
+dispersion — cost is zero, accuracy is strictly better than non-causal.
+
+Frequency convention: formulas use linear frequency f [Hz], not angular
+frequency omega.  The ``causal_attenuation_tf`` unit conversion uses
+f-convention (no 2pi factor in the exponent), matching the dB/(MHz^y·cm)
+user unit.
+"""
+
+import numpy as np
+from numba import njit
+
+
+# ---------------------------------------------------------------------------
+# Unit conversion
+# ---------------------------------------------------------------------------
+
+
+def convert_alpha0_to_nepers(alpha0_dB: float, y: float) -> float:
+    """Convert attenuation coefficient from dB/(MHz^y·cm) to Np/(Hz^y·m).
+
+    Parameters
+    ----------
+    alpha0_dB : float
+        Attenuation in dB/(MHz^y·cm) (user-facing unit).
+    y : float
+        Power-law exponent.
+
+    Returns
+    -------
+    float
+        Attenuation coefficient in Np/(Hz^y·m).
+
+    Notes
+    -----
+    Conversion:
+    ``alpha0_neper = alpha0_dB * 100 / (20 * log10(e) * 1e6^y)``
+
+    * ``100``: 1/cm → 1/m (100 cm = 1 m).
+    * ``20 * log10(e) ≈ 8.686``: dB → Np (1 Np = 8.686 dB).
+    * ``(1e6)^y``: MHz^y → Hz^y.
+    """
+    return float(alpha0_dB) * 100.0 / (20.0 * np.log10(np.e) * (1e6 ** float(y)))
+
+
+# ---------------------------------------------------------------------------
+# Core transfer function
+# ---------------------------------------------------------------------------
+
+
+def causal_attenuation_tf(
+    freqs_hz: np.ndarray,
+    distances_m: np.ndarray,
+    alpha0_dB: float,
+    y: float,
+    f0_hz: float,
+) -> np.ndarray:
+    """Causal power-law attenuation transfer function H_att(f, d).
+
+    Absorption and Kramers–Kronig dispersion combined.
+
+    General case (y ≠ 1):
+
+    .. code-block:: text
+
+        H(f, d) = exp(-α₀ |f|^y d) · exp(-j α₀ |f|^y tan(yπ/2) d)
+
+    Special case (y = 1, O'Donnell 1981):
+
+    .. code-block:: text
+
+        H(f, d) = exp(-α₀ |f| d) · exp(-j (2α₀/π) f ln(|f|/f₀) d)
+
+    Where α₀ is in Np/(Hz^y·m) (converted internally from dB/(MHz^y·cm)).
+
+    Parameters
+    ----------
+    freqs_hz : (N_freq,) ndarray
+        Frequency array in Hz (e.g. from ``numpy.fft.rfftfreq``).
+    distances_m : ndarray, shape (...)
+        Propagation distances in metres.  Any leading shape is accepted —
+        the function broadcasts to return ``(..., N_freq)``.
+    alpha0_dB : float
+        Attenuation coefficient in dB/(MHz^y·cm).
+        Pass ``0`` or ``None`` for no attenuation (returns all-ones array).
+    y : float
+        Power-law exponent (tissue: 1.0–1.3).
+    f0_hz : float
+        Reference frequency in Hz (transducer centre frequency).  Used only
+        for the y = 1 logarithmic dispersion term.
+
+    Returns
+    -------
+    numpy.ndarray
+        Attenuation transfer function H, shape ``(..., N_freq)``,
+        complex128.  ``|H| <= 1``.
+
+    Notes
+    -----
+    * DC (f = 0): H = 1 (no attenuation at zero frequency — correct limit).
+    * ``alpha0_dB = 0``: H = 1 everywhere (identity).
+    """
+    if alpha0_dB is None or alpha0_dB == 0:
+        freqs = np.asarray(freqs_hz, dtype=np.float64)
+        dist = np.asarray(distances_m, dtype=np.float64)
+        return np.ones((*dist.shape, freqs.shape[0]), dtype=np.complex128)
+
+    alpha0 = convert_alpha0_to_nepers(float(alpha0_dB), float(y))
+    freqs = np.asarray(freqs_hz, dtype=np.float64)  # (N_freq,)
+    dist = np.asarray(distances_m, dtype=np.float64)  # (...)
+    freq_abs = np.abs(freqs)  # (N_freq,)
+
+    # Broadcast: dist[..., np.newaxis] * freq_term[np.newaxis, ...]
+    dist_e = dist[..., np.newaxis]  # (..., 1)
+
+    if abs(float(y) - 1.0) < 1e-10:
+        # Special case y = 1: logarithmic K-K dispersion (O'Donnell 1981).
+        f0 = float(f0_hz)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            log_ratio = np.where(freq_abs > 0.0, np.log(freq_abs / f0), 0.0)
+        absorption = np.exp(-alpha0 * freq_abs * dist_e)
+        # f * ln(|f|/f0) → 0 at DC (handled by where above when freq=0 → log_ratio=0)
+        phase = -(2.0 * alpha0 / np.pi) * freqs * log_ratio * dist_e
+        H = absorption * np.exp(1j * phase)
+    else:
+        # General case y ≠ 1: Szabo 1994.
+        freq_pow_y = freq_abs ** float(y)  # (N_freq,)
+        absorption = np.exp(-alpha0 * freq_pow_y * dist_e)  # (..., N_freq)
+        tan_term = np.tan(float(y) * np.pi / 2.0)
+        # sign(f) ensures causal dispersion for negative-frequency components.
+        phase = -alpha0 * np.sign(freqs) * freq_pow_y * tan_term * dist_e
+        H = absorption * np.exp(1j * phase)
+
+    return H  # complex128, shape (..., N_freq)
+
+
+# ---------------------------------------------------------------------------
+# Scalar njit form (one frequency, one path) — shared with the SDI kernels
+# ---------------------------------------------------------------------------
+
+
+@njit(inline="always")
+def _causal_atten_factor(omega, dist, alpha0_np, y, tan_y, f0_hz, y_is_one):
+    """Causal power-law attenuation H_att for one angular frequency over one path.
+
+    Scalar twin of `causal_attenuation_tf`, written for the Numba SDI kernels so the
+    analytic one-way spectrum can attenuate each patch's contribution *per path* as it
+    is summed (the patch-to-point distance is already in hand). Same physics: a
+    band-damping magnitude times a Kramers-Kronig phase that keeps the pulse causal.
+
+    The formulas are stated in linear frequency ``f = ω/2π`` (Hz), matching
+    `causal_attenuation_tf`. With absorption coefficient ``α₀`` in Np/(Hz^y·m):
+
+        y ≠ 1 :  H = exp(−α₀|f|^y d) · exp(−j α₀ sign(f) |f|^y tan(yπ/2) d)
+        y = 1 :  H = exp(−α₀|f|  d) · exp(−j (2α₀/π) f ln(|f|/f₀) d)   (O'Donnell 1981)
+
+    Parameters
+    ----------
+    omega : float
+        Angular frequency 2πf (rad/s).
+    dist : float
+        Propagation path length d (metres).
+    alpha0_np : float
+        Absorption coefficient in Np/(Hz^y·m) (already converted from dB/(MHz^y·cm)
+        with `convert_alpha0_to_nepers`).
+    y : float
+        Power-law exponent.
+    tan_y : float
+        Precomputed ``tan(yπ/2)`` (ignored on the y = 1 branch; pass any value).
+    f0_hz : float
+        Reference frequency f₀ (Hz) for the y = 1 logarithmic dispersion.
+    y_is_one : bool
+        True selects the y = 1 logarithmic-dispersion branch.
+
+    Returns
+    -------
+    complex
+        Complex attenuation factor (``|H| ≤ 1``); 1 at f = 0.
+    """
+    f = omega / (2.0 * np.pi)
+    f_abs = abs(f)
+    if f_abs == 0.0:
+        return complex(1.0, 0.0)
+    if y_is_one:
+        absorption = np.exp(-alpha0_np * f_abs * dist)
+        phase = -(2.0 * alpha0_np / np.pi) * f * np.log(f_abs / f0_hz) * dist
+    else:
+        f_pow_y = f_abs**y
+        absorption = np.exp(-alpha0_np * f_pow_y * dist)
+        sign_f = 1.0 if f > 0.0 else -1.0
+        phase = -alpha0_np * sign_f * f_pow_y * tan_y * dist
+    return absorption * complex(np.cos(phase), np.sin(phase))
+
+
+# ---------------------------------------------------------------------------
+# Distance computation helpers
+# ---------------------------------------------------------------------------
+
+
+def compute_attenuation_distances(
+    field_points_m: np.ndarray,
+    transducer_center_m: np.ndarray,
+    patch_centers_m: np.ndarray | None = None,
+    mode: str = "per_point",
+) -> np.ndarray:
+    """Propagation distance for attenuation.
+
+    Parameters
+    ----------
+    field_points_m : (P, 3) ndarray
+        Field point coordinates in metres.
+    transducer_center_m : (3,) ndarray
+        Transducer geometric centre in metres.
+    patch_centers_m : (M, 3) ndarray or None
+        Patch centre coordinates in metres.  Required when ``mode="per_patch"``.
+    mode : {"per_point", "per_patch"}
+        Distance model:
+
+        * ``"per_point"`` (fast, approximate): ``d_p = |r_p - r_tx_center|``,
+          shape ``(P,)``.
+        * ``"per_patch"`` (accurate near-field): ``d_{pm} = |r_p - r_m|``,
+          shape ``(P, M)``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Distances in metres.  Shape ``(P,)`` for ``per_point``, ``(P, M)``
+        for ``per_patch``.
+
+    Raises
+    ------
+    ValueError
+        If ``mode="per_patch"`` and ``patch_centers_m`` is None, or if
+        ``mode`` is unknown.
+    """
+    field_points_m = np.asarray(field_points_m, dtype=np.float64)  # (P, 3)
+    transducer_center_m = np.asarray(transducer_center_m, dtype=np.float64)  # (3,)
+
+    if mode == "per_point":
+        return np.linalg.norm(field_points_m - transducer_center_m, axis=1)  # (P,)
+
+    if mode == "per_patch":
+        if patch_centers_m is None:
+            raise ValueError("patch_centers_m required for mode='per_patch'.")
+        patch_centers_m = np.asarray(patch_centers_m, dtype=np.float64)  # (M, 3)
+        # (P, M, 3) → norm → (P, M)
+        diff = field_points_m[:, np.newaxis, :] - patch_centers_m[np.newaxis, :, :]
+        return np.linalg.norm(diff, axis=2)
+
+    raise ValueError(f"mode must be 'per_point' or 'per_patch', got '{mode}'.")
+
+
+def reduce_patch_distances_to_element(
+    distances_pm: np.ndarray,
+    sub_el_idx: np.ndarray,
+    n_elements: int,
+    reduce: str = "mean",
+) -> np.ndarray:
+    """Reduce per-patch distances (P, M) to per-element distances (P, E).
+
+    Parameters
+    ----------
+    distances_pm : (P, M) ndarray
+        Per-patch distances from ``compute_attenuation_distances(mode='per_patch')``.
+    sub_el_idx : (M,) int32 ndarray
+        Patch-to-element index from ``compute_sub_elem_attributes``.
+    n_elements : int
+        Total number of elements E.
+    reduce : {"mean", "min", "max"}
+        Reduction strategy over patches belonging to the same element.
+
+        * ``"mean"``: average distance (good when patches cluster tightly).
+        * ``"min"``: minimum distance (conservative — least attenuation).
+        * ``"max"``: maximum distance (most attenuation).
+
+    Returns
+    -------
+    numpy.ndarray
+        One representative distance per field-point / element pair,
+        shape ``(P, E)``.
+
+    Raises
+    ------
+    ValueError
+        If ``reduce`` is not one of the supported strategies.
+    """
+    distances_pm = np.asarray(distances_pm, dtype=np.float64)  # (P, M)
+    sub_el_idx = np.asarray(sub_el_idx, dtype=np.int32)  # (M,)
+    P = distances_pm.shape[0]
+    result = np.zeros((P, n_elements), dtype=np.float64)
+
+    if reduce not in ("mean", "min", "max"):
+        raise ValueError(f"reduce must be 'mean', 'min', or 'max', got '{reduce}'.")
+
+    for e in range(n_elements):
+        mask = sub_el_idx == e
+        if not mask.any():
+            continue
+        d_e = distances_pm[:, mask]  # (P, count_e)
+        if reduce == "mean":
+            result[:, e] = d_e.mean(axis=1)
+        elif reduce == "min":
+            result[:, e] = d_e.min(axis=1)
+        else:
+            result[:, e] = d_e.max(axis=1)
+
+    return result  # (P, E)
+
+
+def compute_reception_distances(
+    scatterer_positions_m: np.ndarray,
+    tx_center_m: np.ndarray,
+    rx_element_centers_m: np.ndarray,
+) -> np.ndarray:
+    """Round-trip distances for per-element Reception attenuation.
+
+    Two-path model:
+    ``d_total[p, e] = |r_s_p - r_tx| + |r_s_p - r_rx_e|``
+
+    TX path is isotropic (same for all RX elements).
+    RX path is per-element (each element receives from a different distance).
+
+    Parameters
+    ----------
+    scatterer_positions_m : (P, 3) ndarray
+        Scatterer positions in metres.
+    tx_center_m : (3,) ndarray
+        TX transducer geometric centre in metres.
+    rx_element_centers_m : (E_rx, 3) ndarray
+        RX element centre positions in metres (one per element).
+
+    Returns
+    -------
+    numpy.ndarray
+        Total round-trip distance per scatterer-element pair (metres),
+        shape ``(P, E_rx)``.  Feed directly into ``causal_attenuation_tf``
+        to get H_att of shape ``(P, E_rx, N_freq)``.
+    """
+    scatterer_positions_m = np.asarray(
+        scatterer_positions_m, dtype=np.float64
+    )  # (P, 3)
+    tx_center_m = np.asarray(tx_center_m, dtype=np.float64)  # (3,)
+    rx_element_centers_m = np.asarray(
+        rx_element_centers_m, dtype=np.float64
+    )  # (E_rx, 3)
+
+    # TX path: (P,)
+    d_tx = np.linalg.norm(scatterer_positions_m - tx_center_m, axis=1)
+
+    # RX path: (P, E_rx)
+    diff = (
+        scatterer_positions_m[:, np.newaxis, :]  # (P, 1, 3)
+        - rx_element_centers_m[np.newaxis, :, :]  # (1, E_rx, 3)
+    )  # (P, E_rx, 3)
+    d_rx = np.linalg.norm(diff, axis=2)  # (P, E_rx)
+
+    return d_tx[:, np.newaxis] + d_rx  # (P, E_rx)

esdiva/beamforming/__init__.py

@@ -0,0 +1,15 @@
+"""Post-processing beamforming functions for eSDIva RF data."""
+
+from .das import (
+    DAS_focused_scanline,
+    das_rca_volume,
+    das_volume,
+    envelope_db,
+)
+
+__all__ = [
+    "DAS_focused_scanline",
+    "das_rca_volume",
+    "das_volume",
+    "envelope_db",
+]