pynamicalsys 1.2.2__py3-none-any.whl → 1.3.1__py3-none-any.whl

pynamicalsys/core/discrete_dynamical_systems.py

@@ -21,6 +21,9 @@ from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union
 
 import numpy as np
 from numpy.typing import NDArray
+import warnings
+from numba.core.errors import NumbaExperimentalFeatureWarning
+
 
 from pynamicalsys.common.recurrence_quantification_analysis import RTEConfig
 from pynamicalsys.common.utils import finite_difference_jacobian, householder_qr
@@ -28,6 +31,7 @@ from pynamicalsys.discrete_time.dynamical_indicators import (
     RTE,
     SALI,
     LDI_k,
+    GALI_k,
     dig,
     finite_time_hurst_exponent,
     finite_time_lyapunov,
@@ -36,6 +40,7 @@ from pynamicalsys.discrete_time.dynamical_indicators import (
     lagrangian_descriptors,
     lyapunov_1D,
     lyapunov_er,
+    maximum_lyapunov_er,
     lyapunov_qr,
 )
 from pynamicalsys.discrete_time.models import (
@@ -322,6 +327,8 @@ class DiscreteDynamicalSystem:
         >>> system = DynamicalSystem(mapping=my_map, jacobian=my_jacobian, system_dimension=dim)
         """
 
+        warnings.filterwarnings("ignore", category=NumbaExperimentalFeatureWarning)
+
         if model is not None and mapping is not None:
             raise ValueError("Cannot specify both model and custom mapping")
 
@@ -404,6 +411,70 @@ class DiscreteDynamicalSystem:
 
         return self.__AVAILABLE_MODELS[model]
 
+    def step(
+        self,
+        u: Union[NDArray[np.float64], Sequence[float], float],
+        parameters: Union[None, float, Sequence[float], NDArray[np.float64]] = None,
+    ) -> NDArray[np.float64]:
+        """Perform one step in the mapping evolution
+
+        Parameters
+        ----------
+        u : Union[NDArray[np.float64], Sequence[float], float]
+            Initial condition(s):
+            - Single IC: 1D array of shape (d,) where d is the system dimension
+            - Ensemble: 2D array of shape (n, d) for n initial conditions
+            - Also accepts sequence types that will be converted to numpy arrays
+            - Scalar
+        parameters : Union[NDArray[np.float64], Sequence[float], float], optional
+            Parameters of the dynamical system, shape (p,) where p is the number of parameters
+
+        Returns
+        -------
+        NDArray[np.float64]
+            The next step of the given initial condition with the same shape as `u`.
+
+        Raises
+        ------
+        ValueError
+            - If `u` is not a scalar, 1D, or 2D array, or if its shape does not match the expected system dimension.
+            - If `u` is a 1D array but its length does not match the system dimension, or if `u` is a 2D array but does not match the expected shape for an ensemble.
+            - If `parameters` is not None and does not match the expected number of parameters.
+            - If `parameters` is None but the system expects parameters.
+            - If `parameters` is a scalar or array-like but not 1D.
+
+        TypeError
+            - If `u` is not a scalar or array-like type.
+            - If `parameters` is not a scalar or array-like type.
+
+        Examples
+        --------
+        >>> from pynamicalsys import DiscreteDynamicalSystem as dds
+        >>> ds = dds(model="standard map")
+        >>> # Single initial condition
+        >>> u = [0.2, 0.5]
+        >>> ds.step(u, parameters=1.5)
+        [[0.92704802 0.72704802]]
+        >>> # Multiple initial conditions
+        >>> u = np.array([[0.2, 0.5], [0.2, 0.3], [0.2, 0.6]])
+        >>> ds.step(u, paramters=1.5)
+        array([[0.92704802, 0.72704802],
+               [0.72704802, 0.52704802],
+               [0.02704802, 0.82704802]])
+        """
+        u = validate_initial_conditions(u, self.__system_dimension, allow_ensemble=True)
+
+        parameters = validate_parameters(parameters, self.__number_of_parameters)
+
+        if u.ndim == 1:
+            u_next = self.__mapping(u, parameters)
+        else:
+            u_next = np.zeros_like(u)
+            for i in range(u_next.shape[0]):
+                u_next[i] = self.__mapping(u[i], parameters)
+
+        return u_next
+
     def trajectory(
         self,
         u: Union[NDArray[np.float64], Sequence[float], float],
@@ -2269,6 +2340,7 @@ class DiscreteDynamicalSystem:
         return_history: bool = False,
         sample_times: Optional[Union[NDArray[np.int32], Sequence[int]]] = None,
         transient_time: Optional[int] = None,
+        num_exponents: Optional[int] = None,
         log_base: float = np.e,
     ) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
         """Compute Lyapunov exponents using specified numerical method.
@@ -2290,7 +2362,9 @@ class DiscreteDynamicalSystem:
         sample_times : Optional[Union[NDArray[np.float64], Sequence[int]]], optional
             Specific times to sample when return_history=True
         transient_time : Optional[int], optional
-            Initial iterations to discard (default None → total_time//10)
+            Initial iterations to discard
+        num_exponents : Optional[int], optional
+            Number of Lyapunov exponents to compute, by default None. If None, compute the whole spectrum.
         log_base : float, optional (default np.e)
             Logarithm base for exponents (e.g. e, 2, or 10)
 
@@ -2314,13 +2388,15 @@ class DiscreteDynamicalSystem:
             - If `transient_time` is greater than or equal to total_time.
             - If `method` is not "QR" or "QR_HH".
             - If `sample_times` is not a 1D array of integers.
-            - If `log_base` is not positive
+            - If `log_base` is not positive.
+            - If `num_exponents` is larger then the system's dimension.
         TypeError
             - If `u` is not a scalar or array-like type.
             - If `parameters` is not a scalar or array-like type.
             - If `total_time` is not int.
             - If `transient_time` is not int.
             - If `log_base` is not float.
+            - If `num_exponents` is not an positive integer.
             - If sample_times cannot be converted to a 1D array of integers.
             - If `method` is not a string.
 
@@ -2376,7 +2452,19 @@ class DiscreteDynamicalSystem:
         if method == "QR" and self.__system_dimension == 2:
             method = "ER"  # Fallback to QR for higher dimensions
 
-        sample_times = validate_sample_times(sample_times, total_time)
+        if return_history and sample_times is not None:
+            sample_times = validate_sample_times(sample_times, total_time)
+        else:
+            sample_times = np.arange(
+                1, total_time - (transient_time or 0) + 1, dtype=np.int64
+            )
+
+        if num_exponents is None:
+            num_exponents = self.__system_dimension
+        elif num_exponents > self.__system_dimension:
+            raise ValueError("num_exponents must be <= system_dimension")
+        else:
+            validate_non_negative(num_exponents, "num_exponents", Integral)
 
         validate_non_negative(log_base, "log_base", Real)
         if log_base == 1:
@@ -2387,30 +2475,38 @@ class DiscreteDynamicalSystem:
             compute_func = lyapunov_1D
         else:
             if method == "ER":
-                compute_func = lyapunov_er
+                if num_exponents == 1:
+                    compute_func = maximum_lyapunov_er
+                else:
+                    compute_func = lyapunov_er
             elif method == "QR":
                 compute_func = lyapunov_qr
             else:  # QR_HH
                 compute_func = lambda *args, **kwargs: lyapunov_qr(
                     *args, QR=householder_qr, **kwargs
                 )
-
         result = compute_func(
             u,
             parameters,
             total_time,
             self.__mapping,
             self.__jacobian,
+            num_exponents,
+            sample_times,
             return_history=return_history,
-            sample_times=sample_times,
             transient_time=transient_time,
             log_base=log_base,
         )
 
         if return_history:
-            return result[0]
+            return result if self.__system_dimension == 1 else result[0]
         else:
-            return result[0][:, 0] if self.__system_dimension > 1 else result[0]
+            if self.__system_dimension == 1:
+                return result[0]
+            elif self.__system_dimension > 1 and num_exponents > 1:
+                return result[0][:, 0]
+            else:
+                return result[0][0]
 
     def finite_time_lyapunov(
         self,
@@ -2420,6 +2516,7 @@ class DiscreteDynamicalSystem:
         parameters: Union[
             None, float, Sequence[np.float64], NDArray[np.float64]
         ] = None,
+        num_exponents: Optional[int] = None,
         method: str = "QR",
         transient_time: Optional[int] = None,
         log_base: float = np.e,
@@ -2519,6 +2616,11 @@ class DiscreteDynamicalSystem:
         if method not in ("QR", "QR_HH"):
             raise ValueError("method must be 'QR' or 'QR_HH'")
 
+        if num_exponents is None:
+            num_exponents = self.__system_dimension
+        elif num_exponents > self.__system_dimension:
+            raise ValueError("num_exponents must be <= system_dimension")
+
         # Validate method for system dimension
         if method == "QR" and self.__system_dimension == 2:
             method = "ER"  # Fallback to QR for higher dimensions
@@ -2537,6 +2639,7 @@ class DiscreteDynamicalSystem:
             finite_time,
             self.__mapping,
             self.__jacobian,
+            num_exponents,
             method=method,
             transient_time=transient_time,
             log_base=log_base,
@@ -2819,7 +2922,12 @@ class DiscreteDynamicalSystem:
         validate_non_negative(total_time, "total_time", Integral)
         validate_transient_time(transient_time, total_time, Integral)
 
-        sample_times = validate_sample_times(sample_times, total_time)
+        if return_history and sample_times is not None:
+            sample_times = validate_sample_times(sample_times, total_time)
+        else:
+            sample_times = np.arange(
+                1, total_time - (transient_time or 0) + 1, dtype=np.int64
+            )
 
         validate_non_negative(tol, "tol", Real)
 
@@ -2832,8 +2940,8 @@ class DiscreteDynamicalSystem:
             total_time,
             self.__mapping,
             self.__jacobian,
+            sample_times,
             return_history=return_history,
-            sample_times=sample_times,
             transient_time=transient_time,
             tol=tol,
             seed=seed,
@@ -2855,7 +2963,7 @@ class DiscreteDynamicalSystem:
         transient_time: Optional[int] = None,
         seed: int = 13,
     ) -> Union[NDArray[np.float64], Tuple[NDArray[np.float64], NDArray[np.float64]]]:
-        """Compute Linear Dependence Index(LDI_k) for chaos detection.
+        """Compute the Linear Dependence Index (LDI_k) for chaos detection.
 
         Parameters
         ----------
@@ -2882,7 +2990,7 @@ class DiscreteDynamicalSystem:
         -------
         Union[NDArray[np.float64], Tuple[NDArray[np.float64], NDArray[np.float64]]]
             - If return_history = False: Final LDI_k value(scalar)
-            - If return_history = True: Tuple of(LDI_history, final_state) where LDI_history is 1D array of values
+            - If return_history = True: Tuple of (LDI_history, final_state) where LDI_history is 1D array of values
 
         Raises
         ------
@@ -2912,7 +3020,7 @@ class DiscreteDynamicalSystem:
         - LDI_k behavior:
         - → 0 exponentially for chaotic orbits(rate depends on k)
         - → positive constant for regular orbits
-        - LDI_2 ~ SALI(same convergence rate)
+        - LDI_2 ~ SALI (same convergence rate)
         - Higher k indices decay faster for chaotic orbits
         - For Hamiltonian systems, k should be ≤ d/2
         - Early termination when LDI_k < tol
@@ -2947,7 +3055,12 @@ class DiscreteDynamicalSystem:
         if k < 2 or k > self.__system_dimension:
             raise ValueError(f"k must be in range [2, {self.__system_dimension}]")
 
-        sample_times = validate_sample_times(sample_times, total_time)
+        if return_history and sample_times is not None:
+            sample_times = validate_sample_times(sample_times, total_time)
+        else:
+            sample_times = np.arange(
+                1, total_time - (transient_time or 0) + 1, dtype=np.int64
+            )
 
         validate_non_negative(tol, "tol", Real)
 
@@ -2961,9 +3074,144 @@ class DiscreteDynamicalSystem:
             total_time,
             self.__mapping,
             self.__jacobian,
-            k=k,
+            k,
+            sample_times,
+            return_history=return_history,
+            transient_time=transient_time,
+            tol=tol,
+            seed=seed,
+        )
+
+        return result if return_history else result[0]
+
+    def GALI(
+        self,
+        u: Union[NDArray[np.float64], Sequence[float]],
+        total_time: int,
+        k: int,
+        parameters: Union[
+            None, float, Sequence[np.float64], NDArray[np.float64]
+        ] = None,
+        return_history: bool = False,
+        sample_times: Optional[Union[NDArray[np.int32], Sequence[int]]] = None,
+        tol: float = 1e-16,
+        transient_time: Optional[int] = None,
+        seed: int = 13,
+    ) -> Union[NDArray[np.float64], Tuple[NDArray[np.float64], NDArray[np.float64]]]:
+        """Compute the Generalized Aligment Index (GALI_k) for chaos detection.
+
+        Parameters
+        ----------
+        u: Union[NDArray[np.float64], Sequence[float]]
+            Initial condition of shape(d,) where d is system dimension
+        total_time: int
+            Maximum number of iterations(must be ≥ 1)
+        k: int
+            Number of deviation vectors to use(2 ≤ k ≤ d, default 2)
+        parameters: Union[None, float, Sequence[np.float64], NDArray[np.float64]], optional
+            System parameters of shape(p,) passed to mapping function
+        return_history: bool, optional
+            If True, returns full evolution(default False)
+        sample_times: Optional[Union[NDArray[np.float64], Sequence[int]]], optional
+            Specific times to sample(must be sorted, default None)
+        tol: float, optional
+            Early termination threshold(default 1e-16)
+        transient_time: Optional[int], optional
+            Initial iterations to discard(default None → total_time//10)
+        seed: int, optional
+            Random seed for reproducibility(default 13)
+
+        Returns
+        -------
+        Union[NDArray[np.float64], Tuple[NDArray[np.float64], NDArray[np.float64]]]
+            - If return_history = False: Final GALI_k value(scalar)
+            - If return_history = True: Tuple of (GALI_history, final_state) where GALI_history is 1D array of values
+
+        Raises
+        ------
+        ValueError
+            - If `u` is not an 1D array, or if its shape does not match the expected system dimension.
+            - If `parameters` is not None and does not match the expected number of parameters.
+            - If `parameters` is None but the system expects parameters.
+            - If `parameters` is a scalar or array-like but not 1D.
+            - If `total_time` is negative.
+            - If `trasient_time` is negative.
+            - If `transient_time` is greater than or equal to total_time.
+            - If `sample_times` is not a 1D array of integers.
+            - If `k` is less than 2 or greater than system dimension.
+
+        TypeError
+            - If `u` is not a scalar or array-like type.
+            - If `parameters` is not a scalar or array-like type.
+            - If `total_time` is not int.
+            - If `transient_time` is not int.
+            - If sample_times cannot be converted to a 1D array of integers.
+            - If `tol` is not a positive float.
+            - If `seed` is not an integer.
+            - If `k` is not a positive integer.
+
+        Notes
+        -----
+        - GALI_k behavior:
+        - → 0 exponentially for chaotic orbits(rate depends on k)
+        - → positive constant for regular orbits
+        - GALI_2 ~ SALI (same convergence rate)
+        - Higher k indices decay faster for chaotic orbits
+        - For Hamiltonian systems, k should be ≤ d/2
+        - Early termination when GALI_k < tol
+
+        Examples
+        --------
+        >>>  # Basic usage (LDI_2 final value)
+        >>> u0 = np.array([0.1, 0.2, 0.0, 0.0])
+        >>> params = np.array([0.5, 1.0])
+        >>> LDI = system.LDI(u0, params, 10000, k=2)
+
+        >>>  # LDI_3 with full history
+        >>> LDI_hist, final = system.LDI(
+        ...     u0, params, 10000, k=3, return_history=True)
+
+        >>>  # With custom sampling
+        >>> times = np.array([100, 1000, 5000])
+        >>> LDI_samples, _ = system.LDI(
+        ...     u0, params, 10000, k=2, sample_times=times, return_history=True)
+        """
+
+        u = validate_initial_conditions(
+            u, self.__system_dimension, allow_ensemble=False
+        )
+
+        parameters = validate_parameters(parameters, self.__number_of_parameters)
+
+        validate_non_negative(total_time, "total_time", Integral)
+        validate_transient_time(transient_time, total_time, Integral)
+
+        validate_positive(k, "k", Integral)
+        if k < 2 or k > self.__system_dimension:
+            raise ValueError(f"k must be in range [2, {self.__system_dimension}]")
+
+        if return_history and sample_times is not None:
+            sample_times = validate_sample_times(sample_times, total_time)
+        else:
+            sample_times = np.arange(
+                1, total_time - (transient_time or 0) + 1, dtype=np.int64
+            )
+
+        validate_non_negative(tol, "tol", Real)
+
+        if not isinstance(seed, Integral):
+            raise TypeError("seed must be an integer")
+
+        # Call underlying implementation
+        result = GALI_k(
+            u,
+            parameters,
+            total_time,
+            self.__mapping,
+            self.__jacobian,
+            k,
+            sample_times,
             return_history=return_history,
-            sample_times=sample_times,
             transient_time=transient_time,
             tol=tol,
             seed=seed,