Class used to finish tracking paths during Homotopy Continuation. More...

#include <cauchy.hpp>

Inheritance diagram for bertini::endgame::CauchyEndgame< PrecT >:

Collaboration diagram for bertini::endgame::CauchyEndgame< PrecT >:

Public Types
using	BaseEGT = EndgameBase<CauchyEndgame<PrecT>, PrecT>
	The base endgame type.
using	FinalEGT = CauchyEndgame<PrecT>
	The final (derived) endgame type.
using	TrackerType = typename PrecT::TrackerType
	The path-tracker type.
using	BaseComplexT = typename tracking::TrackerTraits<TrackerType>::BaseComplexT
	The complex number type.
using	BaseRealT = typename tracking::TrackerTraits<TrackerType>::BaseRealT
	The real number type.
using	EmitterType = CauchyEndgame<PrecT>
	The event-emitter type.
using	Config
	The configuration bundle this endgame reads, public so that generic machinery which works in terms of an object's configs – the Python bindings' ConfiguredVisitor, which needs Config::UsedConfigs – can serve an endgame the same way it serves a tracker or a solver.
using	UsedConfigs = TypeList<Ts...>
	The list of configuration types this object holds.

Public Member Functions
template<typename ComplexT>
void	ClearTimesAndSamples ()
	Function that clears all samples and times from data members for the Cauchy endgame.
template<typename ComplexT>
void	SetPSEGTimes (TimeCont< ComplexT > pseg_times_to_set)
	Setter for the time values for the power series approximation of the Cauchy endgame.
template<typename ComplexT>
TimeCont< ComplexT > &	GetPSEGTimes ()
	Getter for the time values for the power series approximation of the Cauchy endgame.
template<typename ComplexT>
const TimeCont< ComplexT > &	GetPSEGTimes () const
	Const overload returning the power-series time values.
template<typename ComplexT>
void	SetPSEGSamples (SampCont< ComplexT > const &pseg_samples_to_set)
	Setter for the space values for the power series approximation of the Cauchy endgame.
template<typename ComplexT>
SampCont< ComplexT > &	GetPSEGSamples ()
	Getter for the space values for the power series approximation of the Cauchy endgame.
template<typename ComplexT>
const SampCont< ComplexT > &	GetPSEGSamples () const
	Const overload returning the power-series sample values.
template<typename ComplexT>
void	SetCauchySamples (SampCont< ComplexT > const &cauchy_samples_to_set)
	Setter for the space values for the Cauchy endgame.
template<typename ComplexT>
SampCont< ComplexT > &	GetCauchySamples ()
	Getter for the space values for the Cauchy endgame.
template<typename ComplexT>
const SampCont< ComplexT > &	GetCauchySamples () const
	Const overload returning the Cauchy sample values.
template<typename ComplexT>
void	SetCauchyTimes (TimeCont< ComplexT > const &cauchy_times_to_set)
	Setter for the time values for the Cauchy endgame.
template<typename ComplexT>
TimeCont< ComplexT > &	GetCauchyTimes ()
	Getter for the time values for the Cauchy endgame.
template<typename ComplexT>
const TimeCont< ComplexT > &	GetCauchyTimes () const
	Const overload returning the Cauchy time values.
const BCT &	LatestTimeImpl () const
void	SetCauchySettings (CauchyConfig const &new_cauchy_settings)
	Setter for the specific settings in tracking_conifg.hpp under Cauchy.
const auto &	GetCauchySettings () const
	Getter for the specific settings in tracking_conifg.hpp under Cauchy.
	CauchyEndgame (TrackerType const &tr, const ConfigsAsTuple &settings)
	Construct the Cauchy endgame for a tracker, with its configuration as a tuple.
template<typename... Ts>
	CauchyEndgame (TrackerType const &tr, const Ts &... ts)
	Construct the Cauchy endgame for a tracker, with configs given in any order.
virtual	~CauchyEndgame ()=default
void	ValidateConfigs ()
	Validate the endgame configuration (e.g. require >= 3 sample points for circle tracking).
template<typename ComplexT>
SuccessCode	CircleTrack (ComplexT const &target_time)
	Function to track around the origin.
template<typename ComplexT>
void	AddToCauchyData (ComplexT const &time, Vec< ComplexT > const &sample)
	Append a (time, sample) pair to the Cauchy data containers.
template<typename ComplexT>
void	AddToPSData (ComplexT const &time, Vec< ComplexT > const &sample)
	Append a (time, sample) pair to the power-series data containers.
template<typename ComplexT>
bool	CheckClosedLoop ()
	Function that determines if we have closed a loop after calling CircleTrack().
template<typename ComplexT>
bool	RatioEGOperatingZoneTest (ComplexT const &target_time) const
	After we have used CircleTrack and have successfully closed the loop using CheckClosedLoop we need to check the maximum and minimum norms of the samples collected.
template<typename ComplexT>
SuccessCode	InitialCauchyLoops (ComplexT const &target_time)
template<typename ComplexT>
void	RotateOntoPS (ComplexT const &next_time, Vec< ComplexT > const &next_sample)
	Shift the power-series sample window forward by one (time, sample) pair.
template<typename ComplexT>
void	ClearAndSeedCauchyData ()
	Clear the Cauchy data and re-seed it from the current power-series samples.
template<typename ComplexT>
SuccessCode	InitialApproximation (ComplexT const &start_time, Vec< ComplexT > const &start_point, ComplexT const &target_time, Vec< ComplexT > &approximation)
template<typename ComplexT>
SuccessCode	GetIntoEGZone (ComplexT const &start_time, Vec< ComplexT > const &start_point, ComplexT const &target_time)
	Track from the boundary inward until the path enters the endgame (Cauchy) operating zone.
template<typename ComplexT>
SuccessCode	ComputeCauchyApproximationOfXAtT0 (Vec< ComplexT > &result)
	Function that computes the mean of the samples that were collected while tracking around the origin.
template<typename ComplexT>
NumErrorT	MinDehomNormOverLoopSamples () const
	The FLOOR of the current Cauchy loop: the smallest dehomogenized infinity-norm over the loop samples.
template<typename ComplexT>
SuccessCode	ComputeCauchySamples (ComplexT const &target_time)
	Collects samples while tracking around the target time, until we close the loop, or exceed the limit on # of loops.
template<typename ComplexT>
SuccessCode	AdvanceTime (ComplexT const &target_time)
	Advances time, marching toward the target time.
template<typename ComplexT>
NumErrorT	PoleComponentMass () const
	The pole-component mass of the current Cauchy loop: the endgame operating-zone measurement.
template<typename Dummy = void>
NumErrorT	PoleComponentMassAMP () const
	PoleComponentMass read from whichever numeric lane the adaptive (double-first) endgame is currently computing in.
