GitHub
DynamicalSystems — Module

DynamicalSystems.jl logo: The Double Pendulum

DocBuildDOITextbookPackage Downloads

DynamicalSystems.jl is an award-winning Julia-based general-purpose software library for the whole of nonlinear dynamics and nonlinear timeseries analysis.

To install DynamicalSystems.jl, run import Pkg; Pkg.add("DynamicalSystems") as a Julia language command. 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 based on 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 and nonlinear timeseries analysis. It has functionality for complexity measures, delay embeddings, periodic orbits, nonlocal stability analysis, continuation, chaos, fractal dimensions, 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 this wide category of content 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. 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. It is a living, evolving project. Since its beginning in May 2017, DynamicalSystems.jl has had some activity every single month: new features, new packages, bugfixes. The developer team routinely answers users questions on official Julia language forums.
  • 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 DynamicalSystems.jl library started as a vision with three main goals; These same goals now are the core pillars guiding development, and are largely the source of where the aforementioned unique highlights stem from.

Goal 1: Accessible and reproducible nonlinear dynamics

The first goal of the library is to make this beautiful field accessible and reproducible.

Accessible means that if you read on some sorts of fancy algorithm online in a scientific article, you should be able to use it instantly. You shouldn't have to put in the work to code it yourself. The authors of the paper already did that. So why should you do it again?! To resolve this problem we developed, and continue to develop, a library that has an incredibly low threshold of entry: contributing to DynamicalSystems.jl and making your code available to all is truly easier than coding your own algorithms from scratch, due to the well thought out and generic interfaces it provides for dynamical systems.

Reproducible means that given some sorts of dynamical systems analysis in a scientific article, you should be able to do exactly the same analysis and get exactly the same results (within some numeric precision) as the article. After all, computers are deterministic constructs. DynamicalSystems.jl allows this by (1) being written in a modern programming language with incredible environment and reproducibility support, (2) being well tested, and (3) by providing thousands of algorithms out of the box, allowing most dynamical systems analysis to be done instantly while implementing only as little new stuff as necessary.

Goal 2: Library in the literal sense

DynamicalSystems.jl is not just a software library. It is also a library in the literal sense: where people go to learn something new (here in particular for nonlinear dynamics). That is why the documentation is of exceptionally high quality: detailed descriptions and explanations of algorithms, with references to the scientific articles articles. It is also partly a reason for the source code to be written as clearly as possible, so that it is examinable by any user.

Goal 3: A general purpose software

The third goal is to fill the missing gap of a high quality general purpose software for nonlinear dynamics which can be easily extended with new functionality. This can be particularly impactful in teaching. You see, it is unfortunately 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.

DynamicalSystems.jl provides teachers with a framework capable of demonstrating actual, real-world nonlinear dynamics code and its output, without having to invest the weeks to code the internal infrastructure themselves. Its high level syntax requires writing little code to get lots of meaningful analysis done, while its extensive functionality covers most typical classroom applications.

Goal 4: Stopping the endless re-invention of wheel

Because Nonlinear Dynamics as a field lacks a general purpose and "widely accepted" software, almost every software implementation starts from scratch. While doing so much of the code written actually implements functionality that already exists in some other codebase for nonlinear dynamics. This is astonishingly, and shamefully, prevalent in nonlinear dynamics, where up to 90% of the functionality of a codebase may already exist somewhere else. Needless to say this is just an absolute waste of time!

DynamicalSystems.jl hopes to establish itself as the central software for nonlinear dynamics, from which new algorithms can be implementing. Re-using all the well-thought out interfaces and functionality means that one does not have to waste time writing code for functionality that already exists. Rather, they can focus on coding only the new stuff!

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

All subpackages composing DynamicalSystems.jl have their own human-readable CHANGELOG files in their corresponding GitHub repositories. The CHANGELOGs log all meaningful changes in the software.

Notable news for the DynamicalSystems.jl library are also posted on the official Julia language Discourse, and users may subscribe to this particular Topic to get notified of updates:

https://discourse.julialang.org/t/dynamicalsystems-jl-news-updates-and-announcements/122079

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

How to cite

If using DynamicalSystems.jl resulted in a publication with references, we kindly ask that you give appropriate credit in three ways:

  1. Cite the whole DyamicalSystems.jl ecosystem by citing the associated DOI 10.21105/joss.00598 (and see below for a BiBTeX entry). Even if you did not use DynamicalSystems.jl directly, but only a subpackage, we still strongly encourage to cite DynamicalSystems.jl as well. More citations enable us to obtain funding to maintain and further develop DynamicalSystems.jl and the central citation associated with this effort is that assigned to the top-level DynamicalSystems module.
  2. Cite the subpackage that you used directly, if it has an associated publication (see example below).
  3. Cite the specific algorithm(s) you used to also give credit to the originators of the methods.

For example, a typical citation that gives proper credit to using DynamicalSystems.jl could be:

For our work we used the Sample Entropy \cite{Richman2000} that is implemented in the ComplexityMeasures.jl package \cite{ComplexityMeasures} of the DynamicalSystems.jl library \cite{DynamicalSystems}.

or,

For the surrogates for the atmospheric temperature timeseries we used the random cascade surrogates \cite{Palus2008} that is implemented in the TimeseriesSurrogates.jl package \cite{TimeseriesSurrogates} of the DynamicalSystems.jl library \cite{DynamicalSystems}.

or,

We find the attractors of the dynamical systems using the recurrences algorithm \cite{Datseris2022} that is implemented in the Attractors.jl package \cite{Attractors} of the DynamicalSystems.jl library \cite{DynamicalSystems}.

To find the specific references associated with the subpackages visit their respective dedicated documentation pages.

Besides the library, you may also find useful the Nonlinear Dynamics textbook that utilizes DynamicalSystems.jl, which you can cite as:

@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. This option is preferred for any meaningfully involved question, as the answer there will be future-searchable.
  2. As a message in our channel #dynamics-bridged in the Julia Slack workplace. This option is preferred for a brief question with (expected) simple answer, or to get an opinion about something, or to chat about something.
  3. By opening an issue directly on the GitHub page of DynamicalSystems.jl while providing a Minimal Working Example. This option is preferred when you encounter unexpected behavior.

Contributing

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!

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 their respective "contributors" pages.

Version numbers and SemVer

The version of DynamicalSystems by itself is a bit meaningless, because the module does not have any source code, besides re-exporting other modules and offering some visualization functionality. 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", "TransitionsInTimeseries", "SignalDecomposition", "ChaosTools", "CairoMakie",
    ];
    mode = PKGMODE_MANIFEST
)
Status `~/work/DynamicalSystems.jl/DynamicalSystems.jl/docs/Manifest.toml`
  [f3fd9213] Attractors v1.26.4
  [13f3f980] CairoMakie v0.15.6
  [608a59af] ChaosTools v3.5.0
  [ab4b797d] ComplexityMeasures v3.8.1
  [5732040d] DelayEmbeddings v2.9.0
  [61744808] DynamicalSystems v3.5.0
  [6e36e845] DynamicalSystemsBase v3.14.0
  [4665ce21] FractalDimensions v1.9.5
  [31e2f376] PredefinedDynamicalSystems v1.4.0
  [639c3291] RecurrenceAnalysis v2.1.2
  [11a47235] SignalDecomposition v1.2.0
  [40b095a5] StateSpaceSets v2.4.0
  [c804724b] TimeseriesSurrogates v2.7.3
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 mildly 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.

Every single subpackage of DynamicalSystems.jl has a human-written CHANGELOG.md file that details all changes done in each version. You should consult this package if you want to know what changed from version to version.

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: