better docs (#255)

Datseris · web-flow · commit 95356178dd4d · 2025-09-05T10:37:28.000+01:00
* improve version docs

* remove outdated donation information

* add two more packages to the ecosystem

* update reinventing the wheel goal

* finish updatupdatee tuytorial

* add periodicorbits.jl part 1

* improve how to cite

* add periodic orbits

* update changelog

* use signal decomposition

* add new packages to the docs

* fix missing docs

* change parallelization to oh my threads
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,14 @@ The changelog here therefore lists either major changes to the overarching Dynam
 
 The changelogs of individual sub-packages are self-contained for each package.
 
+
+# v3.5
+
+- Improved documentation regarding versions
+- Improved documentation regarding citing
+- Added SignalDecomposition.jl into DynamicalSystems.jl
+- Added PeriodicOrbits.jl into DynamicalSystems.jl
+
 # v3.4
 
 Some important fixes on the `interactive_trajectory` GUI:
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "DynamicalSystems"
 uuid = "61744808-ddfa-5f27-97ff-6e42cc95d634"
 repo = "https://github.com/JuliaDynamics/DynamicalSystems.jl.git"
-version = "3.4.3"
+version = "3.5.0"
 
 [deps]
 Attractors = "f3fd9213-ca85-4dba-9dfd-7fc91308fec7"
@@ -16,6 +16,8 @@ RecurrenceAnalysis = "639c3291-70d9-5ea2-8c5b-839eba1ee399"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
 TimeseriesSurrogates = "c804724b-8c18-5caa-8579-6025a0767c70"
+SignalDecomposition = "11a47235-7b84-4c7c-b885-fc3e2a9cf955"
+PeriodicOrbits = "41be5fce-5647-450b-ae37-a6739b881a1c"
 
 [weakdeps]
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
@@ -24,7 +26,7 @@ Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 DynamicalSystemsVisualizations = "Makie"
 
 [compat]
-Attractors = "0.1, 0.2, 1"
+Attractors = "1"
 ChaosTools = "3"
 ComplexityMeasures = "2, 3"
 DataStructures = "0.18, 0.19"
@@ -37,6 +39,8 @@ RecurrenceAnalysis = "2"
 Reexport = "1"
 StateSpaceSets = "2"
 TimeseriesSurrogates = "2.1"
+SignalDecomposition = "1.2"
+PeriodicOrbits = "0.1"
 julia = "1.9"
 
 [extras]
diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@ Aspects of **DynamicalSystems.jl** that make it stand out among other codebases
 - **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, bugfixes. The developer team routinely answers users questions on official Julia language forums.
+- **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
@@ -54,3 +54,14 @@ You see, it is unfortunately rarely the case that real, _runnable_ code is shown
 
 **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!
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -18,3 +18,5 @@ RecurrenceAnalysis = "639c3291-70d9-5ea2-8c5b-839eba1ee399"
 StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"
+SignalDecomposition = "11a47235-7b84-4c7c-b885-fc3e2a9cf955"
+PeriodicOrbits = "41be5fce-5647-450b-ae37-a6739b881a1c"
diff --git a/docs/make.jl b/docs/make.jl
@@ -38,7 +38,9 @@ build_docs_with_style(pages, DynamicalSystems,
     Attractors,
     FractalDimensions,
     TimeseriesSurrogates,
-    PredefinedDynamicalSystems;
+    PredefinedDynamicalSystems,
+    SignalDecomposition,
+    PeriodicOrbits;
     authors = "George Datseris <datseris.george@gmail.com>",
     expandfirst = ["index.md"],
     # We need to remove the cross references because we don't list here
diff --git a/docs/src/contents.md b/docs/src/contents.md
@@ -13,17 +13,19 @@ The submodules that compose **DynamicalSystems.jl** are the following packages,
 - [`StateSpaceSets`](@ref)
 - [`DynamicalSystemsBase`](@ref)
 
-**For observed/measured data**
+**For observed/measured data and timeseries**
 - [`ComplexityMeasures`](@ref)
 - [`RecurrenceAnalysis`](@ref)
 - [`DelayEmbeddings`](@ref)
 - [`FractalDimensions`](@ref)
 - [`TimeseriesSurrogates`](@ref)
+- [`SignalDecomposition`](@ref)
 
 **For dynamical system instances**
 - [`PredefinedDynamicalSystems`](@ref)
 - [`ChaosTools`](@ref)
 - [`Attractors`](@ref)
+- [`PeriodicOrbits`](@ref)
 
 At the very end of this page, a full list of exported names is presented.
 
@@ -43,6 +45,7 @@ RecurrenceAnalysis
 DelayEmbeddings
 FractalDimensions
 TimeseriesSurrogates
+SignalDecomposition
 ```
 
 ## For dynamical system instances
@@ -51,6 +54,7 @@ TimeseriesSurrogates
 PredefinedDynamicalSystems
 ChaosTools
 Attractors
+PeriodicOrbits
 ```
 
 ## All exported names
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -49,21 +49,25 @@ The materials of the course are on GitHub: <https://github.com/JuliaDynamics/Non
 
 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 subcomponent, 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 submodule (or subpackage, or subcomponent) that you used directly, if it has an associated publication (see example below).
+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{@SampleEntropy}` that is implemented in the ComplexityMeasures.jl component `\cite{ComplexityMeasures}` of the DynamicalSystems.jl library `\cite{DynamicalSystems}`.
+> 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, one more example:
+or,
 
-> For the surrogates for the atmospheric temperature timeseries we used the random cascade surrogates `\cite{Palus2008} that is implemented in the TimeseriesSurrogates.jl component `\cite{TimeseriesSurrogates}` of the DynamicalSystems.jl library `\cite{DynamicalSystems}`.
+> 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 find useful the Nonlinear Dynamics textbook that utilizes **DynamicalSystems.jl**, which you can cite as:
+Besides the library, you may also find useful the Nonlinear Dynamics textbook that utilizes **DynamicalSystems.jl**, which you can cite as:
 
 ```
 @book{DatserisParlitz2022,
@@ -86,28 +90,19 @@ There are three options for asking questions:
 2. As a message in our channel `#dynamics-bridged` in the [Julia Slack](https://julialang.org/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](https://github.com/JuliaDynamics/DynamicalSystems.jl) while providing a Minimal Working Example. This option is preferred when you encounter unexpected behavior.
 
-## Contributing & Donating
+## Contributing
 
 Be sure to visit the [Contributor Guide](@ref) 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](https://github.com/JuliaDynamics/DynamicalSystems.jl)! 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](https://www.bountysource.com/), 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](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+org%3AJuliaDynamics+label%3Abounty).
-
-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](https://github.com/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.
+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
+## 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.
+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:
 
 ```@setup MAIN
@@ -118,14 +113,16 @@ using CairoMakie, DynamicalSystems
 using Pkg
 Pkg.status([
     "DynamicalSystems",
-    "StateSpaceSets", "DynamicalSystemsBase", "RecurrenceAnalysis", "FractalDimensions", "DelayEmbeddings", "ComplexityMeasures", "TimeseriesSurrogates", "PredefinedDynamicalSystems", "Attractors", "ChaosTools", "CairoMakie",
+    "StateSpaceSets", "DynamicalSystemsBase", "RecurrenceAnalysis", "FractalDimensions", "DelayEmbeddings", "ComplexityMeasures", "TimeseriesSurrogates", "PredefinedDynamicalSystems", "Attractors", "TransitionsInTimeseries", "SignalDecomposition", "ChaosTools", "CairoMakie",
     ];
     mode = PKGMODE_MANIFEST
 )
 ```
 
 !!! warn "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.
+    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
@@ -139,7 +136,6 @@ Besides DynamicalSystems.jl, the Julia programming language has a thriving ecosy
 * [NetworkDynamics.jl](https://github.com/PIK-ICoNe/NetworkDynamics.jl) - Simulating dynamics on networks and transforming network systems into `ODEProblem` (that can be made directly into a `ContinuousDynamicalSystem`).
 * [Agents.jl](https://github.com/JuliaDynamics/Agents.jl) - Agent based modelling.
 * [EasyModelAnalysis.jl](https://github.com/SciML/EasyModelAnalysis.jl) - Analysis tools for conveniently analysing solutions of DiffEq systems.
-* [SignalDecomposition.jl](https://github.com/JuliaDynamics/SignalDecomposition.jl) - Decompose a signal/timeseries into structure and noise or seasonal and residual components.
 * [ARFIMA.jl](https://github.com/JuliaDynamics/ARFIMA.jl) - generate ARFIMA process timeseries.
 * [ConcurrentSim.jl](https://github.com/JuliaDynamics/ConcurrentSim.jl) - discrete event process oriented simulation framework.
-* [CausalityTools.jl](https://github.com/JuliaDynamics/CausalityTools.jl) - hundreds of algorithms for relational/causal timeseries analysis and causal graphs.
+* [Associations.jl](https://github.com/JuliaDynamics/Associations.jl) - hundreds of algorithms for relational/causal timeseries analysis and causal graphs.
diff --git a/docs/src/tutorial.jl b/docs/src/tutorial.jl
diff --git a/src/DynamicalSystems.jl b/src/DynamicalSystems.jl
