Namespaces
namespace	adaptive
namespace	amp
namespace	predict
namespace	fixed
namespace	correct

Classes
class	AMPTracker
	Functor-like class for tracking paths on a system. More...
class	Tracker
	Base tracker class for trackers offered in Bertini2. More...
struct	StepMetadata
	Metadata produced by a single predict or correct step. More...
struct	SteppingConfig
	Settings governing step-size adjustment during tracking. More...
struct	NewtonConfig
	Settings governing the Newton corrector's iteration bounds. More...
struct	TrackerConfig
	The thresholds a tracker judges a path against: close enough, and too big. More...
struct	FixedPrecisionConfig
	Settings for a fixed-precision tracker (carries the single working precision in effect). More...
struct	AdaptiveMultiplePrecisionConfig
	Holds the program parameters with respect to Adaptive Multiple Precision. More...
class	FixedPrecisionTracker
	CRTP base for trackers that work at a single fixed precision (double or fixed multiple). More...
struct	TrackerTraits
	Trait lookup mapping a tracker type to its numeric types, event-emitter type, precision config, and the type/config lists it needs. More...
class	SuccessfulPredict
	The predict part of tracking step was successful. More...
class	SuccessfulCorrect
	The correct part of a time step was successful. More...
class	PrecisionChanged
	Event emitted when the tracker's working precision changes. More...
class	PrecisionIncreased
	Precision increased during tracking. More...
class	PrecisionDecreased
	Precision decreased during tracking. More...
class	Initializing
	TrackPath is initializing the tracker. More...
class	DoublePrecisionTracker
	A tracker that works entirely in hardware double precision. More...
class	MultiplePrecisionTracker
	A tracker that works at a fixed multiprecision (set from the default precision at construction). More...
class	FirstPrecisionRecorder
	Observer that records the starting precision and the first precision increase of each track: each call to TrackPath, from its start. More...
class	MinMaxPrecisionRecorder
	Observer that records the minimum and maximum precision of each track: each call to TrackPath, from its start. More...
class	PathPrecisionRecorder
	Observer that records the precision a whole path used, across every call to TrackPath that tracks it: the track to the endgame boundary and every endgame sub-track. More...
class	PrecisionAccumulator
	Observer that collects the precision at every tracking event into a vector. More...
class	AMPPathAccumulator
	Example usage: PathAccumulator<AMPTracker> path_accumulator;. More...
class	GoryDetailLogger
	Observer that logs verbose ("gory detail") diagnostics for every tracking event. More...
class	StepFailScreenPrinter
	Observer that prints a message to standard out whenever a step fails. More...

Enumerations
enum class	PrecisionType { Fixed , FixedMultiple , Adaptive }
	The precision regime a tracker operates in: fixed double, fixed multiple, or adaptive. More...
enum class	Predictor { Constant , Euler , Heun , RK4 , HeunEuler , RKNorsett34 , RKF45 , RKCashKarp45 , RKDormandPrince56 , RKVerner67 }
	The predictor (ODE integration) method used during path tracking. More...

Functions
real_mp	MinTimeForCurrentPrecision (unsigned precision, real_mp const &time_to_go, int safety_digits=3)
	The minimum time that can be represented effectively using a given precision.
real_mp	MinStepSizeForPrecision (unsigned precision, real_mp const &time_to_go, int safety_digits=3)
	Just another name for MinTimeForCurrentPrecision.
double	ArithmeticCost (unsigned precision)
	Compute the cost function for arithmetic versus precision.
template<typename RealT>
RealT	StepsizeSatisfyingCriterionB (unsigned precision, unsigned digits_B, unsigned num_newton_iterations, unsigned predictor_order=0)
	Compute a stepsize satisfying AMP Criterion B with a given precision.
unsigned	MinDigitsForLogOfStepsize (real_mp const &log_of_stepsize, real_mp const &time_to_go, unsigned safety_digits=3)
	The minimum number of digits based on a log10 of a stepsize.
