fullwave25 1.0.7__py3-none-any.whl

fullwave/utils/__init__.py

@@ -0,0 +1,12 @@
+"""misc utils for fullwave package."""
+
+from . import pulse, relaxation_parameters, signal_process
+from .memory_tempfile import MemoryTempfile
+
+# "FullwaveSolver",
+__all__ = [
+    "MemoryTempfile",
+    "pulse",
+    "relaxation_parameters",
+    "signal_process",
+]

fullwave/utils/check_functions.py

@@ -0,0 +1,48 @@
+"""collections of functions to check the input values."""
+
+from pathlib import Path
+from typing import Any
+
+
+def check_instance(target_var: Any, instance: Any) -> None:  # noqa: ANN401
+    """Check whether target_var is an instance of the specified type.
+
+    Raises:
+        TypeError: If target_var is not an instance of instance.
+
+    """
+    if not isinstance(target_var, instance):
+        error_message = f"{target_var} is not a {instance} instance"
+        raise TypeError(error_message)
+
+
+def check_path_exists(target_path: Path) -> None:
+    """Check whether the provided target_path exists.
+
+    Raises:
+        ValueError: If target_path does not exist.
+
+    """
+    if not target_path.exists():
+        error_message = f"{target_path} does not exist"
+        raise ValueError(error_message)
+
+
+def check_compatible_value(
+    value: Any,  # noqa: ANN401
+    compatible_values: list[Any],
+    error_message_template: str = "",
+) -> None:
+    """Check whether the provided value is in the list of compatible values.
+
+    Raises:
+        ValueError: If value is not in compatible_values.
+
+    """
+    if value not in compatible_values:
+        error_message = (
+            f"{value} is not compatible. "
+            f"Compatible values are: {compatible_values}. "
+            f"{error_message_template}"
+        )
+        raise ValueError(error_message)

fullwave/utils/coordinates.py

