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.fixedpointsFunction
fixedpoints(
    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 of DynamicalSystems.jl.

Input

  • bmin (Vector): lower limits of the state space box to be considered, as a vector of coordinates
  • bmax (Vector): upper limits
  • alternatively box (IntervalBox) can replace bmin and bmax

Example: fixedpoints(sys, [-2,-1,0], [2,1,1]) finds the fixed points of the 3D system sys in a cube defined by the intervals [-2,2] × [-1,1] × [0,1].

Output

[fp, eigs, stable]

  • fp: StateSpaceSet of fixed points
  • eigs: vector of Jacobian eigenvalues of each fixed point
  • stable: vector of booleans indicating the stability of each fixed point (true=stable, false=unstable)

Additional methods

  • fixedpoints(sys::CoupedSDEs, box)
source

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.edgetrackingFunction
edgetracking(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 StateSpaceSets, 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 of attractors).
  • u2: second initial state (defaults to first point in second entry of attractors).
  • 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 to step! 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 to AttractorsViaProximity. We strongly recommend to either pass in a high Ttr, or a very small ε, (smaller than the default estimated by AttractorsViaProximity) 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.

source
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 settings
  • kwargs...: all keyword arguments of Attractors.edgetracking
source
Attractors.bisect_to_edgeFunction
bisect_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.

Info

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.

source
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 in attractors)
  • u2: State 2 (default: second state in attractors)
  • bisect_thresh=1e-6: distance threshold
  • diffeq=(;alg = Vern9(), reltol=1e-11): ODE solver settings
  • verbose=false: Verbosity of output
  • ϵ_mapper=nothing: ϵ argument of Attractors.AttractorsViaProximity
  • kwargs...: Keyword arguments passed to Attractors.AttractorsViaProximity
source
Attractors.EdgeTrackingResultsType
EdgeTrackingResults(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 between track1 and track2)
  • track1::StateSpaceSet: the pseudo-trajectory tracking the edge within basin 1
  • track2::StateSpaceSet: the pseudo-trajectory tracking the edge within basin 2
  • time::Vector: time points of the above StateSpaceSets
  • bisect_idx::Vector: indices of time at which a re-bisection occurred
  • success::Bool: indicates whether the edge tracking has been successful or not
source