# 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.

`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

` 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.

` 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)`

.

```
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.

` corrector_maxiters(tracker::PathTracker)`

Current correction maxiters.

`HomotopyContinuation.PathTracking.refinement_tol`

— Function.` refinement_tol(tracker::PathTracker)`

Current refinement tolerance.

` refinement_maxiters(tracker::PathTracker)`

Current refinement maxiters.

`HomotopyContinuation.PathTracking.set_tol!`

— Function.` set_tol!(tracker::PathTracker, tol)`

Set the current tolerance to `tol`

.

` set_corrector_maxiters!(tracker::PathTracker, n)`

Set the current correction maxiters to `n`

.

` set_refinement_maxiters!(tracker::PathTracker, tol)`

Set the current refinement tolerance to `tol`

.

` set_refinement_maxiters!(tracker::PathTracker, n)`

Set the current refinement maxiters to `n`

.