Add finishing touches for registration (#34)

* improve docstrings of key functions. improve periodic_orbits

* improve the remake/solve call in optimized shooting

* mention NLSolve algorithm used

* separate error function in optimized shooting

* bring algorithms to API section

* a bit more info in developer's docs

* better readme

* improve tutorial

* clarify what happens at algorithm failure

* rename `isstable` to `postability`

* better orient apio

b

* add todo for an example

* update CI

* fix almost all errors

* fix davidchack tests

Author: Datseris

.github/workflows/CompatHelper.yml

@@ -42,3 +42,4 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+          # COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV }}

.github/workflows/test_coverage.yml renamed to .github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI - test & coverage
+name: CI
 on:
   pull_request:
     branches:
@@ -34,7 +34,7 @@ jobs:
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v1
+      - uses: actions/cache@v4
         env:
           cache-name: cache-artifacts
         with:

Project.toml

@@ -8,14 +8,12 @@ Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 DynamicalSystemsBase = "6e36e845-645a-534a-86f2-f5d4aa5a06b4"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
-OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 
 [compat]
 Combinatorics = "1"
 DynamicalSystemsBase = "3.8"
 NonlinearSolve = "4"
-OrdinaryDiffEq = "6"
 Reexport = "1"
 julia = "1.9"

README.md

@@ -1,17 +1,20 @@
 # PeriodicOrbits.jl
 
 [![docsdev](https://img.shields.io/badge/docs-dev-lightblue.svg)](https://juliadynamics.github.io/PeriodicOrbits.jl/dev/)
-[![docsstable](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliadynamics.github.io/DynamicalSystemsDocs.jl/periodicorbits/stable/)
+<!-- [![docsstable](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliadynamics.github.io/DynamicalSystemsDocs.jl/periodicorbits/stable/) -->
 [![](https://img.shields.io/badge/DOI-10.1007%2F978--3--030--91032--7-purple)](https://link.springer.com/book/10.1007/978-3-030-91032-7)
 [![CI](https://github.com/JuliaDynamics/PeriodicOrbits.jl/workflows/CI/badge.svg)](https://github.com/JuliaDynamics/PeriodicOrbits.jl/actions?query=workflow%3ACI)
 [![codecov](https://codecov.io/gh/JuliaDynamics/PeriodicOrbits.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliaDynamics/PeriodicOrbits.jl)
 [![Package Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/PeriodicOrbits)](https://pkgs.genieframework.com?packages=PeriodicOrbits)
 
-Interface and algorithms for finding both stable and unstable periodic orbits of dynamical systems based on the DynamicalSystems.jl ecosystem.
+**PeriodicOrbits.jl** provides both the interface and algorithm implementations for finding stable and unstable periodic orbits of dynamical systems based on the DynamicalSystems.jl ecosystem.
 
-Currently this is work in progress and the interface is being finalized. The package is not registered yet.
+Currently this is work in progress and the interface is being finalized. The package is not registered yet. To install it, run
+```
+import Pkg; Pkg.add(url = "https://github.com/JuliaDynamics/PeriodicOrbits.j")
+```
 
-To install it, run `import Pkg; Pkg.add(url = "https://github.com/JuliaDynamics/PeriodicOrbits.j")`.
+In the future this package will be a basis for local continuation integrated with DynamicalSystems.jl.
 
 All further information is provided in the documentation, which you can either find online or build locally by running the `docs/make.jl` file.
 

docs/make.jl

@@ -7,9 +7,7 @@ pages = [
     "index.md",
     "tutorial.md",
     "api.md",
-    "algorithms.md",
     "examples.md",
-    "developer.md",
     "references.md"
 ]
 

docs/src/algorithms.md

@@ -1,17 +1,51 @@
 # The Public API
 
+## Main functions
 
 ```@docs
-PeriodicOrbit
-InitialGuess
 periodic_orbit
 periodic_orbits
+PeriodicOrbitFinder
+InitialGuess
+PeriodicOrbit
 ```
+
 ## Algorithms for Discrete-Time Systems
 
 - [`SchmelcherDiakonos`](@ref)
 - [`DavidchackLai`](@ref)
 
+```@docs
+SchmelcherDiakonos
+lambdamatrix
+lambdaperms
+```
+
+```@docs
+DavidchackLai
+```
+
 ## Algorithms for Continuous-Time Systems
 
 - [`OptimizedShooting`](@ref)
+
+```@docs
+OptimizedShooting
+```
+
+## Utility functions
+
+```@docs
+postability
+minimal_period
+podistance
+poequal
+uniquepos
+PeriodicOrbits.isdiscretetime
+```
+
+
+## Adding new algorithms
+
+To implement a new periodic orbit finding algorithm, simply create a new type,
+make it subtype `PeriodicOrbitFinder`, and then extend the function [`periodic_orbit`](@ref) for it.

docs/src/api.md

@@ -1,6 +1,7 @@
 # Examples
 
 ## Optimized Shooting Example
+
 ```@example MAIN
 using PeriodicOrbits
 using CairoMakie
@@ -30,6 +31,7 @@ plot_result(res, ds; azimuth = 1.3pi, elevation=0.1pi)
 ```
 
 ## SchmelcherDiakonos example
+
 For example, let's find the fixed points of the Standard map of period 2, 3, 4, 5, 6
 and 8. We will use all permutations for the `signs` but only one for the `inds`.
 We will also only use one `λ` value, and a 11×11 density of initial conditions.
@@ -124,7 +126,7 @@ Okay, this output is great, and we can tell that it is correct because:
 ### Logistic map example
 
 The idea of periodic orbits can be illustrated easily on 1D maps. Finding all periodic orbits of period
-$n$ is equivalent to finding all points $x$ such that $f^{n}(x)=x$, where $f^{n}$ is $n$-th composition of $f$. Hence, solving $f^{n}(x)-x=0$ yields such points. However, this is often impossible analytically. 
+$n$ is equivalent to finding all points $x$ such that $f^{n}(x)=x$, where $f^{n}$ is $n$-th composition of $f$. Hence, solving $f^{n}(x)-x=0$ yields such points. However, this is often impossible analytically.
 Let's see how [`DavidchackLai`](@ref) deals with it:
 
 First let's start with finding periodic orbits with period $1$ to $9$ for the logistic map with parameter $3.72$.
@@ -141,7 +143,7 @@ output = periodic_orbits(ds, alg, seeds)
 output = uniquepos(output);
 ```
 
-Let's plot the periodic orbits of period $6$. 
+Let's plot the periodic orbits of period $6$.
 
 ```@example MAIN
 function ydata(ds, period, xdata)
@@ -168,14 +170,14 @@ lines!(axis, x, y, color = :blue, linewidth=1.7)
 scatter!(axis, [i[1] for i in fpsx], fpsy, color = :red, markersize=15)
 fig
 ```
-Points $x$ which fulfill $f^{n}(x)=x$ can be interpreted as an intersection of the function 
-$f^{n}(x)$ and the identity function $y=x$. Our result is correct because all the points of 
-the intersection between the identity function and the sixth iterate of the logistic map 
+Points $x$ which fulfill $f^{n}(x)=x$ can be interpreted as an intersection of the function
+$f^{n}(x)$ and the identity function $y=x$. Our result is correct because all the points of
+the intersection between the identity function and the sixth iterate of the logistic map
 were found.
 
 ### Henon Map example
 
-Let's try to use [`DavidchackLai`](@ref) in higher dimension. We will try to detect 
+Let's try to use [`DavidchackLai`](@ref) in higher dimension. We will try to detect
 all periodic points of Henon map of period `1` to `12`.
 
 ```@example MAIN
@@ -213,5 +215,5 @@ fig
 ```
 The theory of periodic orbits states that UPOs form sort of a skeleton of the chaotic attractor. Our results supports this claim since it closely resembles the Henon attractor.
 
-Note that in this case parameter `m` has to be set to at least `6`. Otherwise, the algorithm 
+Note that in this case parameter `m` has to be set to at least `6`. Otherwise, the algorithm
 fails to detect orbits of higher periods correctly.

docs/src/developer.md

@@ -1,34 +1,43 @@
 # Tutorial
 
-Let's attempt to detect a periodic orbit of the Lorenz system. First we define the Lorenz 
-system itself.
+In this tutorial we will detect an unstable periodic orbit of the well-known Lorenz-63 dynamical system. The tutorial assumes you are familiar with **DynamicalSystems.jl**; go through its overarching tutorial first if not.
+
+First we define the Lorenz-63 system itself.
 
 ```@example MAIN
-using PeriodicOrbits
+using PeriodicOrbits # or `DynamicalSystems`
 
-function lorenz(u0=[0.0, 10.0, 0.0]; σ = 10.0, ρ = 28.0, β = 8/3)
-    return CoupledODEs(lorenz_rule, u0, [σ, ρ, β]; diffeq=(abstol=1e-10, reltol=1e-10))
+function lorenz63(u0=[0.0, 10.0, 0.0]; σ = 10.0, ρ = 28.0, β = 8/3)
+    diffeq = (abstol=1e-10, reltol=1e-10) # higher accuracy
+    return CoupledODEs(lorenz63_rule, u0, [σ, ρ, β]; diffeq)
 end
-@inbounds function lorenz_rule(u, p, t)
+@inbounds function lorenz63_rule(u, p, t)
     du1 = p[1]*(u[2]-u[1])
     du2 = u[1]*(p[2]-u[3]) - u[2]
     du3 = u[1]*u[2] - p[3]*u[3]
     return SVector{3}(du1, du2, du3)
 end
 
-ds = lorenz()
+ds = lorenz63()
 ```
+At the default parameter values the system is chaotic; it only has unstable periodic orbits.
+
+Given a dynamical system, the main function of the package is [`periodic_orbit`](@ref) which will find unstable/stable periodic orbits and return them.
+To call it, we need two things:
+1. An initial guess.
+2. A periodic orbit finding algorithm.
 
-Next, we give initial guess of the location of the periodic orbit and its period.
+For the initial guess Next, we give initial guess of the location of the periodic orbit and its period. The initial guess must be an instance of [`InitialGuess`](@ref).
 
 ```@example MAIN
 u0_guess = SVector(1.0, 2.0, 5.0)
 T_guess = 4.2
-ig = InitialGuess(u0_guess, T_guess) 
+ig = InitialGuess(u0_guess, T_guess)
 ```
-Then we pick an appropriate algorithm that will detect the PO. In this case we can use 
-any algorithm intended for continuous-time dynamical systems. We choose Optimized Shooting 
-algorithm, for more information see [`OptimizedShooting`](@ref).
+
+Then we pick an appropriate algorithm that will detect the PO.
+In this case we can use any algorithm intended for continuous time dynamical systems.
+We choose [`OptimizedShooting`](@ref) (see the documentation for more information).
 
 ```@example MAIN
 alg = OptimizedShooting(Δt=0.01, n=3)
@@ -41,43 +50,45 @@ po = periodic_orbit(ds, alg, ig)
 po
 ```
 
-The closed curve of the periodic orbit can be visualized using plotting library such as 
-[`Makie`](https://github.com/MakieOrg/Makie.jl).
+The closed curve of the periodic orbit can be visualized using plotting library such as [`Makie`](https://github.com/MakieOrg/Makie.jl).
+Here we will visualize it inside an otherwise normal trajectory of the system.
 
 
 ```@example MAIN
 using CairoMakie
 
-u0 = po.points[1]
-T = po.T
-traj, t = trajectory(ds, T, u0; Dt = 0.01)
+# plot trajectory
+X, t = trajectory(ds, 100.0; Δt = 0.01)
 fig = Figure()
 ax = Axis3(fig[1,1], azimuth = 0.6pi, elevation= 0.1pi)
-lines!(ax, traj[:, 1], traj[:, 2], traj[:, 3], color = :blue, linewidth=1.7)
-scatter!(ax, u0)
+lines!(ax, X, color = :black, linewidth=1.0)
+# over-plot the PO
+u0 = po.points[1]
+T = po.T
+traj, t = trajectory(ds, T, u0; Δt = 0.01)
+lines!(ax, traj; color = :blue, linewidth=3)
 fig
 ```
 
-To ensure that the detected period is minimal, eg. it is not a multiple of the minimal 
-period, we can use [`minimal_period`](@ref).
+To ensure that the detected period is minimal, eg. it is not a multiple of the minimal period, we can use [`minimal_period`](@ref).
 
 ```@example MAIN
 minT_po = minimal_period(ds, po)
 minT_po
 ```
 
-Whether two periodic orbits are equivalent up to some tolerance. Function [`poequal`](@ref) 
-can be used.
+We see that the orbit is indeed minimal; the period did not change.
+To check whether two periodic orbits are equivalent up to some tolerance, the function [`poequal`](@ref) can be used.
 
 ```@example MAIN
 equal = poequal(po, minT_po; dthres=1e-3, Tthres=1e-3)
 "Detected periodic orbit had minimal period: $(equal)"
 ```
 
-To determine whether found periodic orbit is stable or unstable, we can apply 
-[`isstable`](@ref) function.
+Most algorithms do not detect the stability of a PO automatically, so you can see it is reported as `missing` above.
+To determine whether found periodic orbit is stable or unstable, we can apply the [`postability`](@ref) function.
 
 ```@example MAIN
-po = isstable(ds, po)
+po = postability(ds, po)
 "Detected periodic orbit is $(po.stable ? "stable" : "unstable")."
-```
+```