@@ -0,0 +1,155 @@
+"""It manipulates the coordinates of the mask."""
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def make_circle_idx(
+    dims: NDArray[np.float64],
+    cen: NDArray[np.float64],
+    rad: float,
+) -> NDArray[np.bool_]:
+    """Make a circle index mask.
+
+    Args:
+        dims: The dimensions of the mask.
+        cen: The center of the circle.
+        rad: The radius of the circle.
+
+    Returns:
+        mask: The mask of the circle.
+
+    """
+    x, y = np.meshgrid(np.arange(dims[0]), np.arange(dims[1]), indexing="ij")
+    dist = np.sqrt(np.round((x - cen[0]) + 1e-9) ** 2 + np.round((y - cen[1]) + 1e-9) ** 2)
+    return dist <= rad
+
+
+def map_to_coords(
+    map_data: NDArray[np.float64 | np.int64 | np.bool],
+    *,
+    export_as_xyz: bool = False,
+) -> NDArray[np.int64]:
+    """Map the mask map to coordinates.
+
+    Returns:
+        NDArray[np.int64]: An array of coordinates corresponding to non-zero elements in the mask.
+
+    """
+    is_3d = map_data.ndim == 3
+    # indices = np.where(map_data.T != 0)
+    indices = np.where(map_data != 0)
+    if is_3d:
+        # out = np.array([indices[2], indices[1], indices[0]]).T
+        # out = np.array([indices[2], indices[1], indices[0]]).T
+        out = np.array([*indices]).T
+
+        if export_as_xyz:
+            out = np.stack([out[:, 2], out[:, 1], out[:, 0]], axis=1)
+    else:
+        out = np.array([*indices]).T
+        if export_as_xyz:
+            out = np.stack([out[:, 1], out[:, 0]], axis=1)
+    return out
+
+
+def coords_to_map(
+    coords: NDArray[np.int64],
+    grid_shape: NDArray[np.int64] | tuple[int, ...],
+    *,
+    is_3d: bool = False,
+) -> NDArray[np.int64]:
+    """Map the coordinates to a mask map.
+
+    Parameters
+    ----------
+    coords: NDArray[np.int64]
+        The coordinates to map.
+    grid_shape: tuple[int, ...]
+        The shape of the grid.
+    is_3d: bool
+        Whether the grid is 3D or not.
+
+    Returns
+    -------
+    NDArray[np.int64]: The mask map.
+
+    """
+    mask = np.zeros(grid_shape, dtype=int)
+    if is_3d:
+        mask = np.zeros((grid_shape[0], grid_shape[1], grid_shape[2]), dtype=int)
+        mask[coords[:, 0].astype(int), coords[:, 1].astype(int), coords[:, 2].astype(int)] = 1
+    else:
+        mask = np.zeros((grid_shape[0], grid_shape[1]), dtype=int)
+        mask[coords[:, 0].astype(int), coords[:, 1].astype(int)] = 1
+    return mask
+
+
+def coords_to_index_map(
+    coords: NDArray[np.int64],
+    grid_shape: NDArray[np.int64] | tuple[int, ...],
+    *,
+    is_3d: bool = False,
+) -> NDArray[np.int64]:
+    """Map the coordinates to an index map."""
+    mask = np.zeros(grid_shape, dtype=int)
+    if is_3d:
+        mask = np.zeros((grid_shape[0], grid_shape[1], grid_shape[2]), dtype=int)
+        mask[coords[:, 0].astype(int), coords[:, 1].astype(int), coords[:, 2].astype(int)] = (
+            np.arange(coords.shape[0]) + 1
+        )
+    else:
+        mask = np.zeros((grid_shape[0], grid_shape[1]), dtype=int)
+        mask[coords[:, 0].astype(int), coords[:, 1].astype(int)] = np.arange(coords.shape[0]) + 1
+    return mask
+
+
+def map_to_coords_with_sort(map_data: NDArray[np.int64]) -> NDArray[np.int64]:
+    """Map the mask map to coordinates with sorting.
+
+    Args:
+        map_data: The mask map.
+
+    Returns:
+        NDArray[np.int64]: An array of coordinates corresponding to non-zero elements in the mask.
+
+    """
+    coords = map_to_coordinates(map_data)
+    return coords[:, np.argsort(coords[0], kind="mergesort")].T
+
+
+def map_to_coordinates(
+    map_data: NDArray[np.int64],
+    *,
+    is_3d: bool = False,
+    sort: bool = False,
+) -> NDArray[np.int64]:
+    """Map the mask map to coordinates.
+
+    Args:
+        map_data: The mask map.
+        is_3d: Whether the grid is 3D or not.
+        sort: Whether to sort the coordinates by the first dimension.
+
+    Returns:
+        NDArray[np.int64]: An array of coordinates corresponding to non-zero elements in the mask.
+
+    """
+    if is_3d:
+        idx, idy, idz = np.where(map_data != 0)
+        if idx.shape[0] == 0 or idy.shape[0] == 0 or idz.shape[0] == 0:
+            return np.array([[], [], []]).T
+        coords = np.array([idx, idy, idz])
+    else:
+        idx, idy = np.where(map_data != 0)
+        if idx.shape[0] == 0 or idy.shape[0] == 0:
+            return np.array([[], []]).T
+        coords = np.array([idx, idy])
+
+    unique_num_list = np.unique(coords[1])
+    unique_num_list.sort()
+    out_list = [np.sort(coords[:, coords[1] == value]) for value in unique_num_list]
+    coords = np.concatenate(out_list, axis=1)
+    if sort:
+        return coords[:, np.argsort(coords[0], kind="mergesort")]
+    return coords

fullwave/utils/memory_tempfile.py

