**DynamicalSystems.jl** is an award-winning Julia software library for dynamical systems, nonlinear dynamics, deterministic chaos, and nonlinear timeseries analysis. It is part of JuliaDynamics, an organization dedicated to creating high quality scientific software.

To learn how to use this library please see Getting started below, and subsequently, the Contents page to get an overview of all offered functionality of **DynamicalSystems.jl**.

Welcome to this new (and slightly breaking) release of DynamicalSystems.jl! You can find an announcement of the new version on the Julia discourse:

https://discourse.julialang.org/t/nonlinear-dynamics-textbook-dynamicalsystems-jl-2-0/65665

The *breaking* changes in this release are:

- The keyword
`dt`

of many functions has been renamed to`Δt`

. This keyword had conflicts with the options of DifferentialEquations.jl. No warning can be thrown for this change, and users still using`dt`

will have it silently propagated as keyword to the diffeq solvers. Functions affected:`trajectory, lyapunov, lyapunovspectrum, gali, expansionentropy, orbitdiagram`

- If
`A`

is a`Dataset`

then`A[range_of_integers]`

now returns a`Dataset`

. Before it used to return`Vector{SVector}`

.

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.

## Getting started

**DynamicalSystems.jl** is a collection of Julia packages bundled together under a single package `DynamicalSystems`

. To install this bundle you can do:

`using Pkg; Pkg.add("DynamicalSystems")`

The individual packages that compose `DynamicalSystems`

interact flawlessly with each other because of the following two structures:

- The
`DynamicalSystem`

represents a dynamical system with known dynamic rule $f$. The system can be in discrete time (often called a map), $\vec{u}_{n+1} = \vec{f}(\vec{u}_n, p, n)$, or in continuous time (often called an ordinary differential equation) $\frac{d\vec{u}}{dt} = \vec{f}(\vec{u}, p, t)$. In both cases $u$ is the*state*of the dynamical system and $p$ a parameter container. You should have a look at the page Dynamical System Definition for how to create this object. A list of several pre-defined systems exists in the Predefined Dynamical Systems page. - Numerical data, that can represent measured experiments, sampled trajectories of dynamical systems, or just sets in the state space, are represented by
`Dataset`

, which is a container of equally-sized data points. Timeseries in**DynamicalSystems.jl**are represented by the already existing`Vector`

type of the Julia language.

These core structures `DynamicalSystem, Dataset`

are used throughout the package to do useful calculations often used in the field of nonlinear dynamics and chaos. For example, using `lyapunovspectrum`

and `DynamicalSystem`

gives you the Lyapunov exponents of a dynamical system with known equations of motion. Alternatively, by using `lyapunov_from_data`

and `Dataset`

you can approximate the maximum Lyapunov exponent of a measured trajectory or a reconstructed set resulting from `embed`

.

All things possible in **DynamicalSystems.jl** are listed in the Contents page. For transparency, the packages and versions used to build the documentation you are reading now are:

```
using Pkg
Pkg.status([
"DelayEmbeddings", "RecurrenceAnalysis",
"DynamicalSystemsBase", "ChaosTools",
"Entropies",];
mode = PKGMODE_MANIFEST, io=stdout
)
```

```
Status `~/work/DynamicalSystems.jl/DynamicalSystems.jl/docs/Manifest.toml`
[608a59af] ChaosTools v2.5.0
[5732040d] DelayEmbeddings v2.0.1
[6e36e845] DynamicalSystemsBase v2.3.2
[ed8fcbec] Entropies v1.1.0
[639c3291] RecurrenceAnalysis v1.6.1
```

### Tutorials

Tutorials for **DynamicalSystems.jl** exist in the form of Jupyter notebooks.

In addition, a full 2-hours YouTube tutorial is available below:

Our library assumes some basic knowledge of nonlinear dynamics and complex systems.

If you are new to the field but want to learn more, we can suggest the following textbooks as introductions:

- Chaos in Dynamical Systems - E. Ott
- Nonlinear Time series Analysis - H. Kantz & T. Schreiber

### Advanced Installation

Notice that for targeted usage of `DynamicalSystems`

(e.g. you only need a specific function like `lyapunovspectrum`

or `rqa`

), you don't have to install the entire `DynamicalSystems`

suite. You can leave with only installing the necessary package that exports the function you need. You see this information prefacing the function. E.g. for `rqa`

you will see `RecurrenceAnalysis.rqa`

, which means that you need to install `RecurrenceAnalysis`

to use it.

## Our Goals

**DynamicalSystems.jl** was created with three goals in mind. The first was to fill the missing gap of a high quality and general purpose software for nonlinear dynamics. The second was to create a useful *library* where students and scientists from different fields may come and learn about methods of nonlinear dynamics.

The third was 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. But published 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.

To achieve these goals we made **DynamicalSystems.jl** so that it is:

- Transparent: extra care is taken so that the source code of all functions is clear and easy to follow, while remaining as small and concise as possible.
- Intuitive: a software simple to use and understand makes experimentation easier.
- Easy to install, easy to extend: This makes contributions more likely, and can motivate researchers to implement their method here, instead of leaving it in a cryptic script stored in some data server, never-to-be-published with the paper.
- Reliable: the algorithm implementations are tested extensively.
- Well-documented: all implemented algorithms provide a high-level scientific description of their functionality in their documentation string as well as references to scientific papers.
- General: all algorithms work just as well with any system, whether it is a simple continuous chaotic system, like the Lorenz model, or a high dimensional discrete system like coupled standard maps.
- Performant: written entirely in Julia, and taking advantage of some of the best packages within the language,
**DynamicalSystems.jl**is*really fast*.

## Citing

There is a (small) paper associated with **DynamicalSystems.jl**. If we have helped you in research that led to a publication, please be kind enough to 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}
}
```

## 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 :)

## Asking questions

There are three options for asking questions:

- Join the official Julia discourse and ask a question under the category Specific Domains > Modelling & Simulations.
- Join our chatroom on gitter or the channel
`#dynamics-bridged`

in the Julia Slack workplace. - Open an issue directly on the GitHub page of DynamicalSystems.jl while providing a Minimal Working Example.

## Contributing & Donating

*TL;DR: See "good first issues" or "wanted features".*

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.

## Maintainers and Contributors

The DynamicalSystems.jl software is maintained by George Datseris, who is also curating and writing this documentation page.

The software code however is built from the contributions of several individuals. For an accurate list of the names as well as contributions of each one, please visit our webpage.