v3 (JuliaDynamics#209)

* start writing an actual release notes

* set versoiun to 3.0, comment out all bounds

* add some changelog notes for new DS interface

* progress more the cahngelog

* remove rqa docs

* update changelog more

* new docstyle

* update project files

* correct reexports

* new readme + use as docstring

* actually for dynamicalsystmes it doesn't make much sense

* reorder

* remove unused pages

* update docs and remove old stuff

* better org in content

* use predefined systems

* all correct imports

* more intro and tutorial improvements

* new github workflows

* finish introduction page

* halfwaythrough with the tutorial

* finish using dataset tutorial

* finish tutorial!!!

* finish announcement post

* correct equations

* demand 2.1 timeseries surrogates

* use textbook for the badge

* show that dynamical systems can be arbitrarily stepped

* Update changelog

* update all text, time to tag

.github/ISSUE_TEMPLATE/bug_report.md

@@ -22,9 +22,8 @@ Please provide the versions you use. To do this, run the code:
 using Pkg
 Pkg.status([
     "DynamicalSystems",
-    "DelayEmbeddings", "RecurrenceAnalysis",
-    "DynamicalSystemsBase", "ChaosTools",
-    "Entropies",];
+    "StateSpaceSets", "DynamicalSystemsBase", "RecurrenceAnalysis", "FractalDimensions", "DelayEmbeddings", "ComplexityMeasures", "TimeseriesSurrogates", "PredefinedDynamicalSystems", "Attractors", "ChaosTools"
+    ];
     mode = PKGMODE_MANIFEST
 )
 ```

.github/workflows/TagBot.yml

@@ -4,11 +4,6 @@ on:
     types:
       - created
   workflow_dispatch:
-    inputs:
-      lookback:
-        default: 3
-permissions:
-  contents: write
 jobs:
   TagBot:
     if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
@@ -17,4 +12,4 @@ jobs:
       - uses: JuliaRegistries/TagBot@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          ssh: ${{ secrets.DOCUMENTER_KEY }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/ci.yml

@@ -3,6 +3,7 @@ on:
   pull_request:
     branches:
       - main
+      - '**' # matches every branch
   push:
     branches:
       - main
@@ -16,7 +17,7 @@ jobs:
       matrix:
         version:
           - '1'
-        os:  [ubuntu-latest]
+        os:  [ubuntu-latest] # adjust according to need, e.g. os: [ubuntu-latest] if testing only on linux
         arch:
           - x64
     steps:
@@ -33,32 +34,6 @@ jobs:
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v2
-        env:
-          cache-name: cache-artifacts
-        with:
-          path: ~/.julia/artifacts
-          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-test-${{ env.cache-name }}-
-            ${{ runner.os }}-test-
-            ${{ runner.os }}-
-      - uses: julia-actions/julia-buildpkg@latest
-      - uses: julia-actions/julia-runtest@latest
-  docs:
-    name: Documentation
-    runs-on: ubuntu-latest
-    steps:
-      # Cancel ongoing documentation build if pushing to branch again before the previous
-      # build is finished.
-      - name: Cancel ongoing builds and checkout
-        uses: styfle/[email protected]
-        with:
-          access_token: ${{ github.token }}
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
-        with:
-          version: '1'
       - uses: actions/cache@v1
         env:
           cache-name: cache-artifacts
@@ -69,14 +44,9 @@ jobs:
             ${{ runner.os }}-test-${{ env.cache-name }}-
             ${{ runner.os }}-test-
             ${{ runner.os }}-
-      - name: Instantiate and install dependencies
-        run: |
-          julia --project=docs -e '
-            using Pkg
-            Pkg.develop(PackageSpec(path=pwd()))
-            Pkg.instantiate()'
-      - name: Generate documentation and deploy
-        env: # needed for pushing to gh-pages branch
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=docs --color=yes docs/make.jl
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v1
+        with:
+          file: lcov.info

.github/workflows/doccleanup.yml

@@ -12,17 +12,15 @@ jobs:
         uses: actions/checkout@v2
         with:
           ref: gh-pages
-
-      - name: Delete preview and history
+      - name: Delete preview and history + push changes
         run: |
-            git config user.name "Documenter.jl"
-            git config user.email "[email protected]"
-            git rm -rf "previews/PR$PRNUM"
-            git commit -m "delete preview"
-            git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+            if [ -d "previews/PR$PRNUM" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "previews/PR$PRNUM"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+            fi
         env:
-            PRNUM: ${{ github.event.number }}
-
-      - name: Push changes
-        run: |
-            git push --force origin gh-pages-new:gh-pages
+            PRNUM: ${{ github.event.number }}

.github/workflows/documentation.yml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.gitignore

@@ -6,3 +6,4 @@ update*
 Manifest.toml
 *.scss
 *.css
+*style.jl

CHANGELOG.md

@@ -1,2 +1,108 @@
+# Changelog for DynamicalSystems
+
 The package DynamicalSystems.jl does not have any actual code.
-It re-exports other packages (see [docs](https://juliadynamics.github.io/DynamicalSystems.jl/dev/#Getting-started). As a result it has no real changelog and one should see the individual packages' changelogs.
+It re-exports other packages. The changelog here only lists major changes to the overarching DynamicalSystems.jl ecosystem. The changelogs of individual subpackages are self-contained for each package.
+
+# DynamicalSystems.jl v3.0
+
+Super duper major update.
+
+1. [Overhauling](#overhauling)
+2. [Modularization](#modularization)
+3. [New documentation](#new-documentation)
+4. [Notable breaking changes](#notable-breaking-changes)
+   1. [Renames](#renames)
+5. [Re-write of `DynamicalSystem`](#re-write-of-dynamicalsystem)
+6. [ODE solver change](#ode-solver-change)
+7. [Package split: StateSpaceSets.jl](#package-split-statespacesetsjl)
+8. [Package split: FractalDimensions.jl](#package-split-fractaldimensionsjl)
+9. [Partial overhaul: RecurrenceAnalysis.jl](#partial-overhaul-recurrenceanalysisjl)
+10. [New amazing package ComplexityMeasures.jl](#new-amazing-package-complexitymeasuresjl)
+11. [New amazing package Attractors.jl](#new-amazing-package-attractorsjl)
+12. [Co-maintainer(s) needed](#co-maintainers-needed)
+
+## Overhauling
+
+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.
+
+## Modularization
+
+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](https://docs.sciml.ai/DiffEqDocs/stable/), 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.
+
+### Renames
+
+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.
+3. 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.
+4. 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: https://juliadynamics.github.io/DynamicalSystemsBase.jl/dev/
+
+## 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.
+
+https://juliadynamics.github.io/StateSpaceSets.jl/dev/
+
+## Package split: FractalDimensions.jl
+
+All functionality related to computing fractal dimensions has been detached from ChaosTools.jl into a new package: https://juliadynamics.github.io/FractalDimensions.jl/dev/
+
+## 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:
+
+https://juliadynamics.github.io/RecurrenceAnalysis.jl/dev/
+
+## New amazing package ComplexityMeasures.jl
+
+This is a complete overhaul and massive enhancement of the previous Entropies.jl and deserves its own announcement post: https://discourse.julialang.org/t/complexitymeasures-jl/95198
+
+## 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!!!
+
+https://juliadynamics.github.io/Attractors.jl/dev/
+
+## 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!

CITATION.bib

@@ -10,3 +10,14 @@ @article{DynamicalSystems.jl-2018
   title = {DynamicalSystems.jl: A Julia software library for chaos and nonlinear dynamics},
   journal = {Journal of Open Source Software}
 }
+
+@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",
+}

CONTRIBUTING.md

@@ -1 +1 @@
-See https://juliadynamics.github.io/DynamicalSystems.jl/latest/contributors_guide/.
+See https://juliadynamics.github.io/DynamicalSystems.jl/dev/contributors_guide/.

Project.toml

@@ -1,23 +1,33 @@
 name = "DynamicalSystems"
 uuid = "61744808-ddfa-5f27-97ff-6e42cc95d634"
 repo = "https://github.com/JuliaDynamics/DynamicalSystems.jl.git"
-version = "2.3.2"
+version = "3.0.0"
 
 [deps]
+Attractors = "f3fd9213-ca85-4dba-9dfd-7fc91308fec7"
 ChaosTools = "608a59af-f2a3-5ad4-90b4-758bdf3122a7"
+ComplexityMeasures = "ab4b797d-85ee-42ba-b621-05d793b346a2"
 DelayEmbeddings = "5732040d-69e3-5649-938a-b6b4f237613f"
 DynamicalSystemsBase = "6e36e845-645a-534a-86f2-f5d4aa5a06b4"
-Entropies = "ed8fcbec-b94c-44b6-89df-898894ad9591"
+FractalDimensions = "4665ce21-e117-4649-aed8-08bbe5ccbead"
+PredefinedDynamicalSystems = "31e2f376-db9e-427a-b76e-a14f56347a14"
 RecurrenceAnalysis = "639c3291-70d9-5ea2-8c5b-839eba1ee399"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Scratch = "6c6a2e73-6563-6170-7368-637461726353"
+StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
+TimeseriesSurrogates = "c804724b-8c18-5caa-8579-6025a0767c70"
 
 [compat]
-ChaosTools = "~2.9.0"
-DelayEmbeddings = "~2.4"
-DynamicalSystemsBase = "~2.8"
-Entropies = "~1.1"
-RecurrenceAnalysis = "~1.8"
-Reexport = "0.2, 0.3, 1"
+ChaosTools = "3"
+DelayEmbeddings = "2.7"
+DynamicalSystemsBase = "3"
+ComplexityMeasures = "2"
+RecurrenceAnalysis = "2"
+FractalDimensions = "1"
+PredefinedDynamicalSystems = "1"
+Reexport = "1"
 Scratch = "1"
-julia = "1.5"
+StateSpaceSets = "1"
+Attractors = "0.1, 0.2, 1"
+TimeseriesSurrogates = "2.1"
+julia = "1.8"

README.md

@@ -1,9 +1,15 @@
 ![DynamicalSystems.jl logo: The Double Pendulum](https://i.imgur.com/nFQFdB0.gif)
 
-[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaDynamics.github.io/DynamicalSystems.jl/dev)
+[![](https://img.shields.io/badge/docs-online-blue.svg)](https://JuliaDynamics.github.io/DynamicalSystems.jl/dev)
 [![DocBuild](https://github.com/juliadynamics/DynamicalSystems.jl/workflows/CI/badge.svg)](https://github.com/JuliaDynamics/DynamicalSystems.jl/actions)
 [![DOI](http://joss.theoj.org/papers/10.21105/joss.00598/status.svg)](https://doi.org/10.21105/joss.00598)
+[![Textbook](https://img.shields.io/badge/Textbook-10.1007%2F978--3--030--91032--7-purple)](https://link.springer.com/book/10.1007/978-3-030-91032-7)
 [![Package Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/DynamicalSystems)](https://pkgs.genieframework.com?packages=DynamicalSystems)
 
-**DynamicalSystems.jl** is an award-winning Julia software library for the exploration of chaos and nonlinear dynamics. The current repository holds the documentation and exports *all* relevant packages.
-**For installation instructions, full content overview and detailed documentation, [click here](https://juliadynamics.github.io/DynamicalSystems.jl/latest/).**
+**DynamicalSystems.jl** is an [award-winning](https://dsweb.siam.org/The-Magazine/Article/winners-of-the-dsweb-2018-software-contest) Julia software library for nonlinear dynamics and nonlinear timeseries analysis. The current repository holds the documentation and exports all packages composing DynamicalSystems.jl.
+
+To install it, run `import Pkg; Pkg.add("DynamicalSystems")`.
+
+**DynamicalSystems.jl** is part of [JuliaDynamics](https://juliadynamics.github.io/JuliaDynamics/), an organization dedicated to creating high quality scientific software.
+
+All further information is provided in the documentation, which you can either find [online](https://juliadynamics.github.io/DynamicalSystems.jl/dev/) or build locally by running the `docs/make.jl` file.

docs/Project.toml

@@ -1,24 +1,16 @@
 [deps]
+Attractors = "f3fd9213-ca85-4dba-9dfd-7fc91308fec7"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 ChaosTools = "608a59af-f2a3-5ad4-90b4-758bdf3122a7"
 DelayEmbeddings = "5732040d-69e3-5649-938a-b6b4f237613f"
-DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
-Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
-DynamicalSystems = "61744808-ddfa-5f27-97ff-6e42cc95d634"
 DynamicalSystemsBase = "6e36e845-645a-534a-86f2-f5d4aa5a06b4"
-Entropies = "ed8fcbec-b94c-44b6-89df-898894ad9591"
-FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+ComplexityMeasures = "ab4b797d-85ee-42ba-b621-05d793b346a2"
 InteractiveDynamics = "ec714cd0-5f51-11eb-0b6e-452e7367ff84"
-Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
-GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
-Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
-Neighborhood = "645ca80c-8b79-4109-87ea-e1f58159d116"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 RecurrenceAnalysis = "639c3291-70d9-5ea2-8c5b-839eba1ee399"
-SimpleDiffEq = "05bca326-078c-5bf0-a5bf-ce7c7982d7fd"
-StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
-StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+FractalDimensions = "4665ce21-e117-4649-aed8-08bbe5ccbead"