⚙️ Configuration reference¶

This page collects every tracker and algorithm setting the Python interface to Bertini 2 has, with its default and what it does.

Note

The tables below are read out of the library when these docs are built, so they describe the version you are reading about rather than the version someone last wrote a table for.

Three ways to set a setting¶

Name the field, and it is routed to whichever config holds it. This is the usual way, and it reaches the solver’s own settings, its tracker’s, and its endgame’s alike:

solver.update(final_tolerance="1e-11", max_step_size="0.05", num_sample_points=6)

Name the config, when you want to set several of its fields at once:

solver.configure(stepping={'max_step_size': "0.05"},
                 endgame={'final_tolerance': "1e-8"})

Hand over a whole config object, which is what get_settings() and set_settings() carry between solvers:

settings = tuned_solver.get_settings()
next_solver.set_settings(settings)

A misspelled name raises immediately and suggests the one you meant, rather than doing nothing.

Numbers, exactly¶

Numeric settings take strings, and a string is the noise-free way to write one: "1e-11" means exactly that, where the Python float 1e-11 is the nearest double to it. For the settings stored as exact rationals – a sample ladder’s ratio, the homotopy times – a Python float is refused outright, since 0.1 the double is not one tenth; write "1/10" or "0.1" and both give the exact rational, or pass an int, a fractions.Fraction, or a bertini.multiprec.rational_mp.

Tracker settings that have no config struct¶

Todo

Get these into a config, so the interface is uniform.

These are set by calling a method on the tracker rather than by naming a field, so they appear in no config listing, including the generated ones below. They are among the most consequential settings there are, and this is the only place they are collected.

Setting	Default	What it does
`tracker.infinite_truncation(bool)`	`True`	Whether to truncate such paths at all.
`tracker.precision_preservation(bool)`	`False`	Whether an adaptive tracker returns to its starting precision when a path ends.
`tracker.reinitialize_initial_step_size(bool)`	`True`	Whether each path starts from the configured initial step size rather than inheriting the last one used.
`tracker.set_max_wall_clock_duration(seconds)`	none	A wall-clock deadline; a track in progress is abandoned between steps once it passes. Cleared with `clear_max_wall_clock_time()`. See ⏱️ Stopping a solve, and using a wall-clock budget.

The configs¶

Everything below is generated. Each heading is a config class; the keyword beside it is what configure() takes, and every field name is what update() accepts directly.

Tracking¶

How a path is followed: step sizes, Newton’s method, and the precision model.

AMPConfig¶

Set as amp=..., or by any of its field names directly. API: bertini.tracking.AMPConfig.

Setting	Default	What it does
`coefficient_bound`	derived from the system	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> float
`degree_bound`	derived from the system	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> float
`function_eval_error_bound`	derived from the system	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> float
`jacobian_eval_error_bound`	derived from the system	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> float
`linear_solve_error_bound`	derived from the system	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> float
`max_num_precision_decreases`	`10`	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> int
`maximum_precision`	`300`	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> int
`safety_digits_1`	`1`	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> int
`safety_digits_2`	`1`	None( (bertini._pybertini.tracking.AMPConfig)arg1) -> int

FixedPrecisionConfig¶

Set as fixed_precision=..., or by any of its field names directly. API: bertini.tracking.FixedPrecisionConfig.

Setting	Default	What it does
`precision`	`0`	The number of digits to always work at. For a double-precision tracker this is DoublePrecision() (16) and cannot be changed; for a fixed-multiple tracker it is the precision the whole solve runs at – set it to choose a different fixed precision. A tracker keeps this in sync with its actual precision, so reading it tells you the precision in effect.

NewtonConfig¶

Set as newton=..., or by any of its field names directly. API: bertini.tracking.NewtonConfig.

Setting	Default	What it does
`max_num_newton_iterations`	`2`	None( (bertini._pybertini.tracking.NewtonConfig)arg1) -> int
`min_num_newton_iterations`	`1`	None( (bertini._pybertini.tracking.NewtonConfig)arg1) -> int

SteppingConfig¶

Set as stepping=..., or by any of its field names directly. API: bertini.tracking.SteppingConfig.

