Path tracking

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

Construct a 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.

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. This is convenient if you want to investigate single paths.

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 = track(tracker, x_a).x

Trace a path

To trace a path you can use the iterator method.

tracker = pathtracker(f, parameters=p, p₁=a, p₀=b, max_step_size =0.01)
for (x, t) in iterator(tracker, x₁)
    @show (x,t)
end

If we want to guarantee smooth traces we can limit the maximal step size.

tracker = pathtracker(f, parameters=p, p₁=a, p₀=b, max_step_size =0.01)
for (x, t) in iterator(tracker, x₁)
    @show (x,t)
end

 PathTracker(H::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.

PathTrackerOptions

• corrector::AbstractCorrector: The corrector used during in the predictor-corrector scheme. The default is NewtonCorrector.
• max_corrector_iters=3: The maximal number of correction steps in a single step.
• initial_step_size=0.1: The step size of the first step.
• max_steps=10_000: The maximal number of iterations the path tracker has available.
• min_step_size =1e-14: The minimal step size.
• max_step_size =Inf: The maximal step size.
• maximal_lost_digits::Real=-(log₁₀(eps) + 3): The tracking is terminated if we estimate that we loose more than maximal_lost_digits in the linear algebra steps.
• predictor::AbstractPredictor: The predictor used during in the predictor-corrector scheme. The default is Heun()`.
• max_refinement_iters=max_corrector_iters: The maximal number of correction steps used to refine the final value.
• refinement_accuracy=1e-8: The precision used to refine the final value.
• accuracy=1e-7: The precision used to track a value.
• auto_scaling=true: This only applies if we track in affine space. Automatically regauges the variables to effectively compute with a relative accuracy instead of an absolute one.

 PathTrackerResult{V<:AbstractVector}

Containing the result of a tracked path. The fields are

• returncode::PathTrackerStatus.states If the tracking was successfull then it is PathTrackerStatus.success.
• x::V The result.
• t::ComplexF64 The t when the path tracker stopped.
• accuracy::Float64: The estimated accuracy of x.

PathTrackerStatus.states

The possible states the pathtracker can achieve are

• PathTrackerStatus.success
• PathTrackerStatus.tracking
• PathTrackerStatus.terminated_maximal_iterations
• PathTrackerStatus.terminated_invalid_startvalue
• PathTrackerStatus.terminated_step_size_too_small
• PathTrackerStatus.terminated_singularity
• PathTrackerStatus.terminated_ill_conditioned

track(tracker, x₁, t₁=1.0, t₀=0.0; options...)::PathTrackerResult

Track a value x₁ from t₁ to t₀ using the given PathTracker tracker. This returns a PathTrackerResult. This modifies tracker. See track! for the possible options.

track(tracker, x::AbstractVector, edge::Edge, loop::Loop, stats::MonodromyStatistics)

Track x along the edge edge in the loop loop using tracker. Record statistics in stats.

 track!(tracker, x₁, t₁=1.0, t₀=0.0; setup_patch=true, checkstartvalue=true, compute_ẋ=true)

Track a value x₁ from t₁ to t₀ using the given PathTracker tracker. Returns one of the enum values of PathTrackerStatus.states indicating the status. If the tracking was successfull it is PathTrackerStatus.success. If setup_patch is true then setup! is called at the beginning of the tracking.

track!(x₀, tracker, x₁, t₁=1.0, t₀=0.0; options...)

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

setup!(::AbstractAffinePatchState, x::AbstractVector)

Setup the affine patch depending on x and modify x if necessary. This is only called once at the beginning of a tracked path.

setup!(cache::AbstractStatefulPredictorCache, H, x, ẋ, t, fac)

Setup the cache. x is the new path value at t and ẋ is the derivative at t. fac is a factorization of the Jacobian at (x,t). This falls back to calling update.

setup!(pathtracker, x₁, t₁=1.0, t₀=0.0, setup_patch=pathtracker.options.update_patch, checkstartvalue=true, compute_ẋ=true)

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

iterator(tracker::PathTracker, x₁, t₁=1.0, t₀=0.0; affine=true)

Prepare a tracker to make it usable as a (stateful) iterator. Use this if you want to inspect a specific path. In each iteration the tuple (x,t) is returned. If affine == true then x is the affine solution (internally we compute in projective space).

Example

Assume you have PathTracker tracker and you wan to track x₁ from 1.0 to 0.25:

for (x,t) in iterator(tracker, x₁, 1.0, 0.25)
    println("x at t=$t:")
    println(x)
end

Note that this is a stateful iterator. You can still introspect the state of the tracker. For example to check whether the tracker was successfull (and did not terminate early due to some problem) you can do

println("Success: ", currstatus(tracker) == PathTrackerStatus.success)

currx(tracker::PathTracker)

Return the current value of x.

 currt(tracker::PathTracker)

Current t.

 currΔt(tracker::PathTracker)

Current step_size Δt.

 curriters(tracker::PathTracker)

Current number of iterations.

 currstatus(tracker::PathTracker)

Current status.

 accuracy(tracker::PathTracker)

Current accuracy.

 set_accuracy!(tracker::PathTracker, accuracy)

Set the current accuracy to accuracy.

 max_corrector_iters(tracker::PathTracker)

Current correction max_steps.

 set_max_corrector_iters!(tracker::PathTracker, n)

Set the correction max_steps to n.

 max_step_size (tracker::PathTracker)

Current maximal step size.

 set_max_corrector_iters!(tracker::PathTracker, Δs)

Set the maximal step size to Δs.

 max_refinement_iters(tracker::PathTracker)

Current refinement max_steps.

 set_max_refinement_iters!(tracker::PathTracker, n)

Set the current refinement max_steps to n.

 refinement_accuracy(tracker::PathTracker)

Current refinement accuracy.

 set_max_refinement_iters!(tracker::PathTracker, accuracy)

Set the current refinement accuracy to accuracy.