Functor-like class for tracking paths on a system. More...

#include <amp_tracker.hpp>

Inheritance diagram for bertini::tracking::AMPTracker:

Collaboration diagram for bertini::tracking::AMPTracker:

Public Types
enum	UpsampleRefinementOption { upsample_refine_off = 0 , upsample_refine_on = 1 }
	Whether to refine after upsampling precision. More...
typedef Tracker< AMPTracker >	Base
	The base tracker type.
typedef TrackerTraits< AMPTracker >::EventEmitterType	EmitterType
	The event-emitter type.
using	Config
	The configuration-holding base, carrying the config types this tracker needs.
using	Stepping
	The stepping (step-size adjustment) configuration type.
using	Newton
	The Newton corrector configuration type.
using	PrecConf
	The precision configuration type for this tracker.
using	UsedConfigs = TypeList<Ts...>
	The list of configuration types this object holds.

Public Member Functions
	AMPTracker (class System const &sys)
	Construct an Adaptive Precision tracker, associating to it a System.
void	PrecisionSetup (AdaptiveMultiplePrecisionConfig const &AMP_config)
	Special additional setup call for the AMPTracker, selecting the config for adaptive precision.
unsigned	GetCurrentPrecision () const
	Get the current working precision of the adaptive tracker.
void	PrecisionPreservation (bool should_preseve_precision)
	Switch preservation of precision after tracking on / off.
void	SetStartPrecision (std::optional< unsigned > p=std::nullopt)
	Override the precision at which tracking starts.
virtual	~AMPTracker ()=default
Vec< complex_mp >	CurrentPoint () const override
	Get the current space point, returned in multiprecision regardless of the working type.
template<UpsampleRefinementOption refine_if_necessary = upsample_refine_off>
SuccessCode	ChangePrecision (unsigned new_precision) const
	Change precision of tracker to next_precision.
unsigned	CurrentPrecision () const override
	Get the current working precision of the tracker.
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.
SuccessCode	Refine (Vec< C > &new_space, Vec< C > const &start_point, C const &current_time) const
	Refine a point to tolerance implicitly internally set.
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.
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.
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.
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.
template<typename T, typename = typename std::enable_if<IsTemplateParameter<T,Ts...>::value>::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
	A tuple of complex vectors, one per numeric type the tracker uses.
using	TupOfReal
	A tuple of real vectors, one per numeric type the tracker uses.

Protected Member Functions
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().
void	IncrementBaseCountersFail () const
	Increment and reset counters after a failed TrackerIteration().
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_
	Whether should check if the path is going to infinity while tracking. On by default.
bool	reinitialize_stepsize_
	Whether should re-initialize the stepsize with each call to Trackpath. On by default.
unsigned	num_successful_steps_taken_
	The number of successful steps taken so far.
unsigned	num_consecutive_successful_steps_
	The number of CONSECUTIVE successful steps taken in a row.
unsigned	num_consecutive_failed_steps_
	The number of CONSECUTIVE failed steps taken in a row.
unsigned	num_failed_steps_taken_
	The total number of failed steps taken.
unsigned	num_successful_steps_cumulative_
	Successful steps since ResetCumulativeStepCounts, across TrackPath calls.
unsigned	num_failed_steps_cumulative_
	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_
	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).

Friends
class	Tracker< AMPTracker >

Detailed Description

Functor-like class for tracking paths on a system.

Explanation

The bertini::AMPTracker class enables tracking using Adaptive Multiple Precision on an arbitrary square homotopy.

The intended usage is to:

Create a system, and instantiate some settings.
Create an AMPTracker, associating it to the system you are going to solve or track on.
Run AMPTracker::Setup and AMPTracker::PrecisionSetup, getting the settings in line for tracking.
Repeatedly, or as needed, call the AMPTracker::TrackPath function, feeding it a start point, and start and end times. The initial precision is that of the start point.

Working precision and stepsize are adjusted automatically to get around nearby singularities to the path. If the endpoint is singular, this may very well fail, as prediction and correction get more and more difficult with proximity to singularities.

The TrackPath method is intended to allow the user to track to nonsingular endpoints, or to an endgame boundary, from which an appropriate endgame will be called.

Some notes

The AMPTracker has internal state. That is, it stores the current state of the path being tracked as data members. After tracking has concluded, these statistics may be extracted. If you need additional accessors for these data, contact the software authors.

The class additionally uses the Boost.Log library for logging. At time of this writing, the trivial logger is being used. As development continues we will move toward using a more sophisticated logging model. Suggestions are welcome.

This class, like the other Tracker classes, uses mutable members to store the current state of the tracker. The tracking tolerances, settings, etc, remain constant throughout a track, but the internal state such as the current time or space values, will change. You can also expect the precision of the tracker to differ after a certain calls, too.

Example Usage

Below we demonstrate a basic usage of the AMPTracker class to track a single path.

The pattern is as described above: create an instance of the class, feeding it the system to be tracked, and some configuration. Then, use the tracker to track paths of the system.

DefaultPrecision(30); // set initial precision.  This is not strictly necessary.
 
using namespace bertini::tracking;
 
// 1. Create the system
Var x = Variable::Make("x");
Var y = Variable::Make("y");
Var t = Variable::Make("t");
 
System sys;
 
VariableGroup v{x,y};
 
sys.AddFunction(pow(x,2) + (1-t)*x - 1);
sys.AddFunction(pow(y,2) + (1-t)*x*y - 2);
sys.AddPathVariable(t);
sys.AddVariableGroup(v);
 
auto AMP = bertini::tracking::AMPConfigFrom(sys);
 
//  2. Create the Tracker object, associating the system to it.
bertini::tracking::AMPTracker tracker(sys);
 
SteppingConfig stepping_preferences;
NewtonConfig newton_preferences;
 
// 3. Get the settings into the tracker
tracker.Setup(Predictor::Euler,
                real_mp("1e-5"),
                real_mp("1e5"),
                stepping_preferences,
                newton_preferences);
 
tracker.PrecisionSetup(AMP);
 
//  4. Create a start and end time.  These are complex numbers.
complex_mp t_start("1.0");
complex_mp t_end("0");
 
//  5. Create a start point, and container for the end point.
Vec<complex_mp> start_point(2);
start_point << complex_mp("1"), complex_mp("1.414");  // set the value of the start point.  This is Eigen syntax.
 
Vec<complex_mp> end_point;
 
// 6. actually do the tracking
SuccessCode tracking_success = tracker.TrackPath(end_point,
                  t_start, t_end, start_point);
 
// 7. and then onto whatever processing you are doing to the computed point.

If this documentation is insufficient, please contact the authors with suggestions, or get involved! Pull requests welcomed.

Testing

Test suite driving this class: AMP_tracker_basics. File: test/tracking_basics/tracker_test.cpp Functionality tested: Can use an AMPTracker to track in various situations, including tracking on nonsingular paths. Also track to a singularity on the square root function. Furthermore test that tracking fails to start from a singular start point, and tracking fails if a singularity is directly on the path being tracked.

Member Typedef Documentation

◆ Base

typedef Tracker<AMPTracker> bertini::tracking::AMPTracker::Base

The base tracker type.

◆ Config

using bertini::tracking::Tracker< AMPTracker >::Config

inherited

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

◆ EmitterType

typedef TrackerTraits<AMPTracker>::EventEmitterType bertini::tracking::AMPTracker::EmitterType

The event-emitter type.

◆ Newton

using bertini::tracking::Tracker< AMPTracker >::Newton

inherited

The Newton corrector configuration type.

◆ PrecConf

using bertini::tracking::Tracker< AMPTracker >::PrecConf

inherited

The precision configuration type for this tracker.

◆ Stepping

using bertini::tracking::Tracker< AMPTracker >::Stepping

inherited

The stepping (step-size adjustment) configuration type.

◆ TupOfReal

using bertini::tracking::Tracker< AMPTracker >::TupOfReal

protectedinherited

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

◆ TupOfVec

using bertini::tracking::Tracker< AMPTracker >::TupOfVec

protectedinherited

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

◆ UsedConfigs

template<typename ... Ts>

using bertini::detail::Configured< Ts >::UsedConfigs = TypeList<Ts...>

inherited

The list of configuration types this object holds.

Member Enumeration Documentation

◆ UpsampleRefinementOption

enum bertini::tracking::AMPTracker::UpsampleRefinementOption

Whether to refine after upsampling precision.

Enumerator
upsample_refine_off	Do not refine after upsampling.
upsample_refine_on	Refine after upsampling.

Constructor & Destructor Documentation

◆ AMPTracker()

bertini::tracking::AMPTracker::AMPTracker ( class System const & sys )

inline

Construct an Adaptive Precision tracker, associating to it a System.

◆ ~AMPTracker()

virtual bertini::tracking::AMPTracker::~AMPTracker ( )

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

◆ ChangePrecision()

template<UpsampleRefinementOption refine_if_necessary = upsample_refine_off>

SuccessCode bertini::tracking::AMPTracker::ChangePrecision ( unsigned new_precision ) const

inline

Change precision of tracker to next_precision.

Converts the internal temporaries, and adjusts precision of system. Then refines if necessary.

If the new precision is higher than current precision, a refine step will be called, which runs Newton's method. This may fail, leaving the tracker in a state with higher precision internals, but garbage digits after the previously known digits.

Parameters

new_precision The precision to change to.

Returns: SuccessCode indicating whether the change was successful. If the precision increases, and the refinement loop fails, this could be not Success. Changing down is guaranteed to succeed.

◆ ClearMaxWallClockTime()

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

inlineinherited

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

◆ CumulativeFailedSteps()

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

inlineinherited

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

◆ CumulativeSuccessfulSteps()

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

inlineinherited

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

◆ CurrentPoint()

Vec< complex_mp > bertini::tracking::AMPTracker::CurrentPoint ( ) const

inlineoverridevirtual

Get the current space point, returned in multiprecision regardless of the working type.

Implements bertini::tracking::Tracker< AMPTracker >.

◆ CurrentPrecision()

unsigned bertini::tracking::AMPTracker::CurrentPrecision ( ) const

inlineoverridevirtual

Get the current working precision of the tracker.

Implements bertini::tracking::Tracker< AMPTracker >.

◆ CurrentStepsize()

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

inlineinherited

Get the current step size.

◆ CurrentTime()

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

inlineinherited

Get the current time value of the track.

◆ DeltaT()

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

inlineinherited

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

◆ DigitsTrackingTolerance()

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

inlineinherited

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

( ) const

inherited

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

◆ GetCurrentPrecision()

unsigned bertini::tracking::AMPTracker::GetCurrentPrecision ( ) const

inline

Get the current working precision of the adaptive tracker.

◆ GetPredictor()

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

inlineinherited

Query the currently set predictor.

◆ GetSystem()

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

inlineinherited

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

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

inlineprotectedinherited

Increment and reset counters after a failed TrackerIteration().

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

◆ IncrementBaseCountersSuccess()

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

inlineprotectedinherited

Increment and reset counters after a successful TrackerIteration().

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

◆ InfiniteTruncation()

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

inlineinherited

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

◆ InfiniteTruncationTolerance()

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

inlineinherited

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

◆ LatestConditionNumber()

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

inlineinherited

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

◆ LatestErrorEstimate()

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

inlineinherited

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

◆ LatestNormOfStep()

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

inlineinherited

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

◆ MaxWallClockTime()

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

inlineinherited

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

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

inlineinherited

See how many steps have been taken.

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

◆ NumVariables()

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

inlineinherited

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

◆ PrecisionPreservation()

void bertini::tracking::AMPTracker::PrecisionPreservation ( bool should_preseve_precision )

inline

Switch preservation of precision after tracking on / off.

By default, precision is preserved after tracking, so the precision of the ambient workspace is returned to its previous state once Adaptive Precision tracking is done.

◆ PrecisionSetup()

void bertini::tracking::AMPTracker::PrecisionSetup ( AdaptiveMultiplePrecisionConfig const & AMP_config )

inline

Special additional setup call for the AMPTracker, selecting the config for adaptive precision.

◆ Refine() [1/2]

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

inlineinherited

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]

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

inlineinherited

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

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

inlineinherited

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

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

inlineinherited

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.

◆ ResetCountersBase()

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

inlineprotectedinherited

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

◆ ResetCumulativeStepCounts()

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

inlineinherited

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

template<typename ... Ts>

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

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

inlineinherited

Set the held configuration object of type T.

◆ SetInfiniteTruncation()

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

inlineinherited

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

◆ SetInfiniteTruncationTolerance()

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

inlineinherited

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

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

inlineinherited

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

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

inlineinherited

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

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

inlineinherited

Change tracker to use a predictor.

Parameters

new_predictor_choice The new predictor to be used.

See also: Predictor

◆ SetStartPrecision()

void bertini::tracking::AMPTracker::SetStartPrecision ( std::optional< unsigned > p = std::nullopt )

inline

Override the precision at which tracking starts.

Pass a value to start tracking at that precision regardless of the start point's precision. Pass std::nullopt (or call with no argument) to use the start point's precision (default).

◆ SetStepSize()

void bertini::tracking::Tracker< AMPTracker >::SetStepSize ( RealT const & new_stepsize ) const

inlineinherited

Set how large the stepsize should be.

Parameters

new_stepsize The new value.

◆ SetSystem()

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

inlineinherited

get a const reference to the system.

◆ SetTrackingTolerance()

void bertini::tracking::Tracker< AMPTracker >::SetTrackingTolerance ( NumErrorT const & tracking_tolerance )

inlineinherited

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]

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

inlineinherited

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]

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

inlineinherited

Get the tracker set up for tracking.

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

◆ SyncSettings()

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

inlineinherited

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

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

inlineinherited

Get the currently set tracking tolerance.

◆ TrackPath()

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

inlineinherited

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.

◆ Tracker< AMPTracker >

friend class Tracker< AMPTracker >

friend

Member Data Documentation

◆ configuration_

template<typename ... Ts>

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

inherited

The held configuration objects, one per config type.

◆ corrector_

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

mutableprotectedinherited

The Newton corrector used to refine predicted points.

◆ current_space_

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

mutableprotectedinherited

The current space value.

◆ current_stepsize_

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

mutableprotectedinherited

The current stepsize.

◆ current_time_

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

mutableprotectedinherited

The current time.

◆ delta_t_

ComplexT bertini::tracking::Tracker< AMPTracker >::delta_t_

mutableprotectedinherited

The current delta_t.

◆ digits_final_

unsigned bertini::tracking::Tracker< AMPTracker >::digits_final_

protectedinherited

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

◆ endtime_

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

mutableprotectedinherited

The time we are tracking to.

◆ infinite_path_truncation_

bool bertini::tracking::Tracker< AMPTracker >::infinite_path_truncation_

protectedinherited

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

◆ last_step_

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

mutableprotectedinherited

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_

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

mutableprotectedinherited

The next stepsize.

◆ num_consecutive_failed_steps_

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

mutableprotectedinherited

The number of CONSECUTIVE failed steps taken in a row.

◆ num_consecutive_successful_steps_

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

mutableprotectedinherited

The number of CONSECUTIVE successful steps taken in a row.

◆ num_failed_steps_cumulative_

unsigned bertini::tracking::Tracker< AMPTracker >::num_failed_steps_cumulative_

mutableprotectedinherited

Failed steps since ResetCumulativeStepCounts, across TrackPath calls.

◆ num_failed_steps_taken_

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

mutableprotectedinherited

The total number of failed steps taken.

◆ num_steps_since_last_condition_number_computation_

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

mutableprotectedinherited

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

◆ num_successful_steps_cumulative_

unsigned bertini::tracking::Tracker< AMPTracker >::num_successful_steps_cumulative_

mutableprotectedinherited

Successful steps since ResetCumulativeStepCounts, across TrackPath calls.

◆ num_successful_steps_since_stepsize_increase_

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

mutableprotectedinherited

How many successful steps have been taken since increased stepsize.

◆ num_successful_steps_taken_

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

mutableprotectedinherited

The number of successful steps taken so far.

◆ predictor_

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

mutableprotectedinherited

The predictor to use while tracking.

◆ predictor_order_

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

mutableprotectedinherited

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_

bool bertini::tracking::Tracker< AMPTracker >::reinitialize_stepsize_

protectedinherited

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

◆ step_success_code_

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

mutableprotectedinherited

The code for step success.

◆ temporary_space_

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

mutableprotectedinherited

After prediction, the tentative next space value.

◆ tentative_space_

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

mutableprotectedinherited

After correction, the tentative next space value.

◆ tracked_system_

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

protectedinherited

Reference to the system being tracked.

◆ wall_clock_deadline_

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

mutableprotectedinherited

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

Public Types

Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Explanation

Some notes

Example Usage

Testing

Member Typedef Documentation

◆ Base

◆ Config

◆ EmitterType

◆ Newton

◆ PrecConf

◆ Stepping

◆ TupOfReal

◆ TupOfVec

◆ UsedConfigs

Member Enumeration Documentation

◆ UpsampleRefinementOption

Constructor & Destructor Documentation

◆ AMPTracker()

◆ ~AMPTracker()

Member Function Documentation

◆ AddObserver() [1/2]

◆ AddObserver() [2/2]

◆ ChangePrecision()

◆ ClearMaxWallClockTime()

◆ CumulativeFailedSteps()

◆ CumulativeSuccessfulSteps()

◆ CurrentPoint()

◆ CurrentPrecision()

◆ CurrentStepsize()

◆ CurrentTime()

◆ DeltaT()

◆ DigitsTrackingTolerance()

◆ Get()

◆ GetCurrentPrecision()

◆ GetPredictor()

◆ GetSystem()

◆ HasObservers()

◆ IncrementBaseCountersFail()

◆ IncrementBaseCountersSuccess()

◆ InfiniteTruncation()

◆ InfiniteTruncationTolerance()

◆ LatestConditionNumber()

◆ LatestErrorEstimate()

◆ LatestNormOfStep()

◆ MaxWallClockTime()

◆ NotifyObservers() [1/2]

◆ NotifyObservers() [2/2]

◆ NumTotalStepsTaken()

◆ NumVariables()

◆ ObservableIsA()

◆ PrecisionPreservation()

◆ PrecisionSetup()

◆ Refine() [1/2]

◆ Refine() [2/2]

◆ RefreshConditionDirection()

◆ ReinitializeInitialStepSize()

◆ RemoveObserver()

◆ ResetCountersBase()

◆ ResetCumulativeStepCounts()

◆ Set()

◆ SetInfiniteTruncation()

◆ SetInfiniteTruncationTolerance()

◆ SetMaxWallClockDuration()

◆ SetMaxWallClockTime()

◆ SetPredictor()

◆ SetStartPrecision()

◆ SetStepSize()

◆ SetSystem()

◆ SetTrackingTolerance()

◆ Setup() [1/2]

◆ Setup() [2/2]

◆ SyncSettings()