pynamicalsys 1.0.1__tar.gz → 1.2.2__tar.gz

pynamicalsys-1.2.2/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+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.2.2] - 2025-06-29
+
+### Added
+
+- `ContinuousDynamicalSystem` class for simulating and analyzing continuous nonlinear dynamical systems:
+  - Integration using the 4th order Runge-Kutta method with fixed time step.
+  - Integration using the adaptive 4th/5th order Runge-Kutta method with adaptive time step.
+  - Trajectory computation.
+  - Lyapunov exponents calculation.
+  - The smallest aligment index (SALI) and linear dependence index (LDI) for chaos detection.
+
+## [v1.0.0] - 2025-06-16
+
+### Added
+
+- `DiscreteDynamicalSystems` class for simulating and analyzing discrete nonlinear dynamical systems:
+  - Trajectory computation.
+  - Chaotic indicators.
+  - Fixed points, periodic orbits, and manifolds.
+  - Statistical analysis of ensemble of trajetories.
+  - Escape basin quantification.
+- Initial release of the package
+- First version of documentation
+- Basic tests
+
+- `BasinMetrics` class to compute basin metris such as basin entropy and boundary dimension.
+
+- `TimeSeriesMetrics` class to compute metrics related to time series analysis.
+
+- `PlotStyler` utility class to globally configure and apply consistent styling for Matplotlib plots.
+
+---
+
+<!-- Dummy heading to avoid ending on a transition -->
+
+##

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pynamicalsys
-Version: 1.0.1
-Summary: A Python toolkit for chaotic analysis and dynamical systems
+Version: 1.2.2
+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
                                Version 3, 29 June 2007
@@ -689,6 +689,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: numpy>=1.21
 Requires-Dist: matplotlib>=3.4
 Requires-Dist: numba>=0.55
+Requires-Dist: scipy>=0.6
 
 # pynamicalsys: A Python toolkit for the analysis of dynamical systems
 
@@ -698,28 +699,28 @@ Requires-Dist: numba>=0.55
 
 ## Overview
 
-**pynamicalsys** is designed to provide a fast, flexible, and user-friendly environment for analyzing **nonlinear dynamical systems**. It is designed for students, researchers, educators, and enthusiasts who want to explore the world of chaos and dynamical systems. Beyond standard tools like trajectory generation and Lyapunov exponents calculation, pynamicalsys includes advanced features such as
+**pynamicalsys** is designed to provide a fast, flexible, and user-friendly environment for analyzing **nonlinear dynamical systems**. It is intended for students, researchers, educators, and enthusiasts who want to explore the world of chaos and dynamical systems. Beyond standard tools like trajectory generation and Lyapunov exponents calculation, **pynamicalsys** includes advanced features such as
 
--   **Linear dependence index** for chaos detection.
--   **Recurrence plots** and recurrence time statistics.
--   Chaos indicators based on **weighted Birkhoff averages**.
--   Statistical measures of **diffusion and transport** in dynamical systems.
--   Computation of **periodic orbits**, their **stability** and their **manifolds**.
--   Basin metric for **quantifying** the structure of **basins of attraction**.
--   **Plot styling** for consistent and customizable visualizations.
+- **Linear dependence index** for chaos detection.
+- **Recurrence plots** and recurrence time statistics.
+- Chaos indicators based on **weighted Birkhoff averages**.
+- Statistical measures of **diffusion and transport** in dynamical systems.
+- Computation of **periodic orbits**, their **stability** and their **manifolds**.
+- Basin metric for **quantifying** the structure of **basins of attraction**.
+- **Plot styling** for consistent and customizable visualizations.
 
-pynamicalsys is built on top of NumPy and Numba, ensuring high performance and efficiency. Thanks to Numba accelerated computation, pynamicalsys offers speedups up to **130x** compared to the original Python implementation of the algorithms. This makes it suitable for large-scale simulations and analyses.
+**pynamicalsys** is built on top of NumPy and Numba, ensuring high performance and efficiency. Thanks to Numba accelerated computation, **pynamicalsys** offers speedups up to **130x** compared to the original Python implementation of the algorithms. This makes it suitable for large-scale simulations and analyses.
 
 ## Installation
 
 ### Prerequisites
 
--   Python 3.8 or higher
--   pip (Python package installer)
+- Python 3.8 or higher
+- pip (Python package installer)
 
 ### Install via PyPI
 
