| Name | pyhamsys JSON |
| Version |
0.60
JSON |
| download |
| home_page | http://github.com/cchandre/pyhamsys |
| Summary | Some tools for Hamiltonian systems |
| upload_time | 2024-12-17 15:48:36 |
| maintainer | None |
| docs_url | None |
| author | Cristel Chandre |
| requires_python | >=3.6 |
| license | BSD 2-Clause License Copyright (c) 2023, Cristel Chandre Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
hamiltonian
symplectic integrators
ode solver
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pyHamSys
pyHamSys (short for Python Hamiltonian Systems) is a Python library for scientific computing involving Hamiltonian systems. It provides tools to model, analyze, and simulate Hamiltonian systems. In particular, the library offers a streamlined and user-friendly environment for implementing and running symplectic-split integrators. These specialized numerical methods are designed to preserve the geometric structure of Hamiltonian systems, ensuring accurate and stable simulations of their dynamics over long time periods.
## Installation
Installation within a Python virtual environment:
```
python3 -m pip install pyhamsys
```
For more information on creating a Python virtual environment, click [here](https://realpython.com/python-virtual-environments-a-primer/).
## Symplectic Integrators
pyHamSys features a dedicated class, `SymplecticIntegrator`, which provides a comprehensive implementation of symplectic-split integrators. These integrators are designed specifically for the numerical integration of Hamiltonian systems, ensuring the preservation of the symplectic structure of phase space—a key property that underpins the stability and accuracy of long-term simulations of such systems.
Symplectic-split integrators decompose the Hamiltonian into subcomponents that are individually solvable, allowing for efficient and accurate integration. This decomposition is particularly effective for complex or high-dimensional systems, as it minimizes numerical drift and conserves critical invariants like energy over extended time intervals.
The `SymplecticIntegrator` class offers a variety of splitting methods, enabling users to select the most appropriate scheme for their specific Hamiltonian system and computational requirements. Each integrator is implemented to handle both autonomous and non-autonomous systems, supporting applications in classical mechanics, molecular dynamics, astrophysics, and quantum mechanics.
- `Verlet` (order 2, all purpose), also referred to as Strang or Störmer-Verlet splitting
- From [Forest, Ruth, Physica D 43, 105 (1990)](https://doi.org/10.1016/0167-2789(90)90019-L):
- `FR` (order 4, all purpose)
- From [Yoshida, Phys. Lett. A 150, 262 (1990)](https://doi.org/10.1016/0375-9601(90)90092-3):
- `Yo#`: # should be replaced by an even integer, e.g., `Yo6` for 6th order symplectic integrator (all purpose)
- `Yos6`: (order 6, all purpose) optimized symplectic integrator (solution A from Table 1)
- From [McLachlan, SIAM J. Sci. Comp. 16, 151 (1995)](https://doi.org/10.1137/0916010):
- `M2` (order 2, all purpose)
- `M4` (order 4, all purpose)
- From [Omelyan, Mryglod, Folk, Comput. Phys. Commun. 146, 188 (2002)](https://doi.org/10.1016/S0010-4655(02)00451-4):
- `EFRL` (order 4) optimized for *H* = *A* + *B*
- `PEFRL` and `VEFRL` (order 4) optimized for *H* = *A*(*p*) + *B*(*q*). For `PEFRL`, *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>). For `VEFRL`, *chi* should be exp(*h* X<sub>B</sub>)exp(*h* X<sub>A</sub>).
- From [Blanes, Moan, J. Comput. Appl. Math. 142, 313 (2002)](https://doi.org/10.1016/S0377-0427(01)00492-7):
- `BM4` (order 4, all purpose) refers to S<sub>6</sub>
- `BM6` (order 6, all purpose) refers to S<sub>10</sub>
- `RKN4b` (order 4) refers to SRKN<sub>6</sub><sup>*b*</sup> optimized for *H* = *A*(*p*) + *B*(*q*). Here *chi* should be exp(*h* X<sub>B</sub>)exp(*h* X<sub>A</sub>).
- `RKN6b` (order 6) refers to SRKN<sub>11</sub><sup>*b*</sup> optimized for *H* = *A*(*p*) + *B*(*q*). Here *chi* should be exp(*h* X<sub>B</sub>)exp(*h* X<sub>A</sub>).
- `RKN6a` (order 6) refers to SRKN<sub>14</sub><sup>*a*</sup> optimized for *H* = *A*(*p*) + *B*(*q*). Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).
- From [Blanes, Casas, Farrés, Laskar, Makazaga, Murua, Appl. Numer. Math. 68, 58 (2013)](http://dx.doi.org/10.1016/j.apnum.2013.01.003):
- `ABA104` (order (10,4)) optimized for *H* = *A* + ε *B*. Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).
- `ABA864` (order (8,6,4)) optimized for *H* = *A* + ε *B*. Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).
- `ABA1064` (order (10,6,4)) optimized for *H* = *A* + ε *B*. Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).
All purpose integrators are for any splitting of the Hamiltonian *H*=∑<sub>*k*</sub> *A*<sub>*k*</sub> in any order of the functions *A*<sub>*k*</sub>. Otherwise, the order of the operators is specified for each integrator. These integrators are used in the functions `solve_ivp_symp` and `solve_ivp_sympext` by specifying the entry `method` (default is `BM4`).
----
## HamSys class
The `HamSys` class provides a robust framework for defining and integrating Hamiltonian systems. It allows users to specify the number of degrees of freedom, coordinate representations, and key attributes like the Hamiltonian and associated equations of motion.
### Parameters
- `ndof` : integer or half-integer, optional
The number of degrees of freedom in the Hamiltonian system. Half integers denote an explicit time dependence. Default is 1.
- `complex` : bool, optional
If False, the dynamical variables (*q*, *p*) are real and canonically conjugate. If True, the dynamical variables are (ψ, ψ<sup>*</sup>) where $\psi=(q + i p)/\sqrt{2}$. Default is False.
### Parameters and Attributes
- `y_dot` : callable, optional
A function of (*t*, *y*) which returns {*y*,*H*(*t*,*y*)} where *y* is the state vector and *H* is the Hamiltonian. In (real) canonical coordinates (used, e.g., in `solve_ivp_sympext`) where *y* = (*q*, *p*), this function returns (∂*H*/∂*p*, -∂*H*/∂*q*). In complex coordinate ψ, this function returns -i ∂*H*/∂ψ<sup>*</sup>. For practical implementation, the state vector *y* should be represented as a one-dimensional array with a shape of (*n*,), where *n* denotes the total number of dynamical variables in the system. This ensures compatibility with numerical solvers and facilitates efficient computation of the system's evolution.
- `k_dot` : callable, optional
A function of (*t*, *y*) which returns {*k*,*H*(*t*,*y*)} = -∂*H*/∂*t* where *k* is canonically conjugate to *t* and *H* is the Hamiltonian.
- `hamiltonian` : callable, optional
A function of (*t*, *y*) which returns the Hamiltonian *H*(*t*,*y*) where *y* is the state vector.
### Functions
- `compute_vector_field` : from a callable function (Hamiltonian in canonical coordinates) written with symbolic variables ([SymPy](https://www.sympy.org/en/index.html)), computes the vector fields, `y_dot` and `k_dot`.
Determine Hamilton's equations of motion from a given scalar function –the Hamiltonian– *H*(*q*, *p*, *t*) where *q* and *p* are respectively positions and momenta. However, it is preferrable to code explicitly and optimize `y_dot` and `k_dot`.
#### Parameters
- `hamiltonian` : callable
Function *H*(*q*, *p*, *t*) –the Hamiltonian expressed in symbolic variables–, expressed using [SymPy](https://www.sympy.org/en/index.html) functions.
- `output` : bool, optional
If True, displays the equations of motion. Default is False.
The function `compute_vector_field` determines the HamSys function attributes `y_dot` and `k_dot` to be used in `solve_ivp_sympext`. The derivatives are computed symbolically using SymPy.
- `compute_energy` : callable
A function of `sol` –a solution provided by `solve_ivp_sympext`– and a boolean `maxerror`. If `maxerror`is `True` the function `compute_energy` returns the maximum error in total energy; otherwise, it returns all the values of the total energy.
#### Parameters
- `sol` : OdeSolution
Solution provided by `solve_ivp_sympext`.
- `maxerror` : bool, optional
Default is True.
---
## solve_ivp_symp and solve_ivp_sympext
The functions `solve_ivp_symp` and `solve_ivp_sympext` solve an initial value problem for a Hamiltonian system using an element of the class SymplecticIntegrator, an explicit symplectic splitting scheme (see [1]). These functions numerically integrate a system of ordinary differential equations given an initial value:
d*y* / d*t* = {*y*, *H*(*t*, *y*)}
*y*(*t*<sub>0</sub>) = *y*<sub>0</sub>
Here *t* is a 1-D independent variable (time), *y*(*t*) is an N-D vector-valued function (state). A Hamiltonian *H*(*t*, *y*) and a Poisson bracket {. , .} determine the differential equations. The goal is to find *y*(*t*) approximately satisfying the differential equations, given an initial value *y*(*t*<sub>0</sub>) = *y*<sub>0</sub>.
The function `solve_ivp_symp` solves an initial value problem using an explicit symplectic integration. The Hamiltonian flow is defined by two functions `chi` and `chi_star` of (*h*, *t*, *y*) (see [2]). This function works for any set of coordinates, canonical or non-canonical, provided that the splitting *H*=∑<sub>*k*</sub> *A*<sub>*k*</sub> leads to facilitated expressions for the operators exp(*h* X<sub>*k*</sub>) where X<sub>*k*</sub> = {*A*<sub>*k*</sub> , ·}.
The function `solve_ivp_sympext` solves an initial value problem using an explicit symplectic approximation obtained by an extension in phase space (see [3]). This symplectic approximation works for canonical Poisson brackets, and the state vector should be of the form *y* = (*q*, *p*).
### Parameters:
- `chi` (for `solve_ivp_symp`) : callable
Function of (*h*, *t*, *y*) returning exp(*h* X<sub>*n*</sub>)...exp(*h* X<sub>1</sub>) *y* at time *t*. If the selected integrator is not all purpose, refer to the list above for the specific ordering of the operators. The operator X<sub>*k*</sub> is the Liouville operator associated with the function *A*<sub>*k*</sub>, i.e., for Hamiltonian flows X<sub>*k*</sub> = {*A*<sub>*k*</sub> , ·} where {· , ·} is the Poisson bracket.
`chi` must return an array of the same shape as `y`.
- `chi_star` (for `solve_ivp_symp`) : callable
Function of (*h*, *t*, *y*) returning exp(*h* X<sub>1</sub>)...exp(*h* X<sub>*n*</sub>) *y* at time *t*.
`chi_star` must return an array of the same shape as `y`.
- `hs` (for `solve_ivp_sympext`) : element of class HamSys
The attribute `y_dot` of `hs` should be defined. If `check_energy` is True, the attribute `hamiltonian` and if the Hamiltonian system has an explicit time dependence (i.e., the parameter `ndof` of `hs` is a half-integer), the attribute `k_dot` of `hs` should be specified.
- `t_span` : 2-member sequence
Interval of integration (*t*<sub>0</sub>, *t*<sub>f</sub>). The solver starts with *t*=*t*<sub>0</sub> and integrates until it reaches *t*=*t*<sub>f</sub>. Both *t*<sub>0</sub> and *t*<sub>f</sub> must be floats or values interpretable by the float conversion function.
- `y0` : array_like
Initial state. For `solve_ivp_sympext`, the vector `y0` should be with shape (n,).
- `step` : float
Step size.
- `t_eval` : array_like or None, optional
Times at which to store the computed solution, must be sorted, and lie within `t_span`. If None (default), use points selected by the solver.
- `method` : string, optional
Integration methods are listed on [pyhamsys](https://pypi.org/project/pyhamsys/). Default is 'BM4'.
- `omega` (for `solve_ivp_sympext`) : float, optional
Coupling parameter in the extended phase space (see [3]). Default is 10.
- `command` : void function of (*t*, *y*), optional
Void function to be run at each step size (e.g., plotting an observable associated with the state vector *y*, modify global or mutable variables, or register specific events).
- `check_energy` (for `solve_ivp_sympext`) : bool, optional
If True, the attribute `hamiltonian` of `hs` should be defined. Default is False.
### Returns:
Bunch object with the following fields defined:
- `t` : ndarray, shape (n_points,)
Time points.
- `y` : ndarray, shape y0.shape + (n_points,)
Values of the solution `y` at `t`.
- `k` (for `solve_ivp_sympext`) : ndarray, shape (n_points,)
Values of `k` at `t`. Only for `solve_ivp_sympext` and if `check_energy` is True for a Hamiltonian system with an explicit time dependence (i.e., the parameter `ndof` of `hs` is half an integer).
- `err` (for `solve_ivp_sympext`) : float
Error in the computation of the total energy. Only for `solve_ivp_sympext` and if `check_energy` is True.
- `step` : step size used in the computation.
### Remarks:
- Use `solve_ivp_symp` if the Hamiltonian can be split and if each partial operator exp(*h* X<sub>*k*</sub>) can be easily and explicitly expressed/computed. Otherwise use `solve_ivp_sympext` if your coordinates are canonical, i.e., in $(q,p)$ or $(\psi,\psi^*)$ variables.
- The step size is slightly readjusted so that the final time *t*<sub>f</sub> corresponds to an integer number of step sizes. The step size used in the computation is recorded in the solution as `sol.step`.
- For integrating multiple trajectories at the same time, extend phase space and define a state vector y = (y<sub>1</sub>, y<sub>2</sub>,...y<sub>N</sub>) where N is the number of trajectories. The Hamiltonian is given by $H(t,\mathbf{y})=\sum_{i=1}^N h(t, y_i)$.
### References:
- [1] Hairer, Lubich, Wanner, 2003, *Geometric Numerical Integration: Structure-Preserving Algorithms for Ordinary Differential Equations* (Springer)
- [2] McLachlan, *Tuning symplectic integrators is easy and worthwhile*, Commun. Comput. Phys. 31, 987 (2022); [arxiv:2104.10269](https://arxiv.org/abs/2104.10269)
- [3] Tao, M., *Explicit symplectic approximation of nonseparable Hamiltonians: Algorithm and long time performance*, Phys. Rev. E 94, 043303 (2016)
### Example
```python
import numpy as xp
import sympy as sp
import matplotlib.pyplot as plt
from pyhamsys import HamSys, solve_ivp_sympext
hs = HamSys()
hamiltonian = lambda q, p, t: p**2 / 2 - sp.cos(q)
hs.compute_vector_field(hamiltonian, output=True)
sol = solve_ivp_sympext(hs, (0, 20), xp.asarray([3, 0]), step=1e-1, check_energy=True)
print(f"Error in energy : {sol.err}")
plt.plot(sol.y[0], sol.y[1])
plt.show()
```
For more examples, see the folder [Examples](https://github.com/cchandre/pyhamsys/tree/main/Examples)
---
For more information: <cristel.chandre@cnrs.fr>
Raw data
{
"_id": null,
"home_page": "http://github.com/cchandre/pyhamsys",
"name": "pyhamsys",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "Cristel Chandre <cristel.chandre@cnrs.fr>",
"keywords": "Hamiltonian, symplectic integrators, ODE solver",
"author": "Cristel Chandre",
"author_email": "Cristel Chandre <cristel.chandre@cnrs.fr>",
"download_url": "https://files.pythonhosted.org/packages/d9/25/8394034e71f59f8ecfa9bc3b0d2becb0f985d87a500a58bf94620c89b756/pyhamsys-0.60.tar.gz",
"platform": null,
"description": "# pyHamSys\npyHamSys (short for Python Hamiltonian Systems) is a Python library for scientific computing involving Hamiltonian systems. It provides tools to model, analyze, and simulate Hamiltonian systems. In particular, the library offers a streamlined and user-friendly environment for implementing and running symplectic-split integrators. These specialized numerical methods are designed to preserve the geometric structure of Hamiltonian systems, ensuring accurate and stable simulations of their dynamics over long time periods. \n\n\n\n\n## Installation \nInstallation within a Python virtual environment: \n```\npython3 -m pip install pyhamsys\n```\nFor more information on creating a Python virtual environment, click [here](https://realpython.com/python-virtual-environments-a-primer/).\n\n## Symplectic Integrators\n\npyHamSys features a dedicated class, `SymplecticIntegrator`, which provides a comprehensive implementation of symplectic-split integrators. These integrators are designed specifically for the numerical integration of Hamiltonian systems, ensuring the preservation of the symplectic structure of phase space\u2014a key property that underpins the stability and accuracy of long-term simulations of such systems.\nSymplectic-split integrators decompose the Hamiltonian into subcomponents that are individually solvable, allowing for efficient and accurate integration. This decomposition is particularly effective for complex or high-dimensional systems, as it minimizes numerical drift and conserves critical invariants like energy over extended time intervals.\nThe `SymplecticIntegrator` class offers a variety of splitting methods, enabling users to select the most appropriate scheme for their specific Hamiltonian system and computational requirements. Each integrator is implemented to handle both autonomous and non-autonomous systems, supporting applications in classical mechanics, molecular dynamics, astrophysics, and quantum mechanics.\n\n\n- `Verlet` (order 2, all purpose), also referred to as Strang or St\u00f6rmer-Verlet splitting \n- From [Forest, Ruth, Physica D 43, 105 (1990)](https://doi.org/10.1016/0167-2789(90)90019-L): \n - `FR` (order 4, all purpose)\n- From [Yoshida, Phys. Lett. A 150, 262 (1990)](https://doi.org/10.1016/0375-9601(90)90092-3):\n - `Yo#`: # should be replaced by an even integer, e.g., `Yo6` for 6th order symplectic integrator (all purpose)\n - `Yos6`: (order 6, all purpose) optimized symplectic integrator (solution A from Table 1)\n- From [McLachlan, SIAM J. Sci. Comp. 16, 151 (1995)](https://doi.org/10.1137/0916010):\n - `M2` (order 2, all purpose)\n - `M4` (order 4, all purpose)\n- From [Omelyan, Mryglod, Folk, Comput. Phys. Commun. 146, 188 (2002)](https://doi.org/10.1016/S0010-4655(02)00451-4): \n - `EFRL` (order 4) optimized for *H* = *A* + *B*\n - `PEFRL` and `VEFRL` (order 4) optimized for *H* = *A*(*p*) + *B*(*q*). For `PEFRL`, *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>). For `VEFRL`, *chi* should be exp(*h* X<sub>B</sub>)exp(*h* X<sub>A</sub>).\n- From [Blanes, Moan, J. Comput. Appl. Math. 142, 313 (2002)](https://doi.org/10.1016/S0377-0427(01)00492-7):\n - `BM4` (order 4, all purpose) refers to S<sub>6</sub> \n - `BM6` (order 6, all purpose) refers to S<sub>10</sub>\n - `RKN4b` (order 4) refers to SRKN<sub>6</sub><sup>*b*</sup> optimized for *H* = *A*(*p*) + *B*(*q*). Here *chi* should be exp(*h* X<sub>B</sub>)exp(*h* X<sub>A</sub>).\n - `RKN6b` (order 6) refers to SRKN<sub>11</sub><sup>*b*</sup> optimized for *H* = *A*(*p*) + *B*(*q*). Here *chi* should be exp(*h* X<sub>B</sub>)exp(*h* X<sub>A</sub>).\n - `RKN6a` (order 6) refers to SRKN<sub>14</sub><sup>*a*</sup> optimized for *H* = *A*(*p*) + *B*(*q*). Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).\n- From [Blanes, Casas, Farr\u00e9s, Laskar, Makazaga, Murua, Appl. Numer. Math. 68, 58 (2013)](http://dx.doi.org/10.1016/j.apnum.2013.01.003):\n - `ABA104` (order (10,4)) optimized for *H* = *A* + ε *B*. Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).\n - `ABA864` (order (8,6,4)) optimized for *H* = *A* + ε *B*. Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).\n - `ABA1064` (order (10,6,4)) optimized for *H* = *A* + ε *B*. Here *chi* should be exp(*h* X<sub>A</sub>)exp(*h* X<sub>B</sub>).\n \nAll purpose integrators are for any splitting of the Hamiltonian *H*=∑<sub>*k*</sub> *A*<sub>*k*</sub> in any order of the functions *A*<sub>*k*</sub>. Otherwise, the order of the operators is specified for each integrator. These integrators are used in the functions `solve_ivp_symp` and `solve_ivp_sympext` by specifying the entry `method` (default is `BM4`). \n\n----\n## HamSys class \nThe `HamSys` class provides a robust framework for defining and integrating Hamiltonian systems. It allows users to specify the number of degrees of freedom, coordinate representations, and key attributes like the Hamiltonian and associated equations of motion.\n\n### Parameters\n- `ndof` : integer or half-integer, optional \n \tThe number of degrees of freedom in the Hamiltonian system. Half integers denote an explicit time dependence. Default is 1. \n- `complex` : bool, optional \n\tIf False, the dynamical variables (*q*, *p*) are real and canonically conjugate. If True, the dynamical variables are (ψ, ψ<sup>*</sup>) where $\\psi=(q + i p)/\\sqrt{2}$. Default is False.\n\n### Parameters and Attributes\n- `y_dot` : callable, optional \n \tA function of (*t*, *y*) which returns {*y*,*H*(*t*,*y*)} where *y* is the state vector and *H* is the Hamiltonian. In (real) canonical coordinates (used, e.g., in `solve_ivp_sympext`) where *y* = (*q*, *p*), this function returns (∂*H*/∂*p*, -∂*H*/∂*q*). In complex coordinate ψ, this function returns -i ∂*H*/∂ψ<sup>*</sup>. For practical implementation, the state vector *y* should be represented as a one-dimensional array with a shape of (*n*,), where *n* denotes the total number of dynamical variables in the system. This ensures compatibility with numerical solvers and facilitates efficient computation of the system's evolution. \n- `k_dot` : callable, optional \n\tA function of (*t*, *y*) which returns {*k*,*H*(*t*,*y*)} = -∂*H*/∂*t* where *k* is canonically conjugate to *t* and *H* is the Hamiltonian.\n- `hamiltonian` : callable, optional \n\tA function of (*t*, *y*) which returns the Hamiltonian *H*(*t*,*y*) where *y* is the state vector.\n\n### Functions\n- `compute_vector_field` : from a callable function (Hamiltonian in canonical coordinates) written with symbolic variables ([SymPy](https://www.sympy.org/en/index.html)), computes the vector fields, `y_dot` and `k_dot`.\n\n\tDetermine Hamilton's equations of motion from a given scalar function –the Hamiltonian– *H*(*q*, *p*, *t*) where *q* and *p* are respectively positions and momenta. However, it is preferrable to code explicitly and optimize `y_dot` and `k_dot`.\n\n\t#### Parameters\n\t- `hamiltonian` : callable \n\t\tFunction *H*(*q*, *p*, *t*) –the Hamiltonian expressed in symbolic variables–, expressed using [SymPy](https://www.sympy.org/en/index.html) functions.\n\t- `output` : bool, optional \n\t\tIf True, displays the equations of motion. Default is False.\n\t\n\tThe function `compute_vector_field` determines the HamSys function attributes `y_dot` and `k_dot` to be used in `solve_ivp_sympext`. The derivatives are computed symbolically using SymPy.\n\n- `compute_energy` : callable \n \tA function of `sol` –a solution provided by `solve_ivp_sympext`– and a boolean `maxerror`. If `maxerror`is `True` the function `compute_energy` returns the maximum error in total energy; otherwise, it returns all the values of the total energy. \n\t#### Parameters\n\t- `sol` : OdeSolution \n \t\tSolution provided by `solve_ivp_sympext`. \n \t- `maxerror` : bool, optional \n \t\tDefault is True.\n\n---\n## solve_ivp_symp and solve_ivp_sympext\n\nThe functions `solve_ivp_symp` and `solve_ivp_sympext` solve an initial value problem for a Hamiltonian system using an element of the class SymplecticIntegrator, an explicit symplectic splitting scheme (see [1]). These functions numerically integrate a system of ordinary differential equations given an initial value: \n\t d*y* / d*t* = {*y*, *H*(*t*, *y*)} \n\t *y*(*t*<sub>0</sub>) = *y*<sub>0</sub> \nHere *t* is a 1-D independent variable (time), *y*(*t*) is an N-D vector-valued function (state). A Hamiltonian *H*(*t*, *y*) and a Poisson bracket {. , .} determine the differential equations. The goal is to find *y*(*t*) approximately satisfying the differential equations, given an initial value *y*(*t*<sub>0</sub>) = *y*<sub>0</sub>. \n\nThe function `solve_ivp_symp` solves an initial value problem using an explicit symplectic integration. The Hamiltonian flow is defined by two functions `chi` and `chi_star` of (*h*, *t*, *y*) (see [2]). This function works for any set of coordinates, canonical or non-canonical, provided that the splitting *H*=∑<sub>*k*</sub> *A*<sub>*k*</sub> leads to facilitated expressions for the operators exp(*h* X<sub>*k*</sub>) where X<sub>*k*</sub> = {*A*<sub>*k*</sub> , ·}.\n\nThe function `solve_ivp_sympext` solves an initial value problem using an explicit symplectic approximation obtained by an extension in phase space (see [3]). This symplectic approximation works for canonical Poisson brackets, and the state vector should be of the form *y* = (*q*, *p*). \n\n### Parameters: \n\n - `chi` (for `solve_ivp_symp`) : callable \n\tFunction of (*h*, *t*, *y*) returning exp(*h* X<sub>*n*</sub>)...exp(*h* X<sub>1</sub>) *y* at time *t*. If the selected integrator is not all purpose, refer to the list above for the specific ordering of the operators. The operator X<sub>*k*</sub> is the Liouville operator associated with the function *A*<sub>*k*</sub>, i.e., for Hamiltonian flows X<sub>*k*</sub> = {*A*<sub>*k*</sub> , ·} where {· , ·} is the Poisson bracket.\n\t`chi` must return an array of the same shape as `y`.\n - `chi_star` (for `solve_ivp_symp`) : callable \n\tFunction of (*h*, *t*, *y*) returning exp(*h* X<sub>1</sub>)...exp(*h* X<sub>*n*</sub>) *y* at time *t*.\n\t`chi_star` must return an array of the same shape as `y`.\n - `hs` (for `solve_ivp_sympext`) : element of class HamSys \n\tThe attribute `y_dot` of `hs` should be defined. If `check_energy` is True, the attribute `hamiltonian` and if the Hamiltonian system has an explicit time dependence (i.e., the parameter `ndof` of `hs` is a half-integer), the attribute `k_dot` of `hs` should be specified. \n - `t_span` : 2-member sequence \n\tInterval of integration (*t*<sub>0</sub>, *t*<sub>f</sub>). The solver starts with *t*=*t*<sub>0</sub> and integrates until it reaches *t*=*t*<sub>f</sub>. Both *t*<sub>0</sub> and *t*<sub>f</sub> must be floats or values interpretable by the float conversion function.\t\n - `y0` : array_like \n\tInitial state. For `solve_ivp_sympext`, the vector `y0` should be with shape (n,).\n - `step` : float \n\tStep size.\n - `t_eval` : array_like or None, optional \n\tTimes at which to store the computed solution, must be sorted, and lie within `t_span`. If None (default), use points selected by the solver.\n - `method` : string, optional \n \tIntegration methods are listed on [pyhamsys](https://pypi.org/project/pyhamsys/). Default is 'BM4'.\n - `omega` (for `solve_ivp_sympext`) : float, optional \n \tCoupling parameter in the extended phase space (see [3]). Default is 10.\n - `command` : void function of (*t*, *y*), optional \n\tVoid function to be run at each step size (e.g., plotting an observable associated with the state vector *y*, modify global or mutable variables, or register specific events).\n - `check_energy` (for `solve_ivp_sympext`) : bool, optional \n\tIf True, the attribute `hamiltonian` of `hs` should be defined. Default is False. \n\n### Returns: \n Bunch object with the following fields defined:\n - `t` : ndarray, shape (n_points,) \n\tTime points.\n - `y` : ndarray, shape y0.shape + (n_points,) \n\tValues of the solution `y` at `t`.\n - `k` (for `solve_ivp_sympext`) : ndarray, shape (n_points,) \n \tValues of `k` at `t`. Only for `solve_ivp_sympext` and if `check_energy` is True for a Hamiltonian system with an explicit time dependence (i.e., the parameter `ndof` of `hs` is half an integer).\n - `err` (for `solve_ivp_sympext`) : float \n \tError in the computation of the total energy. Only for `solve_ivp_sympext` and if `check_energy` is True.\n - `step` : step size used in the computation.\n\n### Remarks: \n - Use `solve_ivp_symp` if the Hamiltonian can be split and if each partial operator exp(*h* X<sub>*k*</sub>) can be easily and explicitly expressed/computed. Otherwise use `solve_ivp_sympext` if your coordinates are canonical, i.e., in $(q,p)$ or $(\\psi,\\psi^*)$ variables. \n - The step size is slightly readjusted so that the final time *t*<sub>f</sub> corresponds to an integer number of step sizes. The step size used in the computation is recorded in the solution as `sol.step`.\n - For integrating multiple trajectories at the same time, extend phase space and define a state vector y = (y<sub>1</sub>, y<sub>2</sub>,...y<sub>N</sub>) where N is the number of trajectories. The Hamiltonian is given by $H(t,\\mathbf{y})=\\sum_{i=1}^N h(t, y_i)$.\n\n### References: \n - [1] Hairer, Lubich, Wanner, 2003, *Geometric Numerical Integration: Structure-Preserving Algorithms for Ordinary Differential Equations* (Springer) \n - [2] McLachlan, *Tuning symplectic integrators is easy and worthwhile*, Commun. Comput. Phys. 31, 987 (2022); [arxiv:2104.10269](https://arxiv.org/abs/2104.10269) \n - [3] Tao, M., *Explicit symplectic approximation of nonseparable Hamiltonians: Algorithm and long time performance*, Phys. Rev. E 94, 043303 (2016)\n\n### Example\n\n```python\nimport numpy as xp\nimport sympy as sp\nimport matplotlib.pyplot as plt\nfrom pyhamsys import HamSys, solve_ivp_sympext\nhs = HamSys()\nhamiltonian = lambda q, p, t: p**2 / 2 - sp.cos(q)\nhs.compute_vector_field(hamiltonian, output=True)\nsol = solve_ivp_sympext(hs, (0, 20), xp.asarray([3, 0]), step=1e-1, check_energy=True)\nprint(f\"Error in energy : {sol.err}\")\nplt.plot(sol.y[0], sol.y[1])\nplt.show()\n```\nFor more examples, see the folder [Examples](https://github.com/cchandre/pyhamsys/tree/main/Examples)\n\n---\nFor more information: <cristel.chandre@cnrs.fr>\n",
"bugtrack_url": null,
"license": "BSD 2-Clause License Copyright (c) 2023, Cristel Chandre Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "Some tools for Hamiltonian systems",
"version": "0.60",
"project_urls": {
"GitHub": "http://github.com/cchandre/pyhamsys",
"Homepage": "http://github.com/cchandre/pyhamsys"
},
"split_keywords": [
"hamiltonian",
" symplectic integrators",
" ode solver"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e44f75228e2cca33adc2417e7d25aa4c528c5a88523d72fef0aa2877ab8097f2",
"md5": "0c2ed1e56e91c93dd37a2bfc49360f3b",
"sha256": "df159e3a2246225098bffd6ba56b53f69893adf0d76a8d8053c527a2d335a06f"
},
"downloads": -1,
"filename": "pyhamsys-0.60-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c2ed1e56e91c93dd37a2bfc49360f3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 15831,
"upload_time": "2024-12-17T15:48:34",
"upload_time_iso_8601": "2024-12-17T15:48:34.291588Z",
"url": "https://files.pythonhosted.org/packages/e4/4f/75228e2cca33adc2417e7d25aa4c528c5a88523d72fef0aa2877ab8097f2/pyhamsys-0.60-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d9258394034e71f59f8ecfa9bc3b0d2becb0f985d87a500a58bf94620c89b756",
"md5": "d4615244973872bad683f0c233638505",
"sha256": "cfbcd2d0ff09ceb67e212f5ced240d4b5bc8d2b15e7050865842b24ed91cd02e"
},
"downloads": -1,
"filename": "pyhamsys-0.60.tar.gz",
"has_sig": false,
"md5_digest": "d4615244973872bad683f0c233638505",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15756,
"upload_time": "2024-12-17T15:48:36",
"upload_time_iso_8601": "2024-12-17T15:48:36.759375Z",
"url": "https://files.pythonhosted.org/packages/d9/25/8394034e71f59f8ecfa9bc3b0d2becb0f985d87a500a58bf94620c89b756/pyhamsys-0.60.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 15:48:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cchandre",
"github_project": "pyhamsys",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyhamsys"
}
