GitHub
DynamicalSystems — Module

DynamicalSystems.jl logo: The Double Pendulum

DocBuild DOI Textbook Package Downloads

DynamicalSystems.jl is an award-winning Julia software library for nonlinear dynamics and nonlinear timeseries analysis.

To install DynamicalSystems.jl, run import Pkg; Pkg.add("DynamicalSystems"). To learn how to use it and see its contents visit the documentation, which you can either find online or build locally by running the docs/make.jl file.

DynamicalSystems.jl is part of JuliaDynamics, an organization dedicated to creating high quality scientific software.

Highlights

Aspects of DynamicalSystems.jl that make it stand out among other codebases for nonlinear dynamics or nonlinear timeseries analysis are:

  • Exceptional documentation. All implemented algorithms provide a high-level scientific description of their functionality in their documentation string as well as references to scientific papers. The documentation features hundreds of tutorials and examples ranging from introductory to expert usage.
  • Accessible source code. One of the main priorities of the library is that the source code of (almost) all implementations is small, simple, easy to understand and modify. This increases confidence, reduces bugs, and allows users to become developers without unnecessary effort.
  • Open source community project. Built from the ground up entirely on GitHub, DynamicalSystems.jl is 100% open source and built by community contributions. Anyone can be a developer of the library. Everyone is welcomed.
  • Extensive content. It aims to cover the entire field of nonlinear dynamics. It has functionality for complexity measures, delay embeddings, stability and bifurcation analysis, chaos, surrogate testing, recurrence quantification analysis, and much more. Furthermore, all algorithms are "general" and work for any dynamical system applicable. Missing functionality that falls under nonlinear dynamics is welcomed to be part of the library!
  • Well tested. All implemented functionality is extensively tested. Each time any change in the code base is done, the extensive test suite is run and checked before merging the change in.
  • Extendable. DynamicalSystems.jl is a living, evolving project. New contributions can become part of the library and be accessed by all users in the next release. Most importantly, all parts of the library follow professional standards in software design and implement extendable interfaces so that it is easy to contribute new functionality.
  • Active development. Since the start of the project (May 2017) there has been activity every month: new features, bugfixes, and the developer team answers users questions on Discourse/Slack.
  • Performant. Written entirely in Julia, heavily optimized and parallelized, and taking advantage of some of the best packages within the language, DynamicalSystems.jl is really fast.

Goals

The primary goal of DynamicalSystems.jl is to be a library in the literal sense: where people go to learn something (here in particular for nonlinear dynamics). That is why the main priority is that the documentation is detailed and references articles and why the source code is written as clearly as possible, so that it is examinable by any user.

The second goal is to fill the missing gap of high quality general purpose software for nonlinear dynamics which can be easily extended with new functionality. The purpose of this is to make the field of nonlinear dynamics accessible and reproducible.

The third goal is to fundamentally change the perception of the role of code in both scientific education as well as research. It is rarely the case that real, runnable code is shown in the classroom, because it is often long and messy. This is especially hurtful for nonlinear dynamics, a field where computer-assisted exploration is critical. And published scientific work in this field fares even worse, with the overwhelming majority of published research not sharing the code used to create the paper. This makes reproducing these papers difficult, while some times straight-out impossible. DynamicalSystems.jl can change this situation, because it is high level (requires writing little code to get lots of results) while offering extensive and well-tested functionality.

source
Star us on GitHub!

If you have found this library useful, please consider starring it on GitHub. This gives us an accurate lower bound of the (satisfied) user count.

Introduction

Welcome to the documentation of DynamicalSystems.jl!

  • If you have not used the library before, and would like to get started, then please read the overarching tutorial for the library.
  • The contents page gives a summary of all packages that are part of the library.
  • See the learning resources below to find out more resources about learning the library and using it in scientific research and/or education.
  • Besides the formal algorithmic/scientific content of DynamicalSystems.jl (those in the contents) page, the library also provides basic functionality for interactive or offline animations and visualizations. These are found in the visualizations page.
  • The remaining of this introduction page discusses our goals with the library, how to participate as a user or developer, how to cite, and other relevant information (see the sections of the sidebar on the left).

Latest news

DynamicalSystems.jl now integrates with ModelingToolkit.jl and allows using symbolic variables to access/observe state and parameter.

At a low level, this happens via the functions observe_state, set_state!, current_parameter and set_parameter!.

Additionally, interactive_trajectory_timeseries allows symbolic indexing for state space plot, timeseries plots, or parameter sliders. Everything is also automatically named and limits are also automatically deduced for everything! Super convenient!

Learning resources

Textbook with DynamicalSystems.jl

We have written an undergraduate level textbook as an introduction to nonlinear dynamics. The text is written in an applied, hands-on manner, while still covering all fundamentals. The book pages are interlaced with real Julia code that uses DynamicalSystems.jl and is published in the Undergraduate Lecture Notes in Physics by Springer Nature:

Additional textbooks on nonlinear dynamics with practical focus are:

  • Chaos in Dynamical Systems - E. Ott
  • Nonlinear Time series Analysis - H. Kantz & T. Schreiber
  • Nonlinear Dynamics and Chaos - S. Strogatz

Course on applied nonlinear dynamics and complex systems

