fullwave25 1.0.7__py3-none-any.whl

fullwave/medium_builder/__init__.py

@@ -0,0 +1,12 @@
+"""domain builder module."""
+
+from .domain import Domain
+from .medium_builder import MediumBuilder
+
+from . import presets  # isort:skip
+
+__all__ = [
+    "Domain",
+    "MediumBuilder",
+    "presets",
+]

fullwave/medium_builder/domain.py

@@ -0,0 +1,151 @@
+"""domain base module."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from fullwave import Grid, Medium
+from fullwave.utils import check_functions
+
+
+@dataclass
+class Domain(ABC):
+    """A base domain class defining abstract methods for domain parameter setup.
+
+    override abstract methods (_setup_*) to use in the derived classes.
+    """
+
+    name: str
+    grid: Grid
+    nx: int = field(init=False)
+    ny: int = field(init=False)
+    nz: int = field(init=False)
+    base_geometry: NDArray[np.float64] = field(init=False)
+    sound_speed: NDArray[np.float64] = field(init=False)
+    density: NDArray[np.float64] = field(init=False)
+    alpha_coeff: NDArray[np.float64] = field(init=False)
+    alpha_power: NDArray[np.float64] = field(init=False)
+    beta: NDArray[np.float64] = field(init=False)
+    air: NDArray[np.int64] = field(init=False)
+
+    def __init__(
+        self,
+        name: str,
+        grid: Grid,
+        *,
+        path_relaxation_parameters_database: Path = Path(__file__).parent.parent
+        / "solver"
+        / "bins"
+        / "database"
+        / "relaxation_params_database_num_relax=2_20251027_1437.mat",
+        n_relaxation_mechanisms: int = 2,
+    ) -> None:
+        """Initialize the Domain class.
+
+        Parameters
+        ----------
+        name: (str)
+            The name of the domain.
+        grid: (Grid)
+            The grid associated with the domain.
+        path_relaxation_parameters_database: (Path, optional)
+            The path to the relaxation parameters database.
+        n_relaxation_mechanisms: (int, optional)
+            The number of relaxation mechanisms.
+
+        """
+        self.name = name
+        self.grid = grid
+        self.is_3d = self.grid.is_3d
+        self.path_relaxation_parameters_database = path_relaxation_parameters_database
+        self.n_relaxation_mechanisms = n_relaxation_mechanisms
+        self.__post_init__()
+
+    def __post_init__(self) -> None:
+        """Post-initialization processing for Domain.
+
+        will be called after __init__.
+        """
+        check_functions.check_instance(self.grid, Grid)
+
+        self.nx = self.grid.nx
+        self.ny = self.grid.ny
+        if self.is_3d:
+            self.nz = self.grid.nz
+
+        self.base_geometry = self._setup_base_geometry()
+
+        self.sound_speed = self._setup_sound_speed()
+        self.density = self._setup_density()
+        self.alpha_coeff = self._setup_alpha_coeff()
+        self.alpha_power = self._setup_alpha_power()
+        self.beta = self._setup_beta()
+        self.air = self._setup_air()
+
+    @abstractmethod
+    def _setup_base_geometry(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.zeros((self.nx, self.ny, self.nz))
+        return np.zeros((self.nx, self.ny))
+
+    @abstractmethod
+    def _setup_sound_speed(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.zeros((self.nx, self.ny, self.nz))
+        return np.zeros((self.nx, self.ny))
+
+    @abstractmethod
+    def _setup_density(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.zeros((self.nx, self.ny, self.nz))
+        return np.zeros((self.nx, self.ny))
+
+    @abstractmethod
+    def _setup_alpha_coeff(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.zeros((self.nx, self.ny, self.nz))
+        return np.zeros((self.nx, self.ny))
+
+    @abstractmethod
+    def _setup_alpha_power(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.zeros((self.nx, self.ny, self.nz))
+        return np.zeros((self.nx, self.ny))
+
+    @abstractmethod
+    def _setup_beta(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.zeros((self.nx, self.ny, self.nz))
+        return np.zeros((self.nx, self.ny))
+
+    def _setup_air(self) -> NDArray[np.int64]:
+        if self.is_3d:
+            return np.zeros((self.nx, self.ny, self.nz), dtype=bool)
+        return np.zeros((self.nx, self.ny), dtype=bool)
+
+    @property
+    def medium(self) -> Medium:
+        """Returns the medium instance with its configured properties."""
+        return Medium(
+            grid=self.grid,
+            sound_speed=self.sound_speed,
+            density=self.density,
+            alpha_coeff=self.alpha_coeff,
+            alpha_power=self.alpha_power,
+            beta=self.beta,
+            air_map=self.air,
+            path_relaxation_parameters_database=self.path_relaxation_parameters_database,
+            n_relaxation_mechanisms=self.n_relaxation_mechanisms,
+        )
+
+    def plot(
+        self,
+        export_path: Path | str | None = Path("./temp/temp.png"),
+        *,
+        show: bool = False,
+    ) -> None:
+        """Plot the fields using matplotlib."""
+        self.medium.plot(export_path=export_path, show=show)

fullwave/medium_builder/medium_builder.py

@@ -0,0 +1,198 @@
+"""medium builder module."""
+
+from collections import OrderedDict
+from pathlib import Path
+
+import numpy as np
+
+from fullwave import Medium
+from fullwave.constants import MaterialProperties
+from fullwave.grid import Grid
+from fullwave.medium_builder.domain import Domain
+from fullwave.utils import check_functions
+
+
+class MediumBuilder:
+    """organize the domain properties and export Medium instances.
+
+    registered domains will be combined to construct the final domain properties.
+    """
+
+    def __init__(
+        self,
+        grid: Grid,
+        background_domain_properties: str = "water",
+        *,
+        ignore_non_linearity: bool = False,
+        material_properties: MaterialProperties | None = None,
+        path_relaxation_parameters_database: Path = Path(__file__).parent.parent
+        / "solver"
+        / "bins"
+        / "database"
+        / "relaxation_params_database_num_relax=2_20251027_1437.mat",
+        n_relaxation_mechanisms: int = 2,
+        attenuation_builder: str = "lookup",
+    ) -> None:
+        """Initialize a DomainOrganizer.
+
+        with background domain properties, non-linearity flag, and material properties.
+
+        Parameters
+        ----------
+        grid: Grid
+            grid instance.
+        background_domain_properties: str
+            The background domain properties.
+            Defaults to "water".
+        ignore_non_linearity: bool
+            Ignore non-linearity.
+            Defaults to False.
+        material_properties: MaterialProperties, optional
+            Material properties.
+            Defaults to None.
+        path_relaxation_parameters_database : Path, optional
+            Path to the relaxation parameters database.
+        n_relaxation_mechanisms : int, optional
+            Number of relaxation mechanisms, by default 2
+        attenuation_builder : str, optional
+            Attenuation builder type, by default "lookup".
+            Currently supports "lookup" only.
+            If "lookup", it uses the lookup table for attenuation.
+
+        """
+        check_functions.check_instance(grid, Grid)
+        self.grid = grid
+        self.registered_domain_dict: OrderedDict = OrderedDict()
+        self.constructed_domain_dict: OrderedDict = OrderedDict()
+
+        if material_properties is None:
+            self.material_properties: MaterialProperties = MaterialProperties()
+        else:
+            self.material_properties = material_properties
+
+        self.background_domain_properties: str = background_domain_properties
+        self.ignore_non_linearity: bool = ignore_non_linearity
+        self.path_relaxation_parameters_database = path_relaxation_parameters_database
+        self.n_relaxation_mechanisms = n_relaxation_mechanisms
+        self.attenuation_builder = attenuation_builder
+
+    def register_domain(self, domain: Domain) -> None:
+        """Register a single Domain instances.
+
+        Parameters
+        ----------
+        domain: Domain
+            Domain instances to register.
+
+        """
+        check_functions.check_instance(domain, Domain)
+
+        domain_name = domain.name
+        c_map = domain.sound_speed
+        rho_map = domain.density
+        beta_map = domain.beta
+        alpha_coeff_map = domain.alpha_coeff
+        alpha_power_map = domain.alpha_power
+
+        base_geometry = domain.base_geometry
+
+        air_map = domain.air if hasattr(domain, "air") else np.zeros_like(base_geometry)
+
+        self.registered_domain_dict[domain_name] = {
+            "rho_map": rho_map,
+            "beta_map": beta_map,
+            "c_map": c_map,
+            "a_map": alpha_coeff_map,
+            "a_power_map": alpha_power_map,
+            "air_map": air_map,
+            "geometry": base_geometry,
+        }
+
+    def register_domain_list(self, domain_list: list[Domain]) -> None:
+        """Register a list of Domain instances.
+
+        Parameters
+        ----------
+        domain_list: List
+            List of Domain instances to register.
+
+        """
+        for domain in domain_list:
+            self.register_domain(domain)
+
+    def _check_registered_domain(self) -> None:
+        if "background" not in self.registered_domain_dict:
+            error_msg = "Background domain is not registered."
+            raise ValueError(error_msg)
+        if len(self.registered_domain_dict) == 0:
+            error_msg = "No domain is registered."
+            raise ValueError(error_msg)
+        if next(iter(self.registered_domain_dict.keys())) != "background":
+            error_msg = "The first domain must be background domain."
+            raise ValueError(error_msg)
+
+    def run(self) -> Medium:
+        """Construct maps from registered maps.
+
+        Combine the maps like an image stecker.
+        The first map must be background map.
+
+        Returns
+        -------
+        Medium
+            A Medium instance with the constructed domain properties.
+
+        """
+        self._check_registered_domain()
+
+        for map_name in ["c_map", "rho_map", "a_map", "a_power_map", "beta_map", "air_map"]:
+            base_map_data = self.registered_domain_dict["background"][map_name].copy()
+            for domain_name in self.registered_domain_dict:
+                if domain_name == "background":
+                    continue
+
+                non_zero_index = np.where(
+                    self.registered_domain_dict[domain_name]["geometry"] != 0,
+                )
+                base_map_data[non_zero_index] = self.registered_domain_dict[domain_name][map_name][
+                    non_zero_index
+                ]
+            self.constructed_domain_dict[map_name] = base_map_data.copy()
+
+        if self.ignore_non_linearity:
+            self.constructed_domain_dict["beta_map"] = np.zeros_like(
+                self.constructed_domain_dict["beta_map"],
+            )
+
+        base_geometry_data = np.zeros_like(self.registered_domain_dict["background"]["geometry"])
+        for i, domain_name in enumerate(self.registered_domain_dict.keys()):
+            geometry_non_zero_index = np.where(
+                self.registered_domain_dict[domain_name]["geometry"] != 0,
+            )
+            base_geometry_data[geometry_non_zero_index] = i
+        self.constructed_domain_dict["geometry"] = base_geometry_data.copy()
+        return Medium(
+            grid=self.grid,
+            sound_speed=self.constructed_domain_dict["c_map"],
+            density=self.constructed_domain_dict["rho_map"],
+            alpha_coeff=self.constructed_domain_dict["a_map"],
+            alpha_power=self.constructed_domain_dict["a_power_map"],
+            beta=self.constructed_domain_dict["beta_map"],
+            air_map=self.constructed_domain_dict["air_map"],
+            path_relaxation_parameters_database=self.path_relaxation_parameters_database,
+            n_relaxation_mechanisms=self.n_relaxation_mechanisms,
+            attenuation_builder=self.attenuation_builder,
+        )
+
+    def plot_current_map(
+        self,
+        export_path: Path | str | None = Path("./temp/temp.png"),
+        *,
+        show: bool = False,
+    ) -> None:
+        """Plot the medium fields using matplotlib."""
+        medium = self.run()
+        medium.plot(
+            export_path=export_path,
+            show=show,
+        )

fullwave/medium_builder/presets/__init__.py

@@ -0,0 +1,8 @@
+"""domain presets."""
+
+from .domain_abdominal_wall import AbdominalWallDomain
+from .domain_background import BackgroundDomain
+from .domain_scatterer import ScattererDomain
+from .domain_simple import SimpleDomain
+
+__all__ = ["AbdominalWallDomain", "BackgroundDomain", "ScattererDomain", "SimpleDomain"]

fullwave/medium_builder/presets/domain_abdominal_wall.py

@@ -0,0 +1,293 @@
+"""abdominal wall domain."""
+
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.io import loadmat
+
+from fullwave import Grid
+from fullwave.constants import MaterialProperties
+from fullwave.medium_builder import Domain
+from fullwave.utils import check_functions
+from fullwave.utils.numerical import matlab_interp2easy
+
+
+def _make_abdominal_property(
+    grid: Grid,
+    abdominal_wall_mat_path: Path = Path(
+        "fullwave/medium_builder/presets/data/abdominal_wall/i2365f_etfw1.mat",
+    ),
+    crop_depth: float = 0.8e-2,
+    start_depth: float = 0,
+    background_domain_properties: str = "liver",
+    *,
+    apply_tissue_compression: bool = True,
+    compression_ratio: float = 0.655,
+    use_center_region: bool = True,
+    skip_background_definition: bool = True,
+    tranducer_surface: NDArray[np.float64] | None = None,
+) -> dict[str, np.ndarray]:
+    mat_data = loadmat(abdominal_wall_mat_path)
+    abdominal_wall_properties = mat_data["cut"].astype(float)
+
+    # this is the pixel size in interpd Visual Human slice.
+    dm = 0.33e-3 / 4
+
+    compression_ratio = compression_ratio if apply_tissue_compression else 1
+
+    interpolation_x = compression_ratio * dm / grid.dx
+    interpolation_y = dm / grid.dy
+
+    abdominal_wall_properties = matlab_interp2easy(
+        abdominal_wall_properties,
+        interpolation_x=interpolation_x,
+        interpolation_y=interpolation_y,
+    )
+
+    crop_depth_index = round(crop_depth / grid.dx) - 1
+    start_depth_index = round(start_depth / grid.dx)
+
+    # axis definition: [axial, lateral], x-> depth, y-> width
+    abdominal_wall_properties = abdominal_wall_properties[
+        crop_depth_index : crop_depth_index + grid.nx,
+        :,
+    ]
+
+    if use_center_region:
+        offset = grid.ny % 2
+        center_y = abdominal_wall_properties.shape[1] // 2
+        abdominal_wall_properties = abdominal_wall_properties[
+            : grid.nx,
+            center_y - grid.ny // 2 : center_y + grid.ny // 2 + offset,
+        ]
+    assert abdominal_wall_properties.shape[1] == grid.ny
+
+    base_map = np.zeros((grid.nx, grid.ny))
+
+    if abdominal_wall_properties.shape[0] + start_depth_index > grid.nx:
+        abdominal_wall_properties = abdominal_wall_properties[: grid.nx - start_depth_index, :]
+    if tranducer_surface is not None:
+        for i in range(abdominal_wall_properties.shape[1]):
+            abdominal_wall_properties[tranducer_surface[i] - 3 :, i] = abdominal_wall_properties[
+                0 : -tranducer_surface[i] + 3,
+                i,
+            ]
+            abdominal_wall_properties[0 : tranducer_surface[i] - 3, i] = 0
+
+    base_map[
+        start_depth_index : start_depth_index + abdominal_wall_properties.shape[0],
+        : abdominal_wall_properties.shape[1],
+    ] = abdominal_wall_properties
+
+    material_properties = MaterialProperties()
+
+    density = np.ones_like(base_map) * -1
+    sound_speed = np.ones_like(base_map) * -1
+    alpha_coeff = np.ones_like(base_map) * -1
+    alpha_power = np.ones_like(base_map) * -1
+    beta = np.ones_like(base_map) * -1
+
+    for i, tissue_name in enumerate(
+        [
+            background_domain_properties,
+            "connective",
+            "muscle",
+            "fat",
+            "connective",
+            "connective",
+        ],
+    ):
+        if i == 0 and skip_background_definition:
+            continue
+        target_index = np.where(base_map == i)
+        density[target_index] = getattr(material_properties, tissue_name)["density"]
+        sound_speed[target_index] = getattr(material_properties, tissue_name)["sound_speed"]
+        alpha_coeff[target_index] = getattr(material_properties, tissue_name)["alpha_coeff"]
+        alpha_power[target_index] = getattr(material_properties, tissue_name)["alpha_power"]
+        beta[target_index] = getattr(material_properties, tissue_name)["beta"]
+
+    # if use_smoothing:
+    #     # use gaussian smoothing to smooth the abdominal wall
+    #     sigma = (5 / 10) ** 2 * grid.ppw / 2
+    #     rho_map_blurred = matlab_gaussian_filter(density, sigma=sigma)
+    #     c_map_blurred = matlab_gaussian_filter(sound_speed, sigma=sigma)
+    #     a_coeff_map_blurred = matlab_gaussian_filter(alpha_coeff, sigma=sigma)
+    #     a_power_map_blurred = matlab_gaussian_filter(alpha_power, sigma=sigma)
+
+    #     density = rho_map_blurred
+    #     sound_speed = c_map_blurred
+    #     alpha_coeff = a_coeff_map_blurred
+    #     alpha_power = a_power_map_blurred
+
+    air_map = np.zeros_like(base_map)
+    return {
+        "base_geometry": base_map > 0,
+        "sound_speed": sound_speed,
+        "density": density,
+        "alpha_coeff": alpha_coeff,
+        "alpha_power": alpha_power,
+        "beta": beta,
+        "air_map": air_map,
+    }
+
+
+class AbdominalWallDomain(Domain):
+    """Represents the abdominal wall domain for simulation."""
+
+    def __init__(
+        self,
+        grid: Grid,
+        *,
+        abdominal_wall_mat_path: Path = Path(
+            "fullwave/medium_builder/presets/data/abdominal_wall/i2365f_etfw1.mat",
+        ),
+        crop_depth: float = 0.8e-2,
+        start_depth: float = 0,
+        name: str = "abdominal_wall",
+        background_domain_properties: str = "water",
+        material_properties: MaterialProperties | None = None,
+        apply_tissue_compression: bool = True,
+        use_center_region: bool = True,
+        skip_background_definition: bool = True,
+        path_relaxation_parameters_database: Path = Path(__file__).parent.parent.parent
+        / "solver"
+        / "bins"
+        / "database"
+        / "relaxation_params_database_num_relax=2_20251027_1437.mat",
+        n_relaxation_mechanisms: int = 2,
+        tranducer_surface: NDArray[np.float64] | None = None,
+    ) -> None:
+        """Define AbdominalWallDomain instance.
+
+        test
+
+        Parameters
+        ----------
+        grid: Grid
+            The grid instance.
+        abdominal_wall_mat_path: Path, optional
+            The path to the abdominal wall mat file.
+            Defaults to
+            Path("fullwave/medium_builder/presets/data/abdominal_wall/i2365f_etfw1.mat").
+        crop_depth: float, optional
+            how much you want to crop the abdominal wall from the top.
+            Defaults to 0.8e-2.
+        start_depth: float, optional
+            it defines the place where the abdominal wall starts in the domain.
+            The start depth.
+            Defaults to 0.
+        name: str, optional
+            The name of the domain.
+            Defaults to "abdominal_wall".
+        background_domain_properties: str, optional
+            The background domain properties.
+            this value will be used to define the background domain properties.
+            this is ignored if skip_background_definition is True.
+            Defaults to "water".
+        material_properties: MaterialProperties, optional
+            Material properties to be used.
+            Defaults to None.
+        apply_tissue_compression: bool, optional
+            if apply tissue compression emulation to the abdominal wall.
+            Defaults to True.
+        use_center_region: bool, optional
+            if use the center region of the abdominal wall.
+            Defaults to True.
+        skip_background_definition: bool, optional
+            if skip background definition.
+            Defaults to True.
+        path_relaxation_parameters_database: Path, optional
+            The path to the relaxation parameters database.
+            Defaults to
+            Path(__file__).parent.parent / "solver" / "bins"
+            / "database"
+            / "relaxation_params_database_num_relax=2_20251027_1437.mat",
+        n_relaxation_mechanisms: int, optional
+            The number of relaxation mechanisms.
+            Defaults to 4.
+        tranducer_surface: NDArray[np.float64] | None, optional
+            The transducer surface.
+            Defaults to None.
+            the shape of this array should be (ny,).
+            and each value contains the depth of the transducer surface at each lateral position.
+
+        """
+        self.material_properties = material_properties
+
+        self.background_domain_properties = background_domain_properties
+        self.crop_depth = crop_depth
+        self.start_depth = start_depth
+        self.abdominal_wall_mat_path = abdominal_wall_mat_path
+
+        self.apply_tissue_compression = apply_tissue_compression
+        self.skip_background_definition = skip_background_definition
+
+        self.use_center_region = use_center_region
+
+        check_functions.check_instance(grid, Grid)
+
+        self.name = name
+        self.grid = grid
+        self.is_3d = grid.is_3d
+        if self.is_3d:
+            error_msg = "3D abdominal wall domain is not supported yet."
+            raise NotImplementedError(error_msg)
+        self.path_relaxation_parameters_database = path_relaxation_parameters_database
+        self.n_relaxation_mechanisms = n_relaxation_mechanisms
+        self.tranducer_surface = tranducer_surface
+        (
+            self.base_geometry,
+            self.sound_speed,
+            self.density,
+            self.alpha_coeff,
+            self.alpha_power,
+            self.beta,
+            self.air,
+        ) = self._setup_maps()
+
+    def _setup_maps(
+        self,
+    ) -> tuple[np.ndarray, ...]:
+        maps = _make_abdominal_property(
+            grid=self.grid,
+            abdominal_wall_mat_path=self.abdominal_wall_mat_path,
+            crop_depth=self.crop_depth,
+            start_depth=self.start_depth,
+            background_domain_properties=self.background_domain_properties,
+            apply_tissue_compression=self.apply_tissue_compression,
+            use_center_region=self.use_center_region,
+            skip_background_definition=self.skip_background_definition,
+            tranducer_surface=self.tranducer_surface,
+        )
+
+        return (
+            maps["base_geometry"],
+            maps["sound_speed"],
+            maps["density"],
+            maps["alpha_coeff"],
+            maps["alpha_power"],
+            maps["beta"],
+            maps["air_map"],
+        )
+
+    def _setup_base_geometry(self) -> NDArray[np.float64]:
+        return self.base_geometry
+
+    def _setup_sound_speed(self) -> NDArray[np.float64]:
+        return self.sound_speed
+
+    def _setup_density(self) -> NDArray[np.float64]:
+        return self.density
+
+    def _setup_beta(self) -> NDArray[np.float64]:
+        return self.beta
+
+    def _setup_alpha_coeff(self) -> NDArray[np.float64]:
+        return self.alpha_coeff
+
+    def _setup_alpha_power(self) -> NDArray[np.float64]:
+        return self.alpha_power
+
+    def _setup_air(self) -> NDArray[np.int64]:
+        return self.air