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 Types
using	Config = detail::Configured< typename TrackerTraits< D >::NeededConfigs >
	The configuration-holding base, carrying the config types this tracker needs.
using	Stepping = SteppingConfig
	The stepping (step-size adjustment) configuration type.
using	Newton = NewtonConfig
	The Newton corrector configuration type.
using	PrecConf = typename TrackerTraits< D >::PrecisionConfig
	The precision configuration type for this tracker.
using	UsedConfigs
	The list of configuration types this object holds.

Public Member Functions
	Tracker (System const &sys)
	Construct a tracker associated to a system to be tracked.
void	Setup (Predictor new_predictor_choice, NumErrorT const &tracking_tolerance, SteppingConfig const &stepping, NewtonConfig const &newton)
	Get the tracker set up for tracking.
void	Setup (Predictor new_predictor_choice, NumErrorT const &tracking_tolerance, NumErrorT const &path_truncation_threshold, SteppingConfig const &stepping, NewtonConfig const &newton)
	Get the tracker set up for tracking, and set its truncation threshold too.
void	SetTrackingTolerance (NumErrorT const &tracking_tolerance)
	Set how tightly to track the path.
void	SetInfiniteTruncationTolerance (NumErrorT const &tol)
	Set the threshold beyond which a path is judged to be going to infinity (and truncated).
void	RefreshConditionDirection ()
	(Re)draw the random probe direction used for condition-number estimation.
SuccessCode	TrackPath (Vec< ComplexT > &solution_at_endtime, ComplexT const &start_time, ComplexT const &endtime, Vec< ComplexT > const &start_point) const
	Track a start point through time, from a start time to a target time.
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, NumErrorT const &tolerance, unsigned max_iterations) const
	Refine a point to a given tolerance.
void	SetPredictor (Predictor new_predictor_choice)
	Change tracker to use a predictor.
Predictor	GetPredictor () const
	Query the currently set predictor.
void	SyncSettings () const
	Bring state derived from the settings in line with the settings.
void	SetSystem (const System &new_sys)
	get a const reference to the system.
const System &	GetSystem () const
	get a const reference to the system.
unsigned	NumTotalStepsTaken () const
	See how many steps have been taken.
void	ResetCumulativeStepCounts () const
	Zero the cumulative step counts.
unsigned	CumulativeSuccessfulSteps () const
	Successful steps since the last ResetCumulativeStepCounts, across every TrackPath call in between.
unsigned	CumulativeFailedSteps () const
	Failed steps since the last ResetCumulativeStepCounts, across every TrackPath call in between.
void	SetMaxWallClockTime (std::chrono::steady_clock::time_point deadline) const
	Give the tracker a wall-clock deadline: a point in time after which any track in progress is abandoned between steps with SuccessCode::WallClockLimitReached.
template<typename Rep, typename Period>
void	SetMaxWallClockDuration (std::chrono::duration< Rep, Period > duration) const
	Give the tracker a wall-clock budget counted from now: SetMaxWallClockTime(now + duration).
void	ClearMaxWallClockTime () const
	Remove the wall-clock deadline; tracking is unlimited again.
std::optional< std::chrono::steady_clock::time_point >	MaxWallClockTime () const
	The wall-clock deadline in force, if any.
void	SetStepSize (RealT const &new_stepsize) const
	Set how large the stepsize should be.
void	ReinitializeInitialStepSize (bool should_reinitialize_stepsize)
	Switch resetting of initial step size to that of the stepping settings.
virtual	~Tracker ()=default
auto	TrackingTolerance () const
	Get the currently set tracking tolerance.
unsigned	DigitsTrackingTolerance () const
	The number of digits tracking to the current tolerance demands, condition number notwithstanding.
auto	InfiniteTruncationTolerance () const
	Get the currently set infinite-truncation (path) threshold.
NumErrorT	LatestConditionNumber () const
	Get the condition-number estimate from the most recent predict/correct step.