We are developing a full course (targeting a graduate or undergraduate semester long course) on applied nonlinear dynamics, nonlinear timeseries analysis, and complex systems, using the packages of JuliaDynamics. DynamicalSystems.jl is part of this course.

The materials of the course are on GitHub: https://github.com/JuliaDynamics/NonlinearDynamicsComplexSystemsCourses

Citing

There is a (small) paper associated with DynamicalSystems.jl. If we have helped you in research that led to a publication, please cite it using the DOI 10.21105/joss.00598 or the following BiBTeX entry:

@article{Datseris2018,
  doi = {10.21105/joss.00598},
  url = {https://doi.org/10.21105/joss.00598},
  year  = {2018},
  month = {mar},
  volume = {3},
  number = {23},
  pages = {598},
  author = {George Datseris},
  title = {DynamicalSystems.jl: A Julia software library for chaos and nonlinear dynamics},
  journal = {Journal of Open Source Software}
}

Irrespectively of DynamicalSystems.jl, please also cite the specific algorithm that you used from the library. The documentation of the function used will point you to the correct reference.

Besides the library, we would also appreciate it if you cited the textbook we wrote that DynamicalSystems.jl accompanies:

@book{DatserisParlitz2022,
  doi = {10.1007/978-3-030-91032-7},
  url = {https://doi.org/10.1007/978-3-030-91032-7},
  year = {2022},
  publisher = {Springer Nature},
  author = {George Datseris and Ulrich Parlitz},
  title     = "Nonlinear dynamics: A concise introduction interlaced with code",
  address   = "Cham, Switzerland",
  language  = "en",
}

Asking questions

There are three options for asking questions:

  1. As a new post in the official Julia discourse and ask a question under the category Specific Domains > Modelling & Simulations, also using dynamical-systems as a tag.
  2. As a message in our channel #dynamics-bridged in the Julia Slack workplace.
  3. By opening an issue directly on the GitHub page of DynamicalSystems.jl while providing a Minimal Working Example. This is the most useful approach when you encounter unexpected behaviour.

Contributing & Donating

Be sure to visit the Contributor Guide page, because you can help make this package better without having to write a single line of code! Also, if you find this package helpful please consider staring it on GitHub! This gives us an accurate lower bound of users that this package has already helped!

Finally, you can donate for the development of DynamicalSystems.jl. You can do that by adding bounties to existing issues on the GitHub repositories (you can open new issues as well). Every issue has an automatic way to create a bounty using Bountysource, see the first comment of each issue.

Issues with Bounties

Money that DynamicalSystems.jl obtains from awards, sponsors, or donators are converted into bounties for GitHub issues. The full list of issues that have a bounty is available here.

By solving these issues you not only contribute to open source, but you also get some pocket money to boot :)

Maintainers and Contributors

The DynamicalSystems.jl library is maintained by George Datseris, who is also curating and writing this documentation. The software code however is built from the contributions of several individuals. The list is too long to write and constantly update, so the best way to find out these contributions is to visit the GitHub page of each of the subpackages and checkout the "contributors" pages there.

Version numbers

The version of DynamicalSystems by itself is a bit meaningless, because the module does not have any source code, besides re-exporting other modules. For transparency, the packages and versions used to build the documentation you are reading now are:

using Pkg
Pkg.status([
    "DynamicalSystems",
    "StateSpaceSets", "DynamicalSystemsBase", "RecurrenceAnalysis", "FractalDimensions", "DelayEmbeddings", "ComplexityMeasures", "TimeseriesSurrogates", "PredefinedDynamicalSystems", "Attractors", "ChaosTools", "CairoMakie",
    ];
    mode = PKGMODE_MANIFEST
)
Status `~/work/DynamicalSystems.jl/DynamicalSystems.jl/docs/Manifest.toml`
  [f3fd9213] Attractors v1.16.0
  [13f3f980] CairoMakie v0.11.10
  [608a59af] ChaosTools v3.1.2
  [ab4b797d] ComplexityMeasures v3.4.1
  [5732040d] DelayEmbeddings v2.7.4
  [61744808] DynamicalSystems v3.3.7 `~/work/DynamicalSystems.jl/DynamicalSystems.jl`
  [6e36e845] DynamicalSystemsBase v3.7.1
  [4665ce21] FractalDimensions v1.8.1
  [31e2f376] PredefinedDynamicalSystems v1.2.0
  [639c3291] RecurrenceAnalysis v2.0.6
  [40b095a5] StateSpaceSets v1.4.5
  [c804724b] TimeseriesSurrogates v2.6.4
Version numbers do not strictly follow SemVer2.0

Because of the nature of the DynamicalSystems.jl library, the exported API contains hundreds of algorithm implementations, most of which are independent of each other. Our development approach is that breaking changes to these individual algorithms (due to e.g., better API design or better performance implementations or better default keyword arguments) can be done without incrementing any major version numbers. We increment major version numbers only for breaking changes that have wide impact over most of the DynamicalSystems.jl library.

Other NLD-relevant packages

Besides DynamicalSystems.jl, the Julia programming language has a thriving ecosystem with plenty of functionality that is relevant for nonlinear dynamics. We list some useful references below: