Analyzing a system's stability properties
To use the following functionalities, you need to load ChoasTools.jl
and Attractors.jl
(which are included as dependencies in CriticalTransitions.jl).
Fixed points
ChaosTools.fixedpoints
— Functionfixedpoints(
sys::CoupledSDEs,
bmin::Vector,
bmax::Vector
) -> Tuple{StateSpaceSet, Vector{Vector{ComplexF64}}, Vector{Bool}}
Returns fixed points, their eigenvalues and stability of the system sys
within the state space volume defined by bmin
and bmax
.
This is a wrapper around the
fixedpoints
function ofDynamicalSystems.jl
.
Input
bmin
(Vector): lower limits of the state space box to be considered, as a vector of coordinatesbmax
(Vector): upper limits- alternatively
box
(IntervalBox) can replacebmin
andbmax
Example:
fixedpoints(sys, [-2,-1,0], [2,1,1])
finds the fixed points of the 3D systemsys
in a cube defined by the intervals[-2,2] × [-1,1] × [0,1]
.
Output
[fp, eigs, stable]
fp
:StateSpaceSet
of fixed pointseigs
: vector of Jacobian eigenvalues of each fixed pointstable
: vector of booleans indicating the stability of each fixed point (true
=stable,false
=unstable)
Additional methods
fixedpoints(sys::CoupedSDEs, box)
Edge tracking
The edge tracking algorithm is a simple numerical method to find the edge state or (possibly chaotic) saddle on the boundary between two basins of attraction. It is first introduced by Battelino et al. [1] and further described by Skufca et al. [2] and Mehling et al. [3].
Attractors.edgetracking
— Functionedgetracking(ds::DynamicalSystem, attractors::Dict; kwargs...)
Track along a basin boundary in a dynamical system ds
with two or more attractors in order to find an edge state. Results are returned in the form of EdgeTrackingResults
, which contains the pseudo-trajectory edge
representing the track on the basin boundary, along with additional output (see below).
The system's attractors
are specified as a Dict
of StateSpaceSet
s, as in AttractorsViaProximity
or the output of extract_attractors
. By default, the algorithm is initialized from the first and second attractor in attractors
. Alternatively, the initial states can be set via keyword arguments u1
, u2
(see below). Note that the two initial states must belong to different basins of attraction.
Keyword arguments
bisect_thresh = 1e-7
: distance threshold for bisection.diverge_thresh = 1e-6
: distance threshold for parallel integration.u1
: first initial state (defaults to first point in first entry ofattractors
).u2
: second initial state (defaults to first point in second entry ofattractors
).maxiter = 100
: maximum number of iterations before the algorithm stops.abstol = 1e-9
: distance threshold for convergence of the updated edge state.T_transient = 0.0
: transient time before the algorithm starts saving the edge track.tmax = Inf
: maximum integration time of parallel trajectories until re-bisection.Δt = 0.01
: time step passed tostep!
when evolving the two trajectories.show_progress = true
: if true, shows progress bar and information while running.verbose = true
: if false, silences print output and warnings while running.kw...
: additional keyword arguments to be passed toAttractorsViaProximity
. We strongly recommend to either pass in a highTtr
, or a very smallε
, (smaller than the default estimated byAttractorsViaProximity
) to avoid transient parts of trajectories wrongly being classified as having converged.
Description
The edge tracking algorithm is a numerical method to find an edge state or (possibly chaotic) saddle on the boundary between two basins of attraction. Introduced by [1] and further described by [2], the algorithm has been applied to, e.g., the laminar-turbulent boundary in plane Couette flow [4], Wada basins [5], as well as Melancholia states in conceptual [3] and intermediate-complexity [6] climate models. Relying only on forward integration of the system, it works even in high-dimensional systems with complicated fractal basin boundary structures.
The algorithm consists of two main steps: bisection and tracking. First, it iteratively bisects along a straight line in state space between the intial states u1
and u2
to find the separating basin boundary. The bisection stops when the two updated states are less than bisect_thresh
(Euclidean distance in state space) apart from each other. Next, a ParallelDynamicalSystem
is initialized from these two updated states and integrated forward until the two trajectories diverge from each other by more than diverge_thresh
(Euclidean distance). The two final states of the parallel integration are then used as new states u1
and u2
for a new bisection, and so on, until a stopping criterion is fulfilled.
Two stopping criteria are implemented via the keyword arguments maxiter
and abstol
. Either the algorithm stops when the number of iterations reaches maxiter
, or when the state space position of the updated edge point changes by less than abstol
(in Euclidean distance) compared to the previous iteration. Convergence below abstol
happens after sufficient iterations if the edge state is a saddle point. However, the edge state may also be an unstable limit cycle or a chaotic saddle. In these cases, the algorithm will never actually converge to a point but (after a transient period) continue populating the set constituting the edge state by tracking along it.
A central idea behind this algorithm is that basin boundaries are typically the stable manifolds of unstable sets, namely edge states or saddles. The flow along the basin boundary will thus lead to these sets, and the iterative bisection neutralizes the unstable direction of the flow away from the basin boundary. If the system possesses multiple edge states, the algorithm will find one of them depending on where the initial bisection locates the boundary.
Output
Returns a data type EdgeTrackingResults
containing the results.
Sometimes, the AttractorMapper used in the algorithm may erroneously identify both states u1
and u2
with the same basin of attraction due to being very close to the basin boundary. If this happens, a warning is raised and EdgeTrackingResults.success = false
.
edgetracking(ds::CoupledSDEs, attractors::Dict; diffeq, kwars...)
Runs the edge tracking algorithm for the deterministic part of the CoupledSDEs ds
.
Keyword arguments
diffeq=(;alg = Vern9(), reltol=1e-11)
: ODE solver settingskwargs...
: all keyword arguments ofAttractors.edgetracking
Attractors.bisect_to_edge
— Functionbisect_to_edge(pds::ParallelDynamicalSystem, mapper::AttractorMapper; kwargs...) -> u1, u2
Finds the basin boundary between two states u1, u2 = current_states(pds)
by bisecting along a straight line in phase space. The states u1
and u2
must belong to different basins.
Returns a triple u1, u2, success
, where u1, u2
are two new states located on either side of the basin boundary that lie less than bisect_thresh
(Euclidean distance in state space) apart from each other, and success
is a Bool indicating whether the bisection was successful (it may fail if the mapper
maps both states to the same basin of attraction, in which case a warning is raised).
Keyword arguments
bisect_thresh = 1e-7
: The maximum (Euclidean) distance between the two returned states.
Description
pds
is a ParallelDynamicalSystem
with two states. The mapper
must be an AttractorMapper
of subtype AttractorsViaProximity
or AttractorsViaRecurrences
.
If the straight line between u1
and u2
intersects the basin boundary multiple times, the method will find one of these intersection points. If more than two attractors exist, one of the two returned states may belong to a different basin than the initial conditions u1
and u2
. A warning is raised if the bisection involves a third basin.
bisect_to_edge(ds::CoupledSDEs, attractors::Dict;
u1, u2, bisect_thresh, diffeq, verbose, kwargs...)
Runs the bisect_to_edge
function for the deterministic part of the CoupledSDEs ds
.
Keyword arguments
u1
: State 1 (default: first state inattractors
)u2
: State 2 (default: second state inattractors
)bisect_thresh=1e-6
: distance thresholddiffeq=(;alg = Vern9(), reltol=1e-11)
: ODE solver settingsverbose=false
: Verbosity of outputϵ_mapper=nothing
: ϵ argument ofAttractors.AttractorsViaProximity
kwargs...
: Keyword arguments passed toAttractors.AttractorsViaProximity
Attractors.EdgeTrackingResults
— TypeEdgeTrackingResults(edge, track1, track2, time, bisect_idx)
Data type that stores output of the edgetracking
algorithm.
Fields
edge::StateSpaceSet
: the pseudo-trajectory representing the tracked edge segment (given by the average in state space betweentrack1
andtrack2
)track1::StateSpaceSet
: the pseudo-trajectory tracking the edge within basin 1track2::StateSpaceSet
: the pseudo-trajectory tracking the edge within basin 2time::Vector
: time points of the aboveStateSpaceSet
sbisect_idx::Vector
: indices oftime
at which a re-bisection occurredsuccess::Bool
: indicates whether the edge tracking has been successful or not