fullwave25 1.0.7__py3-none-any.whl

fullwave/medium_builder/presets/domain_background.py

@@ -0,0 +1,140 @@
+"""background domain."""
+
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from fullwave import Grid
+from fullwave.constants import MaterialProperties
+from fullwave.medium_builder import Domain
+
+
+class BackgroundDomain(Domain):
+    """represents the base medium properties for the simulation."""
+
+    def __init__(
+        self,
+        grid: Grid,
+        background_property_name: str | None = None,
+        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,
+    ) -> None:
+        """Initialize a Background instance.
+
+        Parameters
+        ----------
+        grid: Grid
+            Grid instance.
+        background_property_name: str, optional
+            Background property name.
+            Defaults to None.
+        material_properties: MaterialProperties, optional
+            Material properties.
+            Defaults to MaterialProperties().
+        path_relaxation_parameters_database: (Path, optional)
+            The path to the relaxation parameters database.
+        n_relaxation_mechanisms: (int, optional)
+            The number of relaxation mechanisms.
+
+        """
+        self.background_property_name = background_property_name
+        if material_properties is None:
+            self.material_properties: MaterialProperties = MaterialProperties()
+        else:
+            self.material_properties = material_properties
+
+        super().__init__(
+            name="background",
+            grid=grid,
+            path_relaxation_parameters_database=path_relaxation_parameters_database,
+            n_relaxation_mechanisms=n_relaxation_mechanisms,
+        )
+
+    def _setup_base_geometry(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.ones((self.nx, self.ny, self.nz))
+        return np.ones((self.nx, self.ny))
+
+    def _setup_sound_speed(self) -> NDArray[np.float64]:
+        base_map: NDArray[np.float64]
+        if self.is_3d:
+            base_map = np.ones((self.nx, self.ny, self.nz))
+        else:
+            base_map = np.ones((self.nx, self.ny))
+        if self.background_property_name is not None:
+            sound_speed = (
+                base_map
+                * getattr(self.material_properties, self.background_property_name)["sound_speed"]
+            )
+        else:
+            sound_speed = base_map * self.material_properties.sound_speed
+        return sound_speed
+
+    def _setup_density(self) -> NDArray[np.float64]:
+        base_map: NDArray[np.float64]
+        if self.is_3d:
+            base_map = np.ones((self.nx, self.ny, self.nz))
+        else:
+            base_map = np.ones((self.nx, self.ny))
+        if self.background_property_name is not None:
+            density = (
+                base_map
+                * getattr(self.material_properties, self.background_property_name)["density"]
+            )
+        else:
+            density = base_map * self.material_properties.density
+        return density
+
+    def _setup_alpha_coeff(self) -> NDArray[np.float64]:
+        base_map: NDArray[np.float64]
+        if self.is_3d:
+            base_map = np.ones((self.nx, self.ny, self.nz))
+        else:
+            base_map = np.ones((self.nx, self.ny))
+
+        if self.background_property_name is not None:
+            alpha_coeff = (
+                base_map
+                * getattr(self.material_properties, self.background_property_name)["alpha_coeff"]
+            )
+        else:
+            alpha_coeff = base_map * self.material_properties.alpha_coeff
+        return alpha_coeff
+
+    def _setup_alpha_power(self) -> NDArray[np.float64]:
+        base_map: NDArray[np.float64]
+        if self.is_3d:
+            base_map = np.ones((self.nx, self.ny, self.nz))
+        else:
+            base_map = np.ones((self.nx, self.ny))
+
+        if self.background_property_name is not None:
+            alpha_power = (
+                base_map
+                * getattr(self.material_properties, self.background_property_name)["alpha_power"]
+            )
+        else:
+            alpha_power = base_map * self.material_properties.alpha_power
+        return alpha_power
+
+    def _setup_beta(self) -> NDArray[np.float64]:
+        base_map: NDArray[np.float64]
+        if self.is_3d:
+            base_map = np.ones((self.nx, self.ny, self.nz))
+        else:
+            base_map = np.ones((self.nx, self.ny))
+
+        if self.background_property_name is not None:
+            beta = (
+                base_map * getattr(self.material_properties, self.background_property_name)["beta"]
+            )
+        else:
+            beta = base_map * self.material_properties.beta
+        return beta

fullwave/medium_builder/presets/domain_scatterer.py

@@ -0,0 +1,179 @@
+"""scatterer domain."""
+
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from fullwave import Grid
+from fullwave.constants import MaterialProperties
+from fullwave.medium_builder import Domain
+from fullwave.utils import check_functions
+
+
+class ScattererDomain(Domain):
+    """represents the base medium properties for the simulation."""
+
+    def __init__(
+        self,
+        grid: Grid,
+        num_scatterer: int,
+        ncycles: int,
+        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,
+        seed: int | None = None,
+    ) -> None:
+        """Initialize a Background instance.
+
+        Parameters
+        ----------
+        grid : Grid
+            Grid instance.
+        num_scatterer : int
+            Number of scatterer per resolution cell.
+        ncycles : int
+            Number of cycles for the transmit pulse.
+        material_properties: MaterialProperties, optional
+            Material properties.
+            Defaults to MaterialProperties().
+        path_relaxation_parameters_database: (Path, optional)
+            The path to the relaxation parameters database.
+        n_relaxation_mechanisms: (int, optional)
+            The number of relaxation mechanisms.
+        seed: (int, optional)
+            Random seed for scatterer generation.
+
+        """
+        check_functions.check_instance(grid, Grid)
+        self.grid = grid
+        self.is_3d = grid.is_3d
+        self.nx = grid.nx
+        self.ny = grid.ny
+        if self.is_3d:
+            self.nz = grid.nz
+        self.path_relaxation_parameters_database = path_relaxation_parameters_database
+        self.n_relaxation_mechanisms = n_relaxation_mechanisms
+
+        if material_properties is None:
+            self.material_properties: MaterialProperties = MaterialProperties()
+        else:
+            self.material_properties = material_properties
+
+        self.num_scatterer = num_scatterer
+        self.ncycles = ncycles
+
+        self.seed = seed
+        self.rng = np.random.default_rng(self.seed)
+
+        self.base_geometry = self._setup_base_geometry()
+
+        self.scatterer_map, self.scatterer_count, self.scatterer_percent = self._setup_scatter_map()
+
+        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()
+
+    def _setup_base_geometry(self) -> NDArray[np.float64]:
+        if self.is_3d:
+            return np.ones((self.nx, self.ny, self.nz))
+        return np.ones((self.nx, self.ny))
+
+    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))
+
+    def _setup_density(self) -> NDArray[np.float64]:
+        return self.scatterer_map * self.material_properties.density
+
+    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))
+
+    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))
+
+    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_scatter_map(
+        self,
+    ) -> tuple[NDArray[np.float64], int, float]:
+        # if self.is_3d:
+        #     res_cell = self._rescell3ds(
+        #         self.grid.wavelength,
+        #         self.grid.ny / 2 * self.grid.dy,
+        #         self.grid.domain_size[1],
+        #         self.ncycles,
+        #         self.grid.dx,
+        #         self.grid.dy,
+        #         self.grid.dz,
+        #     )
+        # else:
+        res_cell = self._rescell2ds(
+            self.grid.wavelength,
+            self.grid.ny / 2 * self.grid.dy,
+            self.grid.domain_size[1],
+            self.ncycles,
+            self.grid.dx,
+            self.grid.dy,
+        )
+        scat_density = self.num_scatterer / res_cell
+
+        if self.is_3d:
+            scatter_map = self.rng.random((self.grid.nx, self.grid.ny, self.grid.nz))
+        else:
+            scatter_map = self.rng.random((self.grid.nx, self.grid.ny))
+
+        scatter_map /= scat_density
+        scatter_map[scatter_map > 1] = 0.5
+        scatter_map -= -0.5
+
+        scatterer_count = len(scatter_map != 0)
+        scatterer_percent = 100 * scatterer_count / (scatter_map.shape[0] * scatter_map.shape[0])
+
+        scatter_map *= self.base_geometry
+        return scatter_map, scatterer_count, scatterer_percent
+
+    def _rescell2ds(
+        self,
+        wavelength: float,
+        dy2: float,  # ?
+        ay: float,
+        n_cycles: int,
+        dy: float,
+        dz: float,
+    ) -> float:
+        res_y = wavelength * dy2 / ay
+        res_z = wavelength * n_cycles / 2
+        return res_y / dy * res_z / dz
+
+    def _rescell3ds(
+        self,
+        wavelength: float,
+        dy2: float,  # ?
+        ay: float,
+        n_cycles: int,
+        dx: float,
+        dy: float,
+        dz: float,
+    ) -> float:
+        res_x = wavelength * n_cycles / 2
+        res_y = wavelength * dy2 / ay
+        res_z = wavelength * n_cycles / 2
+        return res_x / dx * res_y / dy * res_z / dz

