capytaine 2.3.1__cp314-cp314-macosx_14_0_arm64.whl

capytaine/post_pro/kochin.py

@@ -0,0 +1,54 @@
+"""Computation of the Kochin function."""
+# Copyright (C) 2017-2019 Matthieu Ancellin
+# See LICENSE file at <https://github.com/capytaine/capytaine>
+
+import logging
+import numpy as np
+
+LOG = logging.getLogger(__name__)
+
+def compute_kochin(result, theta, ref_point=(0.0, 0.0)):
+    """Compute the far field coefficient
+
+    Parameters
+    ----------
+    result: LinearPotentialFlowResult
+        solved potential flow problem
+    theta: float or 1-dim array of floats
+        angles at which the coefficient is computed
+    ref_point: couple of float, optional
+        point of reference around which the far field coefficient is computed
+
+    Returns
+    -------
+    H: same type as theta
+        values of the Kochin function
+    """
+
+    if result.forward_speed != 0.0:
+        LOG.warning("Kochin functions with forward speed have never been validated.")
+
+    if result.sources is None:
+        raise ValueError(f"""The values of the sources of {result} cannot been found.
+        They have not been stored by the solver either because the direct method has been used or the option keep_details=True have not been set.
+        Please re-run the resolution with `method='indirect'` and `keep_details=True`.""")
+
+    k = result.wavenumber
+    h = result.water_depth
+
+    # omega_bar.shape = (nb_faces, 2) @ (2, nb_theta)
+    omega_bar = (result.body.mesh.faces_centers[:, 0:2] - ref_point) @ (np.cos(theta), np.sin(theta))
+
+    if 0 <= k*h < 20:
+        cih = np.cosh(k*(result.body.mesh.faces_centers[:, 2]+h))/np.cosh(k*h)
+    else:
+        cih = np.exp(k*result.body.mesh.faces_centers[:, 2])
+
+    # cih.shape = (nb_faces,)
+    # omega_bar.T.shape = (nb_theta, nb_faces)
+    # result.body.mesh.faces_areas.shape = (nb_faces,)
+    zs = cih * np.exp(-1j * k * omega_bar.T) * result.body.mesh.faces_areas
+
+    # zs.shape = (nb_theta, nb_faces)
+    # result.sources.shape = (nb_faces,)
+    return zs @ result.sources/(4*np.pi)

capytaine/post_pro/rao.py

@@ -0,0 +1,60 @@
+"""Experimental function to compute the Response Amplitude Operator."""
+# Copyright (C) 2017-2019 Matthieu Ancellin
+# See LICENSE file at <https://github.com/mancellin/capytaine>
+
+import logging
+
+import numpy as np
+import xarray as xr
+from capytaine.post_pro.impedance import rao_transfer_function
+
+LOG = logging.getLogger(__name__)
+
+
+def rao(dataset, wave_direction=None, dissipation=None, stiffness=None):
+    """Response Amplitude Operator.
+
+    Parameters
+    ----------
+    dataset: xarray Dataset
+        The hydrodynamical dataset.
+        This function supposes that variables named 'inertia_matrix' and 'hydrostatic_stiffness' are in the dataset.
+        Other variables can be computed by Capytaine, by those two should be manually added to the dataset.
+    wave_direction: float, optional
+        Select a wave directions for the computation. (Not recommended, kept for legacy.)
+        Default: all wave directions in the dataset.
+    dissipation: array, optional
+        An optional dissipation matrix (e.g. Power Take Off) to be included in the RAO.
+        Default: none.
+    stiffness: array, optional
+        An optional stiffness matrix (e.g. mooring stiffness) to be included in the RAO.
+        Default: none.
+
+    Returns
+    -------
+    xarray DataArray
+        The RAO as an array depending of omega and the degree of freedom.
+    """
+
+    # ASSEMBLE MATRICES
+    H = rao_transfer_function(dataset, dissipation, stiffness)
+    fex = dataset.excitation_force
+
+    LOG.info("Compute RAO.")
+
+    # SOLVE LINEAR SYSTEMS
+    # Match dimensions of the arrays to be sure to solve the right systems.
+    H, fex = xr.broadcast(H, fex, exclude=["radiating_dof", "influenced_dof"])
+    H = H.transpose(..., 'radiating_dof', 'influenced_dof')
+    fex = fex.transpose(...,  'influenced_dof')
+
+    if wave_direction is not None:  # Legacy behavior for backward compatibility
+        H = H.sel(wave_direction=wave_direction)
+        fex = fex.sel(wave_direction=wave_direction)
+
+    # Solve and add coordinates
+    rao_dims = [d for d in H.dims if d != 'influenced_dof']
+    rao_coords = {c: H.coords[c] for c in H.coords if c != 'influenced_dof'}
+    rao = xr.DataArray(np.linalg.solve(H.values, fex.values[..., np.newaxis])[..., 0], coords=rao_coords, dims=rao_dims)
+
+    return rao

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.mesh_like_protocol import MeshLike
+
+
+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, MeshLike):
+        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/lru_cache.py

