search

champsproject / ldds

Python package for computing and visualizing Lagrangian Descriptors in Dynamical Systems
BSD 3-Clause "New" or "Revised" License
18 stars 2 forks source link
dynamical-systems lagrangian-descriptors python

readme

LDDS: Python package for Computation of Lagrangian Descriptors of Dynamical Systems.

Table of contents

LDDS

status

.github/workflows/draft-pdf.yml

Documentation Status

Binder

Description

LDDS is an open-source Python module that uses the method of Lagrangian Descriptors (LDs) for visualization of phase space structures of dynamical systems.

First introduced by Madrid & Mancho (Chaos 2009), the method of LDs defines a function, called the Lagrangian descriptor function, defined as a scalar field that maps a set of initial condition in phase space to the "arc length" integral of their evolving trajectories in time. This approach is capable of highlighting the phase space geometry of invariant manifolds associated with periodic orbits and equilibria of dynamical systems. Over the years new formulations of the method have been developed for enhanced visualization of phase space structures. See our online book for an overview on the topic.

In LDDS we implemented the majority of the LD variants and users can be able to work with dynamical systems with continuous flows and discrete maps in deterministic and stochastic settings, with high-dimensional vector fields described as analytical expressions or numerical data. See the Examples and Tutorials section below to have an idea of the versatility of this package.

Nonlinear dynamical systems are ubiquitous in natural and engineering sciences, such as fluid mechanics, theoretical chemistry, ship dynamics, rigid body dynamics, atomic physics, solid mechanics, condensed matter physics, mathematical biology, oceanography, meteorology and celestial mechanics [@wiggins1994normally and references therein]. We expect our package to enable researchers in these and other areas to take advantage of the LDs methods in research.

Dependencies and installation

The setup.py should install the dependencies listed in requirements.txt using

pip install -r requirements.txt (or pip3 install -r requirements.txt)

Installing from source

Clone the git repository and install ldds as a module using

git clone git@github.com:champsproject/ldds.git
cd ldds
python setup.py install

Testing

Test your installation with following command:

cd ldds/tests
python -m unittest

You should see something like the following on the terminal:

Ran 1 test in 11.173s

OK

Documentation

LDDS uses Sphinx for documentation and is made available online here. To build the html version of the docs locally simply:

cd docs
make html

The generated html can be viewed by opening docs/_build/html/index.html.

Examples and Tutorials

You can find useful tutorials on how to use LDDS in the tutorials folder.

Here we show two examples of the output contour maps produced with ldds for the Lagrangian Descriptor values of a deterministic (Tutorial 2) and a stochastic (Tutorial 10) benchmark system:

Duffing oscillator with harmonic forcing.

Double-gyre with stochastic forcing.

How to cite

NOTE 19 May 2020 : We have recently submitted LDDS to JOSS and now awaiting revision.

If you use this package in your publications, provisionally you can cite the package as follows:

LDDS: Python package for Computation of Lagrangian Descriptors of Dynamical Systems. https://github.com/champsproject/ldds

Or if you use LaTeX:

@misc{LDDS,
  author = {B. Aguilar-Sanjuan and V. Garc{\'i}a-Garrido and V. Kraj\v{n}{\'a}k and S. Naik and S. Wiggins},
  title = {{LDDS}: {P}ython package for computing and visualizing {L}agrangian {D}escriptors in {D}ynamical {S}ystems.},
  howpublished = {\url{https://github.com/champsproject/ldds}}
}

Authors and contributors

LDDS is currently developed and mantained by

with the support of and supervision of Prof. Stephen Wiggins (University of Bristol , UK), under the CHAMPS Project.

Contact us by email for further information or questions about LDDS, or suggest pull requests. Contributions improving either the code or the documentation are welcome!

Contributing

Guidelines on how to contribute to this package can be found here along with the code of conduct here for engaging with the fellow contributors. As and when we receive improvements to the package, we will acknowledge the pull request and the contributor in this section.

License

See the LICENSE file for license rights and limitations.

Acknowledgements

We acknowledge the support of EPSRC Grant No. EP/P021123/1 CHAMPS project.