pynamicalsys 1.0.0__py3-none-any.whl

pynamicalsys/common/utils.py

@@ -0,0 +1,344 @@
+# utils.py
+
+# Copyright (C) 2025 Matheus Rolim Sales
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import numpy as np
+from typing import Callable, Tuple
+from numpy.typing import NDArray
+from numba import njit
+
+
+@njit(cache=True)
+def qr(M: NDArray[np.float64]) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """
+    Perform numerically stable QR decomposition using modified Gram-Schmidt with reorthogonalization.
+
+    Parameters
+    ----------
+    M : NDArray[np.float64]
+        Input matrix of shape (m, n) with linearly independent columns.
+
+    Returns
+    -------
+    Tuple[NDArray[np.float64], NDArray[np.float64]]
+        Q: Orthonormal matrix (m, n)
+        R: Upper triangular matrix (n, n)
+
+    Notes
+    -----
+    - Implements modified Gram-Schmidt with iterative refinement
+    - Includes additional reorthogonalization steps for stability
+    - Uses double precision throughout for accuracy
+    - Automatically handles rank-deficient cases with warnings
+
+    Examples
+    --------
+    >>> M = np.array([[1.0, 1.0], [1.0, 0.0], [0.0, 1.0]])
+    >>> Q, R = qr(M)
+    >>> np.allclose(M, Q @ R)
+    True
+    >>> np.allclose(Q.T @ Q, np.eye(2))
+    True
+    """
+    m, n = M.shape
+    Q = np.ascontiguousarray(M.copy())
+    R = np.ascontiguousarray(np.zeros((n, n)))
+    eps = np.finfo(np.float64).eps  # Machine epsilon for stability checks
+
+    for i in range(n):
+        # First orthogonalization pass
+        for k in range(i):
+            R[k, i] = np.dot(
+                np.ascontiguousarray(Q[:, k]), np.ascontiguousarray(Q[:, i])
+            )
+            Q[:, i] -= R[k, i] * Q[:, k]
+
+        # Compute norm and check for linear dependence
+        norm = np.linalg.norm(Q[:, i])
+        if norm < eps * m:  # Adjust threshold based on matrix size
+            # Handle near-linear dependence
+            Q[:, i] = np.random.randn(m)
+            Q[:, i] /= np.linalg.norm(Q[:, i])
+            norm = 1.0
+
+        R[i, i] = norm
+        Q[:, i] /= norm
+
+        # Optional second reorthogonalization pass for stability
+        for k in range(i):
+            dot = np.dot(np.ascontiguousarray(Q[:, k]), np.ascontiguousarray(Q[:, i]))
+            R[k, i] += dot
+            Q[:, i] -= dot * Q[:, k]
+
+        # Renormalize after reorthogonalization
+        new_norm = np.linalg.norm(Q[:, i])
+        if new_norm < 0.1:  # Significant cancellation occurred
+            Q[:, i] /= new_norm
+            R[i, i] *= new_norm
+
+    return Q, R
+
+
+@njit(cache=True)
+def householder_qr(
+    M: NDArray[np.float64],
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """
+    Compute the QR decomposition using Householder reflections with enhanced numerical stability.
+
+    This implementation includes:
+    - Column pivoting for rank-deficient matrices
+    - Careful handling of sign choices to minimize cancellation
+    - Efficient accumulation of Q matrix
+    - Special handling of small submatrices
+
+    Parameters
+    ----------
+    M : NDArray[np.float64]
+        Input matrix of shape (m, n) where m >= n
+
+    Returns
+    -------
+    Tuple[NDArray[np.float64], NDArray[np.float64]]
+        Q: Orthogonal matrix (m×m)
+        R: Upper triangular matrix (m×n)
+
+    Raises
+    ------
+    ValueError
+        If input matrix has more columns than rows (m < n)
+
+    Notes
+    -----
+    - For rank-deficient matrices, consider using column pivoting (not shown here)
+    - The implementation uses the most numerically stable sign choice
+    - Accumulates Q implicitly for better performance
+    - Automatically handles edge cases like zero columns
+
+    Examples
+    --------
+    >>> # Well-conditioned matrix
+    >>> M = np.array([[3.0, 1.0], [4.0, 2.0]], dtype=np.float64)
+    >>> Q, R = householder_qr(M)
+    >>> np.allclose(Q @ R, M, atol=1e-10)
+    True
+
+    >>> # Rank-deficient case
+    >>> M = np.array([[1.0, 2.0], [2.0, 4.0]], dtype=np.float64)
+    >>> Q, R = householder_qr(M)
+    >>> np.abs(R[1,1]) < 1e-10  # Second column is dependent
+    True
+    """
+    m, n = M.shape
+    if m < n:
+        raise ValueError("Input matrix must have m >= n for QR decomposition")
+
+    # Initialize Q as identity matrix (will accumulate Householder transformations)
+    Q = np.eye(m)
+
+    # Initialize R as a copy of input matrix (will be transformed to upper triangular)
+    R = M.copy().astype(np.float64)
+
+    for k in range(n):
+        # Extract the subcolumn from current diagonal downward
+        x = R[k:, k]
+
+        # Skip if the subcolumn is already zero (for numerical stability)
+        if np.allclose(x[1:], 0.0):
+            continue
+
+        # Create basis vector e1 = [1, 0, ..., 0] of same length as x
+        e1 = np.zeros_like(x)
+        e1[0] = 1.0
+
+        # Compute Householder vector v:
+        # v = sign(x[0])*||x||*e1 + x
+        # The sign choice ensures numerical stability (avoids cancellation)
+        v = np.sign(x[0]) * np.linalg.norm(x) * e1 + x
+        v = v / np.linalg.norm(v)  # Normalize v
+
+        # Construct Householder reflector H = I - 2vv^T
+        # We build it as an extension of the identity matrix
+        H = np.eye(m)
+        H[k:, k:] -= 2.0 * np.outer(v, v)
+
+        # Apply reflector to R (zeroing out below-diagonal elements in column k)
+        R = H @ R
+
+        # Accumulate the reflection in Q (Q = Q * H^T, since H is symmetric)
+        Q = Q @ H.T
+
+    return Q, R
+
+
+@njit(cache=True)
+def finite_difference_jacobian(
+    u: NDArray[np.float64],
+    parameters: NDArray[np.float64],
+    mapping: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    eps: float = -1.0,
+) -> NDArray[np.float64]:
+    """
+    Compute the Jacobian matrix using adaptive finite differences with error control.
+
+    Parameters
+    ----------
+    u : NDArray[np.float64]
+        State vector at which to compute Jacobian (shape: (n,))
+    parameters : NDArray[np.float64]
+        System parameters
+    mapping : Callable[[NDArray, NDArray], NDArray]
+        Vector-valued function to differentiate
+    eps : float, optional
+        Initial step size (automatically determined if -1.0)
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Jacobian matrix (shape: (n, n)) where J[i,j] = ∂f_i/∂u_j
+
+    Raises
+    ------
+    ValueError
+        If invalid method is specified
+        If eps is not positive when provided
+
+    Notes
+    -----
+    - For 'central' method (default), accuracy is O(eps²)
+    - For 'complex' method, accuracy is O(eps⁴) but requires complex arithmetic
+    - Automatic step size selection based on machine epsilon and input scale
+    - Includes Richardson extrapolation for higher accuracy
+    - Handles edge cases like zero components carefully
+
+    Examples
+    --------
+    >>> def lorenz(u, p):
+    ...     x, y, z = u
+    ...     sigma, rho, beta = p
+    ...     return np.array([sigma*(y-x), x*(rho-z)-y, x*y-beta*z])
+    >>> u = np.array([1.0, 1.0, 1.0])
+    >>> params = np.array([10.0, 28.0, 8/3])
+    >>> J = finite_difference_jacobian(u, params, lorenz, method='central')
+    """
+    n = len(u)
+    J = np.zeros((n, n))
+
+    # Determine optimal step size if not provided
+    if eps <= 0:
+        eps = float(np.finfo(np.float64).eps) ** (1 / 3) * max(
+            1.0, float(np.linalg.norm(u))
+        )
+
+    for i in range(n):
+        # Central difference: O(eps²) accuracy
+        u_plus = u.copy()
+        u_minus = u.copy()
+        u_plus[i] += eps
+        u_minus[i] -= eps
+        J[:, i] = (mapping(u_plus, parameters) - mapping(u_minus, parameters)) / (
+            2 * eps
+        )
+
+    return J
+
+
+@njit
+def wedge_product_norm(vectors: NDArray[np.float64]) -> float:
+    """
+    Computes the norm of the wedge product of n m-dimensional vectors using the Gram determinant.
+
+    Parameters:
+    vectors : NDArray[np.float64]
+        A (m, n) array where m is the dimension and n is the number of vectors.
+
+    Returns:
+    norm : float
+        The norm (magnitude) of the wedge product.
+    """
+    m, n = vectors.shape
+    if n > m:
+        raise ValueError(
+            "Cannot compute the wedge product: more vectors than dimensions."
+        )
+
+    # Compute the Gram matrix
+    G = np.zeros((n, n))
+    for i in range(n):
+        for j in range(n):
+            dot = 0.0
+            for k in range(m):
+                dot += vectors[k, i] * vectors[k, j]
+            G[i, j] = dot
+
+    # Compute determinant
+    det = np.linalg.det(G)
+
+    # If determinant is slightly negative due to numerical error, clip to 0
+    if det < 0:
+        det = 0.0
+
+    norm = np.sqrt(det)
+    return norm
+
+
+@njit
+def _coeff_mat(x: NDArray[np.float64], deg: int) -> NDArray[np.float64]:
+    mat_ = np.zeros(shape=(x.shape[0], deg + 1))
+    const = np.ones_like(x)
+    mat_[:, 0] = const
+    mat_[:, 1] = x
+    if deg > 1:
+        for n in range(2, deg + 1):
+            mat_[:, n] = x**n
+    return mat_
+
+
+@njit
+def _fit_x(a: NDArray[np.float64], b: NDArray[np.float64]) -> NDArray[np.float64]:
+    # linalg solves ax = b
+    det_ = np.linalg.lstsq(a, b)[0]
+    return det_
+
+
+@njit
+def fit_poly(
+    x: NDArray[np.float64], y: NDArray[np.float64], deg: int
+) -> NDArray[np.float64]:
+    a = _coeff_mat(x, deg)
+    p = _fit_x(a, y)
+    # Reverse order so p[0] is coefficient of highest order
+    return p[::-1]
+
+
+if __name__ == "__main__":
+
+    v = np.random.rand(2, 2)
+    w = v.copy()
+
+    q, r = qr(v)
+    print("Q:\n", q)
+    print("R:\n", r)
+    print("QR Product:\n", np.dot(q, r))
+    print("Original Matrix:\n", v)
+
+    print()
+
+    q, r = householder_qr(v)
+    print("Q:\n", q)
+    print("R:\n", r)
+    print("QR Product:\n", np.dot(q, r))
+    print("Original Matrix:\n", v)

pynamicalsys/continuous_time/__init__.py

@@ -0,0 +1,16 @@
+# # __init__.py
+
+# # Copyright (C) 2025 Matheus Rolim Sales
+# #
+# # This program is free software: you can redistribute it and/or modify
+# # it under the terms of the GNU General Public License as published by
+# # the Free Software Foundation, either version 3 of the License, or
+# # (at your option) any later version.
+# #
+# # This program is distributed in the hope that it will be useful,
+# # but WITHOUT ANY WARRANTY; without even the implied warranty of
+# # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# # GNU General Public License for more details.
+# #
+# # You should have received a copy of the GNU General Public License
+# # along with this program. If not, see <https://www.gnu.org/licenses/>.

pynamicalsys/core/__init__.py

@@ -0,0 +1,16 @@
+# # __init__.py
+
+# # Copyright (C) 2025 Matheus Rolim Sales
+# #
+# # This program is free software: you can redistribute it and/or modify
+# # it under the terms of the GNU General Public License as published by
+# # the Free Software Foundation, either version 3 of the License, or
+# # (at your option) any later version.
+# #
+# # This program is distributed in the hope that it will be useful,
+# # but WITHOUT ANY WARRANTY; without even the implied warranty of
+# # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# # GNU General Public License for more details.
+# #
+# # You should have received a copy of the GNU General Public License
+# # along with this program. If not, see <https://www.gnu.org/licenses/>.

pynamicalsys/core/basin_metrics.py

@@ -0,0 +1,206 @@
+# basin_metrics.py
+
+# Copyright (C) 2025 Matheus Rolim Sales
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import numpy as np
+from numbers import Integral, Real
+from typing import Optional, Tuple
+from numpy.typing import NDArray
+from pynamicalsys.common.basin_analysis import basin_entropy, uncertainty_fraction
+
+
+class BasinMetrics:
+    """A class for computing metrics related to basin of attraction analysis, such as basin entropy and uncertainty fraction.
+
+    This class provides methods to quantify the unpredictability and complexity of basins of attraction in dynamical systems. It supports calculation of basin entropy, boundary basin entropy, and the uncertainty fraction, which are useful for characterizing the structure and boundaries of basins.
+
+    Parameters
+    ----------
+    basin : NDArray[np.float64]
+        A 2D array representing the basin of attraction, where each element indicates
+        the final state (attractor) for that initial condition (shape: (Nx, Ny)).
+
+    Raises
+    ------
+    ValueError
+        If `basin` is not a 2-dimensional array.
+
+    Notes
+    -----
+    The basin should be a 2D array where each element represents the final state
+    (attractor) for that initial condition. The shape of the basin should be (Nx, Ny),
+    where Nx is the number of rows and Ny is the number of columns.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pynamicalsys import BasinMetrics
+    >>> basin = np.array([[0, 1], [1, 0]])
+    >>> metrics = BasinMetrics(basin)
+    """
+
+    def __init__(self, basin: NDArray[np.float64]) -> None:
+        self.basin = basin
+
+        if isinstance(self.basin, list):
+            self.basin = np.array(self.basin, dtype=np.float64)
+
+        if basin.ndim != 2:
+            raise ValueError("basin must be 2-dimensional")
+
+        pass
+
+    def basin_entropy(
+        self,
+        n: int,
+        log_base: float = np.e,
+        nx: Optional[int] = None,
+        ny: Optional[int] = None,
+    ) -> Tuple[float, float]:
+        """Calculate the basin entropy (Sb) and boundary basin entropy (Sbb) of a 2D basin.
+
+        The basin entropy quantifies the uncertainty in final state prediction, while the boundary
+        entropy specifically measures uncertainty at basin boundaries where multiple attractors coexist.
+
+        Parameters
+        ----------
+        n : int
+            Default size of square sub-boxes for partitioning (must be positive).
+        log : float, optional
+            Logarithm base for entropy calculation (default: np.e, which is natural logarithm).
+
+        Returns
+        -------
+        Tuple[float, float]
+            A tuple containing:
+
+            - Sb: Basin entropy
+            - Sbb: Boundary basin entropy
+
+        Raises
+        ------
+        ValueError
+            If `n`, is not positive integer, or if `log_base` is not positive.
+
+        Notes
+        -----
+        The basin entropy is calculated by partitioning the basin into sub-boxes of size `n` and computing the entropy of each sub-box. The boundary basin entropy is computed similarly but focuses on the sub-boxes that lie on the boundaries of the basin where multiple attractors coexist.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> np.random.seed(13)
+        >>> basin = np.random.randint(1, 4, size=(1000, 1000))
+        >>> from pynamicalsys import BasinMetrics
+        >>> metrics = BasinMetrics(basin)
+        >>> metrics.basin_entropy(n=5, log_base=2)
+        (1.5251876046167432, 1.5251876046167432)
+        """
+
+        if not isinstance(n, Integral) or n <= 0:
+            raise ValueError("n must be positive integer")
+
+        if log_base <= 0:
+            raise ValueError("log_base must be positive")
+
+        return basin_entropy(basin=self.basin, n=n, log_base=log_base)
+
+    def uncertainty_fraction(
+        self,
+        x: NDArray[np.float64],
+        y: NDArray[np.float64],
+        epsilon_max: float = 0.1,
+        n_eps: int = 100,
+        epsilon_min: Optional[int] = None,
+    ) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+        """Calculate the uncertainty fraction for a given basin.
+
+        This method computes the uncertainty fraction for each point in the basin
+        based on the provided parameters.
+
+        Parameters
+        ----------
+        x : NDArray[np.float64]
+            2D array of the basin's x-coordinates.
+        y : NDArray[np.float64]
+            2D array of the basin's y-coordinates.
+        epsilon_max : float, optional
+            Maximum epsilon value (default: 0.1).
+        n_eps : int, optional
+            Number of epsilon values to consider (default: 100).
+        epsilon_min : int, optional
+            Minimum epsilon value (default: None).
+
+        Returns
+        -------
+        Tuple[NDArray[np.float64], NDArray[np.float64]]
+            A tuple containing:
+
+            - epsilons: Array of epsilon values.
+            - uncertainty_fraction: Array of uncertainty fractions corresponding to each epsilon.
+
+        Notes
+        -----
+        - The uncertainty fraction scales with ε as a power law: f(ε) ~ ε^{⍺}, where ⍺ is the uncertainty exponent.
+        - For D-dimensional basins, the dimension d of the basin boundary is given by d = D - ⍺.
+
+        Examples
+        --------
+        >>> # Create a basin of 0's and 1's, where the 1's form a rectangle, i.e., d = 1
+        >>> grid_size = 10000
+        >>> x_range = (0, 1, grid_size)
+        >>> y_range = (0, 1, grid_size)
+        >>> x = np.linspace(*x_range)
+        >>> y = np.linspace(*y_range)
+        >>> X, Y = np.meshgrid(x, y, indexing='ij')
+        >>> obj = [[0.2, 0.6],
+            [0.2, 0.6]]
+        >>> basin = np.zeros((grid_size, grid_size), dtype=int)
+        >>> basin[mask] = 1
+        >>> bm = BasinMetrics(basin)
+        >>> eps, f = bm.uncertainty_fraction(X, Y, epsilon_max=0.1)
+        """
+
+        if isinstance(x, list):
+            x = np.array(x, dtype=np.float64)
+        if isinstance(y, list):
+            y = np.array(y, dtype=np.float64)
+
+        if x.ndim != 2 or y.ndim != 2:
+            raise ValueError("x, y, and basin must be 2-dimensional arrays")
+        if x.shape != y.shape or x.shape != self.basin.shape:
+            raise ValueError("x, y, and basin must have the same shape")
+
+        if not isinstance(epsilon_max, Real) or epsilon_max < 0:
+            raise ValueError("epsilon_min must be a non-negative real number")
+
+        if not isinstance(n_eps, Integral) or n_eps <= 0:
+            raise ValueError("n_eps must be a positive integer")
+
+        if epsilon_min is not None:
+            if not isinstance(epsilon_min, Real) and epsilon_min < 0:
+                raise ValueError("epsilon_min must be a non-negative real number")
+        else:
+            epsilon_min = 0.0
+
+        return uncertainty_fraction(
+            x=x,
+            y=y,
+            basin=self.basin,
+            epsilon_max=epsilon_max,
+            n_eps=n_eps,
+            epsilon_min=epsilon_min,
+        )

pynamicalsys/core/continuous_dynamical_systems.py

@@ -0,0 +1,18 @@
+# continuous_dynamical_systems.py
+
+# Copyright (C) 2025 Matheus Rolim Sales
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""To be implemented: Continuous Dynamical Systems (CDS) class."""