Iterator Interface

The iterator interface gives the possibility of stepping through the numerical steps of the continuation procedure. It thus allows to inject custom monitoring function (saving, plotting, bifurcation detection, ...) at will and during the continuation run. In short, it allows to completely re-write the continuation algorithm as one sees fit and this, in a straightforward manner.

The general method continuation is built upon this iterator interface and we refer to the source code for a complete example of use.

Warning

The iterator provided below does not compute eigenvalues nor performs bifurcations detection.

Initialization

More information about iterators can be found on the page of julialang.

The interface is set by defining an iterator, pretty much in the same way one calls continuation:

iter = ContIterable(prob, alg, opts; kwargs...)

Stepping

Once an iterator iter has been defined, one can step through the numerical continuation using a for loop:

for state in iter
	println("Continuation step = ", state.step)
end

The state::ContState has the following description. It is a mutable object which holds the current state of the continuation procedure from which one can step to the next state.

The for loop stops when done(iter, state) returns false. The condition which is implemented is basically that the number of iterations should be smaller than maxIter, that the parameters should be in (p_min, p_max)...

BifurcationKit.ContState — Type

mutable struct ContState{Tv, T, Teigvals, Teigvec, Tcb} <: BifurcationKit.AbstractContinuationState{Tv}

Structure containing the state of the continuation procedure. The fields are meant to change during the continuation procedure.

Danger

If you mutate these fields yourself, you can break the continuation procedure. Use the methods below to access the fields knowing that they do not yield copies.

Arguments

z_pred current solution on the branch
converged Boolean for newton correction
τ tangent predictor
z previous solution
itnewton Number of newton iteration (in corrector)
step current continuation step
ds step size
stopcontinuation Boolean to stop continuation

Useful functions

copy(state) returns a copy of state
copyto!(dest, state) copy state into dest
getsolution(state) returns the current solution (x, p)
gettangent(state) return the tangent at the current solution
getpredictor(state) return the predictor at the current solution
getx(state) returns the x component of the current solution
getp(state) returns the p component of the current solution
get_previous_solution(state) returns the previous solution (x, p)
getpreviousx(state) returns the x component of the previous solution
getpreviousp(state) returns the p component of the previous solution
is_stable(state) whether the current state is stable

source

continuation

You can also call continuation(iter) to have access to the regular continuation method used throughout the tutorials.

Basic example

We show a quick and simple example of use. Note that it is not very optimized because of the use of global variables.

using BifurcationKit, Plots
const BK = BifurcationKit

k = 2

# functional we want to study
F(x, p) = (@. p + x - x^(k+1)/(k+1))

# bifurcation problem
prob = BifurcationProblem(F, [0.8], 1., (@optic _))

# parameters for the continuation
opts = ContinuationPar(dsmax = 0.1, dsmin = 1e-3, ds = -0.001, max_steps = 130, p_min = -3., p_max = 3., newton_options = NewtonPar(tol = 1e-8))

# we define an iterator to hold the continuation routine
iter = BK.ContIterable(prob, PALC(), opts; verbosity = 2)

resp = Float64[]
resx = Float64[]

# this is the PALC algorithm
for state in iter
	# we save the current solution on the branch
	push!(resx, getx(state)[1])
	push!(resp, getp(state))
end

# plot the result
plot(resp, resx; label = "", xlabel = "p")

Additional information

If you want to customize the iterator to your needs, perhaps the best source of inspiration is the code of the function continuation!(it::ContIterable, state::ContState, contRes::ContResult) where the iterator is used at its fullest. You will see how the eigen-elements and the stability are computed, how bifurcations are detected and how results are saved.