UPOsHam

UPOsHam: A Python package for computing unstable periodic orbits in two-degree-of-freedom Hamiltonian systems - Published in JOSS (2020)

https://github.com/wylyu/uposham

Scientific Fields

Repository

UPOsHam is a Python package for computing unstable periodic orbits in two degrees of freedom Hamiltonian systems

README.Rmd

---
title: "UPOsHam"
bibliography: ./paper/paper.bib
link-citations: yes
output:
  md_document:
    fig_height: 6
    fig_width: 6
    toc: yes
    variant: markdown_github
  html_document:
    toc: yes
  pdf_document:
    fig_height: 6
    fig_width: 6
    highlight: zenburn 
    toc: yes
biblio-style: apalike
---

# UPOsHam

[![Documentation Status](https://readthedocs.org/projects/uposham/badge/?version=latest)](https://uposham.readthedocs.io/en/latest/?badge=latest) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3601504.svg)](https://doi.org/10.5281/zenodo.3601504)

## Summary


This Python package is a collection of three methods for computing unstable periodic orbits in two degrees of freedom Hamiltonian systems that model a diverse array of problems in physical sciences and engineering [@Parker_1989; @wiggins_introduction_2003]. The unstable periodic orbits exist in the bottleneck of the equipotential line $V(x,y) = E$ and project as lines on the configuration space $(x,y)$ for the Hamiltonian system of the form kinetic plus potential energy [@wiggins_role_2016]. The three methods implemented here (and available under [src](src/) directory) has been used in [@Pollak_1980;@Deleon_Berne_1981;@koon_heteroclinic_2000;@Koon2011;@naik_geometry_2017;@ross_experimental_2018;@naik_finding_2019b] for transition dynamics in chemical reactions, celestial mechanics, and ship capsize. We have chosen three Hamiltonian systems that have two wells connected by a bottleneck where the unstable periodic orbits exist for energy above the energy of the saddle equilibrium point. A brief description of these systems can be found in the [paper](https://github.com/WyLyu/UPOsHam/tree/master/paper/paper.pdf). 


## Installation

Clone the git repository and install ```uposham``` as a module using

```bash
$ git clone git@github.com:WyLyu/UPOsHam.git
$ cd UPOsHam
$ python setup.py install
```

The ```setup.py``` should also install the modules listed in [requirements.txt](https://github.com/WyLyu/UPOsHam/tree/master/requirements.txt) and which are typically installed using

```bash
$ pip install -r requirements.txt (or pip3 install -r requirements.txt)
```

Now ```uposham``` module is available for import along with the methods and example systems as submodules, for example

```python
import uposham.differential_correction as diffcorr
import uposham.deleonberne_hamiltonian as deleonberne
```


## Usage

To obtain the unstable periodic orbits for a two degree-of-freedom Hamiltonian system, one needs the expressions described in the examples section of the [documentation](https://uposham.readthedocs.io/en/latest/?badge=latest). These expression can then be implemented as functions as shown in the [script](examples/deleonberne_hamiltonian.py) and the function names of the expressions can then be passed to a method's function as in the [script](examples/differential_correction_deleonberne.py). The example script that computes the unstable periodic orbits (UPOs) for a given Hamiltonian system is in the [examples](examples/) directory with names ```_.py```. The example scripts show how the method specific functions take the system specific functions as input and are meant as demonstration of how to set-up computation for a new system using the available methods. 

The user will need to write the system specific functions in a script, import this as module, import one of the method as module, and pass the system specific functions to the method specific functions.


__Solving the De Leon-Berne Hamiltonian system using differential correction method__

For example, to test the computation of unstable periodic orbits (the default setting computes the UPOs for 2 values of the total energy) for the De Leon-Berne Hamiltonian [-@Deleon_Berne_1981] using the differential correction method, the demonstration script can be called from the root directory at the command-line using

```bash
$ python examples/differential_correction_deleonberne.py
```

This will save data files in the root directory and save the plot in the [./tests/plots](tests/plots/) directory.


![](tests/plots/diff_corr_deleonberne_upos.png){width="30.00000%"}

__Fig. 1. Unstable periodic orbits for De Leon-Berne Hamiltonian__


__Solving the coupled quartic Hamiltonian system using differential correction method__

To perform these computations using ipython, for example to obtain the unstable periodic orbits for the coupled quartic Hamiltonian using the differential correction, the user can execute:

```bash
$ ipython
>>> run ./examples/differential_correction_coupled.py
```

This will save data files in the root directory and save the plot in the [./tests/plots](tests/plots/) directory.


![](tests/plots/diff_corr_coupled_upos.png){width="50.00000%"}

__Fig. 2. Unstable periodic orbits for the coupled quartic Hamiltonian__


## Tests

The uncoupled quartic Hamiltonian is an example of a system where the unstable periodic orbits can be obtained in explicit analytical form. This system is used for testing the numerical solutions obtained using the methods implemented in this package. 

__Unit test__

Passing a test constitutes the following:

1. The Hausdorff distance between a given numerical and analytical orbits is within $10^{-8}$. This is implemented using Scipy's spatial module.

2. The element wise comparison test of the orbits agree upto 6 decimal places. This is performed using Numpy's testing module. 

Other nonlinear examples systems can not be solved in this explicit analytical form and these are tested by performing plotting comparison of the orbits obtained using the methods. These are available in the [Jupyter](./tests/tests.ipynb) notebook.


__Comparing the methods for the coupled quartic Hamiltonian__

We demonstrate how the UPOs computed using the different methods compare with each other for a specific system: coupled quartic Hamiltonian.

Comparison of the results (data is located in the [data](https://github.com/WyLyu/UPOsHam/tree/master/data) directory) obtained using the three methods for the coupled quartic Hamiltonian can be done using

```bash
$ ipython
>>> run ./tests/compare_methods_coupled.py
```
and the generated figure is located in the [tests/plots](tests/plots/comparison_coupled.png) directory.


## Contributing

Guidelines on how to contribute to this package can be found  [here](https://github.com/WyLyu/UPOsHam/blob/master/docs/contributing.md) along with the code of conduct [here](https://github.com/WyLyu/UPOsHam/blob/master/CODE_OF_CONDUCT.md) for engaging with the fellow contributors.


## Acknowledgements

We acknowledge the support of EPSRC Grant No. EP/P021123/1 and Office of Naval Research (Grant No. N00014-01-1-0769). The authors would like to acknowledge the London Mathematical Society and School of Mathematics at the University of Bristol for supporting the undergraduate research bursary 2019. We acknowledge contributions from Shane Ross for writing the early MATLAB version of the differential correction and numerical continuation code.


## Copyright and License
Copyright 2019 Wenyang Lyu, Shibabrat Naik, Stephen Wiggins. 

All content is under Creative Commons Attribution [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode.txt) and all the python scripts are under [BSD-3 clause](https://github.com/WyLyu/UPOsHam/blob/master/LICENSE).

## References

Owner

JOSS Publication

UPOsHam: A Python package for computing unstable periodic orbits in two-degree-of-freedom Hamiltonian systems

Published

January 14, 2020

DOI

10.21105/joss.01684

Volume 5, Issue 45, Page 1684

Authors

Wenyang Lyu
School of Mathematics, University of Bristol, Fry Building, Woodland Road, Bristol BS8 1UG, United Kingdom

Shibabrat Naik
School of Mathematics, University of Bristol, Fry Building, Woodland Road, Bristol BS8 1UG, United Kingdom

Stephen Wiggins
School of Mathematics, University of Bristol, Fry Building, Woodland Road, Bristol BS8 1UG, United Kingdom

Editor

Kristen Thyng

Tags

Hamiltonian dynamics Dynamical systems Chemical reaction dynamics Unstable periodic orbits State transition matrix Differential correction Numerical continuation Turning point

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago