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

pynamicalsys/core/continuous_dynamical_systems.py

@@ -25,6 +25,7 @@ from pynamicalsys.common.utils import householder_qr, qr
 from pynamicalsys.continuous_time.chaotic_indicators import (
     LDI,
     SALI,
+    GALI,
     lyapunov_exponents,
 )
 from pynamicalsys.continuous_time.models import (
@@ -56,6 +57,47 @@ from pynamicalsys.continuous_time.validators import (
 
 
 class ContinuousDynamicalSystem:
+    """Class representing a continuous-time dynamical system with various models and methods for analysis.
+
+    This class allows users to work with predefined dynamical models or with user-provided equations of motion, compute trajectories, Lyapunov exponents and more dynamical analyses.
+
+    Parameters
+    ----------
+    model : str, optional
+        Name of the predefined model to use (e.g. "lorenz system").
+    equations_of_motion : callable, optional
+        Custom function that describes the equations of motion with signature f(time, state, parameters) -> array_like. If provided, `model` must be None.
+    jacobian : callable, optional
+        Custom function that describes the Jacobian matrix of the system with signature J(time, state, parameters) -> array_like
+    system_dimension : int, optional
+        Dimension of the system (number of equations). Required if using custom equations of motion and not a predefined model.
+    number_of_parameters : int, optional
+        Number of parameters of the system. Required if using custom equations of motion and not a predefined model.
+
+    Raises
+    ------
+    ValueError
+        - If neither model nor equations_of_motion is provided, or if provided model is not implemented.
+        - If `system_dimension` is negative.
+        - If `number_of_parameters` is negative.
+
+    TypeError
+        - If `equations_of_motion` or `jacobian` are not callable.
+        - If `system_dimension` or `number_of_parameters` are not valid integers.
+
+    Notes
+    -----
+    - When providing custom functions, either provide both `equations_of_motion` and `jacobian`, or just the `equations_of_motion`.
+    - When providing custom functions, the equations of motion functions signature should be f(time, u, parameters) -> NDArray[np.float64].
+    - The class supports various predefined models, such as the Lorenz and Rössler system.
+    - The available models can be queried using the 'available_models' class method.
+
+    Examples
+    --------
+    >>> from pynamicalsys import ContinuousDynamicalSystem as cds
+    >>> #  Using predefined model
+    >>> ds = cds(model="lorenz system")
+    """
 
     __AVAILABLE_MODELS: Dict[str, Dict[str, Any]] = {
         "lorenz system": {
@@ -203,13 +245,13 @@ class ContinuousDynamicalSystem:
 
     @property
     def integrator_info(self):
-        """Return the information about the current integrator"""
+        """Return a dictionary with information about the current integrator."""
         integrator = self.__integrator.lower()
 
         return self.__AVAILABLE_INTEGRATORS[integrator]
 
     def integrator(self, integrator, time_step=1e-2, atol=1e-6, rtol=1e-3):
-        """Set the integrator to use in the simulation.
+        """Define the integrator.
 
         Parameters
         ----------
@@ -228,8 +270,8 @@ class ContinuousDynamicalSystem:
             If `time_step`, `atol`, or `rtol` are negative.
             If `integrator` is not available.
         TypeError
-            If `time_step`, `atol`, or `rtol` are not valid numbers.
-            If `integrator` is not a string.
+            - If `integrator` is not a string.
+            - If `time_step`, `atol`, or `rtol` are not valid numbers
 
         Examples
         --------
@@ -240,6 +282,9 @@ class ContinuousDynamicalSystem:
         >>> ds.integrator("rk4", time_step=0.001) #  To use the RK4 integrator
         >>> ds.integrator("rk45", atol=1e-10, rtol=1e-8) #  To use the RK45 integrator
         """
+
+        if not isinstance(integrator, str):
+            raise ValueError("integrator must be a string.")
         validate_non_negative(time_step, "time_step", type_=Real)
         validate_non_negative(atol, "atol", type_=Real)
         validate_non_negative(rtol, "rtol", type_=Real)
@@ -441,6 +486,7 @@ class ContinuousDynamicalSystem:
         total_time: float,
         parameters: Union[None, Sequence[float], NDArray[np.float64]] = None,
         transient_time: Optional[float] = None,
+        num_exponents: Optional[int] = None,
         return_history: bool = False,
         seed: int = 13,
         log_base: float = np.e,
@@ -461,6 +507,8 @@ class ContinuousDynamicalSystem:
             Parameters of the system, by default None. Can be a scalar, a sequence of floats or a numpy array.
         transient_time : Optional[float], optional
             Transient time, i.e., the time to discard before calculating the Lyapunov exponents, by default None.
+        num_exponents : Optional[int], optional
+            The number of Lyapunov exponents to be calculated, by default None. If None, the method calculates the whole spectrum.
         return_history : bool, optional
             Whether to return or not the Lyapunov exponents history in time, by default False.
         seed : int, optional
@@ -491,6 +539,7 @@ class ContinuousDynamicalSystem:
         TypeError
             - If `method` is not a string.
             - If `total_time`, `transient_time`, or `log_base` are not valid numbers.
+            - If `num_exponents` is not an positive integer.
             - If `seed` is not an integer.
 
         Notes
@@ -502,13 +551,15 @@ class ContinuousDynamicalSystem:
         >>> from pynamicalsys import ContinuousDynamicalSystem as cds
         >>> ds = cds(model="lorenz system")
         >>> u = [0.1, 0.1, 0.1]
-        >>> total_time = 1000
-        >>> transient_time = 500
+        >>> total_time = 10000
+        >>> transient_time = 5000
         >>> parameters = [16.0, 45.92, 4.0]
-        >>> ds.lyapunov(u, total_time, parameters=parameters, transient_time=transient_time, log_base=2)
-        array([ 2.15920769e+00, -4.61882314e-03, -3.24498622e+01])
+        >>> ds.lyapunov(u, total_time, parameters=parameters, transient_time=transient_time)
+        array([ 1.49885208e+00, -1.65186396e-04, -2.24977688e+01])
+        >>> ds.lyapunov(u, total_time, parameters=parameters, transient_time=transient_time, num_exponents=2)
+        array([1.49873694e+00, 1.31950729e-04])
         >>> ds.lyapunov(u, total_time, parameters=parameters, transient_time=transient_time, log_base=2, method="QR_HH")
-        array([ 2.15920769e+00, -4.61882314e-03, -3.24498622e+01])
+        array([ 2.16664847e+00, -6.80920729e-04, -3.24625604e+01])
         """
 
         if self.__jacobian is None:
@@ -527,6 +578,13 @@ class ContinuousDynamicalSystem:
 
         time_step = self.__get_initial_time_step(u, parameters)
 
+        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)
+
         if endpoint:
             total_time += time_step
 
@@ -551,6 +609,7 @@ class ContinuousDynamicalSystem:
             total_time,
             self.__equations_of_motion,
             self.__jacobian,
+            num_exponents,
             transient_time=transient_time,
             time_step=time_step,
             atol=self.__atol,
@@ -717,7 +776,6 @@ class ContinuousDynamicalSystem:
 
             - If `return_history = False`, return time and LDI, where time is the time at the end of the execution. time < total_time if LDI becomes less than `threshold` before `total_time`.
             - If `return_history = True`, return the sampled times and the LDI values.
-            - If `sample_times` is provided, return the LDI at the specified times.
 
         Raises
         ------
@@ -741,7 +799,7 @@ class ContinuousDynamicalSystem:
         >>> transient_time = 500
         >>> parameters = [16.0, 45.92, 4.0]
         >>> ds.LDI(u, total_time, 2, parameters=parameters, transient_time=transient_time)
-        (521.8099999999802, 7.328757804386809e-17)
+        array([5.23170000e+02, 6.93495605e-17])
         >>> ds.LDI(u, total_time, 3, parameters=parameters, transient_time=transient_time)
         (501.26999999999884, 9.984145370766051e-17)
         >>> # Returning the history
@@ -792,3 +850,118 @@ class ContinuousDynamicalSystem:
             return np.array(result)
         else:
             return np.array(result[0])
+
+    def GALI(
+        self,
+        u: NDArray[np.float64],
+        total_time: float,
+        k: int,
+        parameters: Union[None, Sequence[float], NDArray[np.float64]] = None,
+        transient_time: Optional[float] = None,
+        return_history: bool = False,
+        seed: int = 13,
+        threshold: float = 1e-16,
+        endpoint: bool = True,
+    ) -> NDArray[np.float64]:
+        """Calculate the Generalized Aligment Index (GALI) for a given dynamical system.
+
+        Parameters
+        ----------
+        u : NDArray[np.float64]
+            Initial conditions of the system. Must match the system's dimension.
+        total_time : float
+            Total time over which to evolve the system (including transient).
+        parameters : Union[None, Sequence[float], NDArray[np.float64]], optional
+            Parameters of the system, by default None. Can be a scalar, a sequence of floats or a numpy array.
+        transient_time : Optional[float], optional
+            Transient time, i.e., the time to discard before calculating the Lyapunov exponents, by default None.
+        return_history : bool, optional
+            Whether to return or not the Lyapunov exponents history in time, by default False.
+        seed : int, optional
+            The seed to randomly generate the deviation vectors, by default 13.
+        threshold : float, optional
+            The threhshold for early termination, by default 1e-16. When SALI becomes less than `threshold`, stops the execution.
+        endpoint : bool, optional
+            Whether to include the endpoint time = total_time in the calculation, by default True.
+
+        Returns
+        -------
+        NDArray[np.float64]
+            The GALI value
+
+            - If `return_history = False`, return time and GALI, where time is the time at the end of the execution. time < total_time if GALI becomes less than `threshold` before `total_time`.
+            - If `return_history = True`, return the sampled times and the GALI values.
+
+        Raises
+        ------
+        ValueError
+            - If the Jacobian function is not provided.
+            - If the initial condition is not valid, i.e., if the dimensions do not match.
+            - If the number of parameters does not match.
+            - If `parameters` is not a scalar, 1D list, or 1D array.
+            - If `total_time`, `transient_time`, or `threshold` are negative.
+            - If `k` < 2.
+        TypeError
+            - If `total_time`, `transient_time`, or `threshold` are not valid numbers.
+            - If `seed` is not an integer.
+
+        Examples
+        --------
+        >>> from pynamicalsys import ContinuousDynamicalSystem as cds
+        >>> ds = cds(model="lorenz system")
+        >>> u = [0.1, 0.1, 0.1]
+        >>> total_time = 1000
+        >>> transient_time = 500
+        >>> parameters = [16.0, 45.92, 4.0]
+        >>> ds.GALI(u, total_time, 2, parameters=parameters, transient_time=transient_time)
+        (521.8099999999802, 7.328757804386809e-17)
+        >>> ds.GALI(u, total_time, 3, parameters=parameters, transient_time=transient_time)
+        (501.26999999999884, 9.984145370766051e-17)
+        >>> # Returning the history
+        >>> gali = ds.GALI(u, total_time, 2, parameters=parameters, transient_time=transient_time)
+        >>> gali.shape
+        (2181, 2)
+        """
+
+        if self.__jacobian is None:
+            raise ValueError(
+                "Jacobian function is required to compute Lyapunov exponents"
+            )
+
+        u = validate_initial_conditions(
+            u, self.__system_dimension, allow_ensemble=False
+        )
+        u = u.copy()
+
+        parameters = validate_parameters(parameters, self.__number_of_parameters)
+
+        transient_time, total_time = validate_times(transient_time, total_time)
+
+        time_step = self.__get_initial_time_step(u, parameters)
+
+        validate_non_negative(threshold, "threshold", type_=Real)
+
+        if endpoint:
+            total_time += time_step
+
+        result = GALI(
+            u,
+            parameters,
+            total_time,
+            self.__equations_of_motion,
+            self.__jacobian,
+            k,
+            transient_time=transient_time,
+            time_step=time_step,
+            atol=self.__atol,
+            rtol=self.__rtol,
+            integrator=self.__integrator_func,
+            return_history=return_history,
+            seed=seed,
+            threshold=threshold,
+        )
+
+        if return_history:
+            return np.array(result)
+        else:
+            return np.array(result[0])