Base tracker class for trackers offered in Bertini2. More...

#include <base_tracker.hpp>

Inheritance diagram for bertini::tracking::Tracker< D >:

Collaboration diagram for bertini::tracking::Tracker< D >:

Public Member Functions
Predictor	GetPredictor () const
	Query the currently set predictor.

const System &	GetSystem () const
	get a const reference to the system.

unsigned	NumTotalStepsTaken () const
	See how many steps have been taken.

template<typename C>
SuccessCode	Refine (Vec< C > &new_space, Vec< C > const &start_point, C const &current_time) const
	Refine a point to tolerance implicitly internally set.

template<typename C>
SuccessCode	Refine (Vec< C > &new_space, Vec< C > const &start_point, C const &current_time, double const &tolerance, unsigned max_iterations) const
	Refine a point to a given tolerance.

void	ReinitializeInitialStepSize (bool should_reinitialize_stepsize)
	Switch resetting of initial step size to that of the stepping settings.

void	SetPredictor (Predictor new_predictor_choice)
	Change tracker to use a predictor.

void	SetStepSize (RT const &new_stepsize) const
	Set how large the stepsize should be.

void	SetSystem (const System &new_sys)
	get a const reference to the system.

void	SetTrackingTolerance (double const &tracking_tolerance)
	Set how tightly to track the path.

void	Setup (Predictor new_predictor_choice, double const &tracking_tolerance, double const &path_truncation_threshold, SteppingConfig const &stepping, NewtonConfig const &newton)
	Get the tracker set up for tracking.

SuccessCode	TrackPath (Vec< CT > &solution_at_endtime, CT const &start_time, CT const &endtime, Vec< CT > const &start_point) const
	Track a start point through time, from a start time to a target time.

Public Member Functions inherited from bertini::Observable
void	AddObserver (AnyObserver &new_observer) const
	Add an observer, to observe this observable.

void	RemoveObserver (AnyObserver &observer) const
	Remove an observer from this observable.

Protected Member Functions
virtual SuccessCode	CheckGoingToInfinity () const =0
	Check whether the path is going to infinity, as it tracks.

void	IncrementBaseCountersFail () const
	Increment and reset counters after a failed TrackerIteration()

void	IncrementBaseCountersSuccess () const
	Increment and reset counters after a successful TrackerIteration()

virtual void	PostTrackCleanup () const
	Function to be called before exiting the tracker loop.

virtual void	ResetCounters () const =0
	Reset counters used during tracking.

Protected Member Functions inherited from bertini::Observable
void	NotifyObservers (AnyEvent const &e) const
	Sends an Event (more particularly, AnyEvent) to all watching observers of this object.

Protected Attributes
NumErrorT	condition_number_estimate_
	An estimate on the condition number of the Jacobian.

TupOfVec	current_space_
	The current space value.

RT	current_stepsize_
	The current stepsize.

CT	current_time_
	The current time.

CT	delta_t_
	The current delta_t.

unsigned	digits_final_ = 0
	The number of digits to track to, due to being in endgame zone.

unsigned	digits_tracking_tolerance_ = 5
	The number of digits required for tracking to given tolerance, condition number notwithstanding.

CT	endtime_
	The time we are tracking to.

NumErrorT	error_estimate_
	An estimate on the error of a step.

NumErrorT	norm_delta_z_
	The norm of the change in space resulting from a step.

NumErrorT	norm_J_
	An estimate on the norm of the Jacobian.

NumErrorT	norm_J_inverse_
	An estimate on the norm of the inverse of the Jacobian.

unsigned	num_consecutive_failed_steps_
	The number of CONSECUTIVE failed steps taken in a row.

unsigned	num_consecutive_successful_steps_
	The number of CONSECUTIVE successful steps taken in a row.

unsigned	num_failed_steps_taken_
	The total number of failed steps taken.

unsigned	num_steps_since_last_condition_number_computation_
	How many steps have passed since the most recent condition number estimate.

unsigned	num_successful_steps_since_precision_decrease_
	The number of successful steps since decreased precision.

unsigned	num_successful_steps_since_stepsize_increase_
	How many successful steps have been taken since increased stepsize.

unsigned	num_successful_steps_taken_
	The number of successful steps taken so far.

unsigned	num_total_steps_taken_
	The number of steps taken, including failures and successes.

NumErrorT	path_truncation_threshold_ = 1e5
	The threshold for path truncation.

unsigned	predictor_order_
	The order of the predictor – one less than the error estimate order.

bool	reinitialize_stepsize_ = true
	Whether should check if the path is going to infinity while tracking. On by default.

NumErrorT	size_proportion_
	The proportion of the space step size, taking into account the order of the predictor.

SuccessCode	step_success_code_
	The next stepsize.

TupOfVec	temporary_space_
	After prediction, the tentative next space value.