Setting	Default	What it does
`consecutive_successful_steps_before_stepsize_increase`	`5`	This number of successful steps have to taken consecutively, and then the stepsize is permitted to increase
`frequency_of_CN_estimation`	`1`	How frequently the condition number should be updated. Less frequently is faster (estimation requires an additional linear solve), but may cause precision adjustment to lag behind.
`initial_step_size`	`0.1`	The initial stepsize when tracking is started. See also tracking.AMPTracker.reinitialize_initial_step_size
`max_num_steps`	`100000`	The maximum number of steps. Tracking will die if it tries to take more than this number, sad day.
`max_step_size`	`0.1`	The maximum allowed stepsize during tracking. See also min_num_steps
`min_num_steps`	`1`	The minimum number of steps the tracker can take between now and then. This is useful if you are tracking closely between times, and want to guarantee some number of steps are taken. Then again, this could be wasteful, too.
`min_step_size`	`1e-100`	The minimum stepsize the tracker is allowed to take. See also max_step_size
`step_size_fail_factor`	`0.5`	The scale factor for stepsize, after a fail happens. See also step_size_success_factor
`step_size_success_factor`	`2`	The scale factor for stepsize, after some consecutive steps. See also consecutive_successful_steps_before_stepsize_increase

TrackerConfig¶

Set as tracker=..., or by any of its field names directly. API: bertini.tracking.TrackerConfig.

Setting	Default	What it does
`path_truncation_threshold`	`100000.0`	The tracker abandons a path once the largest coordinate of its dehomogenized point exceeds this. Distinct from the endgame’s Security.max_norm and from PostProcessingConfig.endpoint_finite_threshold, which ask the same question later.
`predictor`	`Predictor.RKF45`	The ODE method used to predict the next point along the path. RKF45 – order 4 with an embedded error estimate – is the default; a lower-order choice is how a path crossing is usually provoked.
`tracking_tolerance`	`1e-05`	How tightly Newton must correct onto the path for a step to be accepted. A solver drives this per phase – loose to the endgame boundary, tight through the endgame – so expect it to change under you during a solve.

Endgames¶

How the last stretch to a singular endpoint is handled.

CauchyConfig¶

Set as cauchy=..., or by any of its field names directly. API: bertini.endgame.CauchyConfig.

Setting	Default	What it does
`cycle_cutoff_time`	`1e-08`	None( (bertini._pybertini.endgame.CauchyConfig)arg1) -> float
`fail_safe_maximum_cycle_number`	`250`	max number of loops before giving up.
`maximum_cauchy_ratio`	`0.5`	None( (bertini._pybertini.endgame.CauchyConfig)arg1) -> float
`num_consecutive_same_cycle_number`	`2`	Number of consecutive Cauchy approximations that must report the same cycle number before a converged approximation is trusted.
`ratio_cutoff_time`	`1e-14`	None( (bertini._pybertini.endgame.CauchyConfig)arg1) -> float

EndgameConfig¶

Set as endgame=..., or by any of its field names directly. API: bertini.endgame.EndgameConfig.

Setting	Default	What it does
`final_tolerance`	`1e-11`	The tolerance to which to track the path, using the endgame: in effect, how many digits to get right. An endgame stops when two consecutive approximations of the root are this close to each other in the infinity norm, measured in the solver’s INTERNAL coordinates (homogenized, on the patch), where a point has size about one. In your own variables that is an absolute error of about this tolerance times the size of the solution: a solution of order 1000 found to 1e-6 is known to about 1e-3. The distance reached is reported per solution as accuracy_estimate_internal_coords, and in your variables as accuracy_estimate_user_coords. Default value is 1e-11.
`max_num_refinements`	`4`	the maximum number of Newton refinements to be taken during sample point sharpening. Increasing this can help speed convergence, at the risk of path jumping.
`min_track_time`	`1e-100`	The minimum distance from the target time to track to. Decreasing this may help failing runs succeed, or maybe not, because you are, after all, tracking toward a singularity.
`minimum_for_c_over_k_stabilization`	`0.75`	How closely successive c/k estimates must agree for the path to count as being in the endgame operating zone, as a ratio of the smaller to the larger. Their settling is what says the cycle-number estimate has settled, and so that the Puiseux asymptotics the endgame is built on dominate.
`num_needed_for_stabilization`	`3`	How many consecutive c/k estimates must agree for the path to count as being in the endgame operating zone.
`num_sample_points`	`3`	The number of points to use for extrapolant calculation. In the Power Series Endgame, the is the number of geometrically spaces points on the path. For Cauchy, this is the number of points on each circle tracked around the target time value.
`refine_when_increasing_precision`	`False`	Whether to re-refine the samples the endgame is keeping when it moves to a higher working precision (default False). Off, the retained samples carry the accuracy they were computed at, which is the accuracy of the lower precision; on, they are refined again at the new one, which costs Newton steps per retained sample and buys a sharper sample window. Part of the run’s identity, so changing it is a different ask.
`sample_factor`	`1/2`	The factor by which to space the geometrically spaced ‘distance’ between sample points, or sample circles for Cauchy.
`sample_point_refinement_factor`	`0.01`	Extra amount of tolerance for refining before computing the final approximation, during endgame.

PowerSeriesConfig¶

Set as power_series=..., or by any of its field names directly. API: bertini.endgame.PowerSeriesConfig.

Setting	Default	What it does
`cycle_number_amplification`	`5`	The maximum number allowable iterations during endgames, for points used to approximate the final solution.
`max_cycle_number`	`6`	The maximum cycle number to consider, when calculating the cycle number which best fits the path being tracked.

SecurityConfig¶

Set as security=..., or by any of its field names directly. API: bertini.endgame.SecurityConfig.

Setting	Default	What it does
`level`	`0`	Whether the endgame truncates a path that appears to be going to infinity. 0 (the default) truncates: two consecutive endpoint approximations whose largest coordinate is above max_norm end the path with SuccessCode.SecurityMaxNormReached, in either endgame. 1 does not truncate, and tracks every path to its end.
`max_norm`	`10000.0`	If on, the norm at which to truncate a path.

Algorithms¶

What the solver itself does, around the tracking.

AutoRetrackConfig¶

Set as auto_retrack=..., or by any of its field names directly. API: bertini.nag_algorithm.AutoRetrackConfig.

Setting	Default	What it does
`midpath_decrease_tolerance_factor`	`0.5`	Factor by which tracking tolerances are tightened when retracking after the midpath check detects a path crossing.

MidPathConfig¶

Set as mid_path=..., or by any of its field names directly. API: bertini.nag_algorithm.MidPathConfig.

Setting	Default	What it does
`same_point_tolerance`	`1e-05`	Tolerance used by the midpath check to detect two paths that have crossed (become the same point) partway through tracking, which signals a need to retrack.

PostProcessingConfig¶

Set as post_processing=..., or by any of its field names directly. API: bertini.nag_algorithm.PostProcessingConfig.

Setting	Default	What it does
`condition_number_threshold`	`100000000.0`	Bertini 1’s CondNumThreshold. An endpoint is classified singular if it is the endpoint of multiple paths (multiplicity > 1), or if its spectral-norm condition-number estimate exceeds this value. Default 1e8.
`endpoint_finite_threshold`	`100000.0`	Bertini 1’s EndpointFiniteThreshold. An endpoint is classified at infinity if the infinity norm of its dehomogenized coordinates exceeds this value. Default 1e5.
`real_threshold`	`1e-08`	Bertini 1’s ImagThreshold. A (dehomogenized) endpoint is classified real if the infinity norm of its coordinates’ imaginary parts is below this. Default 1e-8.
`same_point_tolerance_multiplier`	`10.0`	Bertini 1’s EndpointSameThreshold. A multiplier (>= 1) on final_tolerance: two endpoints are the same point (raising multiplicity) when the infinity norm of the difference of their dehomogenized coordinates is below final_tolerance * same_point_tolerance_multiplier. Default 10.

RecordsConfig¶

Set as records=..., or by any of its field names directly. API: bertini.nag_algorithm.RecordsConfig.

Setting	Default	What it does
`recall`	`RecallPolicy.Completed`	Which recorded outcomes of an identical ask already in the records directory are used in place of tracking: a RecallPolicy (default RecallPolicy.Completed). A bool is accepted too: True means Completed, False means Nothing – force a fresh track even when the paths are recorded, e.g. to run path observers, benchmark the solve, or re-verify a run; the fresh track is still recorded. No effect when nothing is recorded.

RegenerationConfig¶

Set as regeneration=..., or by any of its field names directly. API: bertini.nag_algorithm.RegenerationConfig.