bool	PoleMassSignificant (NumErrorT mass, NumErrorT approx_scale) const
	Is a pole-component mass SIGNIFICANT, i.e.
template<typename ComplexT>
SuccessCode	RunImpl (ComplexT const &start_time, Vec< ComplexT > const &start_point, ComplexT const &target_time)
	Primary function that runs the Cauchy endgame.
template<typename Dummy = void>
SuccessCode	RunImplAMP (BCT const &start_time, Vec< BCT > const &start_point, BCT const &target_time)
	Run the Cauchy endgame via the double-first adaptive-numeric-type driver, migrating up to mpfr only on tracker escalation.
template<typename ComplexT>
SuccessCode	RunInitSegmentT (ComplexT const &start_time, Vec< ComplexT > const &start_point, ComplexT const &target_time)
	Run the initialization segment (seed the PSEG window and reach the EG zone) in a given numeric type.
template<typename Dummy = void>
SuccessCode	ComputeCauchyApproxAMP ()
	Compute the Cauchy mean (extrapolation) at the active numeric type, migrating-and-retrying in mpfr on escalation.
template<typename Dummy = void>
SuccessCode	AdvanceTimeAMP (BCT const &target_time)
	Advance time at the active numeric type, migrating-and-retrying in mpfr on escalation.
template<typename Dummy = void>
SuccessCode	ComputeCauchySamplesAMP (BCT const &target_time)
	Build a closed Cauchy loop's samples at the active numeric type, migrating-and-retrying in mpfr on escalation.
template<typename Dummy = void>
void	MigrateContainersToPrecision (unsigned newprec)
	Widen this flavor's Cauchy containers from the complex_dbl slot up to complex_mp at the new precision.
auto	ComputeCOverK (SampCont< ComplexT > const &samples) const -> typename Eigen::NumTraits< ComplexT >::Real
	An estimate of c/k from the three most recent geometric samples.
bool	CheckForCOverKStabilization (std::deque< T > const &c_over_k_array) const
	Have the last few c/k estimates settled to within the user's threshold?
void	SetBoundaryTime (BCT const &t)
	Set the endgame boundary (start) time.
void	SetTargetTime (BCT const &t)
	Set the final target time.
BCT const &	BoundaryTime () const
BCT const &	TargetTime () const
SuccessCode	Run (Vec< BCT > const &start_point)
	Run the endgame from the stored boundary time to the stored target time.
void	EmitComputedSample (Vec< ComplexT > const &sample, ComplexT const &time)
	Announce a completed sample point on the path, as a ComputedSamplePoint.
SuccessCode	RefineAllSamples (SampCont< ComplexT > &samples, TimeCont< ComplexT > &times)
	Refine every sample point to the endgame's refinement tolerance.
SuccessCode	RefineSample (Vec< ComplexT > &result, Vec< ComplexT > const &current_sample, ComplexT const &current_time, NumErrorT tol, unsigned max_iterations) const
	A function passed off to the precision-specific endgame part.
SuccessCode	EndgameTrackPath (Vec< ComplexT > &result, ComplexT const &start_time, ComplexT const &end_time, Vec< ComplexT > const &start_point) const
	Track through the tracker, adapting at the numeric-type boundary.
SuccessCode	EscalateAndMigrate (unsigned guard)
	Raise the endgame to the next precision and migrate the containers' complex_dbl slot up to complex_mp when the tracker's authority escalates.
const auto &	EndgameSettings () const
	This function is inferior to the templated Get<ConfigT> function provided.
const auto &	SecuritySettings () const
bool	BeyondSecurityMaxNorm (RealT const &norm) const
unsigned	CycleNumber () const
void	CycleNumber (unsigned c)
	Set the cycle number.
void	IncrementCycleNumber (unsigned inc)
	Increase the cycle number by the given increment.
const auto &	FinalTolerance () const
	Get the final tolerance to which we are tracking the solution.
void	SetFinalTolerance (NumErrorT const &ft)
	Setter for the final tolerance.
const Vec< ComplexT > &	FinalApproximation () const
	Get the most-recent approximation.
const Vec< ComplexT > &	PreviousApproximation () const
	Get the second-most-recent approximation.
NumErrorT	ApproximateError () const
	Get the most recent accuracy estimate.
const BCT &	LatestTime () const
	Get the latest time at which a point on the path was computed.
SuccessCode	ComputeInitialSamples (const ComplexT &start_time, const ComplexT &target_time, const Vec< ComplexT > &x_endgame_start, TimeCont< ComplexT > &times, SampCont< ComplexT > &samples)
	Get the system being tracked on, which is referred to by the tracker.
template<typename T, typename = typename std::enable_if<IsTemplateParameter<T,Ts...>::value>::type>
const T &	Get () const
	Get the held configuration object of type T.
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.
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.

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

Protected Types
using	TupleOfTimes = typename BaseEGT::TupleOfTimes
	A tuple of time containers, one per precision.
using	TupleOfSamps = typename BaseEGT::TupleOfSamps
	A tuple of sample containers, one per precision.
using	TupOfVec = typename BaseEGT::TupOfVec
	A tuple of vector containers, one per precision.
using	BCT = BaseComplexT
	The complex number type.
using	BRT = BaseRealT
	The real number type.
using	Configs = typename AlgoTraits<FinalEGT>::NeededConfigs
	The configuration bundle (Configured base).
using	ConfigsAsTuple = typename Configs::ToTuple
	The configuration structs as a tuple.
using	Configured
	The Configured base type.
using	NeededTypes
	Arithmetic types this endgame may compute in (sourced from the tracker).
using	TupOfReal
	A tuple of real values, one per numeric type.

Protected Member Functions
void	RefreshCOverKProbe (unsigned size) const
	Draw the c/k probe direction for a run.
Vec< ComplexT > const &	GetCOverKProbe (unsigned size, unsigned prec) const
	The fixed random direction the c/k estimate is projected along.
const CauchyEndgame< PrecT > &	AsFlavor () const
	convert the base endgame into the derived type.
CauchyEndgame< PrecT > &	AsFlavor ()
	Non-const version of AsFlavor.
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
TupleOfTimes	pseg_times_
	A deque of times that are specifically used to compute the power series approximation for the Cauchy endgame.
TupleOfSamps	pseg_samples_
	A deque of samples that are in correspondence with the pseg_times_.
TupleOfTimes	cauchy_times_
	A deque of times that are collected by CircleTrack.
TupleOfSamps	cauchy_samples_
	A deque of samples collected by CircleTrack.
BCT	latest_time_cache_
	Scratch so LatestTimeImpl can return a BCT reference while in the double fast lane.
Vec< BCT >	final_approximation_
	The latest computed approximation of the endpoint.
Vec< BCT >	previous_approximation_
	The previous approximation of the endpoint.
unsigned int	cycle_number_
	The current estimate of the cycle number.
NumErrorT	approximate_error_
	The error estimate between successive approximations.
BCT	start_time_
	The endgame boundary time; set via SetBoundaryTime().
BCT	target_time_
	The final target time (default 0); set via SetTargetTime().
Vec< complex_dbl >	c_over_k_probe_as_drawn_
	The random direction the c/k estimate is projected along, as drawn: in double precision, so that it is exact in every lane and at every multiple precision.
TupOfVec	c_over_k_probe_
	The c/k probe in each numeric type the endgame computes in: exact conversions of c_over_k_probe_as_drawn_, re-derived when their size or precision is wrong, never rounded.

Detailed Description

template<typename PrecT>
class bertini::endgame::CauchyEndgame< PrecT >

Class used to finish tracking paths during Homotopy Continuation.

Explanation

The bertini::CauchyEngame class enables us to finish tracking on possibly singular paths on an arbitrary square homotopy. The intended usage is to:

Create a system, tracker, and instantiate some settings.
Using the tracker created track to the engame boundary.
Create a CauchyEndgame, associating it to the system you are going to solve or track on.
For each path being tracked send the CauchyEndgame the time value and other variable values at that time.
The CauchyEndgame, if successful, will store the target systems solution at $t = 0$.

Example Usage

Below we demonstrate a basic usage of the CauchyEndgame class to find the singularity at $t = 0$. The pattern is as described above: create an instance of the class, feeding it the system to be used, and the endgame boundary time and other variable values at the endgame boundary.

using namespace bertini::tracking;
using RealT = tracking::TrackerTraits<TrackerType>::BaseRealT; // Real types
using ComplexT = tracking::TrackerTraits<TrackerType>::BaseComplexT; Complex types
 
// 1. Define the polynomial system that we wish to solve.
System target_sys;
Var x = Variable::Make("x"), t = Variable::Make("t"), y = Variable::Make("y");
 
VariableGroup vars{x,y};
target_sys.AddVariableGroup(vars);
 
