sigmaepsilon.math 2.2.2__tar.gz → 2.4.0__tar.gz

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sigmaepsilon.math
-Version: 2.2.2
+Version: 2.4.0
 Summary: A Python Library for Applied Mathematics in Physical Sciences.
 License: MIT
 License-File: LICENSE

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "sigmaepsilon.math"
-version = "2.2.2"
+version = "2.4.0"
 description = "A Python Library for Applied Mathematics in Physical Sciences."
 classifiers=[  # https://pypi.org/classifiers/
         "Development Status :: 5 - Production/Stable",

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/__init__.py

@@ -1,3 +1,5 @@
+"""General-purpose applied-math tools for the SigmaEpsilon ecosystem."""
+
 from os.path import dirname, abspath
 from importlib.metadata import metadata
 

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/__init__.py

@@ -1,3 +1,5 @@
+"""Least-squares style approximation tools (moving least squares, weight functions, Lagrange interpolation)."""
+
 from .ls import moving_least_squares, least_squares, weighted_least_squares
 from .functions import (
     CubicWeightFunction,

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/functions.py

@@ -1,3 +1,5 @@
+"""Weight functions used by the moving least squares approximator."""
+
 from typing import Tuple, Any, Iterable
 from numbers import Number
 
@@ -9,9 +11,7 @@ from ..function import Function
 
 
 class MLSWeightFunction(Function):
-    """
-    Base class for weight functions for the moving least squares method.
-    """
+    """Base class for weight functions for the moving least squares method."""
 
     def __init__(
         self,
@@ -48,6 +48,7 @@ class MLSWeightFunction(Function):
 
     @property
     def core(self) -> ndarray | Iterable[Number] | None:
+        """Return the core (center) of the weight function."""
         return self._core
 
     @core.setter
@@ -66,6 +67,7 @@ class MLSWeightFunction(Function):
 
     @property
     def supportdomain(self) -> ndarray | Iterable[Number] | None:
+        """Return the support domain of the weight function."""
         return self._supportdomain
 
     @supportdomain.setter
@@ -81,6 +83,7 @@ class MLSWeightFunction(Function):
         return
 
     def preproc_evaluation(self, x: Iterable[Number]):
+        """Validate and coerce the evaluation point `x` into a NumPy array."""
         if not isinstance(x, (ndarray, float)):
             if isinstance(x, Iterable):
                 x = np.array(x)
@@ -90,16 +93,17 @@ class MLSWeightFunction(Function):
                 )
 
     def value(self, x: Iterable[Number]) -> float:
-        """
-        Evaluates the function.
-        """
+        """Evaluate the function."""
         raise NotImplementedError
 
 
 def isMLSWeightFunction(f: Any) -> bool:
-    """
-    Returns `True` if the argument is a valid weight function for the
-    moving least squares method.
+    """Return `True` if the argument is a valid weight function for the moving least squares method.
+
+    Parameters
+    ----------
+    f : Any
+        The object to check.
     """
     c1 = isinstance(f, MLSWeightFunction)
     c2 = MLSWeightFunction in list(type(f).__bases__)
@@ -107,9 +111,7 @@ def isMLSWeightFunction(f: Any) -> bool:
 
 
 class ConstantWeightFunction(MLSWeightFunction):
-    """
-    A constant weight function for the moving least squares method.
-    """
+    """A constant weight function for the moving least squares method."""
 
     def __init__(self, *, value: Number = 1.0, **kwargs):
         super().__init__(**kwargs)
@@ -117,6 +119,7 @@ class ConstantWeightFunction(MLSWeightFunction):
         return
 
     def value(self, x: Iterable[Number]) -> float:
+        """Return the value of the weight function at `x`."""
         if self.supportdomain is None:
             return self._value
 
@@ -129,16 +132,16 @@ class ConstantWeightFunction(MLSWeightFunction):
         return self._value
 
     def gradient(self, x: Iterable[Number]) -> ndarray:
+        """Return the gradient of the weight function at `x`."""
         return np.zeros(self.dimension, dtype=float)
 
     def Hessian(self, x: Iterable[Number]) -> ndarray:
+        """Return the Hessian of the weight function at `x`."""
         return np.zeros((self.dimension, self.dimension), dtype=float)
 
 
 class SingularWeightFunction(MLSWeightFunction):
-    """
-    A singular weight function for the moving least squares method.
-    """
+    """A singular weight function for the moving least squares method."""
 
     def __init__(self, *, eps: Number = 1e-5, **kwargs):
         super().__init__(**kwargs)
@@ -146,13 +149,16 @@ class SingularWeightFunction(MLSWeightFunction):
         return
 
     def value(self, x: Iterable[Number]):
+        """Return the value of the weight function at `x`."""
         self.preproc_evaluation(x)
         return 1 / (norm(np.subtract(self.core, x)) ** 2 + self.eps**2)
 
     def gradient(self, x: Iterable[Number]) -> ndarray:
+        """Return the gradient of the weight function at `x`."""
         return np.zeros(self.dimension, dtype=float)
 
     def Hessian(self, x: Iterable[Number]) -> ndarray:
+        """Return the Hessian of the weight function at `x`."""
         return np.zeros((self.dimension, self.dimension), dtype=float)
 
 
@@ -170,6 +176,7 @@ class CubicWeightFunction(MLSWeightFunction):
     """
 
     def evaluate(self, x: Iterable[Number]) -> Tuple[float, ndarray, ndarray]:
+        """Return the value, gradient and Hessian of the weight function at `x`."""
         if self.dimension == 1:
             return self._evaluate_1d(x)
         elif self.dimension == 2:
@@ -259,16 +266,19 @@ class CubicWeightFunction(MLSWeightFunction):
         return val, grad, Hessian
 
     def value(self, x: Iterable[Number]) -> float:
+        """Return the value of the weight function at `x`."""
         self.preproc_evaluation(x)
         res, _, _ = self.evaluate(x)
         return res
 
     def gradient(self, x: Iterable[Number]) -> ndarray:
+        """Return the gradient of the weight function at `x`."""
         self.preproc_evaluation(x)
         _, res, _ = self.evaluate(x)
         return res
 
     def Hessian(self, x: Iterable[Number]) -> ndarray:
+        """Return the Hessian of the weight function at `x`."""
         self.preproc_evaluation(x)
         _, _, res = self.evaluate(x)
         return res

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/lagrange.py

@@ -1,3 +1,5 @@
+"""Lagrange polynomial generation and 1d approximation utilities."""
+
 from typing import Iterable, Callable
 
 import sympy as sy
@@ -33,8 +35,9 @@ def gen_Lagrange_1d(
     lambdify: bool = False,
     out: dict | None = None
 ) -> dict:
-    """
-    Generates Lagrange polynomials and their derivatives up to 3rd, for approximation
+    """Generate Lagrange polynomials and their derivatives.
+
+    Generates polynomials and their derivatives up to 3rd order, for approximation
     in 1d space, based on N input pairs of position and value. Geometrical parameters
     can be numeric or symbolic.
 
@@ -165,8 +168,7 @@ def gen_Lagrange_1d(
 def approx_Lagrange_1d(
     points: Iterable, values: Iterable, lambdify: bool = False
 ) -> Callable:
-    """
-    Returns a callable that maps from 'source' to 'target' in 1d.
+    """Return a callable that maps from 'source' to 'target' in 1d.
 
     Parameters
     ----------

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/ls.py

@@ -1,3 +1,5 @@
+"""Least squares and moving least squares approximation."""
+
 from typing import Callable, Iterable
 
 import numpy as np
@@ -18,8 +20,9 @@ def moving_least_squares(
     w: Callable | None = None,
     **kwargs,
 ) -> Callable:
-    """
-    Moving least squares approximation. The usage is the same as for the
+    """Perform moving least squares approximation.
+
+    The usage is the same as for the
     :func:`~sigmaepsilon.math.approx.ls.weighted_least_squares` function.
     """
     dim = 1 if len(points.shape) == 1 else points.shape[1]
@@ -50,7 +53,8 @@ def least_squares(
     deg: int = 1,
     order: int = 2,
 ) -> Callable:
-    """
+    r"""Fit a polynomial to the given points and values in the least-squares sense.
+
     Given :math:`N` points located at :math:`\mathbf{x}_i` in :math:`\mathbb{R}^d`
     where :math:`i \in [1 \dots N]`. The returned fit function approximates the given
     values :math:`f_i` at :math:`\mathbf{x}_i` in the least-squares sence with the
@@ -95,8 +99,7 @@ def weighted_least_squares(
     order: int = 2,
     w: Callable | None = None,
 ) -> Callable:
-    """
-    Returns a Callable that can be used to approximate over datasets.
+    """Return a Callable that can be used to approximate over datasets.
 
     Parameters
     ----------

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/ls_approx.py

@@ -1,3 +1,5 @@
+"""Numba-jitted kernels for moving least squares approximation and its derivatives."""
+
 from typing import Tuple
 
 from numpy import ndarray

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/ls_poly.py

@@ -1,3 +1,5 @@
+"""Polynomial basis functions and their derivatives for least squares approximation."""
+
 import numpy as np
 
 

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/ls_preproc.py

@@ -1,3 +1,5 @@
+"""Assembly of the moment matrices used by moving least squares approximation."""
+
 from typing import Callable, Tuple
 
 import numpy as np

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/approx/mls.py

@@ -1,3 +1,5 @@
+"""High performance, object oriented moving least squares approximation."""
+
 from numbers import Number
 
 from numpy import ndarray
@@ -33,9 +35,9 @@ def _approximate_nd(
 
 
 class MLSApproximator:
-    """
-    Object oriented, high performance implementation of a specific version of the
-    moving least squares method. This implementation is less flexible than the others,
+    """Object oriented, high performance implementation of moving least squares.
+
+    This implementation is less flexible than the others,
     but performes well for extremely large datasets too. If you want to experiment
     with the hyperparameters of the MLS as a method, it is suggested to use the other
     solutions offered by the library.
@@ -130,32 +132,28 @@ class MLSApproximator:
 
     @property
     def neighbours(self) -> ndarray | None:
-        """
-        Returns the neighbours of the target points. If the neighbours are not
-        calculated yet, it returns None.
+        """Return the neighbours of the target points.
+
+        If the neighbours are not calculated yet, it returns None.
         """
         return self._neighbours
 
     @neighbours.setter
     def neighbours(self, val: ndarray) -> None:
-        """
-        Sets the neighbours of the target points.
-        """
+        """Set the neighbours of the target points."""
         self._neighbours = val
 
     @property
     def factors(self) -> ndarray | None:
-        """
-        Returns the factors of the target points. If the factors are not
-        calculated yet, it returns None.
+        """Return the factors of the target points.
+
+        If the factors are not calculated yet, it returns None.
         """
         return self._factors
 
     @factors.setter
     def factors(self, val: ndarray) -> None:
-        """
-        Sets the factors of the target points.
-        """
+        """Set the factors of the target points."""
         self._factors = val
 
     def _calc_factors_and_neighbours(self, X_S: ndarray, X_T: ndarray) -> None:

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/arraysetops.py

@@ -1,3 +1,5 @@
+"""Set operations on arrays, including unique-element finding for 2d arrays."""
+
 import numpy as np
 from numpy import ndarray
 from awkward import Array as akarray

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/decorate.py

@@ -1,3 +1,5 @@
+"""Decorators shared across the package."""
+
 from typing import Callable, Any
 import numpy as np
 
@@ -10,8 +12,9 @@ def _squeeze_if_array(arr: Any) -> Any:
 
 
 def squeeze(default: bool = True) -> Callable:
-    """
-    A decorator that squeezes outputs of a function if
+    """Return a decorator that squeezes outputs of a function.
+
+    Applies when
     * the result is a NumPy array
     * the result is a tuple of NumPy arrays
     * the result is a dictionary of NumPy arrays as values

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/downloads.py

@@ -1,3 +1,5 @@
+"""Utilities for downloading test data used by the library."""
+
 import numpy as np
 
 from sigmaepsilon.core.downloads import download_file, delete_downloads
@@ -10,8 +12,7 @@ __all__ = [
 
 
 def download_mls_testdata() -> np.ndarray:
-    """
-    Downloads the data of a cloud of points.
+    """Download the data of a cloud of points.
 
     Returns
     -------

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/function/__init__.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+"""Function and relation objects used to model optimization problems."""
 from .function import Function, FunctionLike
 from .relation import Equality, InEquality, Relation
 

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/function/function.py

@@ -1,3 +1,5 @@
+"""Base class for symbolic and numerical functions."""
+
 from typing import TypeVar, Callable, Iterable
 from collections import OrderedDict
 import warnings
@@ -19,8 +21,9 @@ FunctionLike = TypeVar("FunctionLike", str, Callable, Expr)
 
 
 class Function(MetaFunction):
-    """
-    Base class for all kinds of functions. It can be used to represent
+    """Base class for all kinds of functions.
+
+    It can be used to represent
     symbolic and numerical functions. The class is designed to be as
     flexible as possible, so it can be used in a wide range of applications.
 
@@ -182,6 +185,7 @@ class Function(MetaFunction):
         variables: Iterable | None = None,
         **kwargs
     ):
+        """Update the instance in place with new function definitions."""
         self.from_str = None
 
         if f0 is not None:
@@ -202,8 +206,8 @@ class Function(MetaFunction):
 
     @property
     def symbolic(self) -> bool:
-        """
-        Returns `True` if the function is a fit subject of symbolic manipulation.
+        """Return `True` if the function is a fit subject of symbolic manipulation.
+
         This is probably only true if the object was created from a string or
         `sympy` expression.
         """
@@ -217,9 +221,7 @@ class Function(MetaFunction):
 
     @property
     def linear(self) -> bool:
-        """
-        Returns True if the function is at most linear in all of its variables.
-        """
+        """Return True if the function is at most linear in all of its variables."""
         warnings.warn(
             "The property `linear` is deprecated and will be removed in a future version. "
             "Use `is_linear` instead.",
@@ -230,9 +232,7 @@ class Function(MetaFunction):
 
     @property
     def is_linear(self) -> bool:
-        """
-        Returns `True` if the function is at most linear in all of its variables.
-        """
+        """Return `True` if the function is at most linear in all of its variables."""
         if self.is_symbolic:
             return all(
                 np.array([degree(self.expr, v) for v in self.variables], dtype=int) <= 1
@@ -242,25 +242,22 @@ class Function(MetaFunction):
 
     @property
     def is_symbolic(self) -> bool:
-        """
-        Returns `True` if the function is a fit subject of symbolic manipulation.
+        """Return `True` if the function is a fit subject of symbolic manipulation.
+
         This is probably only true if the object was created from a string or
         `SymPy` expression.
         """
         return self.expr is not None
 
     def simplify(self) -> None:
-        """
-        Simplifies the symbolic expression of the instance.
-        """
+        """Simplify the symbolic expression of the instance."""
         if self.is_symbolic:
             self.expr = self.expr.simplify()
         else:
             raise TypeError("This is exclusive to symbolic functions.")
 
     def linear_coefficients(self, normalize: bool = False) -> dict | None:
-        """
-        Returns the linear coeffiecients, if the function is symbolic and linear.
+        """Return the linear coeffiecients, if the function is symbolic and linear.
 
         Parameters
         ----------
@@ -284,8 +281,7 @@ class Function(MetaFunction):
         return None
 
     def coefficients(self, normalize: bool = False) -> dict | None:
-        """
-        Returns the coefficients if the function is symbolic.
+        """Return the coefficients if the function is symbolic.
 
         Parameters
         ----------
@@ -322,8 +318,8 @@ class Function(MetaFunction):
             return None
 
     def to_latex(self) -> str:
-        """
-        Returns the LaTeX code of the symbolic expression of the instance.
+        """Return the LaTeX code of the symbolic expression of the instance.
+
         Only for symbolic functions.
 
         Examples

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/function/functions.py

@@ -1,3 +1,5 @@
+"""Standard benchmark test functions for optimizers."""
+
 import sympy as sy
 
 from .testfunction import TestMinFunction2D
@@ -14,8 +16,7 @@ __all__ = [
 
 
 def Rosenbrock(a: float = 1, b: float = 100) -> TestMinFunction2D:
-    """
-    Implements the Rosenbrock function, aka. Banana function.
+    """Implement the Rosenbrock function, aka. Banana function.
 
     :math:`f(x, y) = (a - x)^2 + b (y - x^2)^2`
 
@@ -29,8 +30,7 @@ def Rosenbrock(a: float = 1, b: float = 100) -> TestMinFunction2D:
 
 
 def Himmelblau() -> TestMinFunction2D:
-    """
-    Creates the Himmelblau's function object.
+    """Create the Himmelblau's function object.
 
     :math:`f(x,y) = (x^2 + y - 11)^2 + (x + y^2 - 7)^2`
 
@@ -50,8 +50,7 @@ def Himmelblau() -> TestMinFunction2D:
 
 
 def GoldsteinPrice() -> TestMinFunction2D:
-    """
-    Creates the Goldstein-Price function object.
+    r"""Create the Goldstein-Price function object.
 
     .. math::
         :nowrap:
@@ -72,8 +71,7 @@ def GoldsteinPrice() -> TestMinFunction2D:
 
 
 def Beale() -> TestMinFunction2D:
-    """
-    Creates the Beale function object.
+    r"""Create the Beale function object.
 
     .. math::
         :nowrap:
@@ -93,8 +91,7 @@ def Beale() -> TestMinFunction2D:
 
 
 def Matyas() -> TestMinFunction2D:
-    """
-    Creates the Matyas function object.
+    """Create the Matyas function object.
 
     :math:`f(x, y) = 0.26 (x^2 + y^2) - 0.48 x y`
 

{sigmaepsilon_math-2.2.2 → sigmaepsilon_math-2.4.0}/src/sigmaepsilon/math/function/metafunction.py

@@ -1,3 +1,5 @@
+"""Metaclass and base class shared by symbolic and numerical functions."""
+
 from sympy import Expr
 
 from sigmaepsilon.core.abstract import ABCMeta_Weak
@@ -5,11 +7,10 @@ from .symutils import symbolize
 
 
 class ABCMeta_MetaFunction(ABCMeta_Weak):
-    """
-    Metaclass for defining ABCs for algebraic structures.
-    """
+    """Metaclass for defining ABCs for algebraic structures."""
 
     def __new__(metaclass, name, bases, namespace, /, **kwargs):
+        """Create a new class, promoting `value`/`gradient`/`Hessian` to `f`/`g`/`G`."""
         cls = super().__new__(metaclass, name, bases, namespace, **kwargs)
         if "value" in namespace:
             cls.f = namespace["value"]
@@ -24,14 +25,21 @@ class ABCMeta_MetaFunction(ABCMeta_Weak):
 
 
 class MetaFunction(metaclass=ABCMeta_MetaFunction):
+    """Base class providing the `f`/`g`/`G` interface for functions.
+
+    Subclasses that define `value`, `gradient` and/or `Hessian` methods
+    automatically get those promoted to `f`, `g` and `G` respectively, via
+    :class:`ABCMeta_MetaFunction`.
+    """
+
     __slots__ = ("f0", "f1", "f2", "dimension", "domain", "expr", "variables", "vmap")
 
     def __call__(self, *args, **kwargs):
+        """Return the function value, equivalent to calling :meth:`f`."""
         return self.f(*args, **kwargs)
 
     def f(self, *args, **kwargs):
-        """
-        Returns the function value.
+        """Return the function value.
 
         For this operation the object must have an implementation of
 
@@ -42,8 +50,7 @@ class MetaFunction(metaclass=ABCMeta_MetaFunction):
         return self.f0(*args, **kwargs)
 
     def g(self, *args, **kwargs):
-        """
-        Returns the gradient vector if available.
+        """Return the gradient vector if available.
 
         For this operation the object must have an implementation of
 
@@ -54,8 +61,7 @@ class MetaFunction(metaclass=ABCMeta_MetaFunction):
         return self.f1(*args, **kwargs)
 
     def G(self, *args, **kwargs):
-        """
-        Returns the Hessian matrix if available.
+        """Return the Hessian matrix if available.
 
         For this operation the object must have an implementation of