DynamicalSystems.jl v3

DynamicalSystems.jl v3.0

Super duper major update that has just been tagged! :slight_smile:

It has been a long time and a lot of hard work, but I can already see it was worth it :')

In the remaining of March I’ll spend time “putting out fires” (as I’m sure something broke that I didn’t foresee), porting the documentation to a DiffEq like style with links to other packages overhead, and making a new logo!

  1. Overhauling

  2. Modularization

  3. New documentation

  4. Notable breaking changes

  5. Renames

  6. Re-write of DynamicalSystem

  7. ODE solver change

  8. Package split: StateSpaceSets.jl

  9. Package split: FractalDimensions.jl

  10. Partial overhaul: RecurrenceAnalysis.jl

  11. New amazing package ComplexityMeasures.jl

  12. New amazing package Attractors.jl

  13. Co-maintainer(s) needed


Practically all packages that are part of DynamicalSystems.jl have been overhauled in some way or another. Some have been completely overhauled, like DynamicalSystemsBase and ComplexityMeasures. Some others have been partially overhauled like RecurrenceAnalysis and ChaosTools.

DynamicalSystems.jl was the first library I’ve written and after progressing as a software developer I have learned so much more about good design. I’ve put all this knowledge to good use and decided it was a good point to just do a mass-overhaul on the package.


The packages that compose DynamicalSystems.jl have been split up into more packages, making a more modular library, and also allowing a much smaller dependency tree for users that want only a specific part of the functionality.

The modularization itself did not bring any breaking changes.

New documentation

This modularization also lead to a documentation overhaul: now every package of the library builds and hosts its own documentation. The DynamicalSystems.jl brings everything together with an overarching tutorial and points to the individual docs.

The main documentation of DynamicalSystems.jl now includes an overarching tutorial and overview, and then “dispatches” to documentations of other packages.

In the near future the documentation will be in the style similar to DiffEqDocs, however, I am still exploring alternative and stable ways to achieve similar results.

Notable breaking changes

  • The trajectory function now returns both the state space set and the time vector. In sort, all code that did A = trajectory(...) is now broken and should be replaced by A, tvec = trajectory(...).

  • There are no longer diffeq keyword arguments to downstream functions. All functions such as lyapunovspectrum, basins_of_attraction, etc. no longer accept the diffeq keyword, that used to specify arguments for DifferentialEquations.jl. Instead, the DiffEq solver options are decided during the creation of CoupledODEs (what was before ContinuousDynamicalSystem).

  • The basic dynamical system constructors do not accept a Jacobian. Giving a fourth argument will error. The dedicated TangentDynamicalSystem should be used for this.


Some things have been renamed to have a clearer and more specific name. These aren’t breaking changes, only deprecations. From the top of my head, the most important ones are:

  • Dataset → StateSpaceSet

  • DiscreteDynamicalSystem → DeterministicIteratedMap

  • ContinuousDynamicalSystem → CoupledODEs

  • The special type for 1D discrete dynamical systems has been removed. 1D systems are now represented by a 1D static vector that needs to be reshaped accordingly.

Re-write of DynamicalSystem

The core library DynamicalSystemsBase.jl has had a complete re-write. This has the following major impacts:

  1. Concept of what is a “dynamical system” is much more general. now DynamicalSystem defines a proper, extendable interface. The set of functions that the interface satisfies are listed in DynamicalSystem documentation string.

  2. More variants of a dynamical system are offered. Any arbitrary steppable thing, like an agent based model, can become a dynamical system.

  3. Overall much better and rigorous tests.

  4. Now all concrete implementations of DynamicalSystem can be iteratively evolved in time via the step! function. For example, ContinuousDynamicalSystem is now a light wrapper around ODEIntegrator. After working with this library for years I realized that the “middle man” of representing a dynamical system (like an ode problem) was not really necessary in downstream functions, since all of them exclusively use an integrator.

  5. Dynamical systems are completely detached from a Jacobian creation, which now is the exclusive task of TangentDynamicalSystem. As a result all predefined dynamical systems do not include a hand-coded Jacobian; rather the Jacobian needs to be given from Systems submodule to the TangentDynamicalSystem.

Also, the Systems submodule has been removed from the DynamicalSystemsBase.jl package and became a new package PredefinedDynamicalSystems.jl. It is untested and it is not recommended to use in any other setting other a demonstrational example. (this was always the case, it’s just that so far we weren’t transparent that nothing there was tested…)

Read more here: DynamicalSystemsBase.jl · DynamicalSystemsBase.jl

ODE solver change

The default integrator used in continuous time Ordinary Differential Equations (what was before called ContinuousDynamicalSystem and now called CoupledODEs) is now Tsit5(). This means that OrdinaryDiffEq.jl is a dependency of DynamicalSystemsBase.jl. It is a better option than the previous SimpleATsit5(). Additionally, the insane compile and first-use time improvements in latest Julia versions had made the impact of loading OrdinaryDiffEq.jl much smaller.

Package split: StateSpaceSets.jl

It has all functionality surrounding StateSpaceSet (what was previously known as Dataset). It therefore detaches the infrastructure for handing numeric data from delay embeddings, and now DelayEmbeddings.jl is a package dedicated to creating and optimizing delay coordinates embeddings.


