Library

struct NewtonPar{T, L<:BifurcationKit.AbstractLinearSolver, E<:AbstractEigenSolver}

Returns a variable containing parameters to affect the newton algorithm when solving F(x) = 0.

Arguments (with default values):

• tol::Any: absolute tolerance for F(x) Default: 1.0e-12

• max_iterations::Int64: number of Newton iterations Default: 25

• verbose::Bool: display Newton iterations? Default: false

• linsolver::BifurcationKit.AbstractLinearSolver: linear solver, must be <: AbstractLinearSolver Default: DefaultLS()

• eigsolver::AbstractEigenSolver: eigen solver, must be <: AbstractEigenSolver Default: DefaultEig()

• linesearch::Bool: Default: false

• α::Any: Default: convert(typeof(tol), 1.0)

• αmin::Any: Default: convert(typeof(tol), 0.001)

Arguments for line search (Armijo)

• linesearch = false: use line search algorithm (i.e. Newton with Armijo's rule)
• α = 1.0: initial value of α (damping) parameter for line search algorithm
• αmin = 0.001: minimal value of the damping alpha

struct ContinuationPar{T, S<:BifurcationKit.AbstractLinearSolver, E<:AbstractEigenSolver}

Returns a variable containing the parameters to affect the continuation algorithm used to solve F(x, p) = 0.

Arguments

• dsmin, dsmax are the minimum, maximum allowed arc-length value. It controls the density of points in the computed branch of solutions.
• ds = 0.01 is the initial arc-length.
• p_min, p_max allowed parameter range for p
• max_steps = 100 maximum number of continuation steps
• newton_options::NewtonPar: options for the Newton algorithm
• save_to_file = false: save to file. A name is automatically generated or can be defined in continuation. This requires using JLD2.
• save_sol_every_step::Int64 = 0 at which continuation steps do we save the current solution
• plot_every_step = 10 at which continuation steps do we plot the current solution

Handling eigen-elements, their computation is triggered by the argument detect_bifurcation (see below)

• nev = 3 number of eigenvalues to be computed. It is automatically increased to have at least nev unstable eigenvalues. To be set for proper bifurcation detection. See Detection of bifurcation points of Equilibria for more information.
• save_eig_every_step = 1 record eigen vectors every specified steps. Important for memory limited resource, e.g. GPU.
• save_eigenvectors = true Important for memory limited resource, e.g. GPU.

Handling bifurcation detection

• tol_stability = 1e-10 lower bound on the real part of the eigenvalues to test for stability of equilibria and periodic orbits
• detect_fold = true detect Fold bifurcations? It is a useful option although the detection of Fold is cheap. Indeed, it may happen that there is a lot of Fold points and this can saturate the memory in memory limited devices (e.g. on GPU)
• detect_bifurcation::Int ∈ {0, 1, 2, 3} If set to 0, nothing is done. If set to 1, the eigen-elements are computed. If set to 2, the bifurcations points are detected during the continuation run, but not located precisely. If set to 3, a bisection algorithm is used to locate the bifurcations points (slower). The possibility to switch off detection is a useful option. Indeed, it may happen that there are a lot of bifurcation points and this can saturate the memory of memory limited devices (e.g. on GPU)
• dsmin_bisection = 1e-16 minimal ds for the bisection algorithm for locating bifurcation points
• n_inversion = 2 number of sign inversions in bisection algorithm
• max_bisection_steps = 15 maximum number of bisection steps
• tol_bisection_eigenvalue = 1e-16 tolerance on real part of eigenvalue to detect bifurcation points in the bisection steps

Handling ds adaptation (see continuation for more information)

• a = 0.5 aggressiveness factor. It is used to adapt ds in order to have a number of newton iterations per continuation step roughly constant. The higher a is, the larger the step size ds is changed at each continuation step.

Handling event detection

• detect_event::Int ∈ {0, 1, 2} If set to 0, nothing is done. If set to 1, the event locations are sought during the continuation run, but not located precisely. If set to 2, a bisection algorithm is used to locate the event (slower).
• tol_param_bisection_event = 1e-16 tolerance on parameter to locate event

Misc

• η = 150. parameter to estimate tangent at first point with parameter p₀ + ds / η
• detect_loop [WORK IN PROGRESS] detect loops in the branch and stop the continuation

struct ConstantDDEBifProblem{Tvf, Tdf, Tu, Td, Tp, Tl<:Union{typeof(identity), Nothing, IndexLens, PropertyLens, ComposedFunction}, Tplot, Trec, Tgets, Tδ} <: DDEBifurcationKit.AbstractDDEBifurcationProblem

Structure to hold the bifurcation problem. If don't have parameters, you can pass nothing.

Fields

• VF::Any: Vector field, typically a BifFunction. For more information, please look at the website https://bifurcationkit.github.io/DDEBifurcationKit.jl/dev/BifProblem

• delays::Any: function delays. It takes the parameters and return the non-zero delays in an AbstractVector form. Example: delays = par -> [1.]

• u0::Any: Initial guess

• delays0::Any: initial delays (set internally by the constructor)

• params::Any: parameters

• lens::Union{typeof(identity), Nothing, IndexLens, PropertyLens, ComposedFunction}: Typically a Accessors.@optic. It specifies which parameter axis among params is used for continuation. For example, if par = (α = 1.0, β = 1), we can perform continuation w.r.t. α by using lens = (@optic _.α). If you have an array par = [ 1.0, 2.0] and want to perform continuation w.r.t. the first variable, you can use lens = (@optic _[1]). For more information, we refer to Accessors.jl.

• plotSolution::Any: user function to plot solutions during continuation. Signature: plotSolution(x, p; kwargs...)

• recordFromSolution::Any: record_from_solution = (x, p; k...) -> norm(x) function used record a few indicators about the solution. It could be norm or (x, p) -> x[1]. This is also useful when saving several huge vectors is not possible for memory reasons (for example on GPU...). This function can return pretty much everything but you should keep it small. For example, you can do (x, p) -> (x1 = x[1], x2 = x[2], nrm = norm(x)) or simply (x, p) -> (sum(x), 1). This will be stored in contres.branch (see below). Finally, the first component is used to plot in the continuation curve.

• save_solution::Any: function to save the full solution on the branch. Some problem are mutable (like periodic orbit functional with adaptive mesh) and this function allows to save the state of the problem along with the solution itself. Signature save_solution(x, p)

• δ::Any: delta for Finite differences

Methods

• getu0(pb) calls pb.u0
• getparams(pb) calls pb.params
• getlens(pb) calls pb.lens
• setparam(pb, p0) calls set(pb.params, pb.lens, p0)
• record_from_solution(pb) calls pb.record_from_solution

Constructors

• ConstantDDEBifProblem(F, delays, u0, params, lens; J, Jᵗ, d2F, d3F, kwargs...) and kwargs are the fields above.

struct SDDDEBifProblem{Tvf, Tdf, Tu, Td, Tp, Tl<:Union{typeof(identity), Nothing, IndexLens, PropertyLens, ComposedFunction}, Tplot, Trec, Tgets, Tδ} <: DDEBifurcationKit.AbstractDDEBifurcationProblem

Structure to hold the bifurcation problem. If don't have parameters, you can pass nothing.

Fields

• VF::Any: Vector field, typically a BifFunction. For more information, please look at the website https://bifurcationkit.github.io/DDEBifurcationKit.jl/dev/BifProblem

• delays::Any: function delays. It takes the parameters and the state and return the non-zero delays in an AsbtractVector form. Example: delays = (par, u) -> [1. + u[1]^2]

• u0::Any: Initial guess

• delays0::Any: initial delays (set internally by the constructor)

• params::Any: parameters

• lens::Union{typeof(identity), Nothing, IndexLens, PropertyLens, ComposedFunction}: see ConstantDDEBifProblem for more information.

• plotSolution::Any: user function to plot solutions during continuation. Signature: plotSolution(x, p; kwargs...)

• recordFromSolution::Any: record_from_solution = (x, p; k...) -> norm(x) function used record a few indicators about the solution. It could be norm or (x, p) -> x[1]. This is also useful when saving several huge vectors is not possible for memory reasons (for example on GPU...). This function can return pretty much everything but you should keep it small. For example, you can do (x, p) -> (x1 = x[1], x2 = x[2], nrm = norm(x)) or simply (x, p) -> (sum(x), 1). This will be stored in contres.branch (see below). Finally, the first component is used to plot in the continuation curve.

• save_solution::Any: function to save the full solution on the branch. Some problem are mutable (like periodic orbit functional with adaptive mesh) and this function allows to save the state of the problem along with the solution itself. Signature save_solution(x, p)

• δ::Any: delta for Finite differences

Methods

• getu0(pb) calls pb.u0
• getparams(pb) calls pb.params
• getlens(pb) calls pb.lens
• setparam(pb, p0) calls set(pb.params, pb.lens, p0)
• record_from_solution(pb) calls pb.record_from_solution

Constructors

• SDDDEBifProblem(F, delays, u0, params, lens; J, Jᵗ, d2F, d3F, kwargs...) and kwargs are the fields above.

mutable struct DDE_DefaultEig{T, Tw, Tv} <: DDEBifurcationKit.AbstractDDEEigenSolver

Default eigen solver for DDEBifurcationKit based on the julia package NonlinearEigenproblems.jl. ore precisely, we rely on NonlinearEigenproblems.iar_chebyshev for the computation of eigenvalues.

Fields

• maxit::Int64: Default: 100

• which::Any: Default: real

• σ::Any: Default: 0.0

• γ::Any: Default: 1.0

• tol::Any: Default: 1.0e-10

• logger::Int64: Default: 0

• check_error_every::Int64: Default: 1

• v::Any: Default: nothing

Constructors

• DDE_DefaultEig(; kwargs...) and kwargs are the fields above.

continuation(
    br::BifurcationKit.AbstractBranchResult,
    ind_bif::Int64,
    _contParams::ContinuationPar,
    pbPO::BifurcationKit.AbstractPeriodicOrbitProblem;
    bif_prob,
    detailed,
    use_normal_form,
    autodiff_nf,
    nev,
    kwargs...
) -> Branch

Perform automatic branch switching from a Hopf bifurcation point labelled ind_bif in the list of the bifurcated points of a previously computed branch br::ContResult. It first computes a Hopf normal form.

Arguments

• br branch result from a call to continuation
• ind_hopf index of the bifurcation point in br
• contParams parameters for the call to continuation
• probPO problem used to specify the way toc compute the periodic orbit. It can be PeriodicOrbitTrapProblem, PeriodicOrbitOCollProblem, ShootingProblem or PoincareShootingProblem .

Optional arguments

• alg = br.alg continuation algorithm
• δp used to specify the guess for the parameter on the bifurcated branch which otherwise defaults to contParams.ds. This allows to use an initial step larger than contParams.dsmax.
• ampfactor = 1 multiplicative factor to alter the amplitude of the bifurcated solution. Useful to magnify the bifurcated solution when the bifurcated branch is very steep.
• use_normal_form = true whether to use the normal form in order to compute the predictor. When false, ampfactor and δp are used to make a predictor based on the bifurcating eigenvector. Setting use_normal_form = false can be useful when computing the normal form is not possible for example when higher order derivatives are not available.
• usedeflation = true whether to use nonlinear deflation (see Deflated problems) to help finding the guess on the bifurcated branch
• nev number of eigenvalues to be computed to get the right eigenvector
• autodiff_nf = true whether to use autodiff in get_normal_form. This can be used in case automatic differentiation is not working as intended.
• all kwargs from continuation

A modified version of prob is passed to plot_solution and finalise_solution.

getperiod(
    ::BifurcationKit.AbstractPeriodicOrbitProblem,
    x
) -> Any
getperiod(
    ::BifurcationKit.AbstractPeriodicOrbitProblem,
    x,
    par
) -> Any

Compute the period of the periodic orbit associated to x.

getperiod(prob::PeriodicOrbitTrapProblem, x, p) -> Any

Compute the period of the periodic orbit associated to x.

getperiod(psh::PoincareShootingProblem, x_bar, par) -> Any

Compute the period of the periodic orbit associated to x_bar.

get_normal_form(
    prob::BifurcationKit.AbstractBifurcationProblem,
    br::BifurcationKit.AbstractBranchResult,
    id_bif::Int64;
    ...
) -> Any
get_normal_form(
    prob::BifurcationKit.AbstractBifurcationProblem,
    br::BifurcationKit.AbstractBranchResult,
    id_bif::Int64,
    Teigvec::Type{𝒯eigvec};
    nev,
    verbose,
    lens,
    detailed,
    autodiff,
    scaleζ,
    ζs,
    ζs_ad,
    bls,
    bls_adjoint,
    bls_block,
    start_with_eigen
) -> Any

Compute the reduced equation / normal form of the bifurcation point located at br.specialpoint[ind_bif].

Arguments

• prob::AbstractBifurcationProblem
• br result from a call to continuation
• ind_bif index of the bifurcation point in br.specialpoint

Optional arguments

• nev number of eigenvalues used to compute the spectral projection. This number has to be adjusted when used with iterative methods.
• verbose whether to display information
• ζs list of vectors spanning the kernel of the jacobian at the bifurcation point. Useful for enforcing the kernel basis used for the normal form.
• lens::Lens specify which parameter to take the partial derivative ∂pF
• scaleζ function to normalize the kernel basis. Indeed, the kernel vectors are normalized using norm, the normal form coefficients can be super small and can imped its analysis. Using scaleζ = norminf can help sometimes.
• autodiff = true whether to use ForwardDiff for the differentiations. Used for example for Bogdanov-Takens (BT) point.
• detailed = Val(true) whether to compute only a simplified normal form when only basic information is required. This can be useful is cases the computation is "long", for example for a Bogdanov-Takens point.
• bls = MatrixBLS() specify bordered linear solver. Needed to compute the reduced equation Taylor expansion of Branch/BT points. Indeed, it is required to solve L⋅u = rhs where L is the jacobian at the bifurcation point, L is thus singular and we rely on a bordered linear solver to solve this system.
• bls_block = bls specify bordered linear solver when the border has dimension > 1 (1 for bls). (see bls option above).

Available method(s)

You can directly call

get_normal_form(br, ind_bif ; kwargs...)

which is a shortcut for get_normal_form(getprob(br), br, ind_bif ; kwargs...).

Once the normal form nf has been computed, you can call predictor(nf, δp) to obtain an estimate of the bifurcating branch.

References

[1] Golubitsky, Martin, and David G Schaeffer. Singularities and Groups in Bifurcation Theory. Springer-Verlag, 1985. http://books.google.com/books?id=rrg-AQAAIAAJ.

[2] Kielhöfer, Hansjörg. Bifurcation Theory: An Introduction with Applications to PDEs. Applied Mathematical Sciences 156. Springer, 2003. https://doi.org/10.1007/978-1-4614-0502-3.

get_normal_form(
    prob::BifurcationKit.AbstractPeriodicOrbitProblem,
    br::BifurcationKit.AbstractResult{<:BifurcationKit.PeriodicOrbitCont},
    id_bif::Int64;
    ...
) -> Any
get_normal_form(
    prob::BifurcationKit.AbstractPeriodicOrbitProblem,
    br::BifurcationKit.AbstractResult{<:BifurcationKit.PeriodicOrbitCont},
    id_bif::Int64,
    Teigvec::Type{𝒯eigvec};
    nev,
    verbose,
    ζs,
    lens,
    scaleζ,
    autodiff,
    δ,
    k...
) -> Any

Compute the normal form (NF) of bifurcations of periodic orbits. We detail the additional keyword arguments specific to periodic orbits.

Optional arguments

• prm = true compute the normal form using Poincaré return map (PRM). If false, use the Iooss normal form.
• nev = length(eigenvalsfrombif(br, id_bif)),
• verbose = false,
• ζs = nothing, pass the eigenvectors
• lens = getlens(br),
• Teigvec = _getvectortype(br) type of the eigenvectors (can be useful for GPU)
• scaleζ = norm, scale the eigenvector
• autodiff = false use autodiff or finite differences in some part of the normal form computation
• detailed = true whether to compute only a simplified normal form when only basic information is required. This can be useful is cases the computation is long.
• δ = getdelta(prob) delta used for derivatives based on finite differences.

Notes

For collocation, the default method to compute the NF of Period-doubling and Neimark-Sacker bifurcations is Iooss' one [1].

References

[1] Iooss, "Global Characterization of the Normal Form for a Vector Field near a Closed Orbit.", 1988