pynamicalsys 1.2.2__tar.gz → 1.3.0__tar.gz

{pynamicalsys-1.2.2 → pynamicalsys-1.3.0}/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v1.3.0] 2025-08-23
+
+### Added
+
+- `DiscreteDynamicalSystem` class:
+  - `step` method: returns the next state of the system.
+  - `GALI` method: computes the generalized alignment index (GALI).
+
+- `ContinuousDynamicalSystem` class:
+    - `GALI` method that computes the generalized alignment index (GALI).
+
+### Modified
+
+- `DiscreteDynamicalSystem` class:
+    - Improved performance when checking sampling points by avoiding repeated searches in sample_times.
+    - Refactored the `lyapunov` method to allow computing only a subset of the Lyapunov spectrum.
+
+- `ContinuousDynamicalSystem` class:
+    - Unified integration step logic (previously duplicated across methods like trajectory and lyapunov_exponents) into a single step function.
+    - Refactored the `lyapunov` method to allow computing only a subset of the Lyapunov spectrum.
+
+[v1.3.0]: https://github.com/mrolims/pynamicalsys/compare/v1.2.2...v1.3.0
+
 ## [v1.2.2] - 2025-06-29
 
 ### Added
@@ -16,11 +39,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Lyapunov exponents calculation.
   - The smallest aligment index (SALI) and linear dependence index (LDI) for chaos detection.
 
-## [v1.0.0] - 2025-06-16
+[v1.2.2]: https://github.com/mrolims/pynamicalsys/compare/v1.0.0...v1.2.2
+
+## v1.0.0 - 2025-06-16
 
 ### Added
 
-- `DiscreteDynamicalSystems` class for simulating and analyzing discrete nonlinear dynamical systems:
+- `DiscreteDynamicalSystem` class for simulating and analyzing discrete nonlinear dynamical systems:
   - Trajectory computation.
   - Chaotic indicators.
   - Fixed points, periodic orbits, and manifolds.
@@ -36,8 +61,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `PlotStyler` utility class to globally configure and apply consistent styling for Matplotlib plots.
 
----
-
 <!-- Dummy heading to avoid ending on a transition -->
 
 ##