TupOfVec	tentative_space_
	After correction, the tentative next space value.

std::reference_wrapper< const System >	tracked_system_
	Reference to the system being tracked.

NumErrorT	tracking_tolerance_ = 1e-5
	The tracking tolerance.

Detailed Description

template<class D>
class bertini::tracking::Tracker< D >

Base tracker class for trackers offered in Bertini2.

See also: AMPTracker

Using a tracker

Trackers in Bertini2 are the engine for tracking a path from one space-time pair to another. The path is implicitly described by the system being tracked.

Create a system.
Create a tracker, associating it to the system.
Set the config for the track.
Track from your start point and time, to the target time.
Profit.

Specific examples are given with the implemented tracker types. So far, these types are avaiable:

AMPTracker

Please see their detailed documentation for description of how to use them correctly.

Purpose

Since the Bertini trackers have common functionality, and we want to be able to call arbitrary algorithms using and tracker type, we use inheritance. That is, there is common functionality in all trackers, such as

Setup TrackPath Refine

which we want all Trackers to be able to do. However, the internal behaviour of a particular tracker varies – which is why it is a different type. In particular, the fixed precision trackers produce and work in a fixed precision, whereas the AMPTracker varies precision to get around or near branch points while tracking.

Hence, the use of trackers in Bertini2 is through pointers or references to Trackers, enabling the use of any kind of tracking in any algorithm, and further allowing the development of new tracker types as the theory and practice advance.

Creating a new tracker type

To create a new Tracker type, inherit from this, and override the following functions:

public:
SuccessCode Refine(Vec<mpfr> & new_space,
                    Vec<mpfr> const& start_point, mpfr const& current_time) override
{}
 
private:
 
void TrackerLoopInitialization(mpfr const& start_time, Vec<mpfr> const& start_point) override
{}
 
SuccessCode InitialRefinement() override
{}
 
SuccessCode PreIterationCheck() const override
{}
 
SuccessCode TrackerIteration() override
{}
 
void CopyFinalSolution(Vec<mpfr> & solution_at_endtime) const override
{}

and optionally override the following functions

void ResetCounters() override
{}
 
void PostTrackCleanup() override
{}

where you probably want to call this base function, which is why it is protected, not private.

Member Function Documentation

◆ CheckGoingToInfinity()

template<class D>

virtual SuccessCode bertini::tracking::Tracker< D >::CheckGoingToInfinity ( ) const

protectedpure virtual

Check whether the path is going to infinity, as it tracks.

This check is necessary because a homotopy may be malformed, or may have encountered a probability-0 event. That it is a 0 probability event is why this check is disable-able via a toggle.

◆ GetPredictor()

template<class D>

Predictor bertini::tracking::Tracker< D >::GetPredictor ( ) const

inline

Query the currently set predictor.

◆ GetSystem()

template<class D>

const System & bertini::tracking::Tracker< D >::GetSystem ( ) const

inline

get a const reference to the system.

◆ IncrementBaseCountersFail()

template<class D>

void bertini::tracking::Tracker< D >::IncrementBaseCountersFail ( ) const

inlineprotected

Increment and reset counters after a failed TrackerIteration()

Your custom override, if provided, should almost certainly call this function.

◆ IncrementBaseCountersSuccess()

template<class D>

void bertini::tracking::Tracker< D >::IncrementBaseCountersSuccess ( ) const

inlineprotected

Increment and reset counters after a successful TrackerIteration()

Your custom override, if provided, should almost certainly call this function.

◆ NumTotalStepsTaken()

template<class D>

unsigned bertini::tracking::Tracker< D >::NumTotalStepsTaken ( ) const

inline

See how many steps have been taken.

Returns: The total number of steps taken, including successes and fails.

◆ PostTrackCleanup()

template<class D>

virtual void bertini::tracking::Tracker< D >::PostTrackCleanup ( ) const

inlineprotectedvirtual

Function to be called before exiting the tracker loop.

Here is the caller graph for this function:

◆ Refine() [1/2]

template<class D>

template<typename C>

SuccessCode bertini::tracking::Tracker< D >::Refine	(	Vec< C > &	new_space,
		Vec< C > const &	start_point,
		C const &	current_time ) const

inline

Refine a point to tolerance implicitly internally set.

Runs Newton's method using the current settings for tracking, including the min and max number of iterations allowed, the tracking tolerance, precision, etc. YOU must ensure that the input point has the correct precision.

Returns: The SuccessCode indicating whether the refinement completed.

Parameters

[out]	new_space	The result of refinement.
	start_point	The seed for Newton's method for refinement.
	current_time	The current time value for refinement.

◆ Refine() [2/2]

template<class D>

template<typename C>

SuccessCode bertini::tracking::Tracker< D >::Refine	(	Vec< C > &	new_space,
		Vec< C > const &	start_point,
		C const &	current_time,
		double const &	tolerance,
		unsigned	max_iterations ) const