target_sys.AddFunction((pow(x-1,3));
target_sys.AddFunction((pow(y-1,2));
 
// 1b. Homogenize and patch the polynomial system to work over projective space.
sys.Homogenize();
sys.AutoPatch();
 
// 2. Create a start system, for us we will use a total degree start system.
auto TD_start_sys = bertini::start_system::TotalDegreeLinearProduct(target_sys);
 
// 2b. Creating homotopy between the start system and system we wish to solve.
auto my_homotopy = (1-t)*target_sys + t*TD_start_sys*Rational::Rand(); //the random number is our gamma for a random path between t = 1 and t = 0.
my_homotopy.AddPathVariable(t);
 
//Sets up configuration settings for our particular system.
auto precision_config = PrecisionConfig(my_homotopy);
 
 
// 3. Creating a tracker. For us this is an AMPTracker.
AMPTracker tracker(my_homotopy);
 
//Tracker setup of settings.
SteppingConfig<RealT> stepping_preferences;
stepping_preferences.initial_step_size = RealT(1)/RealT(5);// change a stepping preference
NewtonConfig newton_preferences;
tracker.Setup(TestedPredictor,
            RealFromString("1e-6"),
            RealFromString("1e5"),
    stepping_preferences,
    newton_preferences);
tracker.PrecisionSetup(precision_config);
 
//We start at t = 1, and will stop at t = 0.1 before starting the endgames.
ComplexT t_start(1), t_endgame_boundary(0.1);
 
//This will hold our solutions at t = 0.1
std::vector<Vec<ComplexT> > my_homotopy_solutions_at_endgame_boundary;
 
// result holds the value we track to at 0.1, and tracking success will report if we are unsucessful.
Vec<ComplexT> result;
 
//4. Track all points to 0.1
for (unsigned ii = 0; ii < TD_start_sys.NumStartPoints(); ++ii)
{
    DefaultPrecision(ambient_precision);
    auto start_point = TD_start_sys.StartPoint<ComplexT>(ii);
 
    tracker.TrackPath(result,t_start,t_endgame_boundary,start_point);
 
    my_homotopy_solutions_at_endgame_boundary.push_back(result);
}
 
 
//Settings for the endgames.
 
config::Tolerances<RealT> tolerances;
 
CauchyConfig<RealT> cauchy_settings;
cauchy_settings.fail_safe_maximum_cycle_number = 6;
 
 
// 5. Create a cauchy endgame, and use them to get the soutions at t = 0.
EndgameSelector<TrackerType>::Cauchy my_cauchy_endgame(tracker,cauchy_settings,tolerances);
 
 
std::vector<Vec<ComplexT> > my_homotopy_solutions;
 
std::vector<Vec<ComplexT> > my_homotopy_divergent_paths;
 
for(auto s : my_homotopy_solutions_at_endgame_boundary)
{
    SuccessCode endgame_success = my_cauchy_endgame.Run(t_endgame_boundary,s);
 
    if(endgame_success == SuccessCode::Success)
    {
        my_homotopy_solutions.push_back(my_homotopy.DehomogenizePoint(my_endgame.FinalApproximation<ComplexT>()));
    }
    else
    {
        my_homotopy_divergent_paths.push_back(my_homotopy.DehomogenizePoint(my_endgame.FinalApproximation<ComplexT>()));
    }
}

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

Testing

Test suite driving this class: endgames_test. File: test/endgames/generic_cauchy_test.hpp File: test/endgames/amp_cauchy_test.cpp File: test/endgames/fixed_double_cauchy_test.cpp FIle: test/endgames/fixed_multiple_cauchy_test.cpp

Member Typedef Documentation

◆ BaseComplexT

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::BaseComplexT = typename tracking::TrackerTraits<TrackerType>::BaseComplexT

The complex number type.

◆ BaseEGT

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::BaseEGT = EndgameBase<CauchyEndgame<PrecT>, PrecT>

The base endgame type.

◆ BaseRealT

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::BaseRealT = typename tracking::TrackerTraits<TrackerType>::BaseRealT

The real number type.

◆ BCT

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::BCT = BaseComplexT

protected

The complex number type.

◆ BRT

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::BRT = BaseRealT

protected

The real number type.

◆ Config

using bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::Config

inherited

The configuration bundle this endgame reads, public so that generic machinery which works in terms of an object's configs – the Python bindings' ConfiguredVisitor, which needs Config::UsedConfigs – can serve an endgame the same way it serves a tracker or a solver.

The same type as the protected Configured alias below.

◆ Configs

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::Configs = typename AlgoTraits<FinalEGT>::NeededConfigs

protected

The configuration bundle (Configured base).

◆ ConfigsAsTuple

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::ConfigsAsTuple = typename Configs::ToTuple

protected

The configuration structs as a tuple.

◆ Configured

using bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::Configured

protectedinherited

The Configured base type.

◆ EmitterType

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::EmitterType = CauchyEndgame<PrecT>

The event-emitter type.

◆ FinalEGT

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::FinalEGT = CauchyEndgame<PrecT>

The final (derived) endgame type.

◆ NeededTypes

using bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::NeededTypes

protectedinherited

Arithmetic types this endgame may compute in (sourced from the tracker).

◆ TrackerType

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::TrackerType = typename PrecT::TrackerType

The path-tracker type.

◆ TupleOfSamps

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::TupleOfSamps = typename BaseEGT::TupleOfSamps

protected

A tuple of sample containers, one per precision.

◆ TupleOfTimes

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::TupleOfTimes = typename BaseEGT::TupleOfTimes

protected

A tuple of time containers, one per precision.

◆ TupOfReal

using bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::TupOfReal

protectedinherited

A tuple of real values, one per numeric type.

◆ TupOfVec

template<typename PrecT>

using bertini::endgame::CauchyEndgame< PrecT >::TupOfVec = typename BaseEGT::TupOfVec

protected

A tuple of vector containers, one per precision.

◆ UsedConfigs

template<typename ... Ts>

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

inherited

The list of configuration types this object holds.

Constructor & Destructor Documentation

◆ CauchyEndgame() [1/2]

template<typename PrecT>

bertini::endgame::CauchyEndgame< PrecT >::CauchyEndgame	(	TrackerType const &	tr,
		const ConfigsAsTuple &	settings )

inlineexplicit

Construct the Cauchy endgame for a tracker, with its configuration as a tuple.

◆ CauchyEndgame() [2/2]

template<typename PrecT>

template<typename... Ts>

bertini::endgame::CauchyEndgame< PrecT >::CauchyEndgame	(	TrackerType const &	tr,
		const Ts &...	ts )

inline

Construct the Cauchy endgame for a tracker, with configs given in any order.

◆ ~CauchyEndgame()

template<typename PrecT>

virtual bertini::endgame::CauchyEndgame< PrecT >::~CauchyEndgame ( )

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

◆ AddToCauchyData()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::AddToCauchyData	(	ComplexT const &	time,
		Vec< ComplexT > const &	sample )

inline

Append a (time, sample) pair to the Cauchy data containers.

◆ AddToPSData()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::AddToPSData	(	ComplexT const &	time,
		Vec< ComplexT > const &	sample )

inline

Append a (time, sample) pair to the power-series data containers.

◆ AdvanceTime()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::AdvanceTime ( ComplexT const & target_time )

inline

Advances time, marching toward the target time.

Works from the most recent time-sample pair stored in the power series data.

If the distance between next and target is too small, dies (returns not success).

◆ AdvanceTimeAMP()

template<typename PrecT>

template<typename Dummy = void>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::AdvanceTimeAMP ( BCT const & target_time )

inline

Advance time at the active numeric type, migrating-and-retrying in mpfr on escalation.

◆ ApproximateError()

NumErrorT bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::ApproximateError ( ) const

inlineinherited

Get the most recent accuracy estimate.

◆ AsFlavor() [1/2]

CauchyEndgame< PrecT > & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::AsFlavor ( )

inlineprotectedinherited

Non-const version of AsFlavor.

◆ AsFlavor() [2/2]

const CauchyEndgame< PrecT > & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::AsFlavor ( ) const

inlineprotectedinherited

convert the base endgame into the derived type.

This enables the CRPT as used by the endgames

◆ BeyondSecurityMaxNorm()

bool bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::BeyondSecurityMaxNorm ( RealT const & norm ) const

inlineinherited

Returns: True when a dehomogenized norm calls for security truncation: above max_norm, or NaN. NaN must count as beyond – every IEEE comparison against NaN is false, so a plain norm > max_norm valve is BLIND to exactly the paths most likely to be diverging (a NaN dehom norm means the homogenizing coordinate vanished: the path is at infinity).

◆ BoundaryTime()

BCT const & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::BoundaryTime ( ) const

inlineinherited

Returns: The endgame boundary (start) time.

◆ CheckClosedLoop()

template<typename PrecT>

template<typename ComplexT>

bool bertini::endgame::CauchyEndgame< PrecT >::CheckClosedLoop ( )

inline

Function that determines if we have closed a loop after calling CircleTrack().

Input:

None: all data needed are class data members

Output:

true: if we have closed the loop false: if we have not closed the loop

Details:

Template Parameters

ComplexT The complex number type

◆ CheckForCOverKStabilization()

bool bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::CheckForCOverKStabilization ( std::deque< T > const & c_over_k_array ) const

inlineinherited

Have the last few c/k estimates settled to within the user's threshold?

The operating-zone test: consecutive estimates agreeing to within minimum_for_c_over_k_stabilization, for num_needed_for_stabilization of them, is taken as the cycle-number estimate having settled. Both endgames use this and mean the same thing by it (b2#402).

Template Parameters

T	The element type of the estimate window; real or complex, since only its magnitude is read (the Cauchy endgame keeps reals, the power series endgame keeps its numeric type).

Parameters

c_over_k_array The estimates so far, oldest first.

Returns: Whether they have settled.

◆ CircleTrack()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::CircleTrack ( ComplexT const & target_time )

inline

Function to track around the origin.

Input:

starting_time: time value that we start from to track around the origin target_time: the time value that we are centering out loops around, default is t = 0 starting_sample: an approximate solution of the homotopy at t = starting_time

Output:

SuccessCode: This reports back if we were successful in advancing time.

Details:

Template Parameters

ComplexT The complex number type. Depeding on the number of samples points, we make a polgon around the origin with that many vertices. This function should be called the same number of times as paths converging to the solution we are approximating.

◆ ClearAndSeedCauchyData()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::ClearAndSeedCauchyData ( )

inline

Clear the Cauchy data and re-seed it from the current power-series samples.

◆ ClearTimesAndSamples()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::ClearTimesAndSamples ( )

inline

Function that clears all samples and times from data members for the Cauchy endgame.

◆ ComputeCauchyApproxAMP()

template<typename PrecT>

template<typename Dummy = void>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::ComputeCauchyApproxAMP ( )

inline

Compute the Cauchy mean (extrapolation) at the active numeric type, migrating-and-retrying in mpfr on escalation.

◆ ComputeCauchyApproximationOfXAtT0()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::ComputeCauchyApproximationOfXAtT0 ( Vec< ComplexT > & result )

inline

Function that computes the mean of the samples that were collected while tracking around the origin.

This value is the approximation of the value at the origin.

Input:

result: This vector, passed by reference, holds the approximation that we calculate.

Output:

SuccessCode deeming if we were suceessful, or if we encountered an error.

Details:

Template Parameters

ComplexT The complex number type. We can compute the Cauchy Integral Formula in this particular instance by computing the mean of the samples we have collected around the origin.

/todo i believe this function works incorrectly when the target time is not 0. hence, the target time needs to be passed in.

◆ ComputeCauchySamples()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::ComputeCauchySamples ( ComplexT const & target_time )

inline

Collects samples while tracking around the target time, until we close the loop, or exceed the limit on # of loops.

Input:

the target time, at which we are computing roots of a system

Output:

SuccessCode deeming if we were able to collect all samples around the origin, or if we encounted an error at some point.

Details:

the starting time and point for this routine are the most recent power series samples.

Template Parameters

ComplexT The complex number type. This function populates the deque cauchy_samples and cauchy_times. These are data members of the class and are not passed in. This function will continue to call CircleTrack until we have closed the loop.

◆ ComputeCauchySamplesAMP()

template<typename PrecT>

template<typename Dummy = void>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::ComputeCauchySamplesAMP ( BCT const & target_time )

inline

Build a closed Cauchy loop's samples at the active numeric type, migrating-and-retrying in mpfr on escalation.

◆ ComputeCOverK()

auto bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::ComputeCOverK ( SampCont< ComplexT > const & samples ) const->typenameEigen::NumTraits< ComplexT >::Real

inlineinherited

An estimate of c/k from the three most recent geometric samples.

Assumes the path is in the endgame operating zone, where the Puiseux asymptotics dominate; as the cycle-number estimate settles, successive values of this estimate settle with it, which is what CheckForCOverKStabilization watches for.

It reads only the geometrically-spaced approach samples and the fixed probe, which every endgame flavor maintains – the power series endgame's samples_ and the Cauchy endgame's pseg_samples_ are the same window under two names – so it belongs here rather than to either flavor (b2#402). Consult page 53 of [4] for the heuristic.

Template Parameters

ComplexT The complex number type.

Parameters

samples The geometric approach samples; the first three are used.

Returns: The estimate, never below 1.

◆ ComputeInitialSamples()

SuccessCode bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::ComputeInitialSamples	(	const ComplexT &	start_time,
		const ComplexT &	target_time,
		const Vec< ComplexT > &	x_endgame_start,
		TimeCont< ComplexT > &	times,
		SampCont< ComplexT > &	samples )

inlineinherited

Get the system being tracked on, which is referred to by the tracker.

Populates time and space samples so that we are ready to start the endgame.

Input

    start_time: is the time when we start the endgame process usually this is .1
    x_endgame_start: is the space value at start_time
    times: a deque of time values. These values will be templated to be ComplexT
    samples: a deque of sample values that are in correspondence with the values in times. These values will be vectors with entries of ComplexT.

Output

SuccessCode indicating whether tracking to all samples was successful.

Details

The first sample will be (x_endgame_start) and the first time is start_time.
From there we do a geometric progression using the sample factor (which by default is 1/2).
Hence, next_time = start_time * sample_factor.
We track then to the next_time and construct the next_sample.

Parameters

start_time	The time value at which we start the endgame.
target_time	The time value that we are trying to find a solution to.
x_endgame_start	The current space point at start_time.
times	A deque that will hold all the time values of the samples we are going to use to start the endgame.
samples	a deque that will hold all the samples corresponding to the time values in times.

Template Parameters

ComplexT The complex number type.

◆ CycleNumber() [1/2]

unsigned bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::CycleNumber ( ) const

inlineinherited

Returns: The current cycle number.

◆ CycleNumber() [2/2]

void bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::CycleNumber ( unsigned c )

inlineinherited

Set the cycle number.

◆ EmitComputedSample()

void bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::EmitComputedSample	(	Vec< ComplexT > const &	sample,
		ComplexT const &	time )

inlineinherited

Announce a completed sample point on the path, as a ComputedSamplePoint.

The payload rides at BaseComplexT, so the adaptive endgame's hardware-double fast lane must convert – and only pays for that when something is actually observing. Shared by the initial window here and by each flavor's time advance, so the conversion rule lives in one place.

Parameters

sample	The newly completed sample point on the path.
time	The time value at which it was computed.

Template Parameters

ComplexT The complex number type the endgame is currently working in.

◆ EndgameSettings()

const auto & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::EndgameSettings ( ) const

inlineinherited

This function is inferior to the templated Get<ConfigT> function provided.

◆ EndgameTrackPath()

SuccessCode bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::EndgameTrackPath	(	Vec< ComplexT > &	result,
		ComplexT const &	start_time,
		ComplexT const &	end_time,
		Vec< ComplexT > const &	start_point ) const

inlineinherited

Track through the tracker, adapting at the numeric-type boundary.

The tracker's TrackPath I/O is fixed to BaseComplexT (its TrackerLoopInitialization / CopySolution are non-templatable virtuals). When the adaptive-numeric-type endgame is computing in the hardware complex_dbl fast lane (ComplexT != BCT, i.e. the AMP case), we convert at the boundary: hand the tracker mpfr points at DoublePrecision – so the AMP tracker uses its hardware-double slot internally – then downcast the result back to complex_dbl. If the tracker escalated internally (GetCurrentPrecision() > DoublePrecision()), the caller's escalation hook discards this result and migrates the endgame to mpfr, so the truncating downcast is harmless.

When ComplexT == BCT (every fixed-precision tracker, and the AMP endgame's mpfr lane) this is a direct, zero-overhead call to the tracker – byte-identical to calling TrackPath itself.

MICRO-OPT (future): a native complex_dbl TrackPath overload on the AMP tracker would remove the boundary conversion churn (~1-2% of a track). Deferred – see the sprint notes.

◆ EscalateAndMigrate()

SuccessCode bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::EscalateAndMigrate ( unsigned guard )

inlineinherited

Raise the endgame to the next precision and migrate the containers' complex_dbl slot up to complex_mp when the tracker's authority escalates.

◆ FinalApproximation()

const Vec< ComplexT > & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::FinalApproximation ( ) const

inlineinherited

Get the most-recent approximation.

◆ FinalTolerance()

const auto & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::FinalTolerance ( ) const

inlineinherited

Get the final tolerance to which we are tracking the solution.

◆ Get()

template<typename ... Ts>

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

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

inlineinherited

Get the held configuration object of type T.

◆ GetCauchySamples() [1/2]

template<typename PrecT>

template<typename ComplexT>

SampCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetCauchySamples ( )

inline

Getter for the space values for the Cauchy endgame.

Available in const and non-const flavors

◆ GetCauchySamples() [2/2]

template<typename PrecT>

template<typename ComplexT>

const SampCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetCauchySamples ( ) const

inline

Const overload returning the Cauchy sample values.

◆ GetCauchySettings()

template<typename PrecT>

const auto & bertini::endgame::CauchyEndgame< PrecT >::GetCauchySettings ( ) const

inline

Getter for the specific settings in tracking_conifg.hpp under Cauchy.

◆ GetCauchyTimes() [1/2]

template<typename PrecT>

template<typename ComplexT>

TimeCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetCauchyTimes ( )

inline

Getter for the time values for the Cauchy endgame.

◆ GetCauchyTimes() [2/2]

template<typename PrecT>

template<typename ComplexT>

const TimeCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetCauchyTimes ( ) const

inline

Const overload returning the Cauchy time values.

◆ GetCOverKProbe()

Vec< ComplexT > const & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::GetCOverKProbe	(	unsigned	size,
		unsigned	prec ) const

inlineprotectedinherited

The fixed random direction the c/k estimate is projected along.

An exact conversion of the direction as drawn, at the requested precision. Converted, not rounded in place: the drawn values are doubles, which every multiple precision holds exactly, so the direction is the same in both lanes and survives any change of precision.

Template Parameters

ComplexT The complex number type.

Parameters

size	The number of coordinates the probe must have.
prec	The working precision to supply it at.

Returns: The probe, by const reference.

◆ GetIntoEGZone()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::GetIntoEGZone	(	ComplexT const &	start_time,
		Vec< ComplexT > const &	start_point,
		ComplexT const &	target_time )

inline

Track from the boundary inward until the path enters the endgame (Cauchy) operating zone.

◆ GetPSEGSamples() [1/2]

template<typename PrecT>

template<typename ComplexT>

SampCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetPSEGSamples ( )

inline

Getter for the space values for the power series approximation of the Cauchy endgame.

Available in const and non-const flavors

◆ GetPSEGSamples() [2/2]

template<typename PrecT>

template<typename ComplexT>

const SampCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetPSEGSamples ( ) const

inline

Const overload returning the power-series sample values.

◆ GetPSEGTimes() [1/2]

template<typename PrecT>

template<typename ComplexT>

TimeCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetPSEGTimes ( )

inline

Getter for the time values for the power series approximation of the Cauchy endgame.

◆ GetPSEGTimes() [2/2]

template<typename PrecT>

template<typename ComplexT>

const TimeCont< ComplexT > & bertini::endgame::CauchyEndgame< PrecT >::GetPSEGTimes ( ) const

inline

Const overload returning the power-series time values.

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

◆ IncrementCycleNumber()

void bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::IncrementCycleNumber ( unsigned inc )

inlineinherited

Increase the cycle number by the given increment.

◆ InitialApproximation()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::InitialApproximation	(	ComplexT const &	start_time,
		Vec< ComplexT > const &	start_point,
		ComplexT const &	target_time,
		Vec< ComplexT > &	approximation )

inline

\brief  Tracks til we believe we are in the Endgame Operating Zone, and then does a cauchy approximation

## Input:
        start_time: time value for which we start to make a power series approximation
        start_point: approximate solution to our homotopy H at the start_time
        approximation_time: time at which we are trying to find the solution, usually t = 0
        approximation approximate solution to our homotopy H at the approxmation_time


## Output:
    SuccessCode reporting if any errors had occurred. All data collected is stored in class data members.


##Details:

Template Parameters

ComplexT The complex number type.

This function is in charge of finding the very first approximation of the origin. It does this by first computing some initial samples like what is done in the Power Series Endgame. We continue to track forward in this manner until we have stabilization of the cycle number being approximated. This prevents the unnecessary circle tracking if we are possibly not in the endgame operating zone. Once we have stabilization we then perform InitialCauchyLoops while getting the accurate cycle number, and check the norms of the samples and make sure we are ready to approximate.

◆ InitialCauchyLoops()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::InitialCauchyLoops ( ComplexT const & target_time )

inline

\brief This function tracks into origin while computing loops around the origin. The function is checking to make sure we have reached a time when the ratio of the

maximum and minimum norms are withing some tolerance. When this is the case we return success. If this does not happen we will return an error depending on the error encountered.

## Input:
    target_time: the time value that we are creating loops around, default set to t= 0

## Output:
    initial_cauchy_loop_success: This variable returns any error code we have encountered or success if we have sucessfully
    tracked to an appropriate time.

##Details:
        \tparam ComplexT The complex number type.

◆ LatestTime()

const BCT & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::LatestTime ( ) const

inlineinherited

Get the latest time at which a point on the path was computed.

◆ LatestTimeImpl()

template<typename PrecT>

const BCT & bertini::endgame::CauchyEndgame< PrecT >::LatestTimeImpl ( ) const

inline

Returns: The most recent power-series time value.

◆ MigrateContainersToPrecision()

template<typename PrecT>

template<typename Dummy = void>

void bertini::endgame::CauchyEndgame< PrecT >::MigrateContainersToPrecision ( unsigned newprec )

inline

Widen this flavor's Cauchy containers from the complex_dbl slot up to complex_mp at the new precision.

◆ MinDehomNormOverLoopSamples()

template<typename PrecT>

template<typename ComplexT>

NumErrorT bertini::endgame::CauchyEndgame< PrecT >::MinDehomNormOverLoopSamples ( ) const

inline

The FLOOR of the current Cauchy loop: the smallest dehomogenized infinity-norm over the loop samples.

This is the divergence signal the mean cannot give: around a closed loop the branches of a fractional pole t^(-p/q) cancel, so the Cauchy mean stays near 0 while every SAMPLE has norm ~r^(-p/q). The floor exceeds a bound only when the ENTIRE loop is beyond it, so a transient single-sample spike (the cyclic-6 hazard that forbade watching samples directly) cannot lift it. NaN samples are skipped; a loop with no finite samples returns the largest value (a fully-poisoned loop counts as beyond any bound).

Template Parameters

ComplexT The complex number type of the samples to inspect.

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

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

◆ PoleComponentMass()

template<typename PrecT>

template<typename ComplexT>

NumErrorT bertini::endgame::CauchyEndgame< PrecT >::PoleComponentMass ( ) const

inline

The pole-component mass of the current Cauchy loop: the endgame operating-zone measurement.

The loop samples are a discrete Fourier series of the Puiseux/Laurent expansion of the path around the target time. Every CLEAN Puiseux term t^{k/c} with k >= 0 contributes exactly zero to the twisted means below (roots-of-unity orthogonality), so any surviving mass in the negative modes k = -1..-c measures structure the operating zone forbids:

a pole AT the target time (an affine path to genuine infinity – there is no patch to give it a finite place to go), or
any other singularity of the ramified cover INSIDE the loop (a branch point t* != 0 with |t*| < r), where the Cauchy integral assumption fails and the plain mean is garbage.

The two cases separate as the radius shrinks: an inside singularity's mass dies once r < |t*| (then the endgame may proceed – the zone finally reached); a pole at the target time has mass GROWING like 1/r, so it never reaches the operating zone and never accepts convergence (the acceptance gate in RunImpl).

Uses exactly the samples the mean uses: the closed c-circuit loop, uniform in angle, the duplicate closing sample excluded. Coordinates only – no function values, so system scaling cannot affect the verdict.

Template Parameters

ComplexT The complex number type of the samples.

Returns: max over m = 1..c of the infinity norm of the e^{i m theta / c}-twisted sample mean (the estimated magnitude of the t^{-m/c} coefficient at the current radius).

◆ PoleComponentMassAMP()

template<typename PrecT>

template<typename Dummy = void>

NumErrorT bertini::endgame::CauchyEndgame< PrecT >::PoleComponentMassAMP ( ) const

inline

PoleComponentMass read from whichever numeric lane the adaptive (double-first) endgame is currently computing in.

◆ PoleMassSignificant()

template<typename PrecT>

bool bertini::endgame::CauchyEndgame< PrecT >::PoleMassSignificant	(	NumErrorT	mass,
		NumErrorT	approx_scale ) const

inline

Is a pole-component mass SIGNIFICANT, i.e.

above the noise floor of the refined samples, relative to the approximation's own scale?

Parameters

mass	The pole-component mass (PoleComponentMass).
approx_scale	The infinity norm of the current approximation.

Returns: true when the mass indicates the operating zone has not been reached.

◆ PreviousApproximation()

const Vec< ComplexT > & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::PreviousApproximation ( ) const

inlineinherited

Get the second-most-recent approximation.

◆ RatioEGOperatingZoneTest()

template<typename PrecT>

template<typename ComplexT>

bool bertini::endgame::CauchyEndgame< PrecT >::RatioEGOperatingZoneTest ( ComplexT const & target_time ) const

inline

After we have used CircleTrack and have successfully closed the loop using CheckClosedLoop we need to check the maximum and minimum norms of the samples collected.

If the ratio of the maximum and minimum norm are within the threshold maximum_cauchy_ratio, and the difference is greater than final tolerance than we are successful.

Input:

target_time: Used to stay correct if we are using the endgame for a non-zero target time.

Output:

true: If we are within the ratio cutoff time, or have a ratio within the thresholds. false: otherwise

Details:

Template Parameters

ComplexT The complex number type. It is important to know if we are within the endgame operating zone. This function allows us to have a check that heuristcially will tell us if we are.

◆ RefineAllSamples()

SuccessCode bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::RefineAllSamples	(	SampCont< ComplexT > &	samples,
		TimeCont< ComplexT > &	times )

inlineinherited

Refine every sample point to the endgame's refinement tolerance.

◆ RefineSample()

SuccessCode bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::RefineSample	(	Vec< ComplexT > &	result,
		Vec< ComplexT > const &	current_sample,
		ComplexT const &	current_time,
		NumErrorT	tol,
		unsigned	max_iterations ) const

inlineinherited

A function passed off to the precision-specific endgame part.

Templated on ComplexT so the adaptive-numeric-type endgame can refine in the hardware-complex_dbl fast lane as well as in complex_mp. The precision policy (FixedPrecEndgame / AMPEndgame) provides the matching RefineSampleImpl overload(s). Fixed precision only ever instantiates this at BCT.

◆ RefreshCOverKProbe()

void bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::RefreshCOverKProbe ( unsigned size ) const

inlineprotectedinherited

Draw the c/k probe direction for a run.

Called at the start of every run, after whatever reseed the caller does for the path, so the direction is a function of the random-number stream at that point and nothing else.

Parameters

size	The number of coordinates the probe must have.

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

◆ RotateOntoPS()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::RotateOntoPS	(	ComplexT const &	next_time,
		Vec< ComplexT > const &	next_sample )

inline

Shift the power-series sample window forward by one (time, sample) pair.

◆ Run()

SuccessCode bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::Run ( Vec< BCT > const & start_point )

inlineinherited

Run the endgame from the stored boundary time to the stored target time.

Re-precisions the stored times to match start_point before dispatching to RunImpl, so the caller never needs to worry about precision alignment.

Call SetBoundaryTime() before invoking Run().

◆ RunImpl()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::RunImpl	(	ComplexT const &	start_time,
		Vec< ComplexT > const &	start_point,
		ComplexT const &	target_time )

inline

Primary function that runs the Cauchy endgame.

To begin, this function will compute a first approximation using the power series endgame notion. This approximation is made after a heuristic on the stabilization of the cyle number is made, and after the maximum and minimum norms of tracked space values around the origin are withing a certain tolerance.

## Input:
    start_time: the time value at which we start the endgame
    start_point: an approximate solution to our homotopy H at start_time
    target_time: the time value that we are using the endgame to interpolate to.

## Output:
    SuccessCode: reporting if we were successful in the endgame or if we encountered an error

##Details:

Template Parameters

ComplexT The complex number type. This function runs the entire Cauchy Endgame. We first take our endgame boundary time value and sample to find a first approximation of the origin. This is done by using the idea for the power series endgame. We check for stabilization of the cycle number, and check to see when the ratios of the maximum and minimum norm of samples collected by CircleTrack are withing a tolerance. When both of these conditions are met we do a Hermite interpolation. At this point we can start tracking in to the origin while using CircleTrack to compute samples and calculating their mean to get an approximation of the origin using the Cauchy Integral Formula.

◆ RunImplAMP()

template<typename PrecT>

template<typename Dummy = void>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::RunImplAMP	(	BCT const &	start_time,
		Vec< BCT > const &	start_point,
		BCT const &	target_time )

inline

Run the Cauchy endgame via the double-first adaptive-numeric-type driver, migrating up to mpfr only on tracker escalation.

◆ RunInitSegmentT()

template<typename PrecT>

template<typename ComplexT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::RunInitSegmentT	(	ComplexT const &	start_time,
		Vec< ComplexT > const &	start_point,
		ComplexT const &	target_time )

inline

Run the initialization segment (seed the PSEG window and reach the EG zone) in a given numeric type.

◆ SecuritySettings()

const auto & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::SecuritySettings ( ) const

inlineinherited

Returns: The security (divergence-bailout) settings.

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

◆ SetBoundaryTime()

void bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::SetBoundaryTime ( BCT const & t )

inlineinherited

Set the endgame boundary (start) time.

◆ SetCauchySamples()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::SetCauchySamples ( SampCont< ComplexT > const & cauchy_samples_to_set )

inline

Setter for the space values for the Cauchy endgame.

◆ SetCauchySettings()

template<typename PrecT>

void bertini::endgame::CauchyEndgame< PrecT >::SetCauchySettings ( CauchyConfig const & new_cauchy_settings )

inline

Setter for the specific settings in tracking_conifg.hpp under Cauchy.

◆ SetCauchyTimes()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::SetCauchyTimes ( TimeCont< ComplexT > const & cauchy_times_to_set )

inline

Setter for the time values for the Cauchy endgame.

◆ SetFinalTolerance()

void bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::SetFinalTolerance ( NumErrorT const & ft )

inlineinherited

Setter for the final tolerance.

◆ SetPSEGSamples()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::SetPSEGSamples ( SampCont< ComplexT > const & pseg_samples_to_set )

inline

Setter for the space values for the power series approximation of the Cauchy endgame.

◆ SetPSEGTimes()

template<typename PrecT>

template<typename ComplexT>

void bertini::endgame::CauchyEndgame< PrecT >::SetPSEGTimes ( TimeCont< ComplexT > pseg_times_to_set )

inline

Setter for the time values for the power series approximation of the Cauchy endgame.

◆ SetTargetTime()

void bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::SetTargetTime ( BCT const & t )

inlineinherited

Set the final target time.

◆ TargetTime()

BCT const & bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::TargetTime ( ) const

inlineinherited

Returns: The final target time.

◆ ValidateConfigs()

template<typename PrecT>

void bertini::endgame::CauchyEndgame< PrecT >::ValidateConfigs ( )

inline

Validate the endgame configuration (e.g. require >= 3 sample points for circle tracking).

Member Data Documentation

◆ approximate_error_

NumErrorT bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::approximate_error_

mutableprotectedinherited

The error estimate between successive approximations.

Initialized to infinity, not left indeterminate: ApproximateError() is a public accessor, so a caller may read it before any endgame has run. Infinity is also the only safe sentinel here – every convergence gate in the flavors has the shape approximate_error_ < FinalTolerance(), and an indeterminate value that happened to be small would be a false convergence.

◆ c_over_k_probe_

TupOfVec bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::c_over_k_probe_

mutableprotectedinherited

The c/k probe in each numeric type the endgame computes in: exact conversions of c_over_k_probe_as_drawn_, re-derived when their size or precision is wrong, never rounded.

◆ c_over_k_probe_as_drawn_

Vec<complex_dbl> bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::c_over_k_probe_as_drawn_

mutableprotectedinherited

The random direction the c/k estimate is projected along, as drawn: in double precision, so that it is exact in every lane and at every multiple precision.

Drawn at the start of every run (RefreshCOverKProbe) and fixed for the run, so consecutive estimates differ only because the samples differ. A fresh random probe every call made the stabilization test noisy – it could certify the operating zone spuriously – and churned mpfr allocations. See z_notes/20260629.

◆ cauchy_samples_

template<typename PrecT>

TupleOfSamps bertini::endgame::CauchyEndgame< PrecT >::cauchy_samples_

mutableprotected

A deque of samples collected by CircleTrack.

Computed a mean of the values of this deque, after a loop has been closed, will give an approximation of the origin.

◆ cauchy_times_

template<typename PrecT>

TupleOfTimes bertini::endgame::CauchyEndgame< PrecT >::cauchy_times_

mutableprotected

A deque of times that are collected by CircleTrack.

These samples are used to compute all approximations of the origin after the first.

◆ configuration_

template<typename ... Ts>

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

inherited

The held configuration objects, one per config type.

◆ cycle_number_

unsigned int bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::cycle_number_

mutableprotectedinherited

The current estimate of the cycle number.

◆ final_approximation_

Vec<BCT> bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::final_approximation_

mutableprotectedinherited

The latest computed approximation of the endpoint.

◆ latest_time_cache_

template<typename PrecT>

BCT bertini::endgame::CauchyEndgame< PrecT >::latest_time_cache_

mutableprotected

Scratch so LatestTimeImpl can return a BCT reference while in the double fast lane.

◆ previous_approximation_

Vec<BCT> bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::previous_approximation_

mutableprotectedinherited

The previous approximation of the endpoint.

◆ pseg_samples_

template<typename PrecT>

TupleOfSamps bertini::endgame::CauchyEndgame< PrecT >::pseg_samples_

mutableprotected

A deque of samples that are in correspondence with the pseg_times_.

These samples are also used to compute the first power series approximation for the Cauchy endgame.

◆ pseg_times_

template<typename PrecT>

TupleOfTimes bertini::endgame::CauchyEndgame< PrecT >::pseg_times_

mutableprotected

A deque of times that are specifically used to compute the power series approximation for the Cauchy endgame.

◆ start_time_

BCT bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::start_time_

protectedinherited

The endgame boundary time; set via SetBoundaryTime().

◆ target_time_

BCT bertini::endgame::EndgameBase< CauchyEndgame< PrecT >, PrecT >::target_time_

protectedinherited

The final target time (default 0); set via SetTargetTime().

Public Types

Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Explanation

Example Usage

Testing

Member Typedef Documentation

◆ BaseComplexT

◆ BaseEGT

◆ BaseRealT

◆ BCT

◆ BRT

◆ Config

◆ Configs

◆ ConfigsAsTuple

◆ Configured

◆ EmitterType

◆ FinalEGT

◆ NeededTypes

◆ TrackerType

◆ TupleOfSamps

◆ TupleOfTimes

◆ TupOfReal

◆ TupOfVec

◆ UsedConfigs

Constructor & Destructor Documentation

◆ CauchyEndgame() [1/2]

◆ CauchyEndgame() [2/2]

◆ ~CauchyEndgame()

Member Function Documentation

◆ AddObserver() [1/2]

◆ AddObserver() [2/2]

◆ AddToCauchyData()

◆ AddToPSData()

◆ AdvanceTime()

◆ AdvanceTimeAMP()

◆ ApproximateError()

◆ AsFlavor() [1/2]

◆ AsFlavor() [2/2]

◆ BeyondSecurityMaxNorm()

◆ BoundaryTime()

◆ CheckClosedLoop()

Input:

Output:

Details:

◆ CheckForCOverKStabilization()

◆ CircleTrack()

Input:

Output:

Details:

◆ ClearAndSeedCauchyData()

◆ ClearTimesAndSamples()

◆ ComputeCauchyApproxAMP()

◆ ComputeCauchyApproximationOfXAtT0()

Input:

Output:

Details:

◆ ComputeCauchySamples()

Input:

Output:

Details:

◆ ComputeCauchySamplesAMP()

◆ ComputeCOverK()

◆ ComputeInitialSamples()

Input

Output

Details

◆ CycleNumber() [1/2]

◆ CycleNumber() [2/2]

◆ EmitComputedSample()

◆ EndgameSettings()

◆ EndgameTrackPath()

◆ EscalateAndMigrate()

◆ FinalApproximation()

◆ FinalTolerance()

◆ Get()