@@ -0,0 +1,49 @@
+# Copyright (C) 2017-2024 Matthieu Ancellin
+# See LICENSE file at <https://github.com/capytaine/capytaine>
+"""Tools for memoization of functions."""
+from collections import OrderedDict
+from functools import wraps
+
+import logging
+
+LOG = logging.getLogger(__name__)
+
+
+def lru_cache_with_strict_maxsize(maxsize=1):
+    """Behaves mostly like functools.lru_cache(), but the oldest data in the cache is
+    deleted *before* computing a new one, in order to *never* have more that
+    `maxsize` items in memory.
+    This is useful to limit RAM usage when stored objects are big, like the interaction
+    matrices of Capytaine."""
+
+    def decorator(f):
+        cache = OrderedDict()
+
+        @wraps(f)
+        def decorated_f(*args, **kwargs):
+            hashable_kwargs = tuple((k, v) for (k, v) in kwargs.items())
+            # Might miss a cache hit if the order of kwargs is changed.
+            # But at least unlike a previous version, should not return a wrong value.
+
+            if (args, hashable_kwargs) in cache:
+                # Get item in cache
+                LOG.debug("Get cached version of %s(%s, %s)", f.__name__, args, hashable_kwargs)
+                return cache[(args, hashable_kwargs)]
+
+            if len(cache) + 1 > maxsize:
+                # Drop oldest item in cache.
+                cache.popitem(last=False)
+
+            # Compute and store
+            LOG.debug("Computing %s(%s, %s)", f.__name__, args, hashable_kwargs)
+            result = f(*args, **kwargs)
+            cache[(args, hashable_kwargs)] = result
+
+            return result
+
+        return decorated_f
+
+    return decorator
+
+
+delete_first_lru_cache = lru_cache_with_strict_maxsize  # For backward compatibility...

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}."
+            )

capytaine/tools/symbolic_multiplication.py

@@ -0,0 +1,149 @@
+"""This module is used for the handling of zero and infinite frequencies.
+In this cases, the magnitudes that the solver has to manipulate are in the form of ω times a non-zero term.
+Instead of evaluating this multiplication as zero of infinity, we keep it symbolic using the class defined here.
+
+The frequency can be provided to the solver as something like
+`SymbolicMultiplication("0", 1.0)` (that is zero) and the solver will return an
+output of the form `SymbolicMultiplication("0", np.array(...))`
+(that is also actually zero, except we may be intested in the non-zero array).
+"""
+
+import numpy as np
+from functools import wraps, total_ordering
+
+class SymbolicMultiplication:
+    def __init__(self, symbol, value=1.0):
+        self.symbol = symbol
+        self.value = value
+        if hasattr(value, "shape"):
+            self.shape = value.shape  # When wrapping Numpy arrays
+
+    def __format__(self, format_spec):
+        return f"{self.symbol}×{self.value.__format__(format_spec)}"
+
+    __array_priority__ = 1.0
+
+    def __array_function__(self, func, types, *args, **kwargs):
+        if func in {np.real, np.imag, np.sum}:
+            return SymbolicMultiplication(self.symbol, func(self.value))
+        else:
+            return NotImplemented
+
+    def __str__(self):
+        return f"{self.symbol}×{self.value}"
+
+    def __repr__(self):
+        return f"SymbolicMultiplication(\"{self.symbol}\", {repr(self.value)})"
+
+    def __add__(self, x):
+        return self._concretize() + x
+
+    def __radd__(self, x):
+        return x + self._concretize()
+
+    def __neg__(self):
+        return SymbolicMultiplication(self.symbol, -self.value)
+
+    def __mul__(self, x):
+        return SymbolicMultiplication(self.symbol, self.value * x)
+
+    def __rmul__(self, x):
+        return SymbolicMultiplication(self.symbol, x * self.value)
+
+    def __pow__(self, n):
+        if n == 2:
+            return self * self
+        else:
+            raise NotImplementedError
+
+    def __truediv__(self, x):
+        if hasattr(x, 'symbol') and self.symbol == x.symbol:
+            return self.value / x.value
+        else:
+            return SymbolicMultiplication(self.symbol, self.value / x)
+
+    def __rtruediv__(self, x):
+        if hasattr(x, 'symbol') and self.symbol == x.symbol:
+            return x.value / self.value
+        elif self.symbol == "0":
+            return SymbolicMultiplication("∞", x/self.value)
+        elif self.symbol == "∞":
+            return SymbolicMultiplication("0", x/self.value)
+        else:
+            raise NotImplementedError
+
+    def __matmul__(self, x):
+        return SymbolicMultiplication(self.symbol, self.value @ x)
+
+    def __rmatmul__(self, x):
+        return SymbolicMultiplication(self.symbol, x @ self.value)
+
+    def __getitem__(self, item):
+        return SymbolicMultiplication(self.symbol, self.value[item])
+
+    def __setitem__(self, item, val):
+        if isinstance(val, SymbolicMultiplication) and self.symbol == val.symbol:
+            self.value.__setitem__(item, val.value)
+        else:
+            raise NotImplementedError
+
+    def __lt__(self, x):
+        return self._concretize() < x
+
+    def __le__(self, x):
+        return self._concretize() <= x
+
+    def __eq__(self, x):
+        return self._concretize() == x
+
+    def __ge__(self, x):
+        return self._concretize() >= x
+
+    def __gt__(self, x):
+        return self._concretize() > x
+
+    def __hash__(self):
+        return hash((self.symbol, self.value))
+
+    def _concretize(self):
+        if isinstance(self.value, np.ndarray):
+            if self.symbol == "0":
+                return np.zeros_like(self.value)
+            elif self.symbol == "∞":
+                return np.full_like(self.value, np.inf)
+        else:
+            return float(self)
+
+    def __float__(self):
+        if self.symbol == "0":
+            return 0.0 * float(self.value)
+        elif self.symbol == "∞":
+            return np.inf * float(self.value)
+        else:
+            raise NotImplementedError
+
+    def reshape(self, *args):
+        return SymbolicMultiplication(self.symbol, self.value.reshape(*args))
+
+    def sum(self, *args, **kwargs):
+        return SymbolicMultiplication(self.symbol, self.value.sum(*args, **kwargs))
+
+    @property
+    def T(self):
+        return SymbolicMultiplication(self.symbol, self.value.T)
+
+
+def supporting_symbolic_multiplication(f):
+    """
+    When this decorator is applied to a function, this function can now take
+    as input a `SymbolicMultiplication` object. The function is applied on the
+    `value` part of the `SymbolicMultiplication` without modifying the
+    `symbol`.
+    """
+    @wraps(f)
+    def wrapped_f(a, x):
+        if hasattr(x, 'symbol'):
+            return SymbolicMultiplication(x.symbol, f(a, x.value))
+        else:
+            return f(a, x)
+    return wrapped_f