Package split: FractalDimensions.jl

All functionality related to computing fractal dimensions has been detached from ChaosTools.jl into a new package: FractalDimensions.jl · FractalDimensions.jl

Partial overhaul: RecurrenceAnalysis.jl

RecurrenceAnalysis.jl, now in v2.0, has had its core type (RecurrenceMatrix) overhauled for better design, more clarity, extendibility, and overall more Julian programming utilizing multiple dispatch and dedicated types to specify options.

Now a subtype of AbstractRecurrenceType is used to specify how to create a recurrence matrix. More details in the docpage of the package:


New amazing package ComplexityMeasures.jl

This is a complete overhaul and massive enhancement of the previous Entropies.jl and deserves its own announcement post: ComplexityMeasures.jl

New amazing package Attractors.jl

Incredibly exciting stuff that we (@awage @kalelr @Datseris) have been working on for the last year. It features an interface for finding attractors and their basin fractions, as well as a new approach to “continuation”. We are currently writing a paper for this, so the package doesn’t have an announcement yet. Once we have the preprint though, we will write an announcement post for the package and share the pre-print!

For now, feel free to see the docs and give us feedback!!!


Co-maintainer(s) needed

Some parts of the library have co-maintainers (Attractors.jl has @awage and @kalelr, ComplexityMeasures.jl and TimeseriesSurrogates.jl have @kahaaga) but this whole ecosystem around DynamicalSystems.jl has become too large and I think I just don’t have the time to maintain it alone anymore. So, I am kindly asking for people with expertise in both NLD and programming to consider coming on board and helping with answering questions, addressing issues, fixing bugs, and testing out the ecosystem. Feel free to contact me via a PM on Slack or here on Discourse!


DynamicalSystems.jl is great stuff, happy to continue seeing it progress.


This looks odd to me. Why not just ODE? Because of scalar ODE?

Yeah it was very hard to come up with a very good name…

ContinuousDynamicalSystem wasn’t good enough in this new version, because it allows arbitrary systems, so what does continuous mean? in time, in variable space? And what kind of continuous? many different system types can be in continuous time, including stochastic systems. So that was a no go.

in the end I chose coupled ODEs for two reasons: 1) that’s how we first introduce these systems in our book, so I thought, might as well use the same here, and 2) I didn’t want to use only “ODEs” because, in the overwhelming majority of use cases of DynamicalSystems.jl one will have coupled ODEs. Uncoupled ones do not produce dynamics that are relevant enough for the scope of the package as they are separatable in individual 1-dimensional ODE, 3) only “ODEs” was very short compared to the now rather long DeterministicIteratedMap

I’m not super happy with it, but its the best I could come up with…


I had hoped to see that invariant manifolds of hyperbolic equilibria/fixed points of a DS had also been introduced.
Is it planned to implement the computation of these invariant manifolds in the future?

Which paper are you referring to?

@rveltz I did not refer to a paper, but to a topic. I know that Yorke around 1991, Guckenheimer, a bit later, Osinga, Carles Simo have published algorithms to compute the invariant manifolds. Tomorrow I’ll search for the exact title of each paper and post here.

Out of curiosity, are you referring to ODEs or iterated maps? (discalimer: I have not coded any)

I referred to both. Hyperbolic equilibria for vector fields, i.e. ODEs, while hyperbolic fixed points for discrete DS.

The first paper by Yorke et al, deals with invariant manifolds of discrete systems, and the next to ODEs:

This is easy to do and in fact we have it as an exercise in our book. We already have the fixedpoints function that returns stable/unstable fixed points and their eigenvalues. One can carry one from this code to get the eigenvectors and then evolve the stable ones backwards in time or the unstable ones forwards in time.

Definitely easy to do.

Please open an issue or give it a shot at implementing it!

Hello, i not see function produce_orbitdiagram, it is removed?

Yes, it is obsolete. Now orbitdiagram works for any kind of dynamical system so you initialize a PoincareMap and give this to orbitdiagram. I guess I forgot to add this to the changelog!!!

_that’s exactly what I am talking about putting out fires :smiley: _

1 Like

Ah, it is not removed, it is deprecated: ChaosTools.jl/deprecations.jl at main · JuliaDynamics/ChaosTools.jl · GitHub

Thank you, when I lost function I was scared)

@Datseris It is straightforward to get a one dimensional unstable manifold of a hyperbolic equilibrium, but for two or three dimensional it isn’t, especially when this manifold has a special topology ( see Guckenheimer’s and Osinga’s papers from the links I posted).

Can you share code with example, how use it in v3?
Over the past few months, I’ve been using it quite often for future articles and it has always helped quite a lot. Also I wanted to add save initial condition and saving output in file.

The link i’ve posted is the literal source code of what the function does.

Ah I see. Okay, then this can be done in steps. For 1D manifolds its easy so best to start there!

(EDIT: Also, I think it is rather uncommon to have eigenvalue degeneracy for a generic dynamical system. These are the situations you are referring to, right?)

If I need to save all phase variables, should I specify the full vector? How to build a diagram in this case? I don’t really understand how to select the variable I need from the vector of vectors

Can I make changes to a function that will save the output to a file at each iteration, for example in jld2? If the orbit diagram is calculating for about a day, I think it would be good if you could look at the result at any time