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.ContStateType
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., (@lens _))

# 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")
Example block output

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.