Setting	Default	What it does
`higher_dimension_check`	`True`	Whether to test for, and remove, points lying on higher-dimensional components during regeneration.
`remove_infinite_endpoints`	`True`	Whether endpoints found to be at infinity during regeneration start-point buildup are discarded. Set True if you are not interested in solutions at infinity.
`slice_final_tolerance`	`1e-11`	Final tolerance to track the slice move to, using the endgame (Bertini 1 SliceFinalTol).
`slice_newton_before_endgame`	`1e-05`	Slice-moving tracking tolerance before the endgame (Bertini 1 SliceTolBeforeEG). Separate from TolerancesConfig.newton_before_endgame, which governs the main tracking.
`slice_newton_during_endgame`	`1e-06`	Slice-moving tracking tolerance during the endgame (Bertini 1 SliceTolDuringEG).
`start_level`	`0`	The regeneration level at which to begin.

SharpeningConfig¶

Set as sharpening=..., or by any of its field names directly. API: bertini.nag_algorithm.SharpeningConfig.

Setting	Default	What it does
`function_residual_tolerance`	`1e-12`	A function value is considered zero if its magnitude is smaller than this.
`ratio_tolerance`	`0.99`	A value is considered zero if the ratio of two different approximations is smaller than this.
`sharpendigits`	`0`	How many digits should be correct after sharpening a solution.

TolerancesConfig¶

Set as tolerances=..., or by any of its field names directly. API: bertini.nag_algorithm.TolerancesConfig.

Setting	Default	What it does
`newton_before_endgame`	`1e-05`	Tracking (Newton) tolerance used while tracking before the endgame begins. Tighten this if paths drift together or are missed.
`newton_during_endgame`	`1e-06`	Tracking (Newton) tolerance used during the endgame.

ZeroDimConfig¶

Set as zero_dim=..., or by any of its field names directly. API: bertini.nag_algorithm.ZeroDimConfig.

Setting	Default	What it does
`endgame_boundary`	`0.1`	The time value at which tracking stops and the endgame takes over.
`initial_ambient_precision`	`20`	The working precision (digits) each path starts at. Read at the start of every path, so setting it on an existing solver takes effect on the next solve. Part of the run’s identity.
`max_num_crossed_path_resolve_attempts`	`2`	How many times to re-track crossed paths (with tightened settings) at the endgame boundary before giving up. 0 = detect and report only, do not re-track. Default 2.
`max_path_wall_clock_duration`	`0.0`	Wall-clock budget for EACH path, in seconds; 0 (the default) means none. A path that has not finished when its budget runs out is abandoned between steps with SuccessCode.WallClockLimitReached, stamped with where it got to (`latest_path_point`, `final_time_used`, the step counts), and recorded with this limit. Not part of the run’s identity: a budget says how long to wait for an answer, not what the answer is. How a later run treats a path abandoned under a budget is RecallPolicy’s business. Wall-clock time is machine-dependent; the recorded stamp is the machine-independent account.
`max_solve_wall_clock_duration`	`0.0`	Wall-clock budget for the WHOLE solve() call, in seconds; 0 (the default) means none. Once it runs out no further path is started and any path in flight is abandoned between steps, and the solve reads exactly as if you had pressed Ctrl-C: was_stopped_early() is True, abandoned paths read ExternallyTerminated, unstarted ones NeverStarted, and a later solve of the same ask re-tracks them. The per-path budget is the finer tool (it guarantees progress path by path); this one is for thinking in terms of the whole call. Not applied to the MPI solve.
`num_threads`	`0`	Worker threads tracking paths, in a standalone solve and on each MPI rank. 0 = auto (every CPU this process may run on), 1 = serial (no thread pool), N = N threads. The BERTINI_NUM_THREADS environment variable overrides this. Threading needs no MPI and no free-threaded Python: the heavy tracking runs in C++ with the GIL released.
`path_variable_name`	`ZERO_DIM_PATH_VARIABLE`	The name given to the homotopy’s path variable. Read when the solver BUILDS its homotopy, so set it on a config you hand to a constructor. Setting it on a solver that already built one does not rename that homotopy’s path variable – the name is part of the run’s identity, so the two would then disagree; build a new solver instead. (If the name collides with one of your variables the solver mangles it to keep them apart, so the homotopy’s actual path variable may differ from what you asked for.)
`start_time`	`1`	The time value at which the homotopy starts (where the start solutions live).
`target_time`	`0`	The time value the homotopy tracks to (where the solutions of interest live).