-To install the latest stable release, run:
+To install the latest stable release, run in your command line:
 
 ```bash
 $ pip install pynamicalsys
@@ -727,6 +728,13 @@ $ pip install pynamicalsys
 
 > **Note:** On **Windows**, it is **strongly recommended** to use [Anaconda](https://www.anaconda.com). It simplifies dependency management and avoids potential issues with scientific libraries during installation. Be sure to run the command from the **Anaconda Prompt**, not from Command Prompt or PowerShell, to ensure the correct environment is activated.
 
+### Upgrade via PyPI
+
+To upgrade your current version of **pynamicalsys** to the latest stable release, run in your command line:
+
+```bash
+$ pip install **pynamicalsys** --upgrade
+```
 
 ### Install from source
 
@@ -757,7 +765,19 @@ $ pip install --upgrade pip build
 
 ## Citation
 
-Currently, our research paper is under review, but in the mean time, if you use **pynamicalsys** in your work, you can cite the arXiv version:
+Currently, our research paper is under review, but in the mean time, if you use **pynamicalsys** in your work, you can cite the [arXiv](https://arxiv.org/abs/2506.14044) version:
+
+```bibtex
+@misc{pynamicalsys,
+  title={pynamicalsys: A Python toolkit for the analysis of dynamical systems},
+  author={Matheus Rolim Sales and Leonardo Costa de Souza and Daniel Borin and Michele Mugnaine and José Danilo Szezech Jr. and Ricardo Luiz Viana and Iberê Luiz Caldas and Edson Denis Leonel and Chris G. Antonopoulos},
+  year={2025},
+  eprint={2506.14044},
+  archivePrefix={arXiv},
+  primaryClass={nlin.CD},
+  url={https://arxiv.org/abs/2506.14044},
+}
+```
 
 ## Contributing
 

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

@@ -6,28 +6,28 @@
 
 ## Overview
 
-**pynamicalsys** is designed to provide a fast, flexible, and user-friendly environment for analyzing **nonlinear dynamical systems**. It is designed for students, researchers, educators, and enthusiasts who want to explore the world of chaos and dynamical systems. Beyond standard tools like trajectory generation and Lyapunov exponents calculation, pynamicalsys includes advanced features such as
+**pynamicalsys** is designed to provide a fast, flexible, and user-friendly environment for analyzing **nonlinear dynamical systems**. It is intended for students, researchers, educators, and enthusiasts who want to explore the world of chaos and dynamical systems. Beyond standard tools like trajectory generation and Lyapunov exponents calculation, **pynamicalsys** includes advanced features such as
 
--   **Linear dependence index** for chaos detection.
--   **Recurrence plots** and recurrence time statistics.
--   Chaos indicators based on **weighted Birkhoff averages**.
--   Statistical measures of **diffusion and transport** in dynamical systems.
--   Computation of **periodic orbits**, their **stability** and their **manifolds**.
--   Basin metric for **quantifying** the structure of **basins of attraction**.
--   **Plot styling** for consistent and customizable visualizations.
+- **Linear dependence index** for chaos detection.
+- **Recurrence plots** and recurrence time statistics.
+- Chaos indicators based on **weighted Birkhoff averages**.
+- Statistical measures of **diffusion and transport** in dynamical systems.
+- Computation of **periodic orbits**, their **stability** and their **manifolds**.
+- Basin metric for **quantifying** the structure of **basins of attraction**.
+- **Plot styling** for consistent and customizable visualizations.
 
-pynamicalsys is built on top of NumPy and Numba, ensuring high performance and efficiency. Thanks to Numba accelerated computation, pynamicalsys offers speedups up to **130x** compared to the original Python implementation of the algorithms. This makes it suitable for large-scale simulations and analyses.
+**pynamicalsys** is built on top of NumPy and Numba, ensuring high performance and efficiency. Thanks to Numba accelerated computation, **pynamicalsys** offers speedups up to **130x** compared to the original Python implementation of the algorithms. This makes it suitable for large-scale simulations and analyses.
 
 ## Installation
 
 ### Prerequisites
 
--   Python 3.8 or higher
--   pip (Python package installer)
+- Python 3.8 or higher
+- pip (Python package installer)
 
 ### Install via PyPI
 
-To install the latest stable release, run:
+To install the latest stable release, run in your command line:
 
 ```bash
 $ pip install pynamicalsys
@@ -35,6 +35,13 @@ $ pip install pynamicalsys
 
 > **Note:** On **Windows**, it is **strongly recommended** to use [Anaconda](https://www.anaconda.com). It simplifies dependency management and avoids potential issues with scientific libraries during installation. Be sure to run the command from the **Anaconda Prompt**, not from Command Prompt or PowerShell, to ensure the correct environment is activated.
 
+### Upgrade via PyPI
+
+To upgrade your current version of **pynamicalsys** to the latest stable release, run in your command line:
+
+```bash
+$ pip install **pynamicalsys** --upgrade
+```
 
 ### Install from source
 
@@ -65,7 +72,19 @@ $ pip install --upgrade pip build
 
 ## Citation
 
-Currently, our research paper is under review, but in the mean time, if you use **pynamicalsys** in your work, you can cite the arXiv version:
+Currently, our research paper is under review, but in the mean time, if you use **pynamicalsys** in your work, you can cite the [arXiv](https://arxiv.org/abs/2506.14044) version:
+
+```bibtex
+@misc{pynamicalsys,
+  title={pynamicalsys: A Python toolkit for the analysis of dynamical systems},
+  author={Matheus Rolim Sales and Leonardo Costa de Souza and Daniel Borin and Michele Mugnaine and José Danilo Szezech Jr. and Ricardo Luiz Viana and Iberê Luiz Caldas and Edson Denis Leonel and Chris G. Antonopoulos},
+  year={2025},
+  eprint={2506.14044},
+  archivePrefix={arXiv},
+  primaryClass={nlin.CD},
+  url={https://arxiv.org/abs/2506.14044},
+}
+```
 
 ## Contributing
 

{pynamicalsys-1.0.1 → pynamicalsys-1.2.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 dynamic = ["version"]
 name = "pynamicalsys"
-description = "A Python toolkit for chaotic analysis and dynamical systems"
+description = "A Python toolkit for the analysis of dynamical systems"
 authors = [{ name = "Matheus Rolim Sales", email = "rolim.sales.m@gmail.com" }]
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -15,7 +15,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 
-dependencies = ["numpy >=1.21", "matplotlib >=3.4", "numba >=0.55"]
+dependencies = ["numpy >=1.21", "matplotlib >=3.4", "numba >=0.55", "scipy >=0.6"]
 requires-python = ">=3.8"
 
 [build-system]

{pynamicalsys-1.0.1 → pynamicalsys-1.2.2}/src/pynamicalsys/__init__.py

@@ -16,9 +16,16 @@
 # along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 from pynamicalsys.core.discrete_dynamical_systems import DiscreteDynamicalSystem
+from pynamicalsys.core.continuous_dynamical_systems import ContinuousDynamicalSystem
 from pynamicalsys.core.basin_metrics import BasinMetrics
 from pynamicalsys.core.plot_styler import PlotStyler
 from pynamicalsys.core.time_series_metrics import TimeSeriesMetrics
 from .__version__ import __version__
 
-__all__ = ["DiscreteDynamicalSystem", "PlotStyler", "TimeSeriesMetrics", "BasinMetrics"]
+__all__ = [
+    "DiscreteDynamicalSystem",
+    "ContinuousDynamicalSystem",
+    "PlotStyler",
+    "TimeSeriesMetrics",
+    "BasinMetrics",
+]

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

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.0.1'
-__version_tuple__ = version_tuple = (1, 0, 1)
+__version__ = version = '1.2.2'
+__version_tuple__ = version_tuple = (1, 2, 2)

pynamicalsys-1.2.2/src/pynamicalsys/continuous_time/chaotic_indicators.py

@@ -0,0 +1,347 @@
+# chaotic_indicators.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/>.
+
+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 pynamicalsys.common.utils import qr
+from pynamicalsys.continuous_time.trajectory_analysis import evolve_system
+from pynamicalsys.continuous_time.numerical_integrators import rk4_step_wrapped
+
+
+@njit(cache=True)
+def lyapunov_exponents(
+    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]
+    ],
+    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,
+    log_base: float = np.e,
+    QR: Callable[
+        [NDArray[np.float64]], Tuple[NDArray[np.float64], NDArray[np.float64]]
+    ] = qr,
+) -> NDArray[np.float64]:
+
+    neq = len(u)  # Number of equations of the system
+    nt = neq + neq**2  # 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,
+        )
+        sample_time = total_time - transient_time
+        time = transient_time
+    else:
+        sample_time = total_time
+        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, neq)
+    v, _ = QR(v)
+    uv[neq:] = v.reshape(neq**2)
+
+    exponents = np.zeros(neq, 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(
+            time,
+            uv,
+            parameters,
+            equations_of_motion,
+            jacobian=jacobian,
+            time_step=time_step,
+        )
+
+        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)
+
+            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)
+
+            # Reshape v back to uv
+            uv[neq:] = v.reshape(neq**2)
+
+        time_step = time_step_new
+
+    if return_history:
+        return history
+    else:
+        result = []
+        for i in range(neq):
+            result.append(
+                exponents[i]
+                / (time - (transient_time if transient_time is not None else 0))
+            )
+        return [result]
+
+
+@njit(cache=True)
+def SALI(
+    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]
+    ],
+    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 = 2  # 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_new, time_new, time_step_new, accept = integrator(
+            time,
+            uv,
+            parameters,
+            equations_of_motion,
+            jacobian=jacobian,
+            time_step=time_step,
+            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)
+
+            # 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)
+
+            if return_history:
+                result = [time, sali]
+                history.append(result)
+
+            # Early termination
+            if sali <= threshold:
+                break
+
+            # Reshape v back to uv
+            uv[neq:] = v.reshape(neq * ndv)
+
+        time_step = time_step_new
+
+    if return_history:
+        return history
+    else:
+        return [[time, sali]]
+
+
+# @njit(cache=True)
+def LDI(
+    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_new, time_new, time_step_new, accept = integrator(
+            time,
+            uv,
+            parameters,
+            equations_of_motion,
+            jacobian=jacobian,
+            time_step=time_step,
+            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)
+
+            # 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.prod(S)
+
+            if return_history:
+                result = [time, ldi]
+                history.append(result)
+
+            # Early termination
+            if ldi <= threshold:
+                break
+
+            # Reshape v back to uv
+            uv[neq:] = v.reshape(neq * ndv)
+
+        time_step = time_step_new
+
+    if return_history:
+        return history
+    else:
+        return [[time, ldi]]