fullwave/medium_builder/presets/domain_simple.py

@@ -0,0 +1,92 @@
+"""simple domain module."""
+
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from fullwave import Grid
+from fullwave.medium_builder.domain import Domain
+
+
+class SimpleDomain(Domain):
+    """A simple domain implementation for custom medium builder domains."""
+
+    def __init__(
+        self,
+        grid: Grid,
+        name: str,
+        geometry: NDArray[np.float64],
+        maps: dict[str, NDArray[np.float64] | NDArray[np.int64]],
+        *,
+        path_relaxation_parameters_database: Path = Path(__file__).parent.parent
+        / "solver"
+        / "bins"
+        / "database"
+        / "database"
+        / "relaxation_params_database_num_relax=2_20251027_1437.mat",
+        n_relaxation_mechanisms: int = 2,
+    ) -> None:
+        """Initialize a SimpleDomain.
+
+        This domain is designed to make a arbitrary domain with given maps,
+        so that users can easily create a domain with their own maps
+        and integrate it into the medium_builder.
+
+        Parameters
+        ----------
+        grid: Grid
+            The grid instance.
+        name : str
+            The name of the domain.
+        geometry : NDArray
+            The geometry array.
+        maps : NDArray
+            A dictionary containing maps
+            for sound speed, density, beta, alpha_coeff, alpha_power, and optionally air.
+        path_relaxation_parameters_database : Path, optional
+            The path to the relaxation parameters database.
+        n_relaxation_mechanisms : int, optional
+            The number of relaxation mechanisms.
+
+        """
+        self.grid = grid
+        self.is_3d = grid.is_3d
+        self.name = name
+        self.base_geometry = geometry
+        self.sound_speed = maps["sound_speed"]
+        self.density = maps["density"]
+        self.beta = maps["beta"]
+        self.alpha_coeff = maps["alpha_coeff"]
+        self.alpha_power = maps["alpha_power"]
+        if "air" in maps:
+            self.air = maps["air"]
+        else:
+            self.air = np.zeros_like(geometry, dtype=int)
+        super().__init__(
+            grid=grid,
+            name=name,
+            path_relaxation_parameters_database=path_relaxation_parameters_database,
+            n_relaxation_mechanisms=n_relaxation_mechanisms,
+        )
+
+    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

