capytaine 3.0.0a1__cp310-cp310-macosx_15_0_x86_64.whl

capytaine/tools/block_circulant_matrices.py

@@ -0,0 +1,275 @@
+"""Implementation of block circulant matrices to be used for optimizing resolution with symmetries."""
+# Copyright (C) 2025 Capytaine developers
+# See LICENSE file at <https://github.com/capytaine/capytaine>
+
+import logging
+import numpy as np
+from typing import List, Union, Sequence
+from numpy.typing import NDArray, ArrayLike
+import scipy.linalg as sl
+
+LOG = logging.getLogger(__name__)
+
+
+def circular_permutation(l: List, i: int) -> List:
+    return l[-i:] + l[:-i]
+
+
+def leading_dimensions_at_the_end(a):
+    """Transform an array of shape (n, m, ...) into (..., n, m).
+    Invert of `leading_dimensions_at_the_end`"""
+    return np.moveaxis(a, [0, 1], [-2, -1])
+
+
+def ending_dimensions_at_the_beginning(a):
+    """Transform an array of shape (..., n, m) into (n, m, ...).
+    Invert of `leading_dimensions_at_the_end`"""
+    return np.moveaxis(a, [-2, -1], [0, 1])
+
+
+class BlockCirculantMatrix:
+    """Data-sparse representation of a block matrix of the following form
+
+        ( a  d  c  b )
+        ( b  a  d  c )
+        ( c  b  a  d )
+        ( d  c  b  a )
+
+    where a, b, c and d are matrices of the same shape.
+
+    Parameters
+    ----------
+    blocks: Sequence of matrix-like, can be also a ndarray of shape (nb_blocks, n, n, ...)
+        The **first column** of blocks [a, b, c, d, ...]
+        Each block should have the same shape.
+    """
+    def __init__(self, blocks: Sequence[ArrayLike]):
+        self.blocks = blocks
+        self.nb_blocks = len(blocks)
+        assert all(self.blocks[0].shape == b.shape for b in self.blocks[1:])
+        assert all(self.blocks[0].dtype == b.dtype for b in self.blocks[1:])
+        self.shape = (
+            self.nb_blocks*self.blocks[0].shape[0],
+            self.nb_blocks*self.blocks[0].shape[1],
+            *self.blocks[0].shape[2:]
+        )
+        self.ndim = len(self.shape)
+        self.dtype = self.blocks[0].dtype
+
+    def __array__(self, dtype=None, copy=True):
+        if not copy:
+            raise NotImplementedError
+        if dtype is None:
+            dtype = self.dtype
+        full_blocks = [np.asarray(b) for b in self.blocks]  # Transform all blocks to numpy arrays
+        first_row = [full_blocks[0], *(full_blocks[1:][::-1])]
+        if self.ndim >= 3:
+            first_row = [leading_dimensions_at_the_end(b) for b in first_row]
+            # Need to permute_dims to conform to `block` usage when the array is more than 2D
+        full_matrix = np.block([[b for b in circular_permutation(first_row, i)]
+                         for i in range(self.nb_blocks)]).astype(dtype)
+        if self.ndim >= 3:
+            full_matrix = ending_dimensions_at_the_beginning(full_matrix)
+        return full_matrix
+
+    def __add__(self, other):
+        if isinstance(other, BlockCirculantMatrix) and self.shape == other.shape:
+            return BlockCirculantMatrix([a + b for (a, b) in zip(self.blocks, other.blocks)])
+        else:
+            return NotImplemented
+
+    def __sub__(self, other):
+        if isinstance(other, BlockCirculantMatrix) and self.shape == other.shape:
+            return BlockCirculantMatrix([a - b for (a, b) in zip(self.blocks, other.blocks)])
+        else:
+            return NotImplemented
+
+    def __matmul__(self, other):
+        if self.nb_blocks == 2 and isinstance(other, np.ndarray) and other.ndim == 1:
+            a, b = self.blocks
+            x1, x2 = other[:len(other)//2], other[len(other)//2:]
+            y = np.concatenate([a @ x1 + b @ x2, b @ x1 + a @ x2], axis=0)
+            return y
+        elif self.nb_blocks == 3 and isinstance(other, np.ndarray) and other.ndim == 1:
+            a, b, c = self.blocks
+            n = len(other)
+            x1, x2, x3 = other[:n//3], other[n//3:2*n//3], other[2*n//3:]
+            y = np.concatenate([
+                a @ x1 + c @ x2 + b @ x3,
+                b @ x1 + a @ x2 + c @ x3,
+                c @ x1 + b @ x2 + a @ x3,
+            ], axis=0)
+            return y
+        elif isinstance(other, np.ndarray) and other.ndim == 1:
+            self.blocks
+            y = np.zeros(other.shape, dtype=np.result_type(self.dtype, other.dtype))
+            blocks_indices = list(range(self.nb_blocks))
+            for i, x_i in enumerate(np.split(other, self.nb_blocks)):
+                y += np.concatenate([self.blocks[j] @ x_i for j in circular_permutation(blocks_indices, i)])
+            return y
+        else:
+            return NotImplemented
+
+    def matvec(self, other):
+        return self.__matmul__(other)
+
+    def block_diagonalize(self) -> "BlockDiagonalMatrix":
+        if self.ndim == 2 and self.nb_blocks == 2:
+            a, b = self.blocks
+            return BlockDiagonalMatrix([a + b, a - b])
+        elif self.ndim == 2 and self.nb_blocks == 3:
+            a, b, c = self.blocks
+            return BlockDiagonalMatrix([
+                a + b + c,
+                a + np.exp(-2j*np.pi/3, dtype=self.dtype) * b + np.exp(2j*np.pi/3, dtype=self.dtype) * c,
+                a + np.exp(2j*np.pi/3, dtype=self.dtype) * b + np.exp(-2j*np.pi/3, dtype=self.dtype) * c,
+            ])
+        elif self.ndim == 2 and self.nb_blocks == 4:
+            a, b, c, d = self.blocks
+            return BlockDiagonalMatrix([
+                a + b + c + d,
+                a - 1j*b - c + 1j*d,
+                a - b + c - d,
+                a + 1j*b - c - 1j*d,
+            ])
+        elif self.ndim == 2 and all(isinstance(b, np.ndarray) for b in self.blocks):
+            return BlockDiagonalMatrix(np.fft.fft(np.asarray(self.blocks), axis=0))
+        else:
+            raise NotImplementedError()
+
+    def solve(self, b: np.ndarray) -> np.ndarray:
+        LOG.debug("Called solve on %s of shape %s",
+                  self.__class__.__name__, self.shape)
+        n = self.nb_blocks
+        b_fft = np.fft.fft(b.reshape((n, b.shape[0]//n)), axis=0).reshape(b.shape)
+        res_fft = self.block_diagonalize().solve(b_fft)
+        res = np.fft.ifft(res_fft.reshape((n, b.shape[0]//n)), axis=0).reshape(b.shape)
+        LOG.debug("Done")
+        return res
+
+
+class BlockDiagonalMatrix:
+    """Data-sparse representation of a block matrix of the following form
+
+        ( a  0  0  0 )
+        ( 0  b  0  0 )
+        ( 0  0  c  0 )
+        ( 0  0  0  d )
+
+    where a, b, c and d are matrices of the same shape.
+
+    Parameters
+    ----------
+    blocks: iterable of matrix-like
+        The blocks [a, b, c, d, ...]
+    """
+    def __init__(self, blocks: Sequence[ArrayLike]):
+        self.blocks = blocks
+        self.nb_blocks = len(blocks)
+        assert all(blocks[0].shape == b.shape for b in blocks[1:])
+        self.shape = (
+                sum(bl.shape[0] for bl in blocks),
+                sum(bl.shape[1] for bl in blocks)
+                )
+        assert all(blocks[0].dtype == b.dtype for b in blocks[1:])
+        self.dtype = blocks[0].dtype
+
+    def __array__(self, dtype=None, copy=True):
+        if not copy:
+            raise NotImplementedError
+        if dtype is None:
+            dtype = self.dtype
+        full_blocks = [np.asarray(b) for b in self.blocks]  # Transform all blocks to numpy arrays
+        if self.ndim >= 3:
+            full_blocks = [leading_dimensions_at_the_end(b) for b in full_blocks]
+        full_matrix = np.block([
+            [full_blocks[i] if i == j else np.zeros(full_blocks[i].shape)
+             for j in range(self.nb_blocks)]
+            for i in range(self.nb_blocks)])
+        if self.ndim >= 3:
+            full_matrix = ending_dimensions_at_the_beginning(full_matrix)
+        return full_matrix
+
+    def solve(self, b: np.ndarray) -> np.ndarray:
+        LOG.debug("Called solve on %s of shape %s",
+                  self.__class__.__name__, self.shape)
+        n = self.nb_blocks
+        rhs = np.split(b, n)
+        res = [np.linalg.solve(Ai, bi) if isinstance(Ai, np.ndarray) else Ai.solve(bi)
+               for (Ai, bi) in zip(self.blocks, rhs)]
+        LOG.debug("Done")
+        return np.hstack(res)
+
+
+MatrixLike = Union[np.ndarray, BlockDiagonalMatrix, BlockCirculantMatrix]
+
+
+def lu_decompose(A: MatrixLike, *, overwrite_a : bool = False):
+    if isinstance(A, np.ndarray):
+        return LUDecomposedMatrix(A, overwrite_a=overwrite_a)
+    elif isinstance(A, BlockDiagonalMatrix):
+        return LUDecomposedBlockDiagonalMatrix(A, overwrite_a=overwrite_a)
+    elif isinstance(A, BlockCirculantMatrix):
+        return LUDecomposedBlockCirculantMatrix(A, overwrite_a=overwrite_a)
+    else:
+        raise NotImplementedError()
+
+
+class LUDecomposedMatrix:
+    def __init__(self, A: NDArray, *, overwrite_a : bool = False):
+        LOG.debug("LU decomp of %s of shape %s",
+                  A.__class__.__name__, A.shape)
+        self._lu_decomp = sl.lu_factor(A, overwrite_a=overwrite_a)
+        self.shape = A.shape
+        self.dtype = A.dtype
+
+    def solve(self, b: np.ndarray) -> np.ndarray:
+        LOG.debug("Called solve on %s of shape %s",
+                  self.__class__.__name__, self.shape)
+        return sl.lu_solve(self._lu_decomp, b)
+
+
+class LUDecomposedBlockDiagonalMatrix:
+    """LU decomposition of a BlockDiagonalMatrix,
+    stored as the LU decomposition of each block."""
+    def __init__(self, bdm: BlockDiagonalMatrix, *, overwrite_a : bool = False):
+        LOG.debug("LU decomp of %s of shape %s",
+                  bdm.__class__.__name__, bdm.shape)
+        self._lu_decomp = [lu_decompose(bl, overwrite_a=overwrite_a) for bl in bdm.blocks]
+        self.shape = bdm.shape
+        self.nb_blocks = bdm.nb_blocks
+        self.dtype = bdm.dtype
+
+    def solve(self, b: np.ndarray) -> np.ndarray:
+        LOG.debug("Called solve on %s of shape %s",
+                  self.__class__.__name__, self.shape)
+        rhs = np.split(b, self.nb_blocks)
+        res = [Ai.solve(bi) for (Ai, bi) in zip(self._lu_decomp, rhs)]
+        return np.hstack(res)
+
+
+class LUDecomposedBlockCirculantMatrix:
+    def __init__(self, bcm: BlockCirculantMatrix, *, overwrite_a : bool = False):
+        LOG.debug("LU decomp of %s of shape %s",
+                  bcm.__class__.__name__, bcm.shape)
+        self._lu_decomp = lu_decompose(bcm.block_diagonalize(), overwrite_a=overwrite_a)
+        self.shape = bcm.shape
+        self.nb_blocks = bcm.nb_blocks
+        self.dtype = bcm.dtype
+
+    def solve(self, b: np.ndarray) -> np.ndarray:
+        LOG.debug("Called solve on %s of shape %s",
+                  self.__class__.__name__, self.shape)
+        n = self.nb_blocks
+        b_fft = np.fft.fft(b.reshape((n, b.shape[0]//n)), axis=0).reshape(b.shape)
+        res_fft = self._lu_decomp.solve(b_fft)
+        res = np.fft.ifft(res_fft.reshape((n, b.shape[0]//n)), axis=0).reshape(b.shape)
+        return res
+
+
+LUDecomposedMatrixLike = Union[LUDecomposedMatrix, LUDecomposedBlockDiagonalMatrix, LUDecomposedBlockCirculantMatrix]
+
+
+def has_been_lu_decomposed(A):
+    # Python 3.8 does not support isinstance(A, LUDecomposedMatrixLike)
+    return isinstance(A, (LUDecomposedMatrix, LUDecomposedBlockDiagonalMatrix, LUDecomposedBlockCirculantMatrix))

capytaine/tools/cache_on_disk.py

@@ -0,0 +1,26 @@
+"""
+Adapted from https://github.com/platformdirs/platformdirs (MIT Licensed)
+"""
+import os
+import sys
+from pathlib import Path
+
+from capytaine import __version__
+
+
+def cache_directory():
+    if "CAPYTAINE_CACHE_DIR" in os.environ:
+        path = os.path.join(os.environ["CAPYTAINE_CACHE_DIR"], __version__)
+    elif sys.platform == "win32":  # Windows
+        path = os.path.normpath(os.environ.get("LOCALAPPDATA"))
+        path = os.path.join(path, "capytaine", "Cache", __version__)
+    elif sys.platform == "darwin":  # MacOS
+        path = os.path.expanduser("~/Library/Caches")
+        path = os.path.join(path, "capytaine", __version__)
+    else:
+        path = os.environ.get("XDG_CACHE_HOME", "")
+        if path.strip() == "":
+            path = os.path.expanduser("~/.cache")
+        path = os.path.join(path, "capytaine", __version__)
+    Path(path).mkdir(parents=True, exist_ok=True)
+    return path

capytaine/tools/deprecation_handling.py

@@ -0,0 +1,18 @@
+import logging
+
+import numpy as np
+
+LOG = logging.getLogger(__name__)
+
+def _get_water_depth(free_surface, water_depth, sea_bottom, default_water_depth=np.inf):
+    if water_depth is None and sea_bottom is None:
+        return default_water_depth
+    elif water_depth is not None and sea_bottom is None:
+        if water_depth <= 0.0:
+            raise ValueError(f"`water_depth` should be strictly positive. Received value: {water_depth}")
+        return float(water_depth)
+    elif water_depth is None and sea_bottom is not None:
+        LOG.warning("To uniformize notations througouth Capytaine, setting `water_depth` is preferred to `sea_bottom` since version 2.0.")
+        return float(free_surface - sea_bottom)
+    else:
+        raise ValueError("Cannot give both a `water_depth` and a `sea_bottom`.")

capytaine/tools/lists_of_points.py

@@ -0,0 +1,52 @@
+import numpy as np
+from capytaine.bodies import FloatingBody
+from capytaine.post_pro.free_surfaces import FreeSurface
+from capytaine.meshes.abstract_meshes import AbstractMesh
+
+
+def _normalize_points(points, keep_mesh=False):
+    if isinstance(points, (FloatingBody, FreeSurface)):
+        if keep_mesh:
+            return points.mesh, (points.mesh.nb_faces,)
+        else:
+            return points.mesh.faces_centers, (points.mesh.nb_faces,)
+
+    if isinstance(points, AbstractMesh):
+        if keep_mesh:
+            return points, (points.nb_faces,)
+        else:
+            return points.faces_centers, (points.nb_faces,)
+
+    points = np.asarray(points)
+
+    if points.ndim == 1:  # A single point has been provided
+        output_shape = (1,)
+        points = points.reshape((1, points.shape[0]))
+
+    elif points.ndim == 2:
+        output_shape = (points.shape[0],)
+
+    elif points.ndim > 2:
+        # `points` is expected to be the results of a meshgrid. Points has shape (d, nx, ny, ...)
+        output_shape = points.shape[1:]
+        points = points.reshape(points.shape[0], -1).transpose()
+        # points is now a (nx*ny*... , d) array
+
+    else:
+        raise ValueError(f"Expected a list of points or a mesh, but got instead: {points}")
+
+    return points, output_shape
+
+def _normalize_free_surface_points(points, keep_mesh=False):
+    if keep_mesh and isinstance(points, (FloatingBody, FreeSurface)):
+        return points.mesh, (points.mesh.nb_faces,)
+
+    if keep_mesh and isinstance(points, MeshLike):
+        return points, (points.nb_faces,)
+
+    points, output_shape = _normalize_points(points, keep_mesh)
+
+    if points.ndim == 2 and points.shape[1] == 2:  # Only x and y have been provided
+        points = np.concatenate([points, np.zeros((points.shape[0], 1))], axis=1)
+
+    return points, output_shape

capytaine/tools/memory_monitor.py

@@ -0,0 +1,45 @@
+import logging
+import time
+from threading import Thread
+
+from capytaine.tools.optional_imports import silently_import_optional_dependency
+
+LOG = logging.getLogger(__name__)
+
+class MemoryMonitor(Thread):
+    """Monitor the memory usage in a separate thread.
+    from : https://joblib.readthedocs.io/en/stable/auto_examples/parallel_generator.html#sphx-glr-auto-examples-parallel-generator-py
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.stop = False
+        self.memory_buffer = [0]
+        self.psutil = silently_import_optional_dependency("psutil")
+        self.start()
+
+    def get_memory(self):
+        "Get memory of a process and its children."
+        p = self.psutil.Process()
+        memory = p.memory_info().rss
+        for c in p.children():
+            try:
+                memory += c.memory_info().rss
+            except self.psutil.NoSuchProcess:
+                pass
+        return memory
+
+    def run(self):
+        if self.psutil is not None:
+            memory_start = self.get_memory()
+            while not self.stop:
+                self.memory_buffer.append(self.get_memory() - memory_start)
+                time.sleep(0.2)
+
+    def get_memory_peak(self):
+        self.stop = True 
+        super().join()
+        if self.psutil is None:
+            return None
+        else:
+            return round(max(self.memory_buffer) / 1e9, 2)

capytaine/tools/optional_imports.py

@@ -0,0 +1,27 @@
+"""Tool to import optional dependencies. Inspired by similar code in pandas."""
+
+import importlib
+
+def import_optional_dependency(module_name: str, package_name: str = None):
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        if package_name is None:
+            package_name = module_name
+
+        message = (
+            f"Missing optional dependency '{module_name}'. "
+            f"Use pip or conda to install {package_name}."
+        )
+        raise ImportError(message) from None
+
+    return module
+
+def silently_import_optional_dependency(module_name: str):
+    # Same as above, except it does not raise a exception when the module is not found.
+    # Instead, simply returns None.
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        module = None
+    return module

capytaine/tools/prony_decomposition.py

@@ -0,0 +1,150 @@
+"""Prony decomposition: tool to approximate a function as a sum of exponentials.
+Used in particular in the finite depth Green function.
+"""
+# Copyright (C) 2017-2024 Matthieu Ancellin
+# See LICENSE file at <https://github.com/capytaine/capytaine>
+
+import logging
+
+import numpy as np
+from numpy.polynomial import polynomial
+from scipy.optimize import curve_fit
+from scipy.linalg import toeplitz
+
+LOG = logging.getLogger(__name__)
+RNG = np.random.default_rng()
+
+
+def exponential_decomposition(X, F, m):
+    """Use Prony's method to approximate the sampled real function F=f(X) as a sum of m
+    exponential functions x → Σ a_i exp(lamda_i x).
+
+    Parameters
+    ----------
+    X: 1D array
+        sampling points.
+    F: 1D array (same size as X)
+        values of the function to approximate at the points of x.
+    m: integer
+        number of exponential functions
+
+    Return
+    ------
+    a: 1D array (size m)
+        coefficients of the exponentials
+    lamda: 1D array (size m)
+        growth rate of the exponentials
+    """
+    assert X.shape == F.shape
+
+    # Compute the coefficients of the polynomials of Prony's method
+    A = toeplitz(c=F[m-1:-1], r=F[:m][::-1])
+    P, *_ = np.linalg.lstsq(A, F[m:], rcond=None)
+
+    # Build and solve polynomial function
+    coeffs = np.ones(m+1)
+    # coeffs[:m] = -P[::-1]
+    for i in range(m):
+        coeffs[m-i-1] = -P[i]
+    roots = polynomial.polyroots(coeffs)
+
+    # Discard values where log is undefined
+    roots = roots[np.logical_or(np.imag(roots) != 0.0, np.real(roots) >= 0.0)]
+
+    # Deduce lamda and keep only interesting values
+    lamda = np.real(np.log(roots)/(X[1] - X[0]))
+    lamda = np.unique(lamda)
+    lamda = lamda[np.logical_and(-20.0 < lamda, lamda < 0.0)]
+
+    # Fit the values of 'a' on the curve
+    def f(x, *ar):
+        ar = np.asarray(ar)[:, np.newaxis]
+        la = lamda[:, np.newaxis]
+        return np.sum(ar * np.exp(la * x), axis=0)
+    a, *_ = curve_fit(f, X, F, p0=np.zeros(lamda.shape))
+
+    return a, lamda
+
+
+def error_exponential_decomposition(X, F, a, lamda):
+    """Mean square error of the exponential decomposition defined by the
+    coefficients a and lamda with respect to the reference values in F.
+
+    Parameters
+    ----------
+    X: 1D array
+        sampling points
+    F: 1D array (same size as X)
+        reference values
+    a: 1D array
+        coefficients of the exponentials
+    lamda: 1D array (same size as a)
+        growth rate of the exponentials
+
+    Returns
+    -------
+    error: float
+        mean square error of the decomposition
+    """
+    a = np.asarray(a)[:, np.newaxis]
+    lamda = np.asarray(lamda)[:, np.newaxis]
+
+    def f(x):
+        return np.sum(a * np.exp(lamda*x), axis=0)
+
+    return np.square(f(X) - F).mean()
+
+
+class PronyDecompositionFailure(Exception):
+    pass
+
+
+def find_best_exponential_decomposition(f, x_min, x_max, n_exp_range, *, tol=1e-4, noise_on_domain_points_std=0.01):
+    """Tries to construct an exponential decompositoin of the function f on the
+    domain [x_min, x_max] by testing the number of exponentials in n_exp_range.
+
+    Parameters
+    ----------
+    f: callable
+        The function ℝ→ℝ to be approximated.
+        Should support vectorized calls (that is passing a vector of inputs
+        and get the vector of corresponding outputs)
+    x_min, x_max: floats
+        The bounds of the domain of input in which f should be approximated
+    n_exp_range: iterable of ints
+        The decomposition sizes that will be tested
+    tol: float, optional
+        The target mean square error.
+    noise_on_domain_points_std: float, optional
+        Introduces some random variability on the points where the function is evaluated.
+        Set this parameter to zero to disable randomness.
+
+    """
+    # Try different range of evaluation points to construct the decomposition.
+    for n_exp in n_exp_range:
+
+        # f might be ill-defined at some single specific values
+        # (for the use-case of delhommeau.py, it is when x = kh exactly).
+        # Thus we slightly randomize the range of evaluation points for the Prony decomposition.
+        # This way, if one of the evaluation points hits the singular point, it will most likely not hit it again at the next iteration.
+        x_max_iter = (1 + noise_on_domain_points_std*RNG.uniform())*x_max
+
+        try:
+            # The coefficients are computed on a resolution of 4*n_exp+1 ...
+            X = np.linspace(x_min, x_max_iter, 4*n_exp+1)
+            a, lamda = exponential_decomposition(X, f(X), n_exp)
+
+            # ... and they are evaluated on a finer discretization.
+            X = np.linspace(x_min, x_max_iter, 8*n_exp+1)
+            if error_exponential_decomposition(X, f(X), a, lamda) < tol:
+                return a, lamda
+        except Exception:
+            # If something bad happened while computing the decomposition, try
+            # the next one.
+            continue
+
+    raise PronyDecompositionFailure(
+            "No suitable Prony decomposition has been found in "
+            f"[{x_min}, {x_max}] for tol={tol} "
+            f"using a number of terms in {n_exp_range}."
+            )