capytaine/tools/timer.py

@@ -0,0 +1,66 @@
+"""A simple timer class used to measure the time spent in various parts of the BEM solver."""
+
+from functools import wraps
+import time
+
+class Timer:
+    """A simple timer class that can be used as context manager or as decorator using `wraps_function` method
+
+    Example
+    -------
+    ::
+
+        timer = Timer()
+        with timer:
+            sleep(1.0)
+
+        print(timer.total)  # 1.0...
+
+        @timer.wraps_function
+        def my_function():
+            sleep(0.5)
+
+        my_function()
+        print(timer.total)  # 1.5...
+        my_function()
+        print(timer.total)  # 2.0...
+
+        print(timer.timings)  # [1.0, 0.5, 0.5]
+    """
+
+    def __init__(self, timings=None):
+        if timings is None:
+            self.timings = []
+        else:
+            self.timings = timings
+
+    def __repr__(self):
+        return f"Timer({self.timings})"
+
+    @property
+    def nb_timings(self):
+        return len(self.timings)
+
+    @property
+    def total(self):
+        return sum(self.timings)
+
+    @property
+    def mean(self):
+        if self.nb_timings == 0:
+            return float('nan')
+        else:
+            return self.total/self.nb_timings
+
+    def __enter__(self):
+        self.start_time = time.perf_counter()
+
+    def __exit__(self, *exc):
+        self.timings.append(time.perf_counter() - self.start_time)
+
+    def wraps_function(self, f):
+        @wraps(f)
+        def wrapped_f(*args, **kwargs):
+            with self:
+                return f(*args, **kwargs)
+        return wrapped_f

capytaine/ui/cli.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+# coding: utf-8
+"""Experimental command-line interface for Capytaine."""
+# Copyright (C) 2017-2023 Matthieu Ancellin
+# See LICENSE file at <https://github.com/capytaine/capytaine>
+
+import argparse
+
+import capytaine as cpt
+from capytaine.io.legacy import run_cal_file
+
+cpt.set_logging()
+
+parser = argparse.ArgumentParser(description="Command-line interface for Capytaine taking Nemoh.cal files as input and returning Tecplots files.")
+parser.add_argument('paramfiles',
+                    default=['./Nemoh.cal'],
+                    nargs='*',
+                    help='path of parameters files (default: ./Nemoh.cal)')
+
+
+def main():
+    args = parser.parse_args()
+    for paramfile in args.paramfiles:
+        run_cal_file(paramfile)
+
+
+if __name__ == '__main__':
+    main()