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

#include <cauchy.hpp>

Public Member Functions
template<typename CT>
SuccessCode	AdvanceTime (CT const &target_time)
	Advances time, marching toward the target time.

template<typename CT>
bool	CheckClosedLoop ()
	Function that determines if we have closed a loop after calling CircleTrack().

template<typename CT>
bool	CheckForCOverKStabilization (TimeCont< CT > const &c_over_k_array) const
	Function to determine if ratios of c/k estimates are withing a user defined threshold.

template<typename CT>
SuccessCode	CircleTrack (CT const &target_time)
	Function to track around the origin.

template<typename CT>
void	ClearTimesAndSamples ()
	Function that clears all samples and times from data members for the Cauchy endgame.

template<typename CT>
SuccessCode	ComputeCauchyApproximationOfXAtT0 (Vec< CT > &result)
	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.

template<typename CT>
SuccessCode	ComputeCauchySamples (CT 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 CT>
auto	ComputeCOverK () const -> typename Eigen::NumTraits< CT >::Real
	A function that uses the assumption of being in the endgame operating zone to compute an approximation of the ratio c over k. When the cycle number stabilizes we will see that the different approximations of c over k will stabilize. Returns the computed value of c over k.

template<typename CT>
SampCont< CT > &	GetCauchySamples ()
	Getter for the space values for the Cauchy endgame.

const auto &	GetCauchySettings () const
	Getter for the specific settings in tracking_conifg.hpp under Cauchy.

template<typename CT>
TimeCont< CT > &	GetCauchyTimes ()
	Getter for the time values for the Cauchy endgame.

template<typename CT>
SampCont< CT > &	GetPSEGSamples ()
	Getter for the space values for the power series approximation of the Cauchy endgame.

template<typename CT>
TimeCont< CT > &	GetPSEGTimes ()
	Getter for the time values for the power series approximation of the Cauchy endgame.

template<typename CT>
SuccessCode	InitialApproximation (CT const &start_time, Vec< CT > const &start_point, CT const &target_time, Vec< CT > &approximation)

template<typename CT>
SuccessCode	InitialCauchyLoops (CT const &target_time)

template<typename CT>
bool	RatioEGOperatingZoneTest (CT 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. 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.

template<typename CT>
SuccessCode	RunImpl (CT const &start_time, Vec< CT > const &start_point, CT const &target_time)
	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.

template<typename CT>
void	SetCauchySamples (SampCont< CT > const &cauchy_samples_to_set)
	Setter for the space values for the Cauchy endgame.

void	SetCauchySettings (CauchyConfig const &new_cauchy_settings)
	Setter for the specific settings in tracking_conifg.hpp under Cauchy.

template<typename CT>
void	SetCauchyTimes (TimeCont< CT > const &cauchy_times_to_set)
	Setter for the time values for the Cauchy endgame.

template<typename CT>
void	SetPSEGSamples (SampCont< CT > const &pseg_samples_to_set)
	Setter for the space values for the power series approximation of the Cauchy endgame.

template<typename CT>
void	SetPSEGTimes (TimeCont< CT > pseg_times_to_set)
	Setter for the time values for the power series approximation of the Cauchy endgame.

Protected Attributes
TupleOfSamps	cauchy_samples_
	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.

TupleOfTimes	cauchy_times_
	A deque of times that are collected by CircleTrack. These samples are used to compute all approximations of the origin after the first.

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

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

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>::BaseRealType; // Real types
using ComplexT = tracking::TrackerTraits<TrackerType>::BaseComplexType; 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::TotalDegree(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);
    my_homotopy.precision(ambient_precision); // making sure our precision is all set up 
    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 Function Documentation

◆ AdvanceTime()

template<typename PrecT>

template<typename CT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::AdvanceTime ( CT 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).

Here is the caller graph for this function:

◆ CheckClosedLoop()

template<typename PrecT>

template<typename CT>

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

CT	The complex number type

◆ CheckForCOverKStabilization()

template<typename PrecT>

template<typename CT>

bool bertini::endgame::CauchyEndgame< PrecT >::CheckForCOverKStabilization ( TimeCont< CT > const & c_over_k_array ) const

inline

Function to determine if ratios of c/k estimates are withing a user defined threshold.

Input:

c_over_k_array: A container holding all previous computed C over K ratios. The stabilization of these ratios is key to the convergence of the cauchy endgame.

Output:

true: if we have stabilized and can proceed with the endgame. false: if our ratios are not withing tolerances set by the user or by default.

Details:

Template Parameters

CT	The complex number type.

◆ CircleTrack()

template<typename PrecT>

template<typename CT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::CircleTrack ( CT 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

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

Here is the caller graph for this function:

◆ ClearTimesAndSamples()

template<typename PrecT>

template<typename CT>

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

inline

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

Here is the caller graph for this function:

◆ ComputeCauchyApproximationOfXAtT0()

template<typename PrecT>

template<typename CT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::ComputeCauchyApproximationOfXAtT0 ( Vec< CT > & 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

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

Here is the caller graph for this function:

◆ ComputeCauchySamples()

template<typename PrecT>

template<typename CT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::ComputeCauchySamples ( CT 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

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

Here is the caller graph for this function:

◆ ComputeCOverK()

template<typename PrecT>

template<typename CT>

auto bertini::endgame::CauchyEndgame< PrecT >::ComputeCOverK ( ) const -> typename Eigen::NumTraits<CT>::Real

inline

A function that uses the assumption of being in the endgame operating zone to compute an approximation of the ratio c over k. When the cycle number stabilizes we will see that the different approximations of c over k will stabilize. Returns the computed value of c over k.

Input:

None: all data needed are class data members.

Output:

estimate: The approximation of the ratio of the two numbers C and K heuristically signifying we are in the cauchy endgame operating zone.

Details:

Template Parameters

CT	The complex number type. Consult page 53 of [3], for the reasoning behind this heuristic.

◆ GetCauchySamples()

template<typename PrecT>

template<typename CT>

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

inline

Getter for the space values for the Cauchy endgame.

Available in const and non-const flavors

◆ GetCauchySettings()

template<typename PrecT>

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

inline

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

Here is the caller graph for this function:

◆ GetCauchyTimes()

template<typename PrecT>

template<typename CT>

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

inline

Getter for the time values for the Cauchy endgame.

◆ GetPSEGSamples()

template<typename PrecT>

template<typename CT>

SampCont< CT > & 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

◆ GetPSEGTimes()

template<typename PrecT>

template<typename CT>

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

inline

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

◆ InitialApproximation()

template<typename PrecT>

template<typename CT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::InitialApproximation	(	CT const &	start_time,
		Vec< CT > const &	start_point,
		CT const &	target_time,
		Vec< CT > &	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

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

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::InitialCauchyLoops ( CT 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 CT The complex number type.

Here is the caller graph for this function:

◆ RatioEGOperatingZoneTest()

template<typename PrecT>

template<typename CT>

bool bertini::endgame::CauchyEndgame< PrecT >::RatioEGOperatingZoneTest ( CT 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

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

◆ RunImpl()

template<typename PrecT>

template<typename CT>

SuccessCode bertini::endgame::CauchyEndgame< PrecT >::RunImpl	(	CT const &	start_time,
		Vec< CT > const &	start_point,
		CT 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

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

◆ SetCauchySamples()

template<typename PrecT>

template<typename CT>

void bertini::endgame::CauchyEndgame< PrecT >::SetCauchySamples ( SampCont< CT > 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 CT>

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

inline

Setter for the time values for the Cauchy endgame.

◆ SetPSEGSamples()

template<typename PrecT>

template<typename CT>

void bertini::endgame::CauchyEndgame< PrecT >::SetPSEGSamples ( SampCont< CT > 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 CT>

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

inline

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

Member Data Documentation

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

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

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

cauchy.hpp

Public Member Functions

Protected Attributes

Detailed Description

Explanation

Example Usage

Testing

Member Function Documentation

◆ AdvanceTime()

◆ CheckClosedLoop()

Input:

Output:

Details:

◆ CheckForCOverKStabilization()

Input:

Output:

Details:

◆ CircleTrack()

Input:

Output:

Details:

◆ ClearTimesAndSamples()

◆ ComputeCauchyApproximationOfXAtT0()

Input:

Output:

Details:

◆ ComputeCauchySamples()

Input:

Output:

Details:

◆ ComputeCOverK()

Input:

Output:

Details:

◆ GetCauchySamples()

◆ GetCauchySettings()

◆ GetCauchyTimes()

◆ GetPSEGSamples()

◆ GetPSEGTimes()

◆ InitialApproximation()

◆ InitialCauchyLoops()

◆ RatioEGOperatingZoneTest()

Input:

Output:

Details:

◆ RunImpl()

◆ SetCauchySamples()

◆ SetCauchySettings()

◆ SetCauchyTimes()

◆ SetPSEGSamples()

◆ SetPSEGTimes()

Member Data Documentation

◆ cauchy_samples_

◆ cauchy_times_

◆ pseg_samples_

◆ pseg_times_