inline

Refine a point to a given tolerance.

Runs Newton's method using the current settings for tracking, including the min and max number of iterations allowed, precision, etc, EXCEPT for the tracking tolerance and max number of iterations, which you feed in here. YOU must ensure that the input point has the correct precision.

Returns: The SuccessCode indicating whether the refinement completed.

Parameters

[out]	new_space	The result of refinement.
	start_point	The seed for Newton's method for refinement.
	current_time	The current time value for refinement.
	tolerance	The tolerance to which to refine.
	max_iterations	The maximum number of iterations to use to refine.

◆ ReinitializeInitialStepSize()

template<class D>

void bertini::tracking::Tracker< D >::ReinitializeInitialStepSize ( bool should_reinitialize_stepsize )

inline

Switch resetting of initial step size to that of the stepping settings.

By default, initial step size is retrieved from the stepping settings at the start of each path track. To turn this off, and re-use the previous step size from the previously tracked path, turn off by calling this function with false.

◆ ResetCounters()

template<class D>

virtual void bertini::tracking::Tracker< D >::ResetCounters ( ) const

protectedpure virtual

Reset counters used during tracking.

Your custom tracker type should almost certainly call this function.

◆ SetPredictor()

template<class D>

void bertini::tracking::Tracker< D >::SetPredictor ( Predictor new_predictor_choice )

inline

Change tracker to use a predictor.

Parameters

new_predictor_choice The new predictor to be used.

See also: Predictor

Here is the caller graph for this function:

◆ SetStepSize()

template<class D>

void bertini::tracking::Tracker< D >::SetStepSize ( RT const & new_stepsize ) const

inline

Set how large the stepsize should be.

Parameters

new_stepsize The new value.

◆ SetSystem()

template<class D>

void bertini::tracking::Tracker< D >::SetSystem ( const System & new_sys )

inline

get a const reference to the system.

◆ SetTrackingTolerance()

template<class D>

void bertini::tracking::Tracker< D >::SetTrackingTolerance ( double const & tracking_tolerance )

inline

Set how tightly to track the path.

Smaller values tracks the path more tightly, at the expense of higher computational time.

Parameters

tracking_tolerance The new value. Newton iterations are performed until the step length is less than this number, or the max number of iterations has been reached, in which case the overall predict-correct step is viewed as a failure, and the step is undone. This number must be positive.

Here is the caller graph for this function:

◆ Setup()

template<class D>

void bertini::tracking::Tracker< D >::Setup	(	Predictor	new_predictor_choice,
		double const &	tracking_tolerance,
		double const &	path_truncation_threshold,
		SteppingConfig const &	stepping,
		NewtonConfig const &	newton )

inline

Get the tracker set up for tracking.

Pass the tracker the configuration for tracking, to get it set up.

◆ TrackPath()

template<class D>

SuccessCode bertini::tracking::Tracker< D >::TrackPath	(	Vec< CT > &	solution_at_endtime,
		CT const &	start_time,
		CT const &	endtime,
		Vec< CT > const &	start_point ) const

inline

Track a start point through time, from a start time to a target time.

Parameters

[out]	solution_at_endtime	The value of the solution at the end time.
	start_time	The time at which to start tracking.
	endtime	The time to track to.
	start_point	The intial space values for tracking.

Returns: A success code indicating whether tracking was successful. Will be SuccessCode::Success if was successful, and something else otherwise.

The is the fundamental method for the tracker. First, you create and set up the tracker, telling it what system you will solve, and the settings to use. Then, you actually do the tracking.

Member Data Documentation

◆ condition_number_estimate_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::condition_number_estimate_

mutableprotected

An estimate on the condition number of the Jacobian.

◆ current_space_

template<class D>

TupOfVec bertini::tracking::Tracker< D >::current_space_

mutableprotected

The current space value.

◆ current_stepsize_

template<class D>

RT bertini::tracking::Tracker< D >::current_stepsize_

mutableprotected

The current stepsize.

◆ current_time_

template<class D>

CT bertini::tracking::Tracker< D >::current_time_

mutableprotected

The current time.

◆ delta_t_

template<class D>

CT bertini::tracking::Tracker< D >::delta_t_

mutableprotected

The current delta_t.

◆ digits_final_

template<class D>

unsigned bertini::tracking::Tracker< D >::digits_final_ = 0

protected

The number of digits to track to, due to being in endgame zone.

◆ digits_tracking_tolerance_

template<class D>

unsigned bertini::tracking::Tracker< D >::digits_tracking_tolerance_ = 5

protected

The number of digits required for tracking to given tolerance, condition number notwithstanding.

◆ endtime_

template<class D>

CT bertini::tracking::Tracker< D >::endtime_

mutableprotected

The time we are tracking to.

