FastSIMUS 0.0.1__py3-none-any.whl

fast_simus/transducer_params.py

@@ -0,0 +1,160 @@
+"""Transducer parameter definitions for FastSIMUS."""
+
+from enum import StrEnum
+from math import inf
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, NonNegativeFloat, model_validator
+
+
+class BaffleType(StrEnum):
+    """Baffle type enumeration for transducer acoustic boundary conditions.
+
+    The baffle property affects the obliquity factor in the directivity of elements.
+
+    Attributes:
+        SOFT: Soft baffle (pressure-release boundary), obliquity factor = cos(theta)
+        RIGID: Rigid baffle (pressure-doubling boundary), obliquity factor = 1
+    """
+
+    SOFT = "soft"
+    RIGID = "rigid"
+
+
+class TransducerParams(BaseModel):
+    """Transducer parameters for ultrasound simulation.
+
+    This class encapsulates all physical and geometric parameters needed for
+    ultrasound transducer simulation, following SIMUS/MUST conventions.
+
+    Examples:
+        >>> # Linear array with element width
+        >>> params = TransducerParams(
+        ...     freq_center=2.5e6,
+        ...     pitch=300e-6,
+        ...     n_elements=128,
+        ...     width=250e-6
+        ... )
+        >>> params.element_width
+        0.00025
+        >>> params.kerf_width
+        5e-05
+        >>>
+        >>> # Convex array with kerf
+        >>> params = TransducerParams(
+        ...     freq_center=3.5e6,
+        ...     pitch=400e-6,
+        ...     n_elements=64,
+        ...     kerf=50e-6,
+        ...     radius=50e-3
+        ... )
+        >>> params.element_width
+        0.00035
+    """
+
+    model_config = ConfigDict(use_attribute_docstrings=True, frozen=True)
+
+    # === Required Fields ===
+    freq_center: float = Field(..., gt=0)
+    """Center frequency in Hz. Must be positive."""
+
+    pitch: float = Field(..., gt=0)
+    """Element pitch (center-to-center spacing) in meters. Must be positive."""
+
+    n_elements: int = Field(..., gt=0)
+    """Number of transducer elements. Must be positive integer."""
+
+    # === Mutually Exclusive: Width or Kerf ===
+    width: float | None = Field(None, gt=0)
+    """Element width in meters. Mutually exclusive with kerf. Must be positive if provided."""
+
+    kerf: float | None = Field(None, ge=0)
+    """Kerf width (gap between elements) in meters. Mutually exclusive with width. Must be non-negative if provided."""
+
+    # === Optional Geometric Fields ===
+    height: float = Field(default=inf, gt=0)
+    """Element height in meters. Defaults to infinity for 2D simulation."""
+
+    elev_focus: float = Field(default=inf, gt=0)
+    """Elevation focus distance in meters. Defaults to infinity (unfocused)."""
+
+    radius: float = Field(default=inf, gt=0)
+    """Curvature radius in meters for convex arrays. Defaults to infinity (linear array)."""
+
+    # === Optional Acoustic Fields ===
+    bandwidth: float = Field(default=0.75, gt=0, le=2.0)
+    """Fractional bandwidth (0.75 = 75%). Must be in (0, 2.0]. Defaults to 0.75."""
+
+    baffle: BaffleType | NonNegativeFloat = Field(default=BaffleType.SOFT)
+    """Baffle type or acoustic impedance ratio.
+
+    Input: "soft", "rigid" (case-insensitive), or impedance ratio (float >= 0).
+    After validation, becomes BaffleType.SOFT, BaffleType.RIGID, or float.
+    Defaults to "soft".
+    """
+
+    # === Computed properties ===
+    @property
+    def element_width(self) -> float:
+        """Element width in meters.
+
+        Computed from width (if provided) or pitch - kerf (if kerf provided).
+
+        Returns:
+            Element width in meters.
+
+        Raises:
+            ValueError: If neither width nor kerf is provided.
+        """
+        if self.width is not None:
+            return self.width
+        if self.kerf is not None:
+            return self.pitch - self.kerf
+        msg = "Either width or kerf must be provided"
+        raise ValueError(msg)
+
+    @property
+    def kerf_width(self) -> float:
+        """Kerf width in meters.
+
+        Computed from kerf (if provided) or pitch - width (if width provided).
+
+        Returns:
+            Kerf width in meters.
+
+        Raises:
+            ValueError: If neither width nor kerf is provided.
+        """
+        if self.kerf is not None:
+            return self.kerf
+        if self.width is not None:
+            return self.pitch - self.width
+        msg = "Either width or kerf must be provided"
+        raise ValueError(msg)
+
+    @model_validator(mode="after")
+    def validate_width_kerf(self) -> Self:
+        """Validate that exactly one of width or kerf is provided and physically valid.
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        if self.width is None and self.kerf is None:
+            msg = "Either width or kerf must be provided"
+            raise ValueError(msg)
+        if self.width is not None and self.kerf is not None:
+            msg = "Cannot specify both width and kerf. Provide only one."
+            raise ValueError(msg)
+
+        # Validate physical constraints
+        if self.width is not None and self.width > self.pitch:
+            msg = f"Element width ({self.width}) cannot exceed pitch ({self.pitch})"
+            raise ValueError(msg)
+        if self.kerf is not None and self.kerf >= self.pitch:
+            msg = f"Kerf ({self.kerf}) must be less than pitch ({self.pitch})"
+            raise ValueError(msg)
+
+        return self

fast_simus/transducer_presets.py

@@ -0,0 +1,102 @@
+"""Preset transducer configurations for common ultrasound probes.
+
+These presets are based on Verasonics transducers and match the values
+from the MUST toolbox (getparam.m).
+"""
+
+from math import inf
+
+from fast_simus import TransducerParams
+
+
+def P4_2v() -> TransducerParams:
+    """Create P4-2v phased array transducer preset.
+
+    Verasonics P4-2v phased array transducer for cardiac imaging:
+    - 2.72 MHz center frequency
+    - 64 elements
+    - 300 µm (0.3 mm) pitch
+
+    Returns:
+        TransducerParams instance configured for P4-2v transducer.
+    """
+    return TransducerParams(
+        freq_center=2.72e6,  # 2.72 MHz
+        pitch=300e-6,  # 300 µm
+        n_elements=64,
+        kerf=50e-6,  # 50 µm
+        bandwidth=0.74,  # 74%
+        radius=inf,
+        height=14e-3,  # 14 mm
+        elev_focus=60e-3,  # 60 mm
+    )
+
+
+def L11_5v() -> TransducerParams:
+    """Create L11-5v linear array transducer preset.
+
+    Verasonics L11-5v high-frequency linear array for vascular imaging:
+    - 7.6 MHz center frequency
+    - 128 elements
+    - 300 µm (0.3 mm) pitch
+
+    Returns:
+        TransducerParams instance configured for L11-5v transducer.
+    """
+    return TransducerParams(
+        freq_center=7.6e6,  # 7.6 MHz
+        pitch=300e-6,  # 300 µm
+        n_elements=128,
+        kerf=30e-6,  # 30 µm
+        bandwidth=0.77,  # 77%
+        radius=inf,
+        height=5e-3,  # 5 mm
+        elev_focus=18e-3,  # 18 mm
+    )
+
+
+def L12_3v() -> TransducerParams:
+    """Create L12-3v linear array transducer preset.
+
+    Verasonics L12-3v high-frequency linear array:
+    - 7.54 MHz center frequency
+    - 192 elements
+    - 200 µm (0.2 mm) pitch
+
+    Returns:
+        TransducerParams instance configured for L12-3v transducer.
+    """
+    return TransducerParams(
+        freq_center=7.54e6,  # 7.54 MHz
+        pitch=200e-6,  # 200 µm
+        n_elements=192,
+        kerf=30e-6,  # 30 µm
+        bandwidth=0.93,  # 93%
+        radius=inf,
+        height=5e-3,  # 5 mm
+        elev_focus=20e-3,  # 20 mm
+    )
+
+
+def C5_2v() -> TransducerParams:
+    """Create C5-2v convex array transducer preset.
+
+    Verasonics C5-2v convex array for abdominal imaging:
+    - 3.57 MHz center frequency
+    - 128 elements
+    - 508 µm (0.508 mm) pitch
+    - 49.57 mm radius of curvature
+
+    Returns:
+        TransducerParams instance configured for C5-2v transducer.
+    """
+    return TransducerParams(
+        freq_center=3.57e6,  # 3.57 MHz
+        pitch=508e-6,  # 508 µm
+        n_elements=128,
+        kerf=48e-6,  # 48 µm
+        bandwidth=0.79,  # 79%
+        radius=49.57e-3,  # 49.57 mm
+        height=13.5e-3,  # 13.5 mm
+        elev_focus=60e-3,  # 60 mm
+    )

fast_simus/tx_delay.py

@@ -0,0 +1,276 @@
+"""Transmit delay calculations for ultrasound transducer arrays.
+
+This module provides functions to compute transmit time delays for different
+beam patterns (focused/diverging, plane wave, circular wave) with linear and
+convex arrays.
+
+All functions are Array API compliant and work with NumPy, JAX, CuPy backends.
+
+Coordinate System Convention:
+    - x-axis: Lateral (perpendicular to beam direction), in meters
+    - z-axis: Axial (along beam direction, positive = into tissue), in meters
+    - Origin: Center of transducer face
+
+Sign Convention:
+    - Positive z: Points into the imaging medium (tissue)
+    - Delays are relative to minimum (all non-negative)
+    - For focused beams: positive z0 = focus in front, negative z0 = diverging
+"""
+
+from __future__ import annotations
+
+from math import cos, fmod, inf, pi, sin, sqrt, tan
+
+from array_api_compat import array_namespace
+from beartype import beartype as typechecker
+from jaxtyping import Float, jaxtyped
+
+from fast_simus.utils._array_api import Array
+
+
+@jaxtyped(typechecker=typechecker)
+def focused(
+    element_positions: Float[Array, "n_elements dim"],
+    focus: Float[Array, " dim"],
+    *,
+    speed_of_sound: float,
+    radius: float = inf,
+    apex_offset: float = 0.0,
+) -> Float[Array, " n_elements"]:
+    """Compute transmit time delays for focused or diverging spherical waves.
+
+    Spherical waves propagate like a collapsing sphere focusing onto a point
+    (positive z), or an expanding sphere diverging from a virtual source
+    (negative z).
+
+    Args:
+        element_positions:
+            Element positions in meters. Shape (n_elements, dim).
+            For 2D: (x, z) where x is lateral, z is axial.
+            For 3D: (x, y, z) where z is axial (depth).
+        focus:
+            Focal position in meters. Shape (dim,).
+            Coordinates match element_positions dimensions.
+            - Last coordinate (z): Axial position
+              - Positive z: Focused wave (focus in front of transducer)
+              - Negative z: Diverging wave (virtual source behind transducer)
+              - z=0: Treated as focusing just in front (negative delays)
+        speed_of_sound:
+            Speed of sound in m/s.
+        radius:
+            Curvature radius in meters. Use inf for linear arrays.
+            Convex arrays require dim=2 (runtime check).
+        apex_offset:
+            Distance from array center to arc apex in meters. Zero for linear arrays.
+            Defaults to 0.0.
+
+    Returns:
+        Transmit time delays in seconds. Shape (n_elements,).
+        Delays are relative to minimum (all non-negative).
+
+    Notes:
+        Implementation matches PyMUST reference with identical sign conventions.
+
+        For linear arrays, sign is based on z-coordinate of focus.
+        For convex arrays, sign is based on whether focus is inside or outside
+        the arc (comparing squared distance to squared radius).
+
+        Reference:
+            Perrot et al. 2021, "So you think you can DAS?"
+            https://www.biomecardio.com/publis/ultrasonics21.pdf
+            (Equation 5, extended to support virtual sources)
+    """
+    xp = array_namespace(element_positions, focus)
+
+    # Compute distance from each element to focus
+    # element_positions: (n_elements, dim), focus: (dim,)
+    # Broadcasting: (n_elements, dim) - (dim,) -> (n_elements, dim)
+    diff = element_positions - focus
+    distances = xp.sqrt(xp.sum(diff**2, axis=-1))  # (n_elements,)
+
+    if radius == inf:
+        # Linear array: sign based on axial position (last coordinate)
+        z_focus = focus[-1]
+        sgn = xp.sign(z_focus)
+        sgn = xp.where(sgn == 0, -1, sgn)
+        delays = -distances * sgn / speed_of_sound
+    else:
+        # Convex array: requires 2D coordinates
+        if focus.shape[0] != 2:
+            msg = f"Convex arrays require 2D coordinates, got dim={focus.shape[0]}"
+            raise ValueError(msg)
+
+        # Sign based on inside/outside arc
+        x_focus = focus[0]
+        z_focus = focus[-1]
+        sgn = xp.sign(x_focus**2 + (z_focus + apex_offset) ** 2 - radius**2)
+        sgn = xp.where(sgn == 0, -1, sgn)
+        delays = -distances * sgn / speed_of_sound
+
+    # Make all delays non-negative by subtracting minimum
+    delays = delays - xp.min(delays)
+
+    return delays
+
+
+@jaxtyped(typechecker=typechecker)
+def plane_wave(
+    element_positions: Float[Array, "n_elements xz=2"],
+    tilt_rad: float,
+    *,
+    speed_of_sound: float,
+    radius: float = inf,
+    apex_offset: float = 0.0,
+) -> Float[Array, " n_elements"]:
+    """Compute transmit time delays for plane wave transmission.
+
+    Plane waves have a flat wavefront propagating in a specified direction,
+    defined by the tilt angle from the array normal (z-axis).
+
+    Args:
+        element_positions:
+            Element (x, z) positions in meters. Shape (n_elements, 2).
+            - element_positions[:, 0]: Lateral positions (x)
+            - element_positions[:, 1]: Axial positions (z)
+        tilt_rad:
+            Tilt angle in radians.
+            - tilt_rad=0: Straight ahead (perpendicular to array)
+            - Positive tilt_rad: Beam steers right (positive x direction)
+            - Negative tilt_rad: Beam steers left (negative x direction)
+            Must satisfy |tilt_rad| < π/2.
+        speed_of_sound:
+            Speed of sound in m/s.
+        radius:
+            Curvature radius in meters. Use inf for linear arrays.
+        apex_offset:
+            Distance from array center to arc apex in meters. Zero for linear arrays.
+            Defaults to 0.0.
+
+    Returns:
+        Transmit time delays in seconds. Shape (n_elements,).
+        Delays are relative to minimum (all non-negative).
+
+    Raises:
+        ValueError: If |tilt_rad| >= π/2 (non-physical angle).
+
+    Notes:
+        For linear arrays, delays follow simple sinusoidal pattern based on
+        lateral element position.
+
+        For convex arrays, the computation accounts for the curved geometry
+        by computing distance to the plane perpendicular to the tilt direction.
+    """
+    # Validate tilt angle
+    if abs(tilt_rad) >= pi / 2:
+        msg = "Tilt angles must satisfy |tilt_rad| < π/2"
+        raise ValueError(msg)
+
+    xp = array_namespace(element_positions)
+
+    # Extract element positions
+    x_elem = element_positions[:, 0]  # Shape (n_elements,)
+    z_elem = element_positions[:, 1]  # Shape (n_elements,)
+
+    if radius == inf:
+        # Linear array: delay proportional to lateral position
+        delays = x_elem * sin(tilt_rad) / speed_of_sound
+    else:
+        # Convex array: geometric calculation
+        xn = radius * sin(tilt_rad)
+        zn = radius * cos(tilt_rad) - apex_offset
+        numerator = xp.abs(z_elem + xn / (zn + apex_offset) * x_elem - xn**2 / (zn + apex_offset) - zn)
+        denominator = sqrt(1 + xn**2 / (zn + apex_offset) ** 2)
+        d = numerator / denominator
+        delays = -d / speed_of_sound
+
+    # Make all delays non-negative
+    delays = delays - xp.min(delays)
+
+    return delays
+
+
+@jaxtyped(typechecker=typechecker)
+def diverging_wave(
+    element_positions: Float[Array, "n_elements xz=2"],
+    tilt_rad: float,
+    width_rad: float,
+    *,
+    aperture_length: float,
+    speed_of_sound: float,
+) -> Float[Array, " n_elements"]:
+    """Compute transmit time delays for diverging circular wave transmission.
+
+    Circular waves originate from a virtual point source positioned such that
+    the wavefront spans a specified angular width across the array.
+    Only supported for linear arrays.
+
+    Args:
+        element_positions:
+            Element (x, z) positions in meters. Shape (n_elements, 2).
+            - element_positions[:, 0]: Lateral positions (x)
+            - element_positions[:, 1]: Axial positions (z)
+        tilt_rad:
+            Tilt angle of the wave center in radians.
+        width_rad:
+            Angular width of the wave in radians.
+            Must satisfy 0 < width_rad < π.
+        aperture_length:
+            Array aperture length in meters (typically (n_elements - 1) * pitch).
+        speed_of_sound:
+            Speed of sound in m/s.
+
+    Returns:
+        Transmit time delays in seconds. Shape (n_elements,).
+        Delays are relative to minimum (all non-negative).
+
+    Raises:
+        ValueError: If width_rad is outside (0, π).
+
+    Notes:
+        The virtual source position is computed from the tilt and width angles
+        using geometric constraints. This creates a diverging spherical wave
+        that appears to originate from behind the transducer.
+
+        Only supported for linear arrays (not convex arrays).
+    """
+    if width_rad <= 0 or width_rad >= pi:
+        msg = "Width angles must satisfy 0 < width_rad < π"
+        raise ValueError(msg)
+
+    x0, z0 = _angles_to_virtual_source(aperture_length, tilt_rad, width_rad)
+
+    xp = array_namespace(element_positions)
+    focus = xp.asarray([x0, z0])
+
+    # Delegate to focused() for delay computation
+    return focused(element_positions, focus, speed_of_sound=speed_of_sound)
+
+
+def _angles_to_virtual_source(
+    aperture_length: float,
+    tilt_rad: float,
+    width_rad: float,
+) -> tuple[float, float]:
+    """Convert tilt and width angles to virtual source position.
+
+    Args:
+        aperture_length: Array aperture length in meters.
+        tilt_rad: Tilt angle in radians.
+        width_rad: Angular width in radians.
+
+    Returns:
+        Tuple of (x0_m, z0_m) virtual source position in meters.
+    """
+    # Normalize tilt to [-π/2, π/2]
+    tilt_norm = fmod(-tilt_rad + pi / 2, 2 * pi) - pi / 2
+    sign_correction = 1.0
+
+    if abs(tilt_norm) > pi / 2:
+        tilt_norm = pi - tilt_norm
+        sign_correction = -1.0
+
+    denominator = tan(tilt_norm - width_rad / 2) - tan(tilt_norm + width_rad / 2)
+    z0 = sign_correction * aperture_length / denominator
+    x0 = sign_correction * z0 * tan(width_rad / 2 - tilt_norm) + aperture_length / 2
+
+    return x0, z0

fast_simus/utils/__init__.py

@@ -0,0 +1,5 @@
+"""FastSIMUS utilities."""
+
+from fast_simus.utils.geometry import element_positions
+
+__all__ = ["element_positions"]