pynamicalsys 1.5.3__tar.gz → 1.6.0__tar.gz

{pynamicalsys-1.5.3 → pynamicalsys-1.6.0}/.gitignore

@@ -1,5 +1,6 @@
 __pycache__
 .vscode/
+.venv/
 .DS_Store
 *.egg-info/
 tests/*.png

pynamicalsys-1.6.0/CHANGELOG.md

@@ -0,0 +1,412 @@
+# 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.6.0] - 2026-07-01
+
+### Added
+
+- Support for **general (non-separable) Hamiltonian systems** `H(q, p)`
+  via a new `"imp"` (implicit midpoint) integrator. Specify the system
+  via `eom` and `hess_H` instead of `grad_T`/`grad_V`. All analysis
+  methods (`lyapunov`, `CLV`, `CLV_angles`, `SALI`, `LDI`, `GALI`,
+  `poincare_section`, `recurrence_time_entropy`, `hurst_exponent`)
+  dispatch to the implicit midpoint backend automatically when `"imp"`
+  is selected.
+- Support for **periodic/angular section coordinates** in Poincaré
+  sections via `periodic_section_coordinate` and `period` parameters.
+  Useful for action-angle systems where the section coordinate grows
+  unbounded rather than oscillating. Available on `poincare_section`,
+  `recurrence_time_entropy`, and `hurst_exponent`.
+- `poincare_section` now accepts a `max_workers` parameter controlling
+  the number of parallel workers used when computing an ensemble of
+  initial conditions (default: all available CPUs).
+- The implicit midpoint integrator now raises `RuntimeError` on
+  non-convergence instead of silently returning corrupted results.
+- `BasinMetrics`: added `uncertainty_fraction_mapping` for Monte Carlo
+  estimation of the uncertainty fraction and uncertainty exponent of
+  escape basins, with parallel evaluation and reproducible random
+  sampling via a user-provided seed.
+
+[v1.6.0]: https://github.com/mrolims/pynamicalsys/compare/v1.5.4...v1.6.0
+
+## [v1.5.4] - 2026-05-28
+
+### Added
+
+- `DiscreteDynamicalSystem` class:
+  - Added `return_last_state` to the `SALI`, `LDI`, and `GALI` methods.
+  - Added `method` option to `GALI` with the following implementations:
+    - `"DET"`: computes `GALI_k` from the Gram matrix determinant.
+    - `"QR"`: computes `GALI_k` from the diagonal of the triangular factor returned by the internal QR routine.
+    - `"QR_HH"`: computes `GALI_k` from the diagonal of the triangular factor returned by `numpy.linalg.qr`.
+
+- `ContinuousDynamicalSystem` class:
+  - Added `method` option to `GALI` with the following implementations:
+    - `"DET"`: computes `GALI_k` from the Gram matrix determinant.
+    - `"QR"`: computes `GALI_k` from the diagonal of the triangular factor returned by the internal QR routine.
+    - `"QR_HH"`: computes `GALI_k` from the diagonal of the triangular factor returned by `numpy.linalg.qr`.
+
+- `HamiltonianSystem` class:
+  - Added `method` option to `GALI` with the following implementations:
+    - `"DET"`: computes `GALI_k` from the Gram matrix determinant.
+    - `"QR"`: computes `GALI_k` from the diagonal of the triangular factor returned by the internal QR routine.
+    - `"QR_HH"`: computes `GALI_k` from the diagonal of the triangular factor returned by `numpy.linalg.qr`.
+
+- `discrete_time` module:
+  - Added dedicated low-level modules:
+    - `trajectory.py`
+    - `bifurcation.py`
+    - `birkhoff.py`
+    - `hurst.py`
+    - `rte.py`
+    - `periodic_orbits.py`
+    - `stability.py`
+    - `manifolds.py`
+    - `rotation.py`
+    - `escape.py`
+    - `transport.py`
+    - `averages.py`
+    - `symmetry.py`
+    - `sali.py`
+    - `ldi.py`
+    - `gali.py`
+    - `clv.py`
+
+- `continuous_time` module:
+  - Added dedicated low-level modules:
+    - `fixed_step.py`
+    - `adaptive_step.py`
+    - `step_methods.py`
+    - `variational.py`
+    - `step.py`
+    - `trajectory.py`
+    - `poincare.py`
+    - `stroboscopic.py`
+    - `maxima_map.py`
+    - `basins.py`
+    - `lyapunov.py`
+    - `sali.py`
+    - `ldi.py`
+    - `gali.py`
+    - `clv.py`
+    - `rte.py`
+    - `hurst.py`
+
+- `hamiltonian_systems` module:
+  - Added dedicated low-level modules:
+    - `coefficients.py`
+    - `fixed_step.py`
+    - `tangent.py`
+    - `trajectory.py`
+    - `poincare.py`
+    - `lyapunov.py`
+    - `sali.py`
+    - `ldi.py`
+    - `gali.py`
+    - `clv.py`
+    - `rte.py`
+    - `hurst.py`
+
+- `common.types`:
+  - Added `observable_t` type alias for weighted-Birkhoff observable functions.
+  - Added `flow_t` and `flow_jacobian_t` type aliases for continuous-time vector fields and their Jacobians.
+  - Added `grad_t` and `hess_t` type aliases for Hamiltonian gradients and Hessians.
+  - Added `symplectic_step_t` and `symplectic_tangent_step_t` type aliases for Hamiltonian fixed-step integrators and their tangent-map variants.
+
+### Changed
+
+- Refactored low-level discrete-time analysis routines by splitting the old monolithic modules into dedicated files for improved project organization, readability, and maintainability.
+- Refactored low-level continuous-time analysis routines by splitting the old monolithic modules into dedicated files for improved project organization, readability, and maintainability.
+- Refactored low-level Hamiltonian-system analysis and integration routines by splitting the old monolithic modules into dedicated files for improved project organization, readability, and maintainability.
+
+- `DiscreteDynamicalSystem` class:
+  - Updated wrappers across the discrete-time analysis API with improved type annotations, return annotations, argument validation, and docstrings.
+  - Standardized handling of `sample_times` in wrappers that support sampled outputs by explicitly validating user input and constructing internal sampling arrays only when needed.
+  - Updated `dig` observable validation so the observable must be callable and return a 1D NumPy array with one value per input state.
+  - Improved validation and normalization of wrapper inputs for periodic-orbit, manifold, transport, escape, Hurst, and recurrence diagnostics.
+  - The Lyapunov exponent API now exposes the analytical QR procedure (after Eckmann-Ruelle) explicitly through the `method` argument:
+    - `method="ER"` now selects the analytical QR-based approach (available only for 2D systems).
+    - `method="QR"` now consistently uses the modifed Gram-Schmidt QR decomposition, independent of system dimension.
+    - `method=QR_HH` uses Householder QR decomposition via `np.linalg.qr`.
+  - The previous implicit behavior where method="QR" automatically switched to the Eckmann–Ruelle algorithm for 2D systems has been removed. Existing code relying on this optimization should now explicitly set `ds.lyapunov(..., method="ER")`.
+
+- `ContinuousDynamicalSystem` class:
+  - Reorganized imports and internal plumbing to use the new continuous-time module layout.
+  - Updated constructor, integrator configuration, and wrapper methods with improved type annotations, return annotations, argument validation, and docstrings.
+  - Standardized validation of continuous-time arguments by using dedicated time validation helpers and more explicit normalization of parameters and wrapper inputs.
+  - Updated trajectory-related wrappers to reflect adaptive-step behavior more faithfully when ensemble trajectories do not all share the same stored length.
+  - Updated Lyapunov-related return annotations and docstrings so the scalar `num_exponents=1` case is documented and handled consistently.
+
+- `HamiltonianSystem` class:
+  - Reorganized imports and internal plumbing to use the new Hamiltonian-system module layout.
+  - Updated constructor, integrator configuration, and wrapper methods with improved type annotations, return annotations, argument validation, and docstrings.
+  - Standardized validation of Hamiltonian wrapper inputs for coordinates, momenta, parameters, section arguments, CLV configuration, and time-like arguments.
+  - Updated Lyapunov-, CLV-, SALI-, LDI-, GALI-, RTE-, Hurst-, trajectory-, and Poincaré-related wrappers to use the refactored low-level modules and more explicit scalar/array return semantics.
+
+- `continuous_time.validators`:
+  - Refactored `validate_times()` to return validated `np.float64` values and to enforce stricter type and range checks for continuous-time arguments.
+
+- `hamiltonian_systems.validators`:
+  - Refactored `validate_times()` and `validate_initial_conditions()` with stricter typing, shape checks, and `np.float64` normalization for Hamiltonian-system inputs.
+
+- `common.validators`:
+  - Refactored `validate_clv_subspaces()` and `validate_clv_pairs()` to validate indices against `num_clvs` instead of the full system dimension.
+  - Improved normalization of single subspace and single pair inputs into canonical tuple-based representations.
+
+- `common.utils`:
+  - Refactored the internal QR routine to a simpler reduced modified Gram-Schmidt implementation with manual inner products for better Numba compatibility and lower overhead.
+  - Simplified `householder_qr()` implementation.
+  - Temporarily kept shared CLV helper routines in `utils.py` because they are still used by the continuous and Hamiltonian classes during the refactor.
+  - Added typed `qr_truncate()` helper documentation and return annotations for CLV-related truncation logic.
+
+### Fixed
+
+- `DiscreteDynamicalSystem` class:
+  - Fixed `SALI`, `LDI`, and `GALI` wrappers so that scalar outputs are returned consistently when `return_history=False`, while preserving the final state when `return_last_state=True`.
+  - Fixed `GALI` computation by using stable QR-based volume evaluation.
+  - Fixed `CLV_angles` validation so subspace and pair indices are checked against the number of computed CLVs rather than the ambient phase-space dimension.
+  - Removed a stray debug `print(iter_time)` from `manifold()`.
+  - Added validation to prevent the use of `method="ER"` for systems with dimension greater than 2, raising a clear error instead of silently falling back to another implementation.
+
+- `ContinuousDynamicalSystem` class:
+  - Fixed wrapper regressions introduced during the continuous-time refactor in trajectory, reduced-map, Lyapunov, CLV, SALI, LDI, GALI, RTE, and Hurst-related methods.
+  - Fixed `trajectory()` return handling for ensembles evolved with adaptive integrators, where different initial conditions may produce trajectories with different numbers of stored time steps.
+  - Fixed `lyapunov()` so `method="QR_HH"` works correctly with the refactored low-level implementation.
+  - Fixed `lyapunov()` so `num_exponents=1` returns a scalar instead of a length-1 array when `return_history=False`.
+  - Fixed `GALI()` wrapper so the selected low-level computation method is validated and passed through correctly.
+
+- `HamiltonianSystem` class:
+  - Fixed wrapper validation bugs in trajectory, Poincaré-section, Lyapunov, CLV, CLV-angle, SALI, LDI, GALI, RTE, and Hurst-related methods introduced during the Hamiltonian refactor.
+  - Fixed wrapper shape checks so coordinate and momentum arrays are validated by full shape compatibility rather than only by matching dimensionality.
+  - Fixed `lyapunov()` so `num_exponents=1` returns a scalar instead of a length-1 array when `return_history=False`.
+  - Fixed `GALI()` wrapper so the selected low-level computation method is validated and passed through correctly.
+  - Fixed section-index validation in Hamiltonian reduced-map wrappers so section coordinates are checked against the number of degrees of freedom rather than the full phase-space dimension where appropriate.
+
+- `discrete_time` module:
+  - Fixed low-level `SALI`, `LDI`, and `GALI` implementations to return both the computed result and the final state consistently.
+  - Fixed history allocation and sampling logic in low-level `SALI`, `LDI`, and `GALI` implementations for `return_history=True`.
+  - Fixed the weighted-Birkhoff `dig` implementation to live in its own dedicated module while preserving wrapper behavior.
+  - Fixed dtype consistency in sampled transport routines to avoid Numba typing errors from mixing `int32` and `int64` sampling arrays.
+
+- `continuous_time` module:
+  - Fixed QR-related low-level Lyapunov and GALI computations to handle Householder-based QR consistently under Numba.
+  - Fixed array contiguity issues in low-level QR-based continuous-time routines to avoid reshape/type failures after `numpy.linalg.qr`.
+
+- `hamiltonian_systems` module:
+  - Fixed low-level Lyapunov and GALI computations to support both internal QR and Householder-based QR through method dispatch instead of passing unsupported callable QR objects into Numba-compiled routines.
+  - Fixed low-level trajectory and reduced-map helpers with clearer typing, stricter validation, and dedicated Poincaré-section extraction from stored trajectories.
+  - Fixed Hamiltonian recurrence-time-entropy returns by replacing dynamically assembled list-based returns with explicit tuple branches compatible with static typing.
+
+- `common.validators`:
+  - Fixed `validate_positive()` so zero is rejected correctly.
+
+[v1.5.4]: https://github.com/mrolims/pynamicalsys/compare/v1.5.3...v1.5.4
+
+## [v1.5.3] - 2026-04-08
+
+### Fixed
+
+- Incorrect tangent drift update in symplectic (Verlet/Yoshida) integrators (used δq instead of δp in δq update)
+- QR re-orthonormalization scheduling in Lyapunov spectrum (`(i + 1) % qr_interval`)
+- History allocation using `round` instead of integer division
+- Incorrect normalization of history array (time column was being scaled)
+
+[v1.5.3]: https://github.com/mrolims/pynamicalsys/compare/v1.5.2...v1.5.3
+
+## [v1.5.2] - 2026-03-23
+
+### Fixed
+
+- `DiscreteDynamicalSystem` class:
+  - Fixed parameter handling in `DiscreteDynamicalSystem.bifurcation_diagram()` when the system has no stored default parameters:
+    - user-provided parameters are now validated and the scanned parameter is inserted at `param_index`;
+    - if no parameters are provided, a default parameter array is initialized so the scanned parameter can be assigned correctly.
+
+### Changed
+
+- Minor formatting cleanup in `logistic_map()`.
+
+[v1.5.2]: https://github.com/mrolims/pynamicalsys/compare/v1.5.1...v1.5.2
+
+## [v1.5.1] - 2026-03-16
+
+### Added
+
+- Support for fixed recurrence rate threshold selection via `fixed_rr=True`. When enabled, the recurrence threshold is automatically chosen such that the recurrence matrix achieves the desired recurrence rate (`threshold` interpreted as the target RR).
+
+- Support for callable distance metrics for recurrence matrix computation and recurrence-rate threshold estimation. Custom metrics must have signature `metric(x, y) -> float` and must be Numba-compatible (decorated with `@numba.njit`).
+
+- New `return_eps` option in `TimeSeriesMetrics.recurrence_matrix()` to return the threshold value used to construct the recurrence matrix.
+
+### Modifed
+
+- Internal recurrence matrix computation has been refactored for improved performance and consistency between built-in metrics (supremum, euclidean, manhattan) and callable metrics.
+
+- Threshold selection is now centralized in a new `calculate_threshold()` function, which handles
+  - direct thresholds.
+  - standard-deviation–scaled thresholds (`threshold_mode="std"`).
+  - fixed recurrence rate thresholds (`threshold_mode="rr"`).
+
+[v1.5.1]: https://github.com/mrolims/pynamicalsys/compare/v1.5.0...v1.5.1
+
+## [v1.5.0] - 2026-01-07
+
+### Added
+
+- Added two new methods, `set_parameters` and `get_parameters`, to each of the three main classes to improve parameter management. Parameters can now be set once via `set_parameters` and stored internally, allowing subsequent method calls to use the stored values without requiring parameters to be passed explicitly each time. Existing workflows remain fully backward compatible: methods that accept parameters directly continue to work as before.
+
+- Added **Covariant Lyapunov Vector (CLV) angle diagnostics** to all three core system classes:
+  - The new methods `CLV` and `CLV_angles` allow computation of the **CLVs**, **angles between arbitrary CLV subspaces** and **pairwise CLV angles**, with full user control over:
+    - which subspaces are compared,
+    - which CLV pairs are measured.
+  - Support for **Poincaré-section–restricted CLV angles** in Hamiltonian systems, enabling angle analysis directly on the section.
+  - Angle diagnostics are based on **minimum principal angles between covariant subspaces**, providing a geometrically meaningful measure of hyperbolicity and near-tangencies in high-dimensional systems.
+
+### Modified
+
+- The parameter validator now accepts empty lists for systems that take no parameters.
+
+[v1.5.0]: https://github.com/mrolims/pynamicalsys/compare/v1.4.9...v1.5.0
+
+## [v1.4.9] - 2025-11-18
+
+### Fixed
+
+- Fix missing dependency:
+  - Added `ipython (>=8.13,<9.0.0)` to `pyproject.toml` dependencies, since it is required by the `ContinuousDynamicalSystem` class.
+
+[v1.4.9]: https://github.com/mrolims/pynamicalsys/compare/v1.4.1...v1.4.9
+
+## [v1.4.6] - 2025-10-09
+
+### Modified
+
+- `HamiltonianSystem` class:
+  - Fixed the integration of the tangent vectors that was leading to numerical instability for long integration times.
+
+- Refactored `recurrence_time_entropy` methods and `white_vertline_distr` function to handle the minimum line length parameter more consistently.
+
+[v1.4.6]: https://github.com/mrolims/pynamicalsys/compare/v1.4.1...v1.4.6
+
+## [v1.4.5] - 2025-09-17
+
+### Modified
+
+- `DiscreteDynamicalSystem` class:
+  - Fixed problems in the `finite_hurst_exponent`
+
+- `ContinuousDynamicalSystem` and `HamiltonianSystem` classes:
+  - Fixed the output of the `recurrence_time_entropy` method when `return_final_state=True`.
+
+[v1.4.5]: https://github.com/mrolims/pynamicalsys/compare/v1.4.1...v1.4.5
+
+## [v1.4.1] - 2025-09-15
+
+### 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`.
+
+[v1.4.1]: https://github.com/mrolims/pynamicalsys/compare/v1.3.1...v1.4.1
+
+## [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
+
+- `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
+
+- `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 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
+
+## v1.0.0 - 2025-06-16
+
+### Added
+
+- `DiscreteDynamicalSystem` 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.5.3 → pynamicalsys-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pynamicalsys
-Version: 1.5.3
+Version: 1.6.0
 Summary: A Python toolkit for the analysis of dynamical systems
 Author-email: Matheus Rolim Sales <rolim.sales.m@gmail.com>
 License-Expression: GPL-3.0-only

{pynamicalsys-1.5.3 → pynamicalsys-1.6.0}/src/pynamicalsys/__init__.py

@@ -1,6 +1,6 @@
 # __init__.py
 
-# Copyright (C) 2025 Matheus Rolim Sales
+# Copyright (C) 2025-2026 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
@@ -16,6 +16,7 @@
 # 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.hamiltonian_systems import HamiltonianSystem
 from pynamicalsys.core.basin_metrics import BasinMetrics

{pynamicalsys-1.5.3 → pynamicalsys-1.6.0}/src/pynamicalsys/__version__.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.5.3'
-__version_tuple__ = version_tuple = (1, 5, 3)
+__version__ = version = '1.6.0'
+__version_tuple__ = version_tuple = (1, 6, 0)
 
-__commit_id__ = commit_id = 'ge5f4a0776'
+__commit_id__ = commit_id = 'g4ec6e167d'

pynamicalsys-1.6.0/src/pynamicalsys/common/__init__.py

@@ -0,0 +1,16 @@
+# __init__.py
+#
+# Copyright (C) 2025-2026 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/>.

{pynamicalsys-1.5.3 → pynamicalsys-1.6.0}/src/pynamicalsys/common/basin_analysis.py

@@ -1,6 +1,6 @@
 # basin_analysis.py
 
-# Copyright (C) 2025 Matheus Rolim Sales
+# Copyright (C) 2025-2026 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
@@ -17,8 +17,9 @@
 
 import numpy as np
 from numba import njit, prange
-from typing import Optional, Tuple
+from typing import Tuple
 from numpy.typing import NDArray
+from joblib import delayed, Parallel
 
 
 def uncertainty_fraction(x, y, basin, epsilon_max, n_eps=100, epsilon_min=0):
@@ -168,3 +169,107 @@ def basin_entropy(
     Sbb = np.mean(S[boundary_mask]) if boundary_mask.any() else 0.0
 
     return float(Sb), float(Sbb)
+
+def uncertainty_fraction_mapping(
+    X: NDArray[np.float64],
+    Y: NDArray[np.float64],
+    basin: NDArray[np.float64],
+    mapping: object,
+    parameters: object,
+    exits: object,
+    escape: str = "exiting",
+    n_samples: int = 120_000,
+    p_samples: int = 7,
+    threshold: float = 0.1,
+    n_eps: int = 100,
+    max_time: int = 1000,
+    seed: int = 13,
+    n_jobs: int = -1,
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """
+    Wrapper to compute the uncertainty fraction f(epsilon) for a given basin of attraction with mapping.
+    """
+ 
+    rng = np.random.default_rng(seed)
+ 
+    flat_x = X.flatten()
+    flat_y = Y.flatten()
+    flat_basin = basin.flatten()
+ 
+    epsilons = np.logspace(np.log10(0.1), np.log10(1 / X.size), n_eps)
+ 
+    idx = rng.choice(len(flat_x), size=n_samples, replace=False)
+    xs = flat_x[idx]
+    ys = flat_y[idx]
+    labels = flat_basin[idx]
+ 
+    angles = np.linspace(0, 2 * np.pi, p_samples, endpoint=False)
+    dcos = np.cos(angles)
+    dsin = np.sin(angles)
+ 
+    needed = max(1, int(np.ceil(threshold * p_samples)))
+ 
+    ss = np.random.SeedSequence(seed)
+    child_seeds = ss.spawn(n_eps)
+ 
+    f_eps = Parallel(n_jobs=n_jobs)(
+        delayed(_process_single_epsilon)(
+            eps, xs, ys, labels, p_samples, dcos, dsin, needed,
+            mapping, max_time, parameters, exits, escape, n_samples,
+            child_seeds[i],
+        )
+        for i, eps in enumerate(epsilons)
+    )
+ 
+    return epsilons, f_eps
+ 
+ 
+def _process_single_epsilon(
+    eps: float,
+    xs: NDArray[np.float64],
+    ys: NDArray[np.float64],
+    labels: NDArray[np.float64],
+    p_samples: int,
+    dcos: NDArray[np.float64],
+    dsin: NDArray[np.float64],
+    needed: int,
+    mapping: object,
+    max_time: int,
+    parameters: object,
+    exits: object,
+    escape: str,
+    n_samples: int,
+    child_seed: np.random.SeedSequence,
+) -> float:
+    """Worker function that computes the uncertainty fraction for a single
+    epsilon value.
+    """
+ 
+    rng = np.random.default_rng(child_seed)
+    uncertain = 0
+ 
+    for x, y, side_center in zip(xs, ys, labels):
+        u_rand = rng.random(p_samples)
+        r = eps * np.sqrt(u_rand)
+        x_eps = x + r * dcos
+        y_eps = y + r * dsin
+ 
+        different = 0
+        for xp, yp in zip(x_eps, y_eps):
+            side_p, _ = mapping.escape_analysis(
+                u=(xp, yp),
+                max_time=max_time,
+                parameters=parameters,
+                exits=exits,
+                escape=escape,
+            )
+            if side_p != side_center:
+                different += 1
+                if different >= needed:
+                    break
+ 
+        if different >= needed:
+            uncertain += 1
+ 
+    return uncertain / n_samples
+