◆ error_estimate_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::error_estimate_

mutableprotected

An estimate on the error of a step.

◆ norm_delta_z_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::norm_delta_z_

mutableprotected

The norm of the change in space resulting from a step.

◆ norm_J_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::norm_J_

mutableprotected

An estimate on the norm of the Jacobian.

◆ norm_J_inverse_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::norm_J_inverse_

mutableprotected

An estimate on the norm of the inverse of the Jacobian.

◆ num_consecutive_failed_steps_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_consecutive_failed_steps_

mutableprotected

The number of CONSECUTIVE failed steps taken in a row.

◆ num_consecutive_successful_steps_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_consecutive_successful_steps_

mutableprotected

The number of CONSECUTIVE successful steps taken in a row.

◆ num_failed_steps_taken_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_failed_steps_taken_

mutableprotected

The total number of failed steps taken.

◆ num_steps_since_last_condition_number_computation_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_steps_since_last_condition_number_computation_

mutableprotected

How many steps have passed since the most recent condition number estimate.

◆ num_successful_steps_since_precision_decrease_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_successful_steps_since_precision_decrease_

mutableprotected

The number of successful steps since decreased precision.

◆ num_successful_steps_since_stepsize_increase_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_successful_steps_since_stepsize_increase_

mutableprotected

How many successful steps have been taken since increased stepsize.

◆ num_successful_steps_taken_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_successful_steps_taken_

mutableprotected

The number of successful steps taken so far.

◆ num_total_steps_taken_

template<class D>

unsigned bertini::tracking::Tracker< D >::num_total_steps_taken_

mutableprotected

The number of steps taken, including failures and successes.

◆ path_truncation_threshold_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::path_truncation_threshold_ = 1e5

protected

The threshold for path truncation.

◆ predictor_order_

template<class D>

unsigned bertini::tracking::Tracker< D >::predictor_order_

protected

The order of the predictor – one less than the error estimate order.

◆ reinitialize_stepsize_

template<class D>

bool bertini::tracking::Tracker< D >::reinitialize_stepsize_ = true

protected

Whether should check if the path is going to infinity while tracking. On by default.

Whether should re-initialize the stepsize with each call to Trackpath. On by default.

◆ size_proportion_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::size_proportion_

mutableprotected

The proportion of the space step size, taking into account the order of the predictor.

◆ step_success_code_

template<class D>

SuccessCode bertini::tracking::Tracker< D >::step_success_code_

mutableprotected

The next stepsize.

The code for step success.

◆ temporary_space_

template<class D>

TupOfVec bertini::tracking::Tracker< D >::temporary_space_

mutableprotected

After prediction, the tentative next space value.

◆ tentative_space_

template<class D>

TupOfVec bertini::tracking::Tracker< D >::tentative_space_

mutableprotected

After correction, the tentative next space value.

◆ tracked_system_

template<class D>

std::reference_wrapper<const System> bertini::tracking::Tracker< D >::tracked_system_

protected

Reference to the system being tracked.

◆ tracking_tolerance_

template<class D>

NumErrorT bertini::tracking::Tracker< D >::tracking_tolerance_ = 1e-5

protected

The tracking tolerance.

The documentation for this class was generated from the following file:

base_tracker.hpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Using a tracker

Purpose

Creating a new tracker type

Member Function Documentation

◆ CheckGoingToInfinity()

◆ GetPredictor()

◆ GetSystem()

◆ IncrementBaseCountersFail()

◆ IncrementBaseCountersSuccess()

◆ NumTotalStepsTaken()

◆ PostTrackCleanup()

◆ Refine() [1/2]

◆ Refine() [2/2]

◆ ReinitializeInitialStepSize()

◆ ResetCounters()

◆ SetPredictor()

◆ SetStepSize()

◆ SetSystem()

◆ SetTrackingTolerance()

◆ Setup()

◆ TrackPath()

Member Data Documentation

◆ condition_number_estimate_

◆ current_space_

◆ current_stepsize_

◆ current_time_

◆ delta_t_

◆ digits_final_

◆ digits_tracking_tolerance_

◆ endtime_

◆ error_estimate_

◆ norm_delta_z_

◆ norm_J_

◆ norm_J_inverse_

◆ num_consecutive_failed_steps_

◆ num_consecutive_successful_steps_

◆ num_failed_steps_taken_

◆ num_steps_since_last_condition_number_computation_

◆ num_successful_steps_since_precision_decrease_

◆ num_successful_steps_since_stepsize_increase_

◆ num_successful_steps_taken_

◆ num_total_steps_taken_

◆ path_truncation_threshold_

◆ predictor_order_

◆ reinitialize_stepsize_

◆ size_proportion_

◆ step_success_code_

◆ temporary_space_

◆ tentative_space_

◆ tracked_system_

◆ tracking_tolerance_