Path Tracker

 PathTracker{Prob<:AbstractProblem, T, V<:AbstractVector{T}, CT<:CoreTracker}

PathTracker the way to track single paths. It combines the core path tracking routine with an endgame, i.e., it can also deal with singular solutions as well as paths going to infinity. PathTracker is a wrapper around CoreTracker and thus has all configuration possibilities CoreTracker has.

There are the following PathTracker specific options (with their defaults in parens):

• at_infinity_check::Bool=true: Whether the path tracker should stop paths going to infinity early.
• min_step_size_endgame_start=1e-10: The endgame only starts if the step size becomes smaller that the provided value.
• samples_per_loop::Int=5: To compute singular solutions Cauchy's integral formula is used. The accuracy of the solutions increases with the number of samples per loop.
• max_winding_number::Int=12: The maximal number of loops used in Cauchy's integral formula.
• max_affine_norm::Float64=1e6: A fallback heuristic to decide whether a path is going to infinity.
• min_val_accuracy::Float64=0.001: A tolerance used to decide whether we are in the endgame zone.
• overdetermined_min_accuracy=1e-5: The minimal accuracy a non-singular solution needs to have to be considered a solution of the original system.
• overdetermined_min_residual=1e-3: The minimal residual a singular solution needs to have to be considered a solution of the original system.

In order to construct a pathtracker it is recommended to use the pathtracker and pathtracker_startsolutions helper functions.

pathtracker_startsolutions(args...; kwargs...)

Construct a PathTracker and start solutions in the same way solve does it. This also takes the same input arguments as solve. This is convenient if you want to investigate single paths.

pathtracker(args...; kwargs...)

Construct a PathTracker in the same way solve does it. This also takes the same input arguments as solve with the exception that you do not need to specify startsolutions.

Examples

Obtain single solution

We want to construct a path tracker to track a parameterized system f with parameters p from the parameters a to b.

tracker = pathtracker(f, parameters=p, p₁=a, p₀=b)

You then can obtain a single solution at b by using

x_b = solution(track(tracker, x_a))

track(tracker::PathTracker, x₁, t₁::Float64=1.0; path_number::Int=1, details::Symbol=:default, options...)::PathResult

Track the path with start solution x₁ from t₁ towards t=0. The details options controls the level of details of the informations available in PathResult.

Possible values for the options are

• accuracy::Float64
• max_corrector_iters::Int
• max_steps::Int
• start_parameters::AbstractVector
• target_parameters::AbstractVector

track!(tracker::PathTracker, x₁, t₁::Float64=1.0; options...)::PathTrackerStatus.states

Track the path with start solution x₁ from t₁ towards t=0.

Possible values for the options are

• accuracy::Float64
• max_corrector_iters::Int
• max_steps::Int
• start_parameters::AbstractVector
• target_parameters::AbstractVector

PathTrackerStatus.states

The possible return codes the path tracker can return are

• PathTrackerStatus.success
• PathTrackerStatus.at_infinity
• PathTrackerStatus.terminated_maximal_iterations
• PathTrackerStatus.terminated_invalid_startvalue
• PathTrackerStatus.terminated_step_size_too_small
• PathTrackerStatus.terminated_singularity
• PathTrackerStatus.terminated_ill_conditioned
• PathTrackerStatus.terminated

set_parameters!(tracker::PathTracker; start_parameters=nothing, target_parameters=nothing)

Set the parameters of a parameter homotopy.

PathResult{V<:AbstractVector}

A PathResult is the result of tracking of a path using PathTracker. Its fields are

• return_code: One of :success, :at_infinity or any error code in PathTrackerStatus.states converted to a Symbol.

• solution::V: The solution vector.

• t::Float64: The value of t at which solution was computed. Note that if return_code is :at_infinity, then t is the value when this was decided.

• accuracy::Union{Nothing, Float64}: An approximation of $||x-x^*||₂$ where $x$ is the computed solution and $x^*$ is the true solution.

• residual::Union{Nothing, Float64}: The value of the 2-norm of H(solution, 0).

• condition_jacobian::Union{Nothing, Float64}: This is the condition number of the row-equilibrated Jacobian at the solution. A high condition number indicates a singularity.

• winding_number:Union{Nothing, Int}: The estimated winding number. This is a lower bound on the multiplicity of the solution.

• endgame_zone_start::Union{Nothing, Float64}: The value of t at which we entered the endgame zone, i.e., where the path x(t) has an expansion a convergent Puiseux series near t=0.

• start_solution::Union{Nothing, Int}: The start solution of the path.

• accepted_steps::Int: The number of accepted steps during the path tracking.

• rejected_steps::Int: The number of rejected steps during the path tracking.

• valuation::Union{Nothing, Vector{Float64}}: An approximation of the valuation of the Puiseux series expansion of x(t).

• valuation_accuracy::Union{Nothing, Vector{Float64}}: An estimate of the accuracy of the valuation of the Puiseux series expansion of x(t).

  PathResult(tracker::PathTracker, startsolution=nothing, pathnumber::Union{Nothing,Int}=nothing; details=:default)

Possible details values are :minimal (minimal details), :default (default) and :extensive (all information possible).

solution(pathresult)

Get the solution of the path.

residual(pathresult)

Get the residual of the solution $x$ of the path, i.e., $||H(x, 0)||₂$.

start_solution(pathresult)

Get the start solution of the solution $x$ of the path.

isreal(pathresult; tol=1e-6)

We consider a result as real if the 2-norm of the imaginary part of the solution is at most tol.

issuccess(pathresult)

Checks whether the path is successfull.

isfailed(pathresult)

Checks whether the path failed.

isaffine(pathresult)

Return`s true if the solution is an affine vector.

isprojective(pathresult)

Return`s true if the solution is a projective vector.

isatinfinity(pathresult)

Checks whether the path goes to infinity.

issingular(pathresult; tol=1e10)

Checks whether the path result is singular. This is true if the winding number is larger than 1 or if the condition number of the Jacobian is larger than tol.

isnonsingular(pathresult; tol=1e10)

Checks whether the path result is non-singular. This is true if it is not singular.