NumErrorT	LatestErrorEstimate () const
	Get the error estimate from the most recent predict/correct step.
NumErrorT	LatestNormOfStep () const
	Get the norm of the Newton step from the most recent predict/correct step.
void	SetInfiniteTruncation (bool b)
	Turn the going-to-infinity path truncation check on or off.
auto	InfiniteTruncation ()
	Query whether the going-to-infinity path truncation check is enabled.
unsigned	NumVariables () const
	Get the number of variables in the system being tracked.
auto	CurrentTime () const
	Get the current time value of the track.
auto	DeltaT () const
	Get the current time-step increment (delta t).
auto	CurrentStepsize () const
	Get the current step size.
virtual Vec< ComplexT >	CurrentPoint () const =0
	Get the current space point of the track (in the derived tracker's working type).
virtual unsigned	CurrentPrecision () const =0
	Get the current working precision of the tracker.
template<typename T, typename = typename std::enable_if<IsTemplateParameter<T,Ts...>::value>::type>
const T &	Get () const
	Bring the configuration getter into scope, for querying config settings.
void	AddObserver (AnyObserver &new_observer) const
	Add an observer (non-owning) to observe this observable.
void	AddObserver (std::shared_ptr< AnyObserver > const &new_observer) const
	Add an observer whose lifetime is co-owned by this observable.
void	RemoveObserver (AnyObserver &observer) const
	Remove an observer from this observable.
virtual bool	ObservableIsA (std::type_index t) const
	Whether this observable may be observed as the given type.
void	Set (T const &t)
	Set the held configuration object of type T.

Public Attributes
std::tuple< Ts... >	configuration_
	The held configuration objects, one per config type.

Protected Types
using	TupOfVec = typename NeededTypes::ToTupleOfVec
	A tuple of complex vectors, one per numeric type the tracker uses.
using	TupOfReal = typename NeededTypes::ToTupleOfReal
	A tuple of real vectors, one per numeric type the tracker uses.

Protected Member Functions
template<typename ComplexT>
SuccessCode	CheckGoingToInfinity () const
	Check, at a given complex type, whether the current space value exceeds the truncation threshold.
virtual void	PostTrackCleanup () const
	Function to be called before exiting the tracker loop.
virtual void	ResetCounters () const =0
	Reset counters used during tracking.
void	ResetCountersBase () const
	Reset the base-class step counters (successes, failures, consecutive runs, total) to zero.
void	IncrementBaseCountersSuccess () const
	Increment and reset counters after a successful TrackerIteration().
virtual void	OnStepSuccess () const =0
	Hook invoked after a successful tracker iteration; derived types update their own state here.
void	IncrementBaseCountersFail () const
	Increment and reset counters after a failed TrackerIteration().
virtual void	OnStepFail () const =0
	Hook invoked after a failed tracker iteration; derived types update their own state here.
virtual SuccessCode	CheckGoingToInfinity () const =0
	Check whether the path is going to infinity, as it tracks.
virtual void	OnInfiniteTruncation () const =0
	Hook invoked when a path is truncated for going to infinity; derived types react here.
void	NotifyObservers (AnyEvent const &e) const
	Sends an event to observers that subscribed to its exact dynamic type, then to all catch-all (untyped) observers.
void	NotifyObservers (AnyEvent &e) const
	Notify all observers of a (mutable) event.
bool	HasObservers () const
	Whether anyone is currently observing (conservative).

Protected Attributes
std::reference_wrapper< const System >	tracked_system_
	Reference to the system being tracked.
bool	infinite_path_truncation_ = true
	Whether should check if the path is going to infinity while tracking. On by default.
bool	reinitialize_stepsize_ = true
	Whether should re-initialize the stepsize with each call to Trackpath. On by default.
unsigned	num_successful_steps_taken_ = 0
	The number of successful steps taken so far.
unsigned	num_consecutive_successful_steps_ = 0
	The number of CONSECUTIVE successful steps taken in a row.
unsigned	num_consecutive_failed_steps_ = 0
	The number of CONSECUTIVE failed steps taken in a row.
unsigned	num_failed_steps_taken_ = 0
	The total number of failed steps taken.
unsigned	num_successful_steps_cumulative_ = 0
	Successful steps since ResetCumulativeStepCounts, across TrackPath calls.
unsigned	num_failed_steps_cumulative_ = 0
	Failed steps since ResetCumulativeStepCounts, across TrackPath calls.
std::optional< std::chrono::steady_clock::time_point >	wall_clock_deadline_
	Give up between steps once this passes; none by default.
predict::ExplicitRKPredictor	predictor_
	The predictor to use while tracking.
unsigned	predictor_order_
	The order of the predictor – one less than the error estimate order. Derived from the setting by SyncPredictor, not written when the setting is.
correct::NewtonCorrector	corrector_
	The Newton corrector used to refine predicted points.
unsigned	digits_final_ = 0
	The number of digits to track to, due to being in endgame zone.
ComplexT	endtime_
	The time we are tracking to.
ComplexT	current_time_
	The current time.
ComplexT	delta_t_
	The current delta_t.
RealT	current_stepsize_
	The current stepsize.
RealT	next_stepsize_
	The next stepsize.
SuccessCode	step_success_code_
	The code for step success.
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_stepsize_increase_
	How many successful steps have been taken since increased stepsize.
TupOfVec	current_space_
	The current space value.
TupOfVec	tentative_space_
	After correction, the tentative next space value.
TupOfVec	temporary_space_
	After prediction, the tentative next space value.
StepMetadata	last_step_
	Metadata from the most recent predict or correct step (norms, condition number, size proportion, error estimate, norm of the Newton step).

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 CopySolution(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 Typedef Documentation

◆ Config

template<class D>

using bertini::tracking::Tracker< D >::Config = detail::Configured< typename TrackerTraits< D >::NeededConfigs >

The configuration-holding base, carrying the config types this tracker needs.

◆ Newton

template<class D>

using bertini::tracking::Tracker< D >::Newton = NewtonConfig

The Newton corrector configuration type.

◆ PrecConf

template<class D>

using bertini::tracking::Tracker< D >::PrecConf = typename TrackerTraits< D >::PrecisionConfig

The precision configuration type for this tracker.

◆ Stepping

template<class D>

using bertini::tracking::Tracker< D >::Stepping = SteppingConfig

The stepping (step-size adjustment) configuration type.

◆ TupOfReal

template<class D>

using bertini::tracking::Tracker< D >::TupOfReal = typename NeededTypes::ToTupleOfReal

protected

A tuple of real vectors, one per numeric type the tracker uses.

◆ TupOfVec

template<class D>

using bertini::tracking::Tracker< D >::TupOfVec = typename NeededTypes::ToTupleOfVec

protected

A tuple of complex vectors, one per numeric type the tracker uses.

◆ UsedConfigs

using bertini::detail::Configured< Ts >::UsedConfigs

inherited

The list of configuration types this object holds.

Constructor & Destructor Documentation

◆ Tracker()

template<class D>

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

inline

Construct a tracker associated to a system to be tracked.

◆ ~Tracker()

template<class D>

virtual bertini::tracking::Tracker< D >::~Tracker ( )

virtualdefault

Member Function Documentation

◆ AddObserver() [1/2]

void bertini::Observable::AddObserver ( AnyObserver & new_observer ) const

inlineinherited

Add an observer (non-owning) to observe this observable.

Stores only a raw reference: the caller is responsible for keeping the observer alive while it is attached. This is the right overload for stack-allocated C++ observers added and removed within a scope. For an observer whose lifetime you would rather have tracked, see the shared_ptr overload.

Observers that override SubscribedEventTypes() with a non-empty list are registered in a type-indexed map so NotifyObservers only calls them for events they declared interest in. Observers returning an empty list (the default) are placed in a catch-all list and receive every event.

Safe to call from inside an observer's Observe() (i.e. during a notification): the add is deferred and applied once the current notification loop finishes. This is what lets a "meta-observer" attach new observers in response to events.

Exceptions

IncompatibleObserver if the observer's ObservedKind() is not one this observable can be observed as.

◆ AddObserver() [2/2]

void bertini::Observable::AddObserver ( std::shared_ptr< AnyObserver > const & new_observer ) const

inlineinherited

Add an observer whose lifetime is co-owned by this observable.

The observable keeps a shared_ptr, so the observer stays alive (and keeps receiving events) for as long as it is attached, even after the caller drops their own reference — "attach it and forget it", with no dangling. It is released when RemoveObserver is called or this observable is destroyed. (Stack-allocated C++ observers can't be shared_ptr-owned; use the reference overload for those.)

Exceptions

IncompatibleObserver if incompatible (see the reference overload).

◆ CheckGoingToInfinity() [1/2]

template<class D>

template<typename ComplexT>

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

inlineprotected

Check, at a given complex type, whether the current space value exceeds the truncation threshold.

Template Parameters

ComplexT The complex number type at which to perform the check.

Returns: SuccessCode::GoingToInfinity if the infinity norm of the dehomogenized point exceeds the threshold, else SuccessCode::Success.

The system renders the verdict, so that this threshold, the endgame's Security::max_norm and the post-processing endpoint_finite_threshold are the same question asked with three different amounts of patience – and so that a system which has declared some of its coordinates auxiliary is not truncated on one of them (b2#403). The measurement is the infinity norm, the largest coordinate, as Bertini 1 does: with the 2-norm a point of n coordinates each just under the threshold was truncated once sqrt(n) carried the norm over it (b2#404).

◆ CheckGoingToInfinity() [2/2]

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.

Implemented in bertini::tracking::FixedPrecisionTracker< DerivedT >, and bertini::tracking::FixedPrecisionTracker< MultiplePrecisionTracker >.

◆ ClearMaxWallClockTime()

template<class D>

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

inline

Remove the wall-clock deadline; tracking is unlimited again.

◆ CumulativeFailedSteps()

template<class D>

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

inline

Failed steps since the last ResetCumulativeStepCounts, across every TrackPath call in between.

◆ CumulativeSuccessfulSteps()

template<class D>

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

inline

Successful steps since the last ResetCumulativeStepCounts, across every TrackPath call in between.

◆ CurrentPoint()

template<class D>

virtual Vec< ComplexT > bertini::tracking::Tracker< D >::CurrentPoint ( ) const

pure virtual

Get the current space point of the track (in the derived tracker's working type).

Implemented in bertini::tracking::AMPTracker, bertini::tracking::FixedPrecisionTracker< DerivedT >, bertini::tracking::FixedPrecisionTracker< DoublePrecisionTracker >, and bertini::tracking::FixedPrecisionTracker< MultiplePrecisionTracker >.

◆ CurrentPrecision()

template<class D>

virtual unsigned bertini::tracking::Tracker< D >::CurrentPrecision ( ) const

pure virtual

Get the current working precision of the tracker.

Implemented in bertini::tracking::AMPTracker, bertini::tracking::DoublePrecisionTracker, and bertini::tracking::MultiplePrecisionTracker.

◆ CurrentStepsize()

template<class D>

auto bertini::tracking::Tracker< D >::CurrentStepsize ( ) const

inline

Get the current step size.

◆ CurrentTime()

template<class D>

auto bertini::tracking::Tracker< D >::CurrentTime ( ) const

inline

Get the current time value of the track.

◆ DeltaT()

template<class D>

auto bertini::tracking::Tracker< D >::DeltaT ( ) const

inline

Get the current time-step increment (delta t).

◆ DigitsTrackingTolerance()

template<class D>

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

inline

The number of digits tracking to the current tolerance demands, condition number notwithstanding.

Derived on demand rather than cached at set time, so it cannot go stale behind a setting written through the ordinary config surface.

◆ Get()

template<class D>

template<typename T, typename = typename std::enable_if<IsTemplateParameter<T,Ts...>::value>::type>

const T & bertini::detail::Configured< Ts >::Get ( ) const

inline

Bring the configuration getter into scope, for querying config settings.

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

◆ HasObservers()

bool bertini::Observable::HasObservers ( ) const

inlineprotectedinherited

Whether anyone is currently observing (conservative).

Lets an emitter skip constructing an event – and any work needed to build its payload, such as a numeric-type conversion – when there is no observer to receive it. Conservative: returns true if any watcher list is non-empty (even if a stale, emptied typed bucket lingers), so it never wrongly suppresses a real observer.

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

◆ InfiniteTruncation()

template<class D>

auto bertini::tracking::Tracker< D >::InfiniteTruncation ( )

inline

Query whether the going-to-infinity path truncation check is enabled.

◆ InfiniteTruncationTolerance()

template<class D>

auto bertini::tracking::Tracker< D >::InfiniteTruncationTolerance ( ) const

inline

Get the currently set infinite-truncation (path) threshold.

◆ LatestConditionNumber()

template<class D>

NumErrorT bertini::tracking::Tracker< D >::LatestConditionNumber ( ) const

inline

Get the condition-number estimate from the most recent predict/correct step.

◆ LatestErrorEstimate()

template<class D>

NumErrorT bertini::tracking::Tracker< D >::LatestErrorEstimate ( ) const

inline

Get the error estimate from the most recent predict/correct step.

◆ LatestNormOfStep()

template<class D>

NumErrorT bertini::tracking::Tracker< D >::LatestNormOfStep ( ) const

inline

Get the norm of the Newton step from the most recent predict/correct step.

◆ MaxWallClockTime()

template<class D>

std::optional< std::chrono::steady_clock::time_point > bertini::tracking::Tracker< D >::MaxWallClockTime ( ) const

inline

The wall-clock deadline in force, if any.

◆ NotifyObservers() [1/2]

void bertini::Observable::NotifyObservers ( AnyEvent & e ) const

inlineprotectedinherited

Notify all observers of a (mutable) event.

◆ NotifyObservers() [2/2]

void bertini::Observable::NotifyObservers ( AnyEvent const & e ) const

inlineprotectedinherited

Sends an event to observers that subscribed to its exact dynamic type, then to all catch-all (untyped) observers.

Mutations of the observer lists are deferred for the duration of a notification (see AddObserver/RemoveObserver), so iterating the live lists here is safe even when an observer subscribes/unsubscribes mid-dispatch. An observer that returns ObserveResult::Unsubscribe is dropped once the (possibly nested) notification completes. The depth counter keeps this correct under re-entrant emission.

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

◆ NumVariables()

template<class D>

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

inline

Get the number of variables in the system being tracked.

◆ ObservableIsA()

virtual bool bertini::Observable::ObservableIsA ( std::type_index t ) const

inlinevirtualinherited

Whether this observable may be observed as the given type.

Drives the compatibility check in AddObserver. The default accepts the wildcard typeid(void) and this observable's own dynamic type. An observable that emits its events templated on a base type (so a single observer type serves many concrete observables) should also accept that base type — e.g. ZeroDim accepts AnyZeroDim.

Reimplemented in bertini::algorithm::HomotopySolver< TrackerType, EndgameType, SystemType >, and bertini::algorithm::HomotopySolver< A, B, C >.

◆ OnInfiniteTruncation()

template<class D>

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

protectedpure virtual

Hook invoked when a path is truncated for going to infinity; derived types react here.

Implemented in bertini::tracking::FixedPrecisionTracker< DerivedT >, bertini::tracking::FixedPrecisionTracker< DoublePrecisionTracker >, and bertini::tracking::FixedPrecisionTracker< MultiplePrecisionTracker >.

◆ OnStepFail()

template<class D>

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

protectedpure virtual

Hook invoked after a failed tracker iteration; derived types update their own state here.

Implemented in bertini::tracking::FixedPrecisionTracker< DerivedT >, bertini::tracking::FixedPrecisionTracker< DoublePrecisionTracker >, and bertini::tracking::FixedPrecisionTracker< MultiplePrecisionTracker >.

◆ OnStepSuccess()

template<class D>

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

protectedpure virtual

Hook invoked after a successful tracker iteration; derived types update their own state here.

Implemented in bertini::tracking::FixedPrecisionTracker< DerivedT >, bertini::tracking::FixedPrecisionTracker< DoublePrecisionTracker >, and bertini::tracking::FixedPrecisionTracker< MultiplePrecisionTracker >.

◆ PostTrackCleanup()

template<class D>

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

inlineprotectedvirtual

Function to be called before exiting the tracker loop.

Reimplemented in bertini::tracking::FixedPrecisionTracker< DerivedT >, bertini::tracking::FixedPrecisionTracker< DoublePrecisionTracker >, and bertini::tracking::FixedPrecisionTracker< MultiplePrecisionTracker >.

◆ 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,
		NumErrorT 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.

◆ RefreshConditionDirection()

template<class D>

void bertini::tracking::Tracker< D >::RefreshConditionDirection ( )

inline

(Re)draw the random probe direction used for condition-number estimation.

Call this once, from the algorithm, at the start of tracking a point – after any per-path RNG reseed and before TrackPath – so the direction is fixed for that whole point's track (pre-endgame tracking and the endgame both) and is reproducible across runs/ranks. Do NOT call it per TrackPath: the endgame issues many TrackPath calls per point, and refreshing the direction mid-track perturbs condition estimates and churns the RNG.

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

◆ RemoveObserver()

void bertini::Observable::RemoveObserver ( AnyObserver & observer ) const

inlineinherited

Remove an observer from this observable.

Like AddObserver, this is safe to call during a notification: the removal is deferred until the current notification loop finishes.

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

Implemented in bertini::tracking::FixedPrecisionTracker< DerivedT >, bertini::tracking::FixedPrecisionTracker< DoublePrecisionTracker >, and bertini::tracking::FixedPrecisionTracker< MultiplePrecisionTracker >.

◆ ResetCountersBase()

template<class D>

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

inlineprotected

Reset the base-class step counters (successes, failures, consecutive runs, total) to zero.

◆ ResetCumulativeStepCounts()

template<class D>

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

inline

Zero the cumulative step counts.

The per-call counters (NumTotalStepsTaken and friends) start over at every call to TrackPath. The cumulative counts start over only here, so a caller that issues many TrackPath calls for one logical path – an endgame issues hundreds for its sample circles – can read the total work of the whole path afterwards. The solver zeroes them at the start of each path and stamps them into that path's metadata.

◆ Set()

void bertini::detail::Configured< Ts >::Set ( T const & t )

inlineinherited

Set the held configuration object of type T.

◆ SetInfiniteTruncation()

template<class D>

void bertini::tracking::Tracker< D >::SetInfiniteTruncation ( bool b )

inline

Turn the going-to-infinity path truncation check on or off.

◆ SetInfiniteTruncationTolerance()

template<class D>

void bertini::tracking::Tracker< D >::SetInfiniteTruncationTolerance ( NumErrorT const & tol )

inline

Set the threshold beyond which a path is judged to be going to infinity (and truncated).

Parameters

tol	The new (strictly positive) truncation threshold.

◆ SetMaxWallClockDuration()

template<class D>

template<typename Rep, typename Period>

void bertini::tracking::Tracker< D >::SetMaxWallClockDuration ( std::chrono::duration< Rep, Period > duration ) const

inline

Give the tracker a wall-clock budget counted from now: SetMaxWallClockTime(now + duration).

Parameters

duration How long from now to give up, e.g. std::chrono::seconds(30) or std::chrono::duration<double>(0.5).

◆ SetMaxWallClockTime()

template<class D>

void bertini::tracking::Tracker< D >::SetMaxWallClockTime ( std::chrono::steady_clock::time_point deadline ) const

inline

Give the tracker a wall-clock deadline: a point in time after which any track in progress is abandoned between steps with SuccessCode::WallClockLimitReached.

The primitive is a point in time, not a length of time, because it has to hold across calls: an endgame issues hundreds of TrackPath calls for one path, and a per-call budget would start over with each. The deadline stays armed until cleared or replaced, so a caller limiting one path at a time sets it before the path and clears it after. "Time" here is the clock on the wall; the path variable t is unaffected.

Parameters

deadline The steady-clock time point to give up at.

◆ 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

◆ SetStepSize()

template<class D>

void bertini::tracking::Tracker< D >::SetStepSize ( RealT 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 ( NumErrorT 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.

◆ Setup() [1/2]

template<class D>

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

inline

Get the tracker set up for tracking, and set its truncation threshold too.

The four-argument form leaves the truncation threshold alone, which is what a caller that does not own it should do – it is the tracker's own setting (tracking::TruncationConfig), reachable by Set like any other, and the solver no longer hands one over (b2#457). This form is the convenience for a caller configuring a bare tracker from scratch.

Parameters

new_predictor_choice	The predictor to use.
tracking_tolerance	How tightly Newton must correct onto the path.
path_truncation_threshold	The size at which a path is abandoned as divergent.
stepping	The stepping settings.
newton	The Newton corrector settings.

◆ Setup() [2/2]

template<class D>

void bertini::tracking::Tracker< D >::Setup	(	Predictor	new_predictor_choice,
		NumErrorT const &	tracking_tolerance,
		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.

◆ SyncSettings()

template<class D>

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

inline

Bring state derived from the settings in line with the settings.

The configs are the truth; anything computed from them is derived state, rebuilt when the two disagree rather than at the moment somebody writes a config. That ordering is the point: a setting written through the ordinary config surface never passes through a bespoke setter, so state cached at set-time goes stale silently, and the bespoke setters that avoided this are exactly why these settings were not configs in the first place (b2#457).

Called at the top of every path – late enough to catch a setting written by any route, and cheap enough not to matter, since each check is a comparison and the rebuild happens only on a real change. The predictor object is the one piece of derived state left; the digit count the AMP precision rule wants is simply computed where it is used.

◆ TrackingTolerance()

template<class D>

auto bertini::tracking::Tracker< D >::TrackingTolerance ( ) const

inline

Get the currently set tracking tolerance.

◆ TrackPath()

template<class D>

SuccessCode bertini::tracking::Tracker< D >::TrackPath	(	Vec< ComplexT > &	solution_at_endtime,
		ComplexT const &	start_time,
		ComplexT const &	endtime,
		Vec< ComplexT > 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

◆ configuration_

std::tuple<Ts...> bertini::detail::Configured< Ts >::configuration_

inherited

The held configuration objects, one per config type.

◆ corrector_

template<class D>

correct::NewtonCorrector bertini::tracking::Tracker< D >::corrector_

mutableprotected

The Newton corrector used to refine predicted points.

◆ current_space_

template<class D>

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

mutableprotected

The current space value.

◆ current_stepsize_

template<class D>

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

mutableprotected

The current stepsize.

◆ current_time_

template<class D>

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

mutableprotected

The current time.

◆ delta_t_

template<class D>

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

◆ endtime_

template<class D>

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

mutableprotected

The time we are tracking to.

◆ infinite_path_truncation_

template<class D>

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

protected

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

◆ last_step_

template<class D>

StepMetadata bertini::tracking::Tracker< D >::last_step_

mutableprotected

Metadata from the most recent predict or correct step (norms, condition number, size proportion, error estimate, norm of the Newton step).

Filled by the predictor/corrector via their StepMetadata out-parameter.

◆ next_stepsize_

template<class D>

RealT bertini::tracking::Tracker< D >::next_stepsize_

mutableprotected

The next stepsize.

◆ num_consecutive_failed_steps_

template<class D>

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

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_ = 0

mutableprotected

The number of CONSECUTIVE successful steps taken in a row.

◆ num_failed_steps_cumulative_

template<class D>

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

mutableprotected

Failed steps since ResetCumulativeStepCounts, across TrackPath calls.

◆ num_failed_steps_taken_

template<class D>

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

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_cumulative_

template<class D>

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

mutableprotected

Successful steps since ResetCumulativeStepCounts, across TrackPath calls.

◆ 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_ = 0

mutableprotected

The number of successful steps taken so far.

◆ predictor_

template<class D>

predict::ExplicitRKPredictor bertini::tracking::Tracker< D >::predictor_

mutableprotected

The predictor to use while tracking.

◆ predictor_order_

template<class D>

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

mutableprotected

The order of the predictor – one less than the error estimate order. Derived from the setting by SyncPredictor, not written when the setting is.

◆ reinitialize_stepsize_

template<class D>

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

protected

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

◆ step_success_code_

template<class D>

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

mutableprotected

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.

◆ wall_clock_deadline_

template<class D>

std::optional<std::chrono::steady_clock::time_point> bertini::tracking::Tracker< D >::wall_clock_deadline_

mutableprotected

Give up between steps once this passes; none by default.

Public Types

Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Using a tracker

Purpose

Creating a new tracker type

Member Typedef Documentation

◆ Config

◆ Newton

◆ PrecConf

◆ Stepping

◆ TupOfReal

◆ TupOfVec

◆ UsedConfigs

Constructor & Destructor Documentation

◆ Tracker()

◆ ~Tracker()

Member Function Documentation

◆ AddObserver() [1/2]

◆ AddObserver() [2/2]

◆ CheckGoingToInfinity() [1/2]

◆ CheckGoingToInfinity() [2/2]

◆ ClearMaxWallClockTime()

◆ CumulativeFailedSteps()

◆ CumulativeSuccessfulSteps()

◆ CurrentPoint()

◆ CurrentPrecision()

◆ CurrentStepsize()

◆ CurrentTime()

◆ DeltaT()

◆ DigitsTrackingTolerance()

◆ Get()

◆ GetPredictor()

◆ GetSystem()

◆ HasObservers()

◆ IncrementBaseCountersFail()

◆ IncrementBaseCountersSuccess()

◆ InfiniteTruncation()

◆ InfiniteTruncationTolerance()

◆ LatestConditionNumber()

◆ LatestErrorEstimate()

◆ LatestNormOfStep()

◆ MaxWallClockTime()

◆ NotifyObservers() [1/2]

◆ NotifyObservers() [2/2]

◆ NumTotalStepsTaken()

◆ NumVariables()

◆ ObservableIsA()

◆ OnInfiniteTruncation()

◆ OnStepFail()

◆ OnStepSuccess()

◆ PostTrackCleanup()

◆ Refine() [1/2]

◆ Refine() [2/2]

◆ RefreshConditionDirection()

◆ ReinitializeInitialStepSize()

◆ RemoveObserver()

◆ ResetCounters()

◆ ResetCountersBase()

◆ ResetCumulativeStepCounts()

◆ Set()

◆ SetInfiniteTruncation()

◆ SetInfiniteTruncationTolerance()

◆ SetMaxWallClockDuration()

◆ SetMaxWallClockTime()

◆ SetPredictor()

◆ SetStepSize()

◆ SetSystem()

◆ SetTrackingTolerance()

◆ Setup() [1/2]

◆ Setup() [2/2]

◆ SyncSettings()

◆ TrackingTolerance()

◆ TrackPath()

Member Data Documentation

◆ configuration_