pynamicalsys-1.3.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to pynamicalsys
+
+We appreciate your interest in contributing to pynamicalsys! Whether you're fixing a bug, suggesting an improvement, or adding a new feature, your help is welcome.
+
+## How to Contribute
+
+1. **Fork the Repository**  
+   Create a personal copy of this repository.
+
+2. **Create a Feature Branch**  
+   Use a descriptive branch name:
+
+   ```bash
+   $ git checkout -b fix-typo-in-readme
+   ```
+
+3. **Make Changes**
+
+   Follow the coding style and ensure existing functionality it not broken. Add tests if relevant.
+
+4. **Submit a Pull Request**
+
+   Push your branch and open a pull request on GitHub. Include a clear description of your changes.
+
+5. **Wait for Review**
+
+   We'll review your PR and may request changes or offer suggestions.
+
+## Coding Style
+
+- Follow **PEP8** standards for Pycode code.
+- Use **docstrings** (PEP257) for public classes, functions, and modules.
+- Include **type hints** where appropriate.
+- Keep commits clean and descriptive.
+
+## Bug Reports & Feature Requests
+
+- Submit an [issue](https://github.com/mrolims/pynamicalsys/issues) to report bugs or suggest new features.
+- Include steps to reproduce, error messages, or use cases when possible.
+
+## Code of Conduct
+
+We strive to maintain a respectful and inclusive community. Please follow our [code of conduct](https://pynamicalsys.readthedocs.io/en/latest/) when interacting.
+
+## Thank You
+
+Your contributions help improve the project and support the community — thank you!

{pynamicalsys-1.2.2 → pynamicalsys-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pynamicalsys
-Version: 1.2.2
+Version: 1.3.0
 Summary: A Python toolkit for the analysis of dynamical systems
 Author-email: Matheus Rolim Sales <rolim.sales.m@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -733,7 +733,7 @@ $ pip install pynamicalsys
 To upgrade your current version of **pynamicalsys** to the latest stable release, run in your command line:
 
 ```bash
-$ pip install **pynamicalsys** --upgrade
+$ pip install pynamicalsys --upgrade
 ```
 
 ### Install from source
@@ -781,7 +781,7 @@ Currently, our research paper is under review, but in the mean time, if you use
 
 ## Contributing
 
-We welcome contributions from the community! To get started, please see our Contributing Guidelines.
+We welcome contributions from the community! To get started, please see our [Contributing Guidelines](https://pynamicalsys.readthedocs.io/en/latest/contributing.html).
 
 ## License
 

{pynamicalsys-1.2.2 → pynamicalsys-1.3.0}/README.md

@@ -40,7 +40,7 @@ $ pip install pynamicalsys
 To upgrade your current version of **pynamicalsys** to the latest stable release, run in your command line:
 
 ```bash
-$ pip install **pynamicalsys** --upgrade
+$ pip install pynamicalsys --upgrade
 ```
 
 ### Install from source
@@ -88,7 +88,7 @@ Currently, our research paper is under review, but in the mean time, if you use
 
 ## Contributing
 
-We welcome contributions from the community! To get started, please see our Contributing Guidelines.
+We welcome contributions from the community! To get started, please see our [Contributing Guidelines](https://pynamicalsys.readthedocs.io/en/latest/contributing.html).
 
 ## License
 

{pynamicalsys-1.2.2 → pynamicalsys-1.3.0}/src/pynamicalsys/__version__.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '1.2.2'
-__version_tuple__ = version_tuple = (1, 2, 2)
+__version__ = version = '1.3.0'
+__version_tuple__ = version_tuple = (1, 3, 0)
+
+__commit_id__ = commit_id = 'g138b5d22a'

{pynamicalsys-1.2.2 → pynamicalsys-1.3.0}/src/pynamicalsys/common/utils.py

@@ -257,7 +257,7 @@ def finite_difference_jacobian(
 
 
 @njit
-def wedge_product_norm(vectors: NDArray[np.float64]) -> float:
+def wedge_norm_2(vectors: NDArray[np.float64]) -> float:
     """
     Computes the norm of the wedge product of n m-dimensional vectors using the Gram determinant.
 
@@ -295,6 +295,25 @@ def wedge_product_norm(vectors: NDArray[np.float64]) -> float:
     return norm
 
 
+def wedge_norm(V: NDArray[np.float64]) -> float:
+    """
+    Computes the norm of the wedge product of k d-dimensional vectors using the Gram determinant.
+
+    Parameters:
+    vectors : NDArray[np.float64]
+        A (d, k) array where d is the dimension and k is the number of vectors.
+
+    Returns:
+    norm : float
+        The norm (magnitude) of the wedge product.
+    """
+    G = V.T @ V  # Gram matrix, shape (k, k)
+
+    det = np.linalg.det(G)
+
+    return 0 if det < 0 else np.sqrt(det)
+
+
 @njit
 def _coeff_mat(x: NDArray[np.float64], deg: int) -> NDArray[np.float64]:
     mat_ = np.zeros(shape=(x.shape[0], deg + 1))
@@ -322,23 +341,3 @@ def fit_poly(
     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-1.2.2 → pynamicalsys-1.3.0}/src/pynamicalsys/continuous_time/chaotic_indicators.py

@@ -18,14 +18,14 @@
 from typing import Optional, Callable, Union, Tuple, Dict, List, Any, Sequence
 from numpy.typing import NDArray
 import numpy as np
-from numba import njit, prange
+from numba import njit
 
-from pynamicalsys.common.utils import qr
-from pynamicalsys.continuous_time.trajectory_analysis import evolve_system
+from pynamicalsys.common.utils import qr, wedge_norm
+from pynamicalsys.continuous_time.trajectory_analysis import step, evolve_system
 from pynamicalsys.continuous_time.numerical_integrators import rk4_step_wrapped
 
 
-@njit(cache=True)
+# @njit(cache=True)
 def lyapunov_exponents(
     u: NDArray[np.float64],
     parameters: NDArray[np.float64],
@@ -36,6 +36,7 @@ def lyapunov_exponents(
     jacobian: Callable[
         [np.float64, NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]
     ],
+    num_exponents: int,
     transient_time: Optional[float] = None,
     time_step: float = 0.01,
     atol: float = 1e-6,
@@ -50,7 +51,7 @@ def lyapunov_exponents(
 ) -> NDArray[np.float64]:
 
     neq = len(u)  # Number of equations of the system
-    nt = neq + neq**2  # Total number of equations including variational equations
+    nt = neq + neq * num_exponents  # system + variational equations
 
     u = u.copy()
 
@@ -79,57 +80,55 @@ def lyapunov_exponents(
     # Randomly define the deviation vectors and orthonormalize them
     np.random.seed(seed)
     uv[neq:] = -1 + 2 * np.random.rand(nt - neq)
-    v = uv[neq:].reshape(neq, neq)
+    v = uv[neq:].reshape(neq, num_exponents)
     v, _ = QR(v)
-    uv[neq:] = v.reshape(neq**2)
+    uv[neq:] = v.reshape(neq * num_exponents)
 
-    exponents = np.zeros(neq, dtype=np.float64)
+    exponents = np.zeros(num_exponents, dtype=np.float64)
     history = []
 
     while time < total_time:
         if time + time_step > total_time:
             time_step = total_time - time
 
-        uv_new, time_new, time_step_new, accept = integrator(
+        uv, time, time_step = step(
             time,
             uv,
             parameters,
             equations_of_motion,
             jacobian=jacobian,
             time_step=time_step,
+            atol=atol,
+            rtol=rtol,
+            integrator=integrator,
+            number_of_deviation_vectors=num_exponents,
         )
 
-        if accept:
-            time = time_new
-            uv = uv_new.copy()
-            #  Reshape the deviation vectors into a neq x neq matrix
-            v = uv[neq:].reshape(neq, neq).copy()
-
-            # Perform the QR decomposition
-            v, R = QR(v)
-
-            # Accumulate the log
-            exponents += np.log(np.abs(np.diag(R))) / np.log(log_base)
+        #  Reshape the deviation vectors into a neq x neq matrix
+        v = uv[neq:].reshape(neq, num_exponents).copy()
 
-            if return_history:
-                result = [time]
-                for i in range(neq):
-                    result.append(
-                        exponents[i]
-                        / (time - (transient_time if transient_time is not None else 0))
-                    )
-                history.append(result)
+        # Perform the QR decomposition
+        v, R = QR(v)
+        # Accumulate the log
+        exponents += np.log(np.abs(np.diag(R))) / np.log(log_base)
 
-            # Reshape v back to uv
-            uv[neq:] = v.reshape(neq**2)
+        if return_history:
+            result = [time]
+            for i in range(num_exponents):
+                result.append(
+                    exponents[i]
+                    / (time - (transient_time if transient_time is not None else 0))
+                )
+            history.append(result)
 
-        time_step = time_step_new
+        # Reshape v back to uv
+        uv[neq:] = v.reshape(neq * num_exponents)
 
     if return_history:
         return history
     else:
         result = []
-        for i in range(neq):
+        for i in range(num_exponents):
             result.append(
                 exponents[i]
                 / (time - (transient_time if transient_time is not None else 0))
@@ -197,44 +196,41 @@ def SALI(
         if time + time_step > total_time:
             time_step = total_time - time
 
-        uv_new, time_new, time_step_new, accept = integrator(
+        uv, time, time_step = step(
             time,
             uv,
             parameters,
             equations_of_motion,
             jacobian=jacobian,
             time_step=time_step,
+            atol=atol,
+            rtol=rtol,
+            integrator=integrator,
             number_of_deviation_vectors=ndv,
         )
 
-        if accept:
-            time = time_new
-            uv = uv_new.copy()
+        # Reshape the deviation vectors into a neq x ndv matrix
+        v = uv[neq:].reshape(neq, ndv)
 
-            # Reshape the deviation vectors into a neq x ndv matrix
-            v = uv[neq:].reshape(neq, ndv)
+        # Normalize the deviation vectors
+        v[:, 0] /= np.linalg.norm(v[:, 0])
+        v[:, 1] /= np.linalg.norm(v[:, 1])
 
-            # Normalize the deviation vectors
-            v[:, 0] /= np.linalg.norm(v[:, 0])
-            v[:, 1] /= np.linalg.norm(v[:, 1])
+        # Calculate the aligment indexes and SALI
+        PAI = np.linalg.norm(v[:, 0] + v[:, 1])
+        AAI = np.linalg.norm(v[:, 0] - v[:, 1])
+        sali = min(PAI, AAI)
 
-            # Calculate the aligment indexes and SALI
-            PAI = np.linalg.norm(v[:, 0] + v[:, 1])
-            AAI = np.linalg.norm(v[:, 0] - v[:, 1])
-            sali = min(PAI, AAI)
+        if return_history:
+            result = [time, sali]
+            history.append(result)
 
-            if return_history:
-                result = [time, sali]
-                history.append(result)
+        # Early termination
+        if sali <= threshold:
+            break
 
-            # Early termination
-            if sali <= threshold:
-                break
-
-            # Reshape v back to uv
-            uv[neq:] = v.reshape(neq * ndv)
-
-        time_step = time_step_new
+        # Reshape v back to uv
+        uv[neq:] = v.reshape(neq * ndv)
 
     if return_history:
         return history
@@ -303,45 +299,145 @@ def LDI(
         if time + time_step > total_time:
             time_step = total_time - time
 
-        uv_new, time_new, time_step_new, accept = integrator(
+        uv, time, time_step = step(
             time,
             uv,
             parameters,
             equations_of_motion,
             jacobian=jacobian,
             time_step=time_step,
+            atol=atol,
+            rtol=rtol,
+            integrator=integrator,
             number_of_deviation_vectors=ndv,
         )
 
-        if accept:
-            time = time_new
-            uv = uv_new.copy()
+        # Reshape the deviation vectors into a neq x ndv matrix
+        v = uv[neq:].reshape(neq, ndv)
 
-            # Reshape the deviation vectors into a neq x ndv matrix
-            v = uv[neq:].reshape(neq, ndv)
+        # Normalize the deviation vectors
+        for i in range(ndv):
+            v[:, i] /= np.linalg.norm(v[:, i])
 
-            # Normalize the deviation vectors
-            for i in range(ndv):
-                v[:, i] /= np.linalg.norm(v[:, i])
+        # Calculate the singular values
+        S = np.linalg.svd(v, full_matrices=False, compute_uv=False)
+        ldi = np.exp(np.sum(np.log(S)))  # LDI is the product of all singular values
+        # Instead of computing prod(S) directly, which could lead to underflows
+        # or overflows, we compute the sum_{i=1}^k log(S_i) and then take the
+        # exponential of this sum.
 
-            # Calculate the singular values
-            S = np.linalg.svd(v, full_matrices=False, compute_uv=False)
-            ldi = np.prod(S)
+        if return_history:
+            result = [time, ldi]
+            history.append(result)
 
-            if return_history:
-                result = [time, ldi]
-                history.append(result)
+        # Early termination
+        if ldi <= threshold:
+            break
 
-            # Early termination
-            if ldi <= threshold:
-                break
+        # Reshape v back to uv
+        uv[neq:] = v.reshape(neq * ndv)
 
-            # Reshape v back to uv
-            uv[neq:] = v.reshape(neq * ndv)
+    if return_history:
+        return history
+    else:
+        return [[time, ldi]]
 
-        time_step = time_step_new
+
+def GALI(
+    u: NDArray[np.float64],
+    parameters: NDArray[np.float64],
+    total_time: float,
+    equations_of_motion: Callable[
+        [np.float64, NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]
+    ],
+    jacobian: Callable[
+        [np.float64, NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]
+    ],
+    number_deviation_vectors: int,
+    transient_time: Optional[float] = None,
+    time_step: float = 0.01,
+    atol: float = 1e-6,
+    rtol: float = 1e-3,
+    integrator=rk4_step_wrapped,
+    return_history: bool = False,
+    seed: int = 13,
+    threshold: float = 1e-16,
+) -> NDArray[np.float64]:
+
+    neq = len(u)  # Number of equations of the system
+    ndv = number_deviation_vectors  # Number of deviation vectors
+    nt = neq + neq * ndv  # Total number of equations including variational equations
+
+    u = u.copy()
+
+    # Handle transient time
+    if transient_time is not None:
+        u = evolve_system(
+            u,
+            parameters,
+            transient_time,
+            equations_of_motion,
+            time_step=time_step,
+            atol=atol,
+            rtol=rtol,
+            integrator=integrator,
+        )
+        time = transient_time
+    else:
+        time = 0
+
+    # State + deviation vectors
+    uv = np.zeros(nt)
+    uv[:neq] = u.copy()
+
+    # Randomly define the deviation vectors and orthonormalize them
+    np.random.seed(seed)
+    uv[neq:] = -1 + 2 * np.random.rand(nt - neq)
+    v = uv[neq:].reshape(neq, ndv)
+    v, _ = qr(v)
+    uv[neq:] = v.reshape(neq * ndv)
+
+    history = []
+
+    while time < total_time:
+        if time + time_step > total_time:
+            time_step = total_time - time
+
+        uv, time, time_step = step(
+            time,
+            uv,
+            parameters,
+            equations_of_motion,
+            jacobian=jacobian,
+            time_step=time_step,
+            atol=atol,
+            rtol=rtol,
+            integrator=integrator,
+            number_of_deviation_vectors=ndv,
+        )
+
+        # Reshape the deviation vectors into a neq x ndv matrix
+        v = uv[neq:].reshape(neq, ndv)
+
+        # Normalize the deviation vectors
+        for i in range(ndv):
+            v[:, i] /= np.linalg.norm(v[:, i])
+
+        # Calculate GALI
+        gali = wedge_norm(v)
+
+        if return_history:
+            result = [time, gali]
+            history.append(result)
+
+        # Early termination
+        if gali <= threshold:
+            break
+
+        # Reshape v back to uv
+        uv[neq:] = v.reshape(neq * ndv)
 
     if return_history:
         return history
     else:
-        return [[time, ldi]]
+        return [[time, gali]]

{pynamicalsys-1.2.2 → pynamicalsys-1.3.0}/src/pynamicalsys/continuous_time/numerical_integrators.py

@@ -237,7 +237,7 @@ def rk4_step_wrapped(
     ],
     jacobian=None,
     time_step: float = 0.01,
-    number_of_deviation_vectors=None,
+    number_of_deviation_vectors: Optional[int] = None,
     atol: float = 1e-6,  # unused, just to match signature
     rtol: float = 1e-3,  # unused, just to match signature
 ) -> tuple[NDArray[np.float64], float, float, bool]: