pynamicalsys 1.3.1__tar.gz → 1.4.1__tar.gz

{pynamicalsys-1.3.1 → pynamicalsys-1.4.1}/CHANGELOG.md

@@ -5,12 +5,53 @@ 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).
 
+## [Unreleased]
+
+### Added
+
+- `HamiltonianSystem` class for simulating and analyzing continuous-time Hamiltonian systems.
+  - Support for symplectic integration:
+    - 2nd-order velocity–Verlet
+    - 4th-order Yoshida
+  - Trajectory computation and ensemble trajectories.
+  - Poincaré section generation (single and ensemble).
+  - Chaos indicators:
+    - Lyapunov spectrum and maximum Lyapunov exponent.
+    - Smaller Alignment Index (SALI).
+    - Generalized Alignment Index (GALI).
+    - Linear Dependence Index (LDI).
+    - Recurrence time entropy (RTE).
+    - Hurst exponent.
+
+- `ContinuousDynamicalSystem` class:
+    - `poincare_section` method: return the Poincaré section of a given initial condition or of an ensemble of initial conditions.
+    - `stroboscopic_map` method: return the stroboscopic map of a given initial condition or of an ensemble of initial conditions.
+    - `maxima_map` method: return the maxima map of a given initial condition or of an ensemble of inital conditions.
+    - `basin_of_attraction` method: given an ensemble of initial conditions, detect and label the attractors in the system.
+    - `recurrence_time_entropy` method: calculates the recurrence time entropy for a given initial condition using the Poincaré section, stroboscopic map, or maxima map to construct the recurrence matrix.
+    - `hurst_exponent` method: calculates the Hurst exponent for a given initial condition using the Poincaré section, stroboscopic map, or maxima map.
+
+- `TimeSeriesMetrics`:
+    - `hurst_exponent` method.
+
+### Modified
+
+- `DiscreteDynamicalSystem` class:
+    - Unified the Hurst exponent calculation into a single function.
+
+- `ContinuousDynamicalSystem` class:
+    - `lyapunov` method now uses a specific function to compute only the maximum Lyapunov exponent when `num_exponents=1`.
+
+[Unreleased]: https://github.com/mrolims/pynamicalsys/compare/v1.3.1...HEAD
+
 ## [v1.3.1] - 2025-08-24
 
 ### Modified
 
 - Removed `cache=True` from the low level methods that was leading to cache compilation errors.
 
+[v1.3.1]: https://github.com/mrolims/pynamicalsys/compare/v1.3.0...v1.3.1
+
 ## [v1.3.0] - 2025-08-23
 
 ### Added
@@ -43,7 +84,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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.
+  - The smaller aligment index (SALI) and linear dependence index (LDI) for chaos detection.
 
 [v1.2.2]: https://github.com/mrolims/pynamicalsys/compare/v1.0.0...v1.2.2
 

{pynamicalsys-1.3.1 → pynamicalsys-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pynamicalsys
-Version: 1.3.1
+Version: 1.4.1
 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
@@ -690,6 +690,7 @@ Requires-Dist: numpy>=1.21
 Requires-Dist: matplotlib>=3.4
 Requires-Dist: numba>=0.55
 Requires-Dist: scipy>=0.6
+Requires-Dist: scikit-learn>=0.14
 
 # pynamicalsys: A Python toolkit for the analysis of dynamical systems
 
@@ -701,6 +702,8 @@ Requires-Dist: scipy>=0.6
 
 **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
 
+- **Bifurcation diagrams**, **Poincaré sections**, and **stroboscopic maps** for analyzing system trajectories.
+- **Symplectic integrators** for analyzing Hamiltonian systems.
 - **Linear dependence index** for chaos detection.
 - **Recurrence plots** and recurrence time statistics.
 - Chaos indicators based on **weighted Birkhoff averages**.
@@ -723,7 +726,7 @@ Requires-Dist: scipy>=0.6
 To install the latest stable release, run in your command line:
 
 ```bash
-$ pip install pynamicalsys
+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.
@@ -733,7 +736,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
@@ -741,9 +744,9 @@ $ pip install pynamicalsys --upgrade
 If you want to install the development version from the source repository, clone the repo and install with:
 
 ```bash
-$ git clone https://github.com/mrolims/pynamicalsys.git
-$ cd pynamicalsys
-$ pip install .
+git clone https://github.com/mrolims/pynamicalsys.git
+cd pynamicalsys
+pip install .
 ```
 
 ### Verifying the installation
@@ -760,12 +763,26 @@ After installation, you can verify it by running Python and importing the packag
 If you encounter any issues, make sure you have the latest version of pip:
 
 ```bash
-$ pip install --upgrade pip build
+pip install --upgrade pip build
 ```
 
+## Documentation
+
+For detailed instructions, examples, and API references, please visit the full documentation page:
+
+[pynamicalsys.readthedocs.io](https://pynamicalsys.readthedocs.io/)
+
+The documentation includes:
+
+- **Getting Started** — installation and quick-start examples.  
+- **Tutorial** — step-by-step explanations of key concepts and pratical demonstrations.
+- **API Reference** — detailed descriptions of all functions, parameters, and return values.
+
 ## 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](https://arxiv.org/abs/2506.14044) version:
+Our research paper is currently under review. In the meantime, if you use **pynamicalsys** in your work, please cite the [arXiv version](https://arxiv.org/abs/2506.14044). Below are recommended citation formats for different use cases.
+
+### BibTeX
 
 ```bibtex
 @misc{pynamicalsys,
@@ -779,6 +796,18 @@ Currently, our research paper is under review, but in the mean time, if you use
 }
 ```
 
+### APA style
+
+```
+Rolim Sales, M., Costa de Souza, L., Borin, D., Mugnaine, M., Szezech Jr., J. D., Viana, R. L., Caldas, I. L., Leonel, E. D., & Antonopoulos, C. G. (2025). pynamicalsys: A Python toolkit for the analysis of dynamical systems. arXiv:2506.14044. https://arxiv.org/abs/2506.14044
+```
+
+### Short citation style
+
+```
+Matheus Rolim Sales et al., "pynamicalsys: A Python toolkit for the analysis of dynamical systems," arXiv:2506.14044, 2025. https://arxiv.org/abs/2506.14044
+```
+
 ## Contributing
 
 We welcome contributions from the community! To get started, please see our [Contributing Guidelines](https://pynamicalsys.readthedocs.io/en/latest/contributing.html).

{pynamicalsys-1.3.1 → pynamicalsys-1.4.1}/README.md

@@ -8,6 +8,8 @@
 
 **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
 
+- **Bifurcation diagrams**, **Poincaré sections**, and **stroboscopic maps** for analyzing system trajectories.
+- **Symplectic integrators** for analyzing Hamiltonian systems.
 - **Linear dependence index** for chaos detection.
 - **Recurrence plots** and recurrence time statistics.
 - Chaos indicators based on **weighted Birkhoff averages**.
@@ -30,7 +32,7 @@
 To install the latest stable release, run in your command line:
 
 ```bash
-$ pip install pynamicalsys
+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.
@@ -40,7 +42,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
@@ -48,9 +50,9 @@ $ pip install pynamicalsys --upgrade
 If you want to install the development version from the source repository, clone the repo and install with:
 
 ```bash
-$ git clone https://github.com/mrolims/pynamicalsys.git
-$ cd pynamicalsys
-$ pip install .
+git clone https://github.com/mrolims/pynamicalsys.git
+cd pynamicalsys
+pip install .
 ```
 
 ### Verifying the installation
@@ -67,12 +69,26 @@ After installation, you can verify it by running Python and importing the packag
 If you encounter any issues, make sure you have the latest version of pip:
 
 ```bash
-$ pip install --upgrade pip build
+pip install --upgrade pip build
 ```
 
+## Documentation
+
+For detailed instructions, examples, and API references, please visit the full documentation page:
+
+[pynamicalsys.readthedocs.io](https://pynamicalsys.readthedocs.io/)
+
+The documentation includes:
+
+- **Getting Started** — installation and quick-start examples.  
+- **Tutorial** — step-by-step explanations of key concepts and pratical demonstrations.
+- **API Reference** — detailed descriptions of all functions, parameters, and return values.
+
 ## 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](https://arxiv.org/abs/2506.14044) version:
+Our research paper is currently under review. In the meantime, if you use **pynamicalsys** in your work, please cite the [arXiv version](https://arxiv.org/abs/2506.14044). Below are recommended citation formats for different use cases.
+
+### BibTeX
 
 ```bibtex
 @misc{pynamicalsys,
@@ -86,6 +102,18 @@ Currently, our research paper is under review, but in the mean time, if you use
 }
 ```
 
+### APA style
+
+```
+Rolim Sales, M., Costa de Souza, L., Borin, D., Mugnaine, M., Szezech Jr., J. D., Viana, R. L., Caldas, I. L., Leonel, E. D., & Antonopoulos, C. G. (2025). pynamicalsys: A Python toolkit for the analysis of dynamical systems. arXiv:2506.14044. https://arxiv.org/abs/2506.14044
+```
+
+### Short citation style
+
+```
+Matheus Rolim Sales et al., "pynamicalsys: A Python toolkit for the analysis of dynamical systems," arXiv:2506.14044, 2025. https://arxiv.org/abs/2506.14044
+```
+
 ## Contributing
 
 We welcome contributions from the community! To get started, please see our [Contributing Guidelines](https://pynamicalsys.readthedocs.io/en/latest/contributing.html).

{pynamicalsys-1.3.1 → pynamicalsys-1.4.1}/pyproject.toml

@@ -15,7 +15,13 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 
-dependencies = ["numpy >=1.21", "matplotlib >=3.4", "numba >=0.55", "scipy >=0.6"]
+dependencies = [
+    "numpy >=1.21",
+    "matplotlib >=3.4",
+    "numba >=0.55",
+    "scipy >=0.6",
+    "scikit-learn >=0.14",
+]
 requires-python = ">=3.8"
 
 [build-system]

{pynamicalsys-1.3.1 → pynamicalsys-1.4.1}/src/pynamicalsys/__init__.py

@@ -17,6 +17,7 @@
 
 from pynamicalsys.core.discrete_dynamical_systems import DiscreteDynamicalSystem
 from pynamicalsys.core.continuous_dynamical_systems import ContinuousDynamicalSystem
+from pynamicalsys.core.hamiltonian_systems import HamiltonianSystem
 from pynamicalsys.core.basin_metrics import BasinMetrics
 from pynamicalsys.core.plot_styler import PlotStyler
 from pynamicalsys.core.time_series_metrics import TimeSeriesMetrics
@@ -25,6 +26,7 @@ from .__version__ import __version__
 __all__ = [
     "DiscreteDynamicalSystem",
     "ContinuousDynamicalSystem",
+    "HamiltonianSystem",
     "PlotStyler",
     "TimeSeriesMetrics",
     "BasinMetrics",

{pynamicalsys-1.3.1 → pynamicalsys-1.4.1}/src/pynamicalsys/__version__.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.3.1'
-__version_tuple__ = version_tuple = (1, 3, 1)
+__version__ = version = '1.4.1'
+__version_tuple__ = version_tuple = (1, 4, 1)
 
-__commit_id__ = commit_id = 'g3102ffa8b'
+__commit_id__ = commit_id = 'g62c79d265'

pynamicalsys-1.4.1/src/pynamicalsys/common/time_series_metrics.py

@@ -0,0 +1,85 @@
+from typing import Optional, Tuple, Union, Callable
+from numpy.typing import NDArray
+import numpy as np
+from numba import njit, prange
+
+from pynamicalsys.common.utils import fit_poly
+
+
+@njit(parallel=True)
+def hurst_exponent(
+    time_series: NDArray[np.float64],
+    wmin: int = 2,
+) -> NDArray[np.float64]:
+
+    time_series = time_series.copy()
+
+    sample_size, neq = time_series.shape
+
+    H = np.zeros(neq)
+
+    ells = np.arange(wmin, sample_size // 2)
+    log_ells = np.log(ells)
+    RS = np.empty((ells.shape[0], neq))
+
+    for j in prange(neq):
+        series = time_series[:, j]
+
+        # Precompute cumulative sums and cumulative sums of squares
+        cum_sum = np.zeros(sample_size)
+        cum_sum_sq = np.zeros(sample_size)
+        cum_sum[0] = series[0]
+        cum_sum_sq[0] = series[0] ** 2
+        for t in range(1, sample_size):
+            cum_sum[t] = cum_sum[t - 1] + series[t]
+            cum_sum_sq[t] = cum_sum_sq[t - 1] + series[t] ** 2
+
+        for i, ell in enumerate(ells):
+            num_blocks = sample_size // ell
+            R_over_S = np.zeros(num_blocks)
+
+            for block in range(num_blocks):
+                start = block * ell
+                end = start + ell
+
+                # Mean using cumulative sums
+                block_sum = cum_sum[end - 1] - (cum_sum[start - 1] if start > 0 else 0)
+                block_mean = block_sum / ell
+
+                # Variance using cumulative sums of squares
+                block_sum_sq = cum_sum_sq[end - 1] - (
+                    cum_sum_sq[start - 1] if start > 0 else 0
+                )
+                var = block_sum_sq / ell - block_mean**2
+                S = np.sqrt(var) if var > 0 else 0
+
+                # Cumulative sum of mean-adjusted series for range
+                max_Z = 0.0
+                min_Z = 0.0
+                cumsum = 0.0
+                for k in range(start, end):
+                    cumsum += series[k] - block_mean
+                    if cumsum > max_Z:
+                        max_Z = cumsum
+                    if cumsum < min_Z:
+                        min_Z = cumsum
+                R = max_Z - min_Z
+
+                R_over_S[block] = R / S if S > 0 else 0.0
+
+            positive_mask = R_over_S > 0
+            RS[i, j] = (
+                np.mean(R_over_S[positive_mask]) if np.any(positive_mask) else 0.0
+            )
+
+        # Linear regression in log-log space
+        positive_inds = np.where(RS[:, j] > 0)[0]
+        if positive_inds.size == 0:
+            H[j] = 0.0
+        else:
+            x_fit = log_ells[positive_inds]
+            y_fit = np.log(RS[positive_inds, j])
+            fitting = fit_poly(x_fit, y_fit, 1)
+            H[j] = fitting[0]
+
+    return H