Functions and docstrings of the common interface

[JonasKoziorek]

Status

Ready for review.

[Datseris]

perhaps we should modify all functions to also report the linear (local) stability of the periodic orbits? It seems to me that this information would always be needed. I can't iamgine a situation where someone would care about obtaining POs but not about their stability.

[JonasKoziorek]

Yes, I agree.

[Datseris]

Right, so we decided that the library will always report (linear/local) stability when returning an orbit?

[JonasKoziorek]

Yes, I think it's good to report stability. However that means that we will need to pass Jacobians to each method to determine stability (at least in discrete case, not sure how stability checking works in continuous case). Methods that didn't need Jacobian will now need it and that can cause trouble for example when ds is PoincareMap.

[Datseris]

Methods that didn't need Jacobian will now need it and that can cause trouble for example when ds is PoincareMap

I am not aware of any method that can find unstable periodic orbits on a Poincare map. When you applied the Diakonos algorithm to Poincare maps, did it find anything unstable?

My reasoning is that, at least in DynamicalSystems.jl, PoincareMap is a simple construct: it forward evolves an internal ODE until it crosses a hyper plane. Due to the nature of this computation, forwarding in time, a unstable periodic orbit would not be yielded by iterating the map. I assume at least.

The alternative is to allow the stability to have an unknown value as well. So it can be true, false, or missing.

[Datseris]

Then we use missing for cases like poincare maps, or anything we can't extract the stability.

[Datseris]

in this PR we don't have to alter any algorithms, we only need to decide whether stable must be a component of the PO or not.

[JonasKoziorek]

I have already added stable::Bool to the PO structure. I still have to modify the structure to allow for missing. Should periodic_orbit(s) have additional argument for a jacobian so that stability can be computed?

I am not aware of any method that can find unstable periodic orbits on a Poincare map. When you applied the Diakonos algorithm to Poincare maps, did it find anything unstable?

How do I know if it is unstable or stable if I don't have the jacobian? For example with Schmelcher & Diakonos I found three fixed points of the poincare map of Thomas Cyclical system. Perhaps some of them are unstable.

[Datseris]

How do I know if it is unstable or stable if I don't have the jacobian?

Initialize an initial condition very close to the state and see if it converges to it. That is the definition of a stable state. The Jacobian is just a proxy.

[Datseris]

. I still have to modify the structure to allow for missing

Let's not do this now. Let's assume all methods find the stability. for poincare map everything is stable unless proven otherwise.

[Datseris]

I am merging this in; there are small stylistic changes to do but this can happen later.