fullwave/medium_builder/presets/domain_water_gel.py

@@ -0,0 +1 @@
+"""water gel domain."""

fullwave/sensor.py

@@ -0,0 +1,161 @@
+"""Source class for Fullwave."""
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from matplotlib import pyplot as plt
+from numpy.typing import NDArray
+
+from fullwave.utils import plot_utils
+from fullwave.utils.coordinates import coords_to_index_map, coords_to_map, map_to_coords
+
+logger = logging.getLogger("__main__." + __name__)
+
+
+@dataclass
+class Sensor:
+    """Sensor class for Fullwave."""
+
+    outcoords: NDArray[np.int64]
+    sampling_modulus_time: int = 1
+
+    def __init__(self, mask: NDArray[np.bool], sampling_modulus_time: int = 1) -> None:
+        """Sensor class for Fullwave.
+
+        Parameters
+        ----------
+        mask : NDArray[np.bool]
+            Binary matrix where the pressure is recorded at each time-step
+            shape: [nx, ny] for 2D, [nx, ny, nz] for 3D
+        sampling_modulus_time: int
+            Sampling modulus in time. Default is 1 (record at every time step).
+            Changing this value to n will record the pressure every n time steps.
+            It reduces the size of the output data.
+
+        """
+        mask = np.atleast_2d(mask)
+
+        self.grid_shape = mask.shape
+        self.sampling_modulus_time = sampling_modulus_time
+        self.is_3d = len(self.grid_shape) == 3
+        outcoords = map_to_coords(mask)
+        if self.is_3d:
+            self.outcoords = outcoords
+        else:
+            # self.outcoords = np.stack([outcoords[:, 1], outcoords[:, 0]]).T
+            self.outcoords = outcoords
+        super().__init__()
+
+    def validate(self, grid_shape: NDArray[np.int64] | tuple) -> None:
+        """Check if the source mask has the correct shape."""
+        grid_shape = tuple(grid_shape) if isinstance(grid_shape, np.ndarray) else grid_shape
+        assert self.mask.shape == grid_shape, f"{self.mask.shape} != {grid_shape}"
+        assert np.any(self.mask), "No active sensor found."
+
+    @property
+    def mask(self) -> NDArray[np.int64]:
+        """Returns the source mask.
+
+        it calculates the source mask from the source coordinates to reduce the memory usage.
+        """
+        return coords_to_map(
+            self.outcoords,
+            grid_shape=self.grid_shape,
+            is_3d=self.is_3d,
+        )
+
+    @property
+    def indexed_mask(self) -> NDArray[np.int64]:
+        """Returns the source mask.
+
+        it calculates the source mask from the source coordinates to reduce the memory usage.
+        """
+        return coords_to_index_map(
+            self.outcoords,
+            grid_shape=self.grid_shape,
+            is_3d=self.is_3d,
+        )
+
+    @property
+    def ncoordsout(self) -> int:
+        """Return the number of sensors.
+
+        ailiased to n_sensors for the compatibility with matlab version
+        """
+        return self.n_sensors
+
+    @property
+    def n_sensors(self) -> int:
+        """Return the number of sensors."""
+        return self.outcoords.shape[0]
+
+    def plot(
+        self,
+        export_path: Path | str | None = Path("./temp/temp.png"),
+        *,
+        show: bool = False,
+    ) -> None:
+        """Plot the transducer mask, optionally exporting and displaying the figure.
+
+        Raises:
+            ValueError: If the sensor is 3D because plotting is not supported.
+
+        """
+        if self.is_3d:
+            error_msg = "3D plotting is not supported yet."
+            raise ValueError(error_msg)
+        plt.close("all")
+        fig, ax = plt.subplots()
+        fig = plot_utils.plot_array(
+            self.mask,
+            xlim=[-10, self.mask.shape[1] + 10],
+            ylim=[-10, self.mask.shape[0] + 10],
+            reverse_y_axis=True,
+            save=False,
+            clear_all=False,
+            fig=fig,
+            colorbar=True,
+        )
+        if export_path is not None:
+            plt.savefig(export_path, dpi=300)
+        if show:
+            plt.show()
+
+        plt.close("all")
+
+    def print_info(self) -> None:
+        """Print sensor information to the logger."""
+        print(str(self))
+
+    def summary(self) -> None:
+        """Alias for print_info."""
+        self.print_info()
+
+    def __str__(self) -> str:
+        """Show sensor information.
+
+        Returns
+        -------
+        str
+            Formatted string containing source information.
+
+        """
+        return (
+            f"Sensor: \n"
+            f"  Number of sensors: {self.n_sensors}\n"
+            f"  Grid shape: {self.grid_shape}\n"
+            f"  Is 3D: {self.is_3d}\n"
+        )
+
+    def __repr__(self) -> str:
+        """Show sensor information.
+
+        Returns
+        -------
+        str
+            Formatted string containing source information.
+
+        """
+        return self.__str__()

fullwave/solver/__init__.py

@@ -0,0 +1 @@
+"""fullwave solver module."""