Path tracking

We also export a path tracking primitive to make the core path tracking routine available for other applications. At the heart is a PathTracking.PathTracker object which holds all the state. The easiest way to construct a PathTracker is to use the pathtracker_startsolutions routine.

HomotopyContinuation.PathTracking.pathtracker_startsolutions — Function.

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

Construct a PathTracking.PathTracker and startsolutions 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.

Types

HomotopyContinuation.PathTracking.PathTracker — Type.

 PathTracker(H::Homotopies.AbstractHomotopy, x₁, t₁, t₀; options...)::PathTracker

Create a PathTracker to track x₁ from t₁ to t₀. The homotopy H needs to be homogenous. Note that a PathTracker is also a (mutable) iterator.

Options

corrector::Correctors.AbstractCorrector:

The corrector used during in the predictor-corrector scheme. The default is Correctors.Newton.

corrector_maxiters=2: The maximal number of correction steps in a single step.
predictor::Predictors.AbstractPredictor:

The predictor used during in the predictor-corrector scheme. The default is [Predictors.RK4](@ref)()`.

refinement_maxiters=corrector_maxiters: The maximal number of correction steps used to refine the final value.
refinement_tol=1e-8: The precision used to refine the final value.
steplength::StepLength.AbstractStepLength

The step size logic used to determine changes of the step size. The default is StepLength.HeuristicStepLength.

tol=1e-6: The precision used to track a value.

HomotopyContinuation.PathTracking.PathTrackerResult — Type.

 PathTrackerResult(tracker)

Containing the result of a tracked path. The fields are

successfull::Bool Indicating whether tracking was successfull.
returncode::Symbol If the tracking was successfull then it is :success.

Otherwise the return code gives an indication what happened.

x::V The result.
t::Float64 The t when the path tracker stopped.
res::Float64 The residual at (x, t).

HomotopyContinuation.StepLength.HeuristicStepLength — Type.

HeuristicStepLength(;initial=0.1,
    increase_factor=2.0,
    decrease_factor=inv(increase_factor),
    consecutive_successes_necessary=5,
    maximal_steplength=max(0.1, initial),
    minimal_steplength=1e-14)

The step length is defined as follows. Initially the step length is initial. If consecutive_successes_necessary consecutive steps were sucessfull the step length is increased by the factor increase_factor. If a step fails, i.e. the corrector does not converge, the steplength is reduced by the factor decrease_factor.

Methods

To track from a start to an endpoint with the PathTracker we provide the following routines.

HomotopyContinuation.PathTracking.track! — Function.

 track!(tracker, x₁, t₁, t₀; checkstartvalue=true, precondition=true)

Track a value x₁ from t₁ to t₀ using the given PathTracker tracker. Returns a Symbol indicating the status. If the tracking was successfull it is :success. If predcondition is true then Homotopies.precondition! is called at the beginning of the tracking.

track!(x₀, tracker, x₁, t₁, t₀)

Additionally also stores the result in x₀ if the tracking was successfull.

HomotopyContinuation.PathTracking.track — Function.

track(tracker, x₁, t₁, t₀)::PathTrackerResult

Track a value x₁ from t₁ to t₀ using the given PathTracker tracker. This returns a PathTrackerResult. This modifies tracker.

HomotopyContinuation.PathTracking.setup! — Function.

setup!(pathtracker, x₁, t₁, t₀, checkstartvalue=true))

Setup pathtracker to track x₁ from t₁ to t₀. Use this if you want to use the pathtracker as an iterator.

To introspect the current state and change settings we provide the following routines.

HomotopyContinuation.PathTracking.currx — Function.

currx(tracker::PathTracker)

Return the current value of x.

HomotopyContinuation.PathTracking.currt — Function.

 currt(tracker::PathTracker)

Current t.

HomotopyContinuation.PathTracking.currΔt — Function.

 currΔt(tracker::PathTracker)

Current steplength Δt.

HomotopyContinuation.PathTracking.curriters — Function.

 curriters(tracker::PathTracker)

Current number of iterations.

HomotopyContinuation.PathTracking.currstatus — Function.

 currstatus(tracker::PathTracker)

Current status.

HomotopyContinuation.PathTracking.tol — Function.

 tol(tracker::PathTracker)

Current tolerance.

HomotopyContinuation.PathTracking.corrector_maxiters — Function.

 corrector_maxiters(tracker::PathTracker)

Current correction maxiters.

HomotopyContinuation.PathTracking.refinement_tol — Function.

 refinement_tol(tracker::PathTracker)

Current refinement tolerance.

HomotopyContinuation.PathTracking.refinement_maxiters — Function.

 refinement_maxiters(tracker::PathTracker)

Current refinement maxiters.

HomotopyContinuation.PathTracking.set_tol! — Function.

 set_tol!(tracker::PathTracker, tol)

Set the current tolerance to tol.

HomotopyContinuation.PathTracking.set_corrector_maxiters! — Function.

 set_corrector_maxiters!(tracker::PathTracker, n)

Set the current correction maxiters to n.

HomotopyContinuation.PathTracking.set_refinement_tol! — Function.

 set_refinement_maxiters!(tracker::PathTracker, tol)

Set the current refinement tolerance to tol.

HomotopyContinuation.PathTracking.set_refinement_maxiters! — Function.

 set_refinement_maxiters!(tracker::PathTracker, n)

Set the current refinement maxiters to n.