Package: pyhamsys
pyHamSyspyHamSys is a Python package for scientific computing involving Hamiltonian systemsInstallation:pip install pyhamsysSymplectic IntegratorspyHamSys includes a class SymplecticIntegrator containing the following symplectic splitting integrators:Verlet(order 2, all purpose), also referred to as Strang or Störmer-Verlet splittingFromForest, Ruth, Physica D 43, 105 (1990):FR(order 4, all purpose)FromYoshida, Phys. Lett. A 150, 262 (1990):Yo#: # should be replaced by an even integer, e.g.,Yo6for 6th order symplectic integrator (all purpose)Yos6: (order 6, all purpose) optimized symplectic integrator (solution A from Table 1)FromMcLachlan, SIAM J. Sci. Comp. 16, 151 (1995):M2(order 2, all purpose)M4(order 4, all purpose)FromOmelyan, Mryglod, Folk, Comput. Phys. Commun. 146, 188 (2002):EFRL(order 4) optimized forH=A+BPEFRLandVEFRL(order 4) optimized forH=A(p) +B(q). ForPEFRL,chishould be exp(hXA)exp(hXB). ForVEFRL,chishould be exp(hXB)exp(hXA).FromBlanes, Moan, J. Comput. Appl. Math. 142, 313 (2002):BM4(order 4, all purpose) refers to S6BM6(order 6, all purpose) refers to S10RKN4b(order 4) refers to SRKN6boptimized forH=A(p) +B(q). Herechishould be exp(hXB)exp(hXA).RKN6b(order 6) refers to SRKN11boptimized forH=A(p) +B(q). Herechishould be exp(hXB)exp(hXA).RKN6a(order 6) refers to SRKN14aoptimized forH=A(p) +B(q). Herechishould be exp(hXA)exp(hXB).FromBlanes, Casas, Farrés, Laskar, Makazaga, Murua, Appl. Numer. Math. 68, 58 (2013):ABA104(order (10,4)) optimized forH=A+ εB. Herechishould be exp(hXA)exp(hXB).ABA864(order (8,6,4)) optimized forH=A+ εB. Herechishould be exp(hXA)exp(hXB).ABA1064(order (10,6,4)) optimized forH=A+ εB. Herechishould be exp(hXA)exp(hXB).All purpose integrators are for any splitting of the HamiltonianH=∑kAkin any order of the functionsAk. Otherwise, the order of the operators is specified for each integrator. These integrators are used in the functionssolve_ivp_sympandsolve_ivp_sympextby specifying the entrymethod(default isBM4).HamSys classParametersndof: number of degrees of freedom of the Hamiltonian system
'ndof' should be an integer or half an integer. Half integers denote an explicit time dependence.Attributeshamiltonian: callableA function of (t,y) which returns the HamiltonianH(t,y) whereyis the state vector.y_dot: callableA function of (t,y) which returns {y,H(t,y)} whereyis the state vector andHis the Hamiltonian. In canonical coordinates (used, e.g., insolve_ivp_sympext) wherey= (q,p), this function returns (∂H/∂p, -∂H/∂q).k_dot: callableA function of (t,y) which returns {k,H(t,y)} = -∂H/∂twherekis canonically conjugate totandHis the Hamiltonian.Functionscompute_vector_field: from a callable function (Hamiltonian in canonical coordinates) written with symbolic variables (SymPy), computes the vector fields,y_dotandk_dot.Determine Hamilton's equations of motion from a given scalar function –the Hamiltonian–H(q,p,t) whereqandpare respectively positions and momenta.Parametershamiltonian: callable
FunctionH(q,p,t) –the Hamiltonian expressed in symbolic variables–, expressed usingSymPyfunctions.output: bool, optional
If True, displays the equations of motion. Default is False.The functioncompute_vector_fielddetermines the HamSys function attributesy_dotandk_dotto be used insolve_ivp_sympext. The derivatives are computed symbolically using SymPy.compute_energy: callable
A function ofsol–a solution provided bysolve_ivp_sympext– andmaxerror, a boolean indicating whether the maximum error in total energy is given (if True) or all the values of the total energy (if False).Parameterssol: OdeSolutionSolution provided bysolve_ivp_sympext.maxerror: bool, optionalDefault is True.solve_ivp_symp and solve_ivp_sympextThe functionssolve_ivp_sympandsolve_ivp_sympextsolve 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:dy/ dt= {y,H(t,y)}y(t0) =y0Heretis a 1-D independent variable (time),y(t) is an N-D vector-valued function (state). A HamiltonianH(t,y) and a Poisson bracket {. , .} determine the differential equations. The goal is to findy(t) approximately satisfying the differential equations, given an initial valuey(t0) =y0.The functionsolve_ivp_sympsolves an initial value problem using an explicit symplectic integration. The Hamiltonian flow is defined by two functionschiandchi_starof (h,t,y) (see [2]). This function works for any set of coordinates, canonical or non-canonical, provided that the splittingH=∑kAkleads to facilitated expressions for the operators exp(hXk) where Xk= {Ak, ·}.The functionsolve_ivp_sympextsolves 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 formy= (q,p).Parameters:chi(forsolve_ivp_symp) : callableFunction of (h,t,y) returning exp(hXn)...exp(hX1)yat timet. If the selected integrator is not all purpose, refer to the list above for the specific ordering of the operators. The operator Xkis the Liouville operator associated with the functionAk, i.e., for Hamiltonian flows Xk= {Ak, ·} where {· , ·} is the Poisson bracket.chimust return an array of the same shape asy.chi_star(forsolve_ivp_symp) : callableFunction of (h,t,y) returning exp(hX1)...exp(hXn)yat timet.chi_starmust return an array of the same shape asy.hs(forsolve_ivp_sympext) : element of class HamSysThe attributesy_dotofhsshould be defined. Ifcheck_energyis True. It the Hamiltonian system has an explicit time dependence (i.e., the parameterndofofhsis half an integer), the attributek_dotofhsshould be specified.t_span: 2-member sequenceInterval of integration (t0,tf). The solver starts witht=t0and integrates until it reachest=tf. Botht0andtfmust be floats or values interpretable by the float conversion function.y0: array_like, shape (n,)Initial state.step: floatStep size.t_eval: array_like or None, optionalTimes at which to store the computed solution, must be sorted and equally spaced, and lie withint_span. If None (default), use points selected by the solver.method: string, optionalIntegration methods are listed onpyhamsys.'BM4' is the default.omega(forsolve_ivp_sympext) : float, optionalCoupling parameter in the extended phase space (see [3]). Default = 10.command: function of (t,y)Function to be run at each step size (e.g., plotting an observable associated with the state vectory, or register specific events).check_energy(forsolve_ivp_sympext) : bool, optionalIf True, the attributehamiltonianofhsshould be defined. Default is False.Returns:Bunch object with the following fields defined:t: ndarray, shape (n_points,)Time points.y: ndarray, shape (n, n_points)Values of the solutionyatt.k(forsolve_ivp_sympext) : ndarray, shape (n//2, n_points)
Values ofkatt. Only forsolve_ivp_sympextand ifcheck_energyis True for a Hamiltonian system with an explicit time dependence (i.e., the parameterndofofhsis half an integer).err(forsolve_ivp_sympext) : float
Error in the computation of the total energy. Only forsolve_ivp_sympextand ifcheck_energyis True.step: step size used in the computation.Remarks:Usesolve_ivp_sympis the Hamiltonian can be split and if each partial operator exp(hXk) can be easily expressed/computed. Otherwise usesolve_ivp_sympextif your coordinates are canonical.Ift_evalis a linearly spaced list or array, or ift_evalis None (default), the step size is slightly readjusted so that the output times contain the values int_eval, or the final timetfcorresponds to an integer number of step sizes. The step size used in the computation is recorded in the solution assol.step.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[3] Tao, M.,Explicit symplectic approximation of nonseparable Hamiltonians: Algorithm and long time performance, Phys. Rev. E 94, 043303 (2016)Example>>>importnumpyasxp>>>importsympyassp>>>importmatplotlib.pyplotasplt>>>frompyhamsysimportHamSys,solve_ivp_sympext>>>hs=HamSys()>>>hamiltonian=lambdaq,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 information:cristel.chandre@cnrs.fr