pynamicalsys 1.3.1__py3-none-any.whl → 1.4.1__py3-none-any.whl

pynamicalsys/hamiltonian_systems/numerical_integrators.py

@@ -0,0 +1,248 @@
+# numerical_integrators.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 Callable, Tuple
+from numpy.typing import NDArray
+from numba import njit
+import numpy as np
+
+# Yoshida 4th-order symplectic integrator coefficients
+ALPHA: float = 1.0 / (2.0 - 2.0 ** (1.0 / 3.0))
+BETA: float = -(2.0 ** (1.0 / 3.0)) / (2.0 - 2.0 ** (1.0 / 3.0))
+
+
+@njit
+def velocity_verlet_2nd_step(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    time_step: float,
+    grad_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    grad_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    parameters: NDArray[np.float64],
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """
+    Perform one step of the velocity Verlet integrator (second-order, symplectic).
+
+    Parameters
+    ----------
+    q : NDArray[np.float64]
+        Current generalized coordinates.
+    p : NDArray[np.float64]
+        Current generalized momenta.
+    time_step : float
+        Integration time step.
+    grad_T : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the gradient of the kinetic energy with respect to `p`.
+    grad_V : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the gradient of the potential energy with respect to `q`.
+    parameters : NDArray[np.float64]
+        Additional parameters passed to `grad_T` and `grad_V`.
+
+    Returns
+    -------
+    q_new : NDArray[np.float64]
+        Updated generalized coordinates after one step.
+    p_new : NDArray[np.float64]
+        Updated generalized momenta after one step.
+    """
+    q_new = q.copy()
+    p_new = p.copy()
+
+    # Half kick
+    gradV = grad_V(q, parameters)
+    p_new -= 0.5 * time_step * gradV
+
+    # Drift
+    gradT = grad_T(p_new, parameters)
+    q_new += time_step * gradT
+
+    # Half kick
+    gradV = grad_V(q_new, parameters)
+    p_new -= 0.5 * time_step * gradV
+
+    return q_new, p_new
+
+
+@njit
+def velocity_verlet_2nd_step_tangent(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    dq: NDArray[np.float64],
+    dp: NDArray[np.float64],
+    time_step: float,
+    hess_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    hess_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    parameters: NDArray[np.float64],
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """
+    Perform one step of the tangent map associated with the velocity Verlet integrator.
+
+    This evolves deviation (tangent) vectors `(dq, dp)` along the flow of the system,
+    which is necessary for computing Lyapunov exponents and stability analysis.
+
+    Parameters
+    ----------
+    q : NDArray[np.float64]
+        Current generalized coordinates.
+    p : NDArray[np.float64]
+        Current generalized momenta.
+    dq : NDArray[np.float64]
+        Deviation in coordinates.
+    dp : NDArray[np.float64]
+        Deviation in momenta.
+    time_step : float
+        Integration time step.
+    hess_T : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the Hessian of the kinetic energy with respect to `p`.
+    hess_V : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the Hessian of the potential energy with respect to `q`.
+    parameters : NDArray[np.float64]
+        Additional parameters passed to `hess_T` and `hess_V`.
+
+    Returns
+    -------
+    dq_new : NDArray[np.float64]
+        Updated deviation in coordinates after one step.
+    dp_new : NDArray[np.float64]
+        Updated deviation in momenta after one step.
+    """
+    dq_new = dq.copy()
+    dp_new = dp.copy()
+
+    # Compute Hessians
+    HT = hess_T(p, parameters)
+    HV = hess_V(q, parameters)
+
+    # Half kick
+    HV_dot_dq = HV @ dq
+    dp_new -= 0.5 * time_step * HV_dot_dq
+
+    # Drift
+    HT_dot_dp = HT @ dp_new
+    dq_new += time_step * HT_dot_dp
+
+    # Half kick
+    HV_dot_dq = HV @ dq_new
+    dp_new -= 0.5 * time_step * HV_dot_dq
+
+    return dq_new, dp_new
+
+
+@njit
+def yoshida_4th_step(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    time_step: float,
+    grad_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    grad_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    parameters: NDArray[np.float64],
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """
+    Perform one step of the 4th-order Yoshida symplectic integrator.
+
+    This is constructed by composing three velocity Verlet steps with
+    appropriately chosen coefficients (`ALPHA`, `BETA`).
+
+    Parameters
+    ----------
+    q : NDArray[np.float64]
+        Current generalized coordinates.
+    p : NDArray[np.float64]
+        Current generalized momenta.
+    time_step : float
+        Integration time step.
+    grad_T : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the gradient of the kinetic energy with respect to `p`.
+    grad_V : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the gradient of the potential energy with respect to `q`.
+    parameters : NDArray[np.float64]
+        Additional parameters passed to `grad_T` and `grad_V`.
+
+    Returns
+    -------
+    q_new : NDArray[np.float64]
+        Updated generalized coordinates after one Yoshida step.
+    p_new : NDArray[np.float64]
+        Updated generalized momenta after one Yoshida step.
+    """
+    q_new, p_new = velocity_verlet_2nd_step(
+        q, p, ALPHA * time_step, grad_T, grad_V, parameters
+    )
+    q_new, p_new = velocity_verlet_2nd_step(
+        q_new, p_new, BETA * time_step, grad_T, grad_V, parameters
+    )
+    q_new, p_new = velocity_verlet_2nd_step(
+        q_new, p_new, ALPHA * time_step, grad_T, grad_V, parameters
+    )
+
+    return q_new, p_new
+
+
+@njit
+def yoshida_4th_step_tangent(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    dq: NDArray[np.float64],
+    dp: NDArray[np.float64],
+    time_step: float,
+    hess_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    hess_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    parameters: NDArray[np.float64],
+) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """
+    Perform one step of the tangent map associated with the Yoshida 4th-order integrator.
+
+    This evolves deviation vectors `(dq, dp)` along the flow of the Yoshida integrator,
+    which is useful for stability analysis and Lyapunov exponent computation.
+
+    Parameters
+    ----------
+    q : NDArray[np.float64]
+        Current generalized coordinates.
+    p : NDArray[np.float64]
+        Current generalized momenta.
+    dq : NDArray[np.float64]
+        Deviation in coordinates.
+    dp : NDArray[np.float64]
+        Deviation in momenta.
+    time_step : float
+        Integration time step.
+    hess_T : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the Hessian of the kinetic energy with respect to `p`.
+    hess_V : Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+        Function returning the Hessian of the potential energy with respect to `q`.
+    parameters : NDArray[np.float64]
+        Additional parameters passed to `hess_T` and `hess_V`.
+
+    Returns
+    -------
+    dq_new : NDArray[np.float64]
+        Updated deviation in coordinates after one Yoshida step.
+    dp_new : NDArray[np.float64]
+        Updated deviation in momenta after one Yoshida step.
+    """
+    dq_new, dp_new = velocity_verlet_2nd_step_tangent(
+        q, p, dq, dp, ALPHA * time_step, hess_T, hess_V, parameters
+    )
+    dq_new, dp_new = velocity_verlet_2nd_step_tangent(
+        q, p, dq_new, dp_new, BETA * time_step, hess_T, hess_V, parameters
+    )
+    dq_new, dp_new = velocity_verlet_2nd_step_tangent(
+        q, p, dq_new, dp_new, ALPHA * time_step, hess_T, hess_V, parameters
+    )
+
+    return dq_new, dp_new

pynamicalsys/hamiltonian_systems/trajectory_analysis.py

@@ -0,0 +1,293 @@
+# trajectory_analysis.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 Callable
+import numpy as np
+from numba import njit, prange
+from numpy.typing import NDArray
+
+
+@njit
+def generate_trajectory(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    total_time: np.float64,
+    parameters: NDArray[np.float64],
+    grad_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    grad_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    time_step: np.float64,
+    integrator: Callable[
+        [
+            NDArray[np.float64],
+            NDArray[np.float64],
+            float,
+            Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+            Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+            NDArray[np.float64],
+        ],
+        tuple[NDArray[np.float64], NDArray[np.float64]],
+    ],
+) -> NDArray[np.float64]:
+    """
+    Generate a single trajectory of a Hamiltonian system using a symplectic integrator.
+
+    Parameters
+    ----------
+    q : NDArray[np.float64], shape (dof,)
+        Initial generalized coordinates.
+    p : NDArray[np.float64], shape (dof,)
+        Initial generalized momenta.
+    total_time : float
+        Total integration time.
+    parameters : NDArray[np.float64]
+        Additional system parameters passed to `grad_T` and `grad_V`.
+    grad_T : Callable
+        Function returning the gradient of the kinetic energy with respect to `p`.
+    grad_V : Callable
+        Function returning the gradient of the potential energy with respect to `q`.
+    time_step : float
+        Integration step size.
+    integrator : Callable
+        Symplectic integrator function (e.g. `velocity_verlet_2nd_step`,
+        `yoshida_4th_step`).
+
+    Returns
+    -------
+    result : NDArray[np.float64], shape (num_steps+1, 2*dof+1)
+        Trajectory array:
+        - Column 0: time values.
+        - Columns 1..dof: generalized coordinates `q`.
+        - Columns dof+1..2*dof: generalized momenta `p`.
+    """
+    num_steps = round(total_time / time_step)
+    dof = len(q)
+    result = np.zeros((num_steps + 1, 2 * dof + 1))
+
+    result[0, 1 : dof + 1] = q
+    result[0, dof + 1 :] = p
+    for i in range(1, num_steps + 1):
+        q, p = integrator(q, p, time_step, grad_T, grad_V, parameters)
+        result[i, 0] = i * time_step
+        result[i, 1 : dof + 1] = q
+        result[i, dof + 1 :] = p
+
+    return result
+
+
+@njit(parallel=True)
+def ensemble_trajectories(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    total_time: np.float64,
+    parameters: NDArray[np.float64],
+    grad_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    grad_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    time_step: np.float64,
+    integrator: Callable,
+) -> NDArray[np.float64]:
+    """
+    Generate an ensemble of trajectories from multiple initial conditions.
+
+    Parameters
+    ----------
+    q : NDArray[np.float64], shape (num_ic, dof)
+        Initial coordinates for each trajectory.
+    p : NDArray[np.float64], shape (num_ic, dof)
+        Initial momenta for each trajectory.
+    total_time : float
+        Total integration time.
+    parameters : NDArray[np.float64]
+        Additional system parameters passed to `grad_T` and `grad_V`.
+    grad_T : Callable
+        Function returning the gradient of the kinetic energy with respect to `p`.
+    grad_V : Callable
+        Function returning the gradient of the potential energy with respect to `q`.
+    time_step : float
+        Integration step size.
+    integrator : Callable
+        Symplectic integrator function.
+
+    Returns
+    -------
+    trajectories : NDArray[np.float64], shape (num_ic, num_steps+1, 2*dof+1)
+        Array of trajectories for all initial conditions.
+    """
+    num_steps = round(total_time / time_step)
+    num_ic, dof = q.shape
+
+    trajectories = np.zeros((num_ic, num_steps + 1, 2 * dof + 1), dtype=np.float64)
+
+    for i in prange(num_ic):
+        trajectory = generate_trajectory(
+            q[i], p[i], total_time, parameters, grad_T, grad_V, time_step, integrator
+        )
+        trajectories[i] = trajectory
+
+    return trajectories
+
+
+@njit
+def generate_poincare_section(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    num_intersections: np.int32,
+    parameters: NDArray[np.float64],
+    grad_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    grad_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    time_step: np.float64,
+    integrator: Callable,
+    section_index: int = 0,
+    section_value: float = 0.0,
+    crossing: int = 1,
+) -> NDArray[np.float64]:
+    """
+    Generate a Poincaré section for a Hamiltonian system.
+
+    Parameters
+    ----------
+    q : NDArray[np.float64], shape (dof,)
+        Initial generalized coordinates.
+    p : NDArray[np.float64], shape (dof,)
+        Initial generalized momenta.
+    num_intersections : int
+        Total number of section crossings to record.
+    parameters : NDArray[np.float64]
+        Additional system parameters passed to `grad_T` and `grad_V`.
+    grad_T : Callable
+        Function returning the gradient of the kinetic energy with respect to `p`.
+    grad_V : Callable
+        Function returning the gradient of the potential energy with respect to `q`.
+    time_step : float
+        Integration step size.
+    integrator : Callable
+        Symplectic integrator function.
+    section_index : int, optional
+        Index of coordinate `q[i]` used to define the section (default 0).
+    section_value : float, optional
+        Value of `q[section_index]` defining the section (default 0.0).
+    crossing : int, optional
+        Crossing rule:
+        - +1 : only upward crossings (dq/dt > 0),
+        - -1 : only downward crossings (dq/dt < 0),
+        -  0 : count all crossings.
+
+    Returns
+    -------
+    section_points : NDArray[np.float64], shape (num_intersections, 2*dof)
+        Phase-space points `(q, p)` recorded at section crossings.
+    """
+    dof = len(q)
+    section_points = np.zeros((num_intersections, 2 * dof + 1))
+    count = 0
+    n_steps = 0
+    q_prev, p_prev = q.copy(), p.copy()
+    while count < num_intersections:
+        q_new, p_new = integrator(q_prev, p_prev, time_step, grad_T, grad_V, parameters)
+
+        # Check if crossing occurred
+        if (q_prev[section_index] - section_value) * (
+            q_new[section_index] - section_value
+        ) < 0.0:
+            lam = (section_value - q_prev[section_index]) / (
+                q_new[section_index] - q_prev[section_index]
+            )
+            q_cross = (1 - lam) * q_prev + lam * q_new
+            p_cross = (1 - lam) * p_prev + lam * p_new
+            t_cross = n_steps * time_step + lam * time_step
+
+            velocity = grad_T(p_cross, parameters)[section_index]
+
+            if crossing == 0 or np.sign(velocity) == crossing:
+                section_points[count, 0] = t_cross
+                section_points[count, 1 : dof + 1] = q_cross
+                section_points[count, dof + 1 :] = p_cross
+                count += 1
+
+        q_prev, p_prev = q_new, p_new
+        n_steps += 1
+
+    return section_points
+
+
+@njit(parallel=True)
+def ensemble_poincare_section(
+    q: NDArray[np.float64],
+    p: NDArray[np.float64],
+    num_intersections: int,
+    parameters: NDArray[np.float64],
+    grad_T: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    grad_V: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+    time_step: np.float64,
+    integrator: Callable,
+    section_index: int = 0,
+    section_value: float = 0.0,
+    crossing: int = 1,
+) -> NDArray[np.float64]:
+    """
+    Generate Poincaré sections for an ensemble of initial conditions.
+
+    Parameters
+    ----------
+    q : NDArray[np.float64], shape (num_ic, dof)
+        Initial coordinates for each trajectory.
+    p : NDArray[np.float64], shape (num_ic, dof)
+        Initial momenta for each trajectory.
+    num_intersections : int
+        Number of section crossings to record per trajectory.
+    parameters : NDArray[np.float64]
+        Additional system parameters.
+    grad_T : Callable
+        Gradient of kinetic energy with respect to `p`.
+    grad_V : Callable
+        Gradient of potential energy with respect to `q`.
+    time_step : float
+        Integration step size.
+    integrator : Callable
+        Symplectic integrator function.
+    section_index : int, optional
+        Index of coordinate `q[i]` used for the section (default 0).
+    section_value : float, optional
+        Value of `q[section_index]` defining the section (default 0.0).
+    crossing : int, optional
+        Crossing rule:
+        - +1 : upward crossings,
+        - -1 : downward crossings,
+        -  0 : all crossings.
+
+    Returns
+    -------
+    section_points : NDArray[np.float64], shape (num_ic, num_intersections, 2*dof + 1)
+        Poincaré section points for each initial condition with the first column being the time at each crossing.
+    """
+    num_ic, dof = q.shape
+    section_points = np.zeros((num_ic, num_intersections, 2 * dof + 1))
+    for i in prange(num_ic):
+        section_points[i] = generate_poincare_section(
+            q[i],
+            p[i],
+            num_intersections,
+            parameters,
+            grad_T,
+            grad_V,
+            time_step,
+            integrator,
+            section_index,
+            section_value,
+            crossing,
+        )
+
+    return section_points

pynamicalsys/hamiltonian_systems/validators.py

@@ -0,0 +1,114 @@
+# validators.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 numbers import Integral, Real
+from typing import Type, Union
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def validate_non_negative(
+    value: Union[Integral, int, Real, float],
+    name: str,
+    type_: Type[Union[Integral, int, Real, float]] = Integral,
+) -> None:
+    if not isinstance(value, type_):
+        raise TypeError(f"{name} must be of type {type_.__name__}")
+    if value < 0:
+        raise ValueError(f"{name} must be non-negative")
+
+
+def validate_times(transient_time, total_time) -> tuple[float, float]:
+
+    if isinstance(total_time, (Integral, Real)):
+        total_time = float(total_time)
+    else:
+        raise ValueError("total_time must be a valid number")
+    if total_time < 0:
+        raise ValueError("total_time must be non-negative")
+
+    if transient_time is not None:
+
+        if isinstance(transient_time, (Integral, Real)):
+            transient_time = float(transient_time)
+        else:
+            raise ValueError("transient_time must be a valid number")
+        if transient_time < 0:
+            raise ValueError("transient_time must be non-negative")
+
+        if transient_time >= total_time:
+            raise ValueError("transient_time must be less than total_time")
+
+    return transient_time, total_time
+
+
+def validate_initial_conditions(
+    u, degrees_of_freedom, allow_ensemble=True
+) -> NDArray[np.float64]:
+    if np.isscalar(u):
+        u = np.array([u], dtype=np.float64)
+    else:
+        u = np.asarray(u, dtype=np.float64)
+        if u.ndim not in (1, 2):
+            raise ValueError("Initial condition must be 1D or 2D array")
+
+    u = np.ascontiguousarray(u).copy()
+
+    if u.ndim == 1:
+        if len(u) != degrees_of_freedom:
+            raise ValueError(
+                f"1D initial condition must have length {degrees_of_freedom}"
+            )
+    elif u.ndim == 2:
+        if not allow_ensemble:
+            raise ValueError(
+                "Ensemble of initial conditions not allowed in this context"
+            )
+        if u.shape[1] != degrees_of_freedom:
+            raise ValueError(
+                f"Each initial condition must have length {degrees_of_freedom}"
+            )
+    return u
+
+
+def validate_parameters(parameters, number_of_parameters) -> NDArray[np.float64]:
+    if number_of_parameters == 0:
+        if parameters is not None:
+            raise ValueError("This system does not expect any parameters.")
+        return np.array([0], dtype=np.float64)
+
+    if parameters is None:
+        raise ValueError(
+            f"This system expects {number_of_parameters} parameter(s), but got None."
+        )
+
+    if np.isscalar(parameters):
+        parameters = np.array([parameters], dtype=np.float64)
+    else:
+        parameters = np.asarray(parameters, dtype=np.float64)
+        if parameters.ndim != 1:
+            raise ValueError(
+                f"`parameters` must be a 1D array or scalar. Got shape {parameters.shape}."
+            )
+
+    if parameters.size != number_of_parameters:
+        raise ValueError(
+            f"Expected {number_of_parameters} parameter(s), but got {parameters.size}."
+        )
+
+    return parameters