pynamicalsys 1.5.2__tar.gz → 1.5.4__tar.gz

{pynamicalsys-1.5.2 → pynamicalsys-1.5.4}/.gitignore

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

pynamicalsys-1.5.4/CHANGELOG.md

@@ -0,0 +1,384 @@
+# 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.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.2 → pynamicalsys-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pynamicalsys
-Version: 1.5.2
+Version: 1.5.4
 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.2 → pynamicalsys-1.5.4}/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.4/src/pynamicalsys/__version__.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.5.4'
+__version_tuple__ = version_tuple = (1, 5, 4)
+
+__commit_id__ = commit_id = 'g83b2f0161'

pynamicalsys-1.5.4/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.2 → pynamicalsys-1.5.4}/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,7 +17,7 @@
 
 import numpy as np
 from numba import njit, prange
-from typing import Optional, Tuple
+from typing import Tuple
 from numpy.typing import NDArray
 
 

pynamicalsys-1.5.4/src/pynamicalsys/common/clv.py

@@ -0,0 +1,97 @@
+# clv.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/>.
+
+
+import numpy as np
+from numpy.typing import NDArray
+from numba import njit
+from .types import numeric_t
+
+
+@njit
+def clv_sanitize_inplace(M: NDArray[np.float64]) -> None:
+    nrows, ncols = M.shape
+    for i in range(nrows):
+        for j in range(ncols):
+            x = M[i, j]
+            if not np.isfinite(x):
+                M[i, j] = 0.0
+
+
+@njit
+def clv_col_normalize_inplace(M: NDArray[np.float64], eps_norm: numeric_t) -> None:
+    nrows, ncols = M.shape
+    for j in range(ncols):
+        s = 0.0
+        for i in range(nrows):
+            v = M[i, j]
+            s += v * v
+
+        nrm = np.sqrt(s)
+
+        if (not np.isfinite(nrm)) or (nrm < eps_norm):
+            for i in range(nrows):
+                M[i, j] = 0.0
+            continue
+
+        inv = 1.0 / nrm
+        for i in range(nrows):
+            M[i, j] *= inv
+
+
+@njit
+def clv_solve_upper_inplace(
+    R: NDArray[np.float64],
+    B: NDArray[np.float64],
+    rcond_guard: numeric_t,
+) -> None:
+    """
+    Solve the upper-triangular system ``R X = B`` in place.
+
+    Parameters
+    ----------
+    R : NDArray[np.float64]
+        Upper-triangular matrix of shape `(p, p)`.
+    B : NDArray[np.float64]
+        Right-hand side matrix of shape `(p, m)`. Overwritten in place with
+        the solution `X`.
+    rcond_guard : numeric_t
+        Minimum absolute value allowed for diagonal entries of `R` during the
+        back-substitution step.
+
+    Notes
+    -----
+    This function modifies `B` in place and does not modify `R`.
+    """
+    p = R.shape[0]
+    ncols = B.shape[1]
+
+    for col in range(ncols):
+        for i in range(p - 1, -1, -1):
+            s = B[i, col]
+
+            for k in range(i + 1, p):
+                s -= R[i, k] * B[k, col]
+
+            rii = R[i, i]
+            if (not np.isfinite(rii)) or (np.abs(rii) < rcond_guard):
+                rii = rcond_guard if rii >= 0.0 else -rcond_guard
+
+            if not np.isfinite(s):
+                B[i, col] = 0.0
+            else:
+                B[i, col] = s / rii

pynamicalsys-1.5.4/src/pynamicalsys/common/differentiation.py

@@ -0,0 +1,93 @@
+# differentiation.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/>.
+
+from typing import Callable
+import numpy as np
+from numpy.typing import NDArray
+from numba import njit
+
+
+@njit
+def finite_difference_jacobian(
+    u: NDArray[np.float64],
+    parameters: NDArray[np.float64],
+    mapping: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    eps: float = -1.0,
+) -> NDArray[np.float64]:
+    """
+    Compute the Jacobian matrix using adaptive finite differences with error control.
+
+    Parameters
+    ----------
+    u : NDArray[np.float64]
+        State vector at which to compute Jacobian (shape: (n,))
+    parameters : NDArray[np.float64]
+        System parameters
+    mapping : Callable[[NDArray, NDArray], NDArray]
+        Vector-valued function to differentiate
+    eps : float, optional
+        Initial step size (automatically determined if -1.0)
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Jacobian matrix (shape: (n, n)) where J[i,j] = ∂f_i/∂u_j
+
+    Raises
+    ------
+    ValueError
+        If invalid method is specified
+        If eps is not positive when provided
+
+    Notes
+    -----
+    - For 'central' method (default), accuracy is O(eps²)
+    - For 'complex' method, accuracy is O(eps⁴) but requires complex arithmetic
+    - Automatic step size selection based on machine epsilon and input scale
+    - Includes Richardson extrapolation for higher accuracy
+    - Handles edge cases like zero components carefully
+
+    Examples
+    --------
+    >>> def lorenz(u, p):
+    ...     x, y, z = u
+    ...     sigma, rho, beta = p
+    ...     return np.array([sigma*(y-x), x*(rho-z)-y, x*y-beta*z])
+    >>> u = np.array([1.0, 1.0, 1.0])
+    >>> params = np.array([10.0, 28.0, 8/3])
+    >>> J = finite_difference_jacobian(u, params, lorenz, method='central')
+    """
+    n = len(u)
+    J = np.zeros((n, n))
+
+    # Determine optimal step size if not provided
+    if eps <= 0:
+        eps = float(np.finfo(np.float64).eps) ** (1 / 3) * max(
+            1.0, float(np.linalg.norm(u))
+        )
+
+    for i in range(n):
+        # Central difference: O(eps²) accuracy
+        u_plus = u.copy()
+        u_minus = u.copy()
+        u_plus[i] += eps
+        u_minus[i] -= eps
+        J[:, i] = (mapping(u_plus, parameters) - mapping(u_minus, parameters)) / (
+            2 * eps
+        )
+
+    return J