unsigned	MinDigitsForStepsizeInterval (real_mp const &min_stepsize, real_mp const &max_stepsize, real_mp const &time_to_go)
	For a given range of stepsizes under consideration, gives the minimum number of digits.
unsigned	ExtraDigitsBeforePrecisionDecrease (unsigned current_precision)
	Bertini 1's precision-decrease hysteresis margin (from B1's `AMP2_update`).
void	ApplyPrecisionDecreaseMargin (int &digits_required, unsigned current_digits, unsigned extra)
	Apply B1's precision-decrease hysteresis to one digits requirement (B1 `AMP2_update`).
template<typename RealT>
void	MinimizeTrackingCost (unsigned &new_precision, RealT &new_stepsize, unsigned min_precision, RealT const &min_stepsize, unsigned max_precision, RealT const &max_stepsize, unsigned digits_B, unsigned num_newton_iterations, unsigned predictor_order=0)
	Compute precision and stepsize minimizing the ArithmeticCost() of tracking.
bool	StepFailureIsTerminal (SuccessCode c)
	Whether a failed step leaves the tracker with no corrective action taken.
std::ostream &	operator<< (std::ostream &out, FixedPrecisionConfig const &)
	Stream-insertion for FixedPrecisionConfig (a no-op; the config carries no printable state).
std::ostream &	operator<< (std::ostream &out, AdaptiveMultiplePrecisionConfig const &AMP)
	Stream-insertion for AdaptiveMultiplePrecisionConfig, printing its bounds and safety digits.
static AdaptiveMultiplePrecisionConfig	AMPConfigFrom (System const &sys)
	Construct a ready-to-go set of AMP settings from a system.
	ADD_BERTINI_EVENT_TYPE (TrackingEvent, ConstEvent)
	Generic event for Tracking.
	ADD_BERTINI_EVENT_TYPE (SuccessfulStep, TrackingEvent)
	A successful step occurred.
	ADD_BERTINI_EVENT_TYPE (FailedStep, TrackingEvent)
	A failed step occurred.
	ADD_BERTINI_EVENT_TYPE (NewStep, TrackingEvent)
	Taking a new step – beginning of procedure for attempting to step forward.
	ADD_BERTINI_EVENT_TYPE (SingularStartPoint, TrackingEvent)
	The start point for the TrackPath call was singular.
	ADD_BERTINI_EVENT_TYPE (PrecisionEvent, TrackingEvent)
	A generic event involving precision.
	ADD_BERTINI_EVENT_TYPE (HigherPrecisionNecessary, PrecisionEvent)
	A step failed, because precision needs to increase.
	ADD_BERTINI_EVENT_TYPE (PredictorHigherPrecisionNecessary, HigherPrecisionNecessary)
	Prediction failed, because precision needs to increase.
	ADD_BERTINI_EVENT_TYPE (CorrectorHigherPrecisionNecessary, HigherPrecisionNecessary)
	Correction failed, because precision needs to increase.
	ADD_BERTINI_EVENT_TYPE (MatrixSolveFailure, PrecisionEvent)
	Linear algebra declared a failure.
	ADD_BERTINI_EVENT_TYPE (PredictorMatrixSolveFailure, MatrixSolveFailure)
	Linear algebra declared a failure, during prediction.
	ADD_BERTINI_EVENT_TYPE (FirstStepPredictorMatrixSolveFailure, MatrixSolveFailure)
	Linear algebra declared a failure, during the first step of a multi-point prediction.
	ADD_BERTINI_EVENT_TYPE (CorrectorMatrixSolveFailure, MatrixSolveFailure)
	Linear algebra declared a failure, during correction.
	ADD_BERTINI_EVENT_TYPE (StepsizeEvent, TrackingEvent)
	Stepsize is changing.
	ADD_BERTINI_EVENT_TYPE (StepsizeDecreased, StepsizeEvent)
	Stepsize decreased.
	ADD_BERTINI_EVENT_TYPE (StepsizeIncreased, StepsizeEvent)
	Stepsize increased.
	ADD_BERTINI_EVENT_TYPE (TrackingStarted, TrackingEvent)
	Made a call to TrackPath.
	ADD_BERTINI_EVENT_TYPE (TrackingEnded, TrackingEvent)
	Tracking is stopping for whatever reason.
	ADD_BERTINI_EVENT_TYPE (InfinitePathTruncation, TrackingEvent)
	Tracking terminated because the path was going to infinity.
template<typename T>
T	max (T const &a, T const &b, T const &c)
	Three-argument form of max.
template<typename T>
T	max (T const &a, T const &b, T const &c)
	Three-argument form of max.

Enumeration Type Documentation

◆ PrecisionType

enum class bertini::tracking::PrecisionType

strong

The precision regime a tracker operates in: fixed double, fixed multiple, or adaptive.

Enumerator
Fixed
FixedMultiple
Adaptive

◆ Predictor

enum class bertini::tracking::Predictor

strong

The predictor (ODE integration) method used during path tracking.

Enumerator
Constant
Euler
Heun
RK4
HeunEuler
RKNorsett34
RKF45
RKCashKarp45
RKDormandPrince56
RKVerner67

Function Documentation

◆ ADD_BERTINI_EVENT_TYPE() [1/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	CorrectorHigherPrecisionNecessary	,
		HigherPrecisionNecessary	)

Correction failed, because precision needs to increase.

◆ ADD_BERTINI_EVENT_TYPE() [2/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	CorrectorMatrixSolveFailure	,
		MatrixSolveFailure	)

Linear algebra declared a failure, during correction.

◆ ADD_BERTINI_EVENT_TYPE() [3/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	FailedStep	,
		TrackingEvent	)

A failed step occurred.

◆ ADD_BERTINI_EVENT_TYPE() [4/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	FirstStepPredictorMatrixSolveFailure	,
		MatrixSolveFailure	)

Linear algebra declared a failure, during the first step of a multi-point prediction.

◆ ADD_BERTINI_EVENT_TYPE() [5/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	HigherPrecisionNecessary	,
		PrecisionEvent	)

A step failed, because precision needs to increase.

◆ ADD_BERTINI_EVENT_TYPE() [6/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	InfinitePathTruncation	,
		TrackingEvent	)

Tracking terminated because the path was going to infinity.

◆ ADD_BERTINI_EVENT_TYPE() [7/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	MatrixSolveFailure	,
		PrecisionEvent	)

Linear algebra declared a failure.

◆ ADD_BERTINI_EVENT_TYPE() [8/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	NewStep	,
		TrackingEvent	)

Taking a new step – beginning of procedure for attempting to step forward.

◆ ADD_BERTINI_EVENT_TYPE() [9/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	PrecisionEvent	,
		TrackingEvent	)

A generic event involving precision.

◆ ADD_BERTINI_EVENT_TYPE() [10/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	PredictorHigherPrecisionNecessary	,
		HigherPrecisionNecessary	)

Prediction failed, because precision needs to increase.

◆ ADD_BERTINI_EVENT_TYPE() [11/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	PredictorMatrixSolveFailure	,
		MatrixSolveFailure	)

Linear algebra declared a failure, during prediction.

◆ ADD_BERTINI_EVENT_TYPE() [12/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	SingularStartPoint	,
		TrackingEvent	)

The start point for the TrackPath call was singular.

This is evidenced by step size shrinking too far, or running out of precision.

◆ ADD_BERTINI_EVENT_TYPE() [13/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	StepsizeDecreased	,
		StepsizeEvent	)

Stepsize decreased.

This means that the step failed, and decreasing step size was the best thing to do.

◆ ADD_BERTINI_EVENT_TYPE() [14/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	StepsizeEvent	,
		TrackingEvent	)

Stepsize is changing.

◆ ADD_BERTINI_EVENT_TYPE() [15/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	StepsizeIncreased	,
		StepsizeEvent	)

Stepsize increased.

This means steps have been successful lately.

◆ ADD_BERTINI_EVENT_TYPE() [16/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	SuccessfulStep	,
		TrackingEvent	)

A successful step occurred.

◆ ADD_BERTINI_EVENT_TYPE() [17/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	TrackingEnded	,
		TrackingEvent	)

Tracking is stopping for whatever reason.

◆ ADD_BERTINI_EVENT_TYPE() [18/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	TrackingEvent	,
		ConstEvent	)

Generic event for Tracking.

◆ ADD_BERTINI_EVENT_TYPE() [19/19]

bertini::tracking::ADD_BERTINI_EVENT_TYPE	(	TrackingStarted	,
		TrackingEvent	)

Made a call to TrackPath.

◆ AMPConfigFrom()

AdaptiveMultiplePrecisionConfig bertini::tracking::AMPConfigFrom ( System const & sys )

inlinestatic

Construct a ready-to-go set of AMP settings from a system.

See also: AdaptiveMultiplePrecisionConfig::SetBoundsFrom; AdaptiveMultiplePrecisionConfig::SetErrorBoundsFromDegreeAndCoefficient; AdaptiveMultiplePrecisionConfig::SetAMPConfigFrom

◆ ApplyPrecisionDecreaseMargin()

void bertini::tracking::ApplyPrecisionDecreaseMargin	(	int &	digits_required,
		unsigned	current_digits,
		unsigned	extra )

inline

Apply B1's precision-decrease hysteresis to one digits requirement (B1 AMP2_update).

If digits_required would permit precision to drop below the current precision, demand extra additional digits before allowing the drop, and never raise the requirement above current_digits (a requirement that suggests a decrease must not be turned into a request for an increase).

◆ ArithmeticCost()

double bertini::tracking::ArithmeticCost ( unsigned precision )

inline

Compute the cost function for arithmetic versus precision.

From [2], $C(P)$ . As currently implemented, this is $ 101.47 + 1.59 P $ , where P is the precision in decimal digits.

This function tells you the relative cost of arithmetic at a given precision, relative to std::complex<double> (the double-precision tracker's scalar type).

Calibrated by benchmarking three operations representative of path tracking (dot product / SLP evaluation, dense matvec, LU factorization+solve) using GNU MPC (complex_mp) vs std::complex<double> on modern hardware. See tuning/arithmetic_cost.cpp for the methodology and compile instructions.

The paper [2] reports $C(P) = 10.35 + 0.04 P_\mathrm{bits}$ (measured on a 2009 Opteron 250). Converting to decimal digits gives $10.35 + 0.13 P$ , which was the previous value here. The ~12x increase in the intercept on modern hardware reflects AVX2 vectorization of double-precision arithmetic that MPC cannot exploit.

Parameters

precision An integral number of decimal digits

Returns: A double indicating how expensive arithmetic at a given precision is. 1 is the base-line for double-precision.

◆ ExtraDigitsBeforePrecisionDecrease()

unsigned bertini::tracking::ExtraDigitsBeforePrecisionDecrease ( unsigned current_precision )

inline

Bertini 1's precision-decrease hysteresis margin (from B1's AMP2_update).

The number of EXTRA digits a criterion must clear below the current precision before it is allowed to actually lower the working precision. This prevents precision thrashing and replaces a consecutive-successful-steps counter with a stateless, precision-derived margin.

B1 uses (currPrec_bits/32)*2 ~ 2 digits per 32-bit precision packet (~20% slack). In b2 precision is carried in decimal digits with packet size PrecisionIncrement(), so the faithful analog is (digits/PrecisionIncrement())*2. Double precision gets no margin.

◆ max() [1/2]

template<typename T>

T bertini::max	(	T const &	a,
		T const &	b,
		T const &	c )

Three-argument form of max.

Parameters

a	Input one
b	Input two
c	Input three

◆ max() [2/2]

template<typename T>

T bertini::max	(	T const &	a,
		T const &	b,
		T const &	c )

Three-argument form of max.

Parameters

a	Input one
b	Input two
c	Input three

◆ MinDigitsForLogOfStepsize()

unsigned bertini::tracking::MinDigitsForLogOfStepsize	(	real_mp const &	log_of_stepsize,
		real_mp const &	time_to_go,
		unsigned	safety_digits = 3 )

inline

The minimum number of digits based on a log10 of a stepsize.

Parameters

log_of_stepsize	log10 of a stepsize
time_to_go	How much time you have left to track.
safety_digits	A buffer of extra digits to use, over the computed min. Yes, this is added in, in this function.

Returns: An integral number of necessary digits to use

◆ MinDigitsForStepsizeInterval()

unsigned bertini::tracking::MinDigitsForStepsizeInterval	(	real_mp const &	min_stepsize,
		real_mp const &	max_stepsize,
		real_mp const &	time_to_go )

inline

For a given range of stepsizes under consideration, gives the minimum number of digits.

Parameters

min_stepsize	The smallest stepsize under consideration
max_stepsize	The largest stepsize under consideration
time_to_go	How much time is left to track.

Returns: The min number of digits.

This function assumes you are going to time=0, or that you have taken care of that difference. That is, time_to_go should be a duration, not the current time, unless you are tracking to t=0, in which case current time is the duration left to go. Dig it?

◆ MinimizeTrackingCost()

template<typename RealT>

void bertini::tracking::MinimizeTrackingCost	(	unsigned &	new_precision,
		RealT &	new_stepsize,
		unsigned	min_precision,
		RealT const &	min_stepsize,
		unsigned	max_precision,
		RealT const &	max_stepsize,
		unsigned	digits_B,
		unsigned	num_newton_iterations,
		unsigned	predictor_order = 0 )

Compute precision and stepsize minimizing the ArithmeticCost() of tracking.

For a given range of precisions, an old stepsize, and a maximum stepsize, the Cost of tracking is computed, and a minimizer found.

This function is used in the AMPTracker tracking loop, both in case of successful steps and in Criterion errors.

Parameters

[out]	new_precision	The minimizing precision.
[out]	new_stepsize	The minimizing stepsize.
[in]	min_precision	The minimum considered precision.
[in]	min_stepsize	The minimum permitted stepsize.
[in]	max_precision	The maximum considered precision.
[in]	max_stepsize	The maximum permitted stepsize.
[in]	digits_B	The number of digits required, according to CriterionB from [1], [2]
[in]	num_newton_iterations	The number of allowed Newton corrector iterations.
[in]	predictor_order	The order of the predictor being used. This is the order itself, not the order of the error estimate.

See also: ArithmeticCost

◆ MinStepSizeForPrecision()

real_mp bertini::tracking::MinStepSizeForPrecision	(	unsigned	precision,
		real_mp const &	time_to_go,
		int	safety_digits = 3 )

inline

Just another name for MinTimeForCurrentPrecision.

Parameters

precision	The number of digits you want to use
time_to_go	The duration of remaining time to track
safety_digits	A buffer of extra digits to use

Returns: The smallest permissible stepsize

◆ MinTimeForCurrentPrecision()

real_mp bertini::tracking::MinTimeForCurrentPrecision	(	unsigned	precision,
		real_mp const &	time_to_go,
		int	safety_digits = 3 )

inline

The minimum time that can be represented effectively using a given precision.

Parameters

precision	The number of digits you want to use
time_to_go	The duration of remaining time to track
safety_digits	A buffer of extra digits to use

Returns: The smallest permissible stepsize

◆ operator<<() [1/2]

std::ostream & bertini::tracking::operator<<	(	std::ostream &	out,
		AdaptiveMultiplePrecisionConfig const &	AMP )

inline

Stream-insertion for AdaptiveMultiplePrecisionConfig, printing its bounds and safety digits.

◆ operator<<() [2/2]

std::ostream & bertini::tracking::operator<<	(	std::ostream &	out,
		FixedPrecisionConfig const &	)

inline

Stream-insertion for FixedPrecisionConfig (a no-op; the config carries no printable state).

◆ StepFailureIsTerminal()

bool bertini::tracking::StepFailureIsTerminal ( SuccessCode c )

inline

Whether a failed step leaves the tracker with no corrective action taken.

The stepping loop answers an ordinary failed step by adjusting precision and/or stepsize and trying again, so the retry differs from the attempt that failed. A few outcomes admit no such adjustment: the tracker's state is left exactly as it was, and retrying would repeat the identical step forever. Those outcomes are terminal – the path must fail with that code instead of being retried.

Currently the sole member is FailedToSelectPrecisionAndStepsize, which the AMP adjusters report when MinimizeTrackingCost finds no valid (precision, stepsize) pair anywhere in the allowed window. It assigns neither, so current_precision_ and current_stepsize_ survive the failure unchanged.

Parameters

c	The code returned by a tracker iteration.

Returns: True if the tracking loop must stop rather than retry.

See also: Tracker::TrackPath

◆ StepsizeSatisfyingCriterionB()

template<typename RealT>

RealT bertini::tracking::StepsizeSatisfyingCriterionB	(	unsigned	precision,
		unsigned	digits_B,
		unsigned	num_newton_iterations,
		unsigned	predictor_order = 0 )

inline

Compute a stepsize satisfying AMP Criterion B with a given precision.

Parameters

precision	The current working precision
digits_B	The number of digits from Criterion B
num_newton_iterations	The number of remaining newton iterations allowed in the correction
predictor_order	The order of the predictor

Returns: The stepsize

Namespaces

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ PrecisionType

◆ Predictor

Function Documentation

◆ ADD_BERTINI_EVENT_TYPE() [1/19]

◆ ADD_BERTINI_EVENT_TYPE() [2/19]

◆ ADD_BERTINI_EVENT_TYPE() [3/19]

◆ ADD_BERTINI_EVENT_TYPE() [4/19]

◆ ADD_BERTINI_EVENT_TYPE() [5/19]

◆ ADD_BERTINI_EVENT_TYPE() [6/19]

◆ ADD_BERTINI_EVENT_TYPE() [7/19]

◆ ADD_BERTINI_EVENT_TYPE() [8/19]

◆ ADD_BERTINI_EVENT_TYPE() [9/19]

◆ ADD_BERTINI_EVENT_TYPE() [10/19]

◆ ADD_BERTINI_EVENT_TYPE() [11/19]

◆ ADD_BERTINI_EVENT_TYPE() [12/19]

◆ ADD_BERTINI_EVENT_TYPE() [13/19]

◆ ADD_BERTINI_EVENT_TYPE() [14/19]

◆ ADD_BERTINI_EVENT_TYPE() [15/19]

◆ ADD_BERTINI_EVENT_TYPE() [16/19]

◆ ADD_BERTINI_EVENT_TYPE() [17/19]

◆ ADD_BERTINI_EVENT_TYPE() [18/19]

◆ ADD_BERTINI_EVENT_TYPE() [19/19]

◆ AMPConfigFrom()

◆ ApplyPrecisionDecreaseMargin()

◆ ArithmeticCost()

◆ ExtraDigitsBeforePrecisionDecrease()

◆ max() [1/2]

◆ max() [2/2]

◆ MinDigitsForLogOfStepsize()

◆ MinDigitsForStepsizeInterval()

◆ MinimizeTrackingCost()

◆ MinStepSizeForPrecision()

◆ MinTimeForCurrentPrecision()

◆ operator<<() [1/2]

◆ operator<<() [2/2]

◆ StepFailureIsTerminal()

◆ StepsizeSatisfyingCriterionB()