@@ -0,0 +1,439 @@
+"""memory-tempfile.
+
+adapted from
+https://github.com/mbello/memory-tempfile/commit/c06b5405672435d861ac1d47db77c8067a6de77a
+"""
+
+import os
+import platform
+import sys
+import tempfile
+from collections import OrderedDict
+from pathlib import Path
+
+MEM_BASED_FS = ["tmpfs", "ramfs"]
+SUITABLE_PATHS = ["/tmp", "/run/user/{uid}", "/run/shm", "/dev/shm"]  # noqa: S108
+
+
+class MemoryTempfile:
+    """MemoryTempfile class for creating temporary files in memory-based filesystems.
+
+    This class is a wrapper around the tempfile module to provide
+    functionality for creating temporary files in memory-based filesystems
+    (e.g., tmpfs, ramfs) on Linux systems.
+    It allows users to specify preferred paths, remove certain paths,
+    and add additional paths for temporary files.
+    The class also provides methods to check if a memory temporary directory
+    is found, get the usable memory temporary directory paths,
+    and create temporary files and directories.
+    """
+
+    def __init__(  # noqa: C901, PLR0912
+        self,
+        *,
+        preferred_paths: list | None = None,
+        remove_paths: list | bool | None = None,
+        additional_paths: list | None = None,
+        filesystem_types: list | None = None,
+        fallback: str | bool | None = None,
+    ) -> None:
+        """Initialize MemoryTempfile instance.
+
+        Parameters
+        ----------
+        preferred_paths : list, optional
+            List of preferred paths for temporary files.
+        remove_paths : list | bool, optional
+            List of paths to remove from the suitable paths.
+            If True, all suitable paths are removed.
+        additional_paths : list, optional
+            List of additional paths to include in the suitable paths.
+        filesystem_types : list, optional
+            List of filesystem types to consider as memory-based.
+        fallback : str | bool, optional
+            Fallback path to use if no memory temporary directory is found.
+            If True, the fallback is set to the system's temporary directory.
+            If False, no fallback is used.
+
+        Raises
+        ------
+        RuntimeError
+            If no memory temporary directory is found and fallback is disabled.
+
+        """
+        self.os_tempdir = tempfile.gettempdir()
+        suitable_paths = [self.os_tempdir, *SUITABLE_PATHS]
+
+        if isinstance(fallback, bool):
+            self.fallback = self.os_tempdir if fallback else None
+        else:
+            self.fallback = fallback
+
+        if platform.system() == "Linux":
+            self.filesystem_types = (
+                list(filesystem_types) if filesystem_types is not None else MEM_BASED_FS
+            )
+
+            preferred_paths = [] if preferred_paths is None else preferred_paths
+
+            if isinstance(remove_paths, bool) and remove_paths:
+                suitable_paths = []
+            elif isinstance(remove_paths, list) and len(remove_paths) > 0:
+                suitable_paths = [i for i in suitable_paths if i not in remove_paths]
+
+            additional_paths = [] if additional_paths is None else additional_paths
+
+            self.suitable_paths = preferred_paths + suitable_paths + additional_paths
+
+            uid = os.geteuid()
+
+            with Path("/proc/self/mountinfo").open(encoding="utf-8") as file:
+                mnt_info = {i[2]: i for i in [line.split() for line in file]}
+
+            self.usable_paths: OrderedDict = OrderedDict()
+            for path in self.suitable_paths:
+                path_uid = path.replace("{uid}", str(uid))
+
+                # We may have repeated
+                if self.usable_paths.get(path_uid) is not None:
+                    continue
+                self.usable_paths[path_uid] = False
+                try:
+                    dev = Path(path_uid).stat().st_dev
+                    major, minor = os.major(dev), os.minor(dev)
+                    mp = mnt_info.get(f"{major}:{minor}")
+                    if mp and mp[mp.index("-", 6) + 1] in self.filesystem_types:
+                        self.usable_paths[path_uid] = mp
+                except FileNotFoundError:
+                    pass
+
+            for key in [k for k, v in self.usable_paths.items() if not v]:
+                del self.usable_paths[key]
+
+            if len(self.usable_paths) > 0:
+                self.tempdir = Path(next(iter(self.usable_paths.keys())))
+            elif self.fallback is not None:
+                self.tempdir = Path(self.fallback)
+            else:
+                error_message = "No memory temporary dir found and fallback is disabled.\n"
+                raise RuntimeError(error_message)
+
+    def found_mem_tempdir(self) -> bool:
+        """Check if any memory temporary directory is found.
+
+        Returns
+        -------
+        bool
+            True if any memory temporary directory is found, False otherwise.
+
+        """
+        return len(self.usable_paths) > 0
+
+    def using_mem_tempdir(self) -> bool:
+        """Check if the current temporary directory is a memory temporary directory.
+
+        Returns
+        -------
+        bool
+            True if the current temporary directory is a memory temporary directory,
+            False otherwise.
+
+        """
+        return self.tempdir in self.usable_paths
+
+    def get_usable_mem_tempdir_paths(self) -> list:
+        """Get the list of usable memory temporary directory paths.
+
+        Returns
+        -------
+        list
+            List of usable memory temporary directory paths.
+
+        """
+        return list(self.usable_paths.keys())
+
+    def gettempdir(self) -> Path:
+        """Get the current temporary directory.
+
+        Returns
+        -------
+        Path
+            The current temporary directory.
+
+        """
+        return self.tempdir
+
+    def gettempdirb(self) -> bytes:
+        """Get the current temporary directory as bytes.
+
+        Returns
+        -------
+        bytes
+            The current temporary directory as bytes.
+
+        """
+        return str(self.tempdir).encode(sys.getfilesystemencoding(), "surrogateescape")
+
+    def mkdtemp(
+        self,
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | None = None,  # noqa: A002
+    ) -> str:
+        """Create a temporary directory.
+
+        Parameters
+        ----------
+        suffix : str, optional
+            Suffix for the temporary directory name.
+        prefix : str, optional
+            Prefix for the temporary directory name.
+        dir : str, optional
+            Directory where the temporary directory will be created.
+
+        Returns
+        -------
+        str
+            The name of the created temporary directory.
+
+        """
+        return tempfile.mkdtemp(suffix=suffix, prefix=prefix, dir=dir or self.tempdir)
+
+    def mkstemp(
+        self,
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | None = None,  # noqa: A002
+        *,
+        text: bool = False,
+    ) -> tuple[int, str]:
+        """Create a temporary file using mkstemp and return a tuple (file descriptor, file name).
+
+        Parameters
+        ----------
+        suffix : str, optional
+            Suffix for the temporary file name.
+        prefix : str, optional
+            Prefix for the temporary file name.
+        dir : str, optional
+            Directory where the temporary file will be created.
+        text : bool, optional
+            If True, the file will be opened in text mode (default is False).
+
+        Returns
+        -------
+        tuple[int, str]
+            A tuple containing the file descriptor and the name of the created temporary file.
+
+        """
+        return tempfile.mkstemp(
+            suffix=suffix,
+            prefix=prefix,
+            dir=dir or self.tempdir,
+            text=text,
+        )
+
+    def TemporaryDirectory(  # noqa: N802
+        self,
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | None = None,  # noqa: A002
+    ) -> tempfile.TemporaryDirectory[str]:
+        """Create a temporary directory and return a TemporaryDirectory object.
+
+        Parameters
+        ----------
+        suffix : str, optional
+            Suffix for the temporary file name.
+        prefix : str, optional
+            Prefix for the temporary file name.
+        dir : str, optional
+            Directory where the temporary file will be created.
+
+        Returns
+        -------
+        tempfile.TemporaryDirectory[str]
+            A TemporaryDirectory object representing the created temporary directory.
+
+        """
+        return tempfile.TemporaryDirectory(
+            suffix=suffix,
+            prefix=prefix,
+            dir=dir or self.tempdir,
+        )
+
+    def SpooledTemporaryFile(  # noqa: N802
+        self,
+        max_size: int = 0,
+        mode: str = "w+b",
+        buffering: int = -1,
+        encoding: str | None = None,
+        newline: str | None = None,
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | None = None,  # noqa: A002
+    ) -> tempfile.SpooledTemporaryFile:
+        """Create a spooled temporary file.
+
+        Parameters
+        ----------
+        max_size : int, optional
+            Maximum size of the file before it is moved to disk.
+        mode : str, optional
+            Mode in which the file is opened (default is 'w+b').
+        buffering : int, optional
+            Buffering policy (default is -1, which means the default buffering).
+        encoding : str, optional
+            Encoding of the file (default is None).
+        newline : str, optional
+            Newline handling (default is None).
+        suffix : str, optional
+            Suffix for the temporary file name (default is None).
+        prefix : str, optional
+            Prefix for the temporary file name (default is None).
+        dir : str, optional
+            Directory where the temporary file will be created (default is None).
+
+        Returns
+        -------
+        tempfile.SpooledTemporaryFile
+            A SpooledTemporaryFile object representing the created temporary file.
+
+        Notes
+        -----
+        Temporary file wrapper, specialized to switch from BytesIO
+        or StringIO to a real file when it exceeds a certain size or
+        when a fileno is needed.
+
+        """
+        return tempfile.SpooledTemporaryFile(
+            max_size=max_size,
+            mode=mode,
+            buffering=buffering,
+            encoding=encoding,
+            newline=newline,
+            suffix=suffix,
+            prefix=prefix,
+            dir=dir or self.tempdir,
+        )
+
+    def NamedTemporaryFile(  # noqa: N802
+        self,
+        mode: str = "w+b",
+        buffering: int = -1,
+        encoding: str | None = None,
+        newline: str | None = None,
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | None = None,  # noqa: A002
+        *,
+        delete: bool = True,
+    ) -> tempfile.NamedTemporaryFile:
+        """Create and return a temporary file.
+
+        Parameters
+        ----------
+        mode : str, optional
+            Mode in which the file is opened (default is 'w+b').
+        buffering : int, optional
+            Buffering policy (default is -1, which means the default buffering).
+        encoding : str, optional
+            Encoding of the file (default is None).
+        newline : str, optional
+            Newline handling (default is None).
+        suffix : str, optional
+            Suffix for the temporary file name (default is None).
+        prefix : str, optional
+            Prefix for the temporary file name (default is None).
+        dir : str, optional
+            Directory where the temporary file will be created (default is None).
+        delete : bool, optional
+            If True, the file will be deleted when closed (default is True).
+
+        m        Returns
+        -------
+        tempfile.NamedTemporaryFile
+            A NamedTemporaryFile object representing the created temporary file.
+
+        """
+        return tempfile.NamedTemporaryFile(
+            mode=mode,
+            buffering=buffering,
+            encoding=encoding,
+            newline=newline,
+            suffix=suffix,
+            prefix=prefix,
+            dir=dir or self.tempdir,
+            delete=delete,
+        )
+
+    def TemporaryFile(  # noqa: N802
+        self,
+        mode: str = "w+b",
+        buffering: int = -1,
+        encoding: str | None = None,
+        newline: str | None = None,
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | None = None,  # noqa: A002
+    ) -> tempfile.TemporaryFile:
+        """Create and return a temporary file.
+
+        Parameters
+        ----------
+        mode : str, optional
+            Mode in which the file is opened (default is 'w+b').
+        buffering : int, optional
+            Buffering policy (default is -1, which means the default buffering).
+        encoding : str, optional
+            Encoding of the file (default is None).
+        newline : str, optional
+            Newline handling (default is None).
+        suffix : str, optional
+            Suffix for the temporary file name (default is None).
+        prefix : str, optional
+            Prefix for the temporary file name (default is None).
+        dir : str, optional
+            Directory where the temporary file will be created (default is None).
+
+        Returns
+        -------
+        tempfile.TemporaryFile
+            A TemporaryFile object representing the created temporary file.
+
+        -----
+
+        """
+        return tempfile.TemporaryFile(
+            mode=mode,
+            buffering=buffering,
+            encoding=encoding,
+            newline=newline,
+            suffix=suffix,
+            prefix=prefix,
+            dir=dir or self.tempdir,
+        )
+
+    @staticmethod
+    def gettempprefix() -> str:
+        """Return the default temporary directory.
+
+        Returns
+        -------
+        str
+            The default temporary directory.
+
+        """
+        return tempfile.gettempdir()
+
+    @staticmethod
+    def gettempprefixb() -> bytes:
+        """Return the default temporary directory as bytes.
+
+        Returns
+        -------
+        bytes
+            The default temporary directory as bytes.
+
+        """
+        return tempfile.gettempprefixb()