The fundamental polynomial system class for Bertini2. More...

#include <system.hpp>

Inheritance diagram for bertini::System:

Public Types
using	NE = std::shared_ptr<node::NamedExpression>
	Shorthand for a shared pointer to a named expression (a function of the system).
using	Var = std::shared_ptr<node::Variable>
	Shorthand for a shared pointer to a variable node.
using	Nd = std::shared_ptr<node::Node>
	Shorthand for a shared pointer to a generic expression-tree node.

Public Member Functions
	System ()
	The default constructor for a system.
	System (std::vector< Nd > const &functions)
	Construct a system from a list of functions.
	System (std::string const &input)
	The copy operator, creates a system from a string using the Bertini parser for Bertini classic syntax.
	System (System const &other)
	The copy operator.
	System (System &&other)
	The move copy operator.
System &	operator= (const System &other)
	The assignment operator.
System &	operator= (System &&other)=default
	The move assignment operator.
void	Differentiate () const
	Compute and internally store the symbolic Jacobian of the system.
NodeMatrix	SymbolicJacobian (bool usercoordinates=true) const
	The symbolic Jacobian of the system, as a matrix of expression-tree nodes.
template<typename T>
void	EvalInPlace (Vec< T > &function_values) const
	Evaluate the system using the previously set variable (and time) values, in place.
template<typename T>
Vec< T >	Eval () const
	Evaluate the system using the previously set variable (and time) values, creating vector of function values.
template<typename T, typename Derived>
void	EvalInPlace (Vec< T > &function_values, const Eigen::MatrixBase< Derived > &variable_values) const
	Evaluate the system, provided the system has no path variable defined, in place.
template<typename Derived>
Derived::PlainObject	Eval (const Eigen::MatrixBase< Derived > &variable_values) const
	Evaluate the system, provided the system has no path variable defined.
template<typename T>
Vec< T >	Eval (const Vec< T > &variable_values) const
	Evaluate the system at the given variable values (no path variable defined).
template<typename Derived, typename T>
void	EvalInPlace (Vec< T > &function_values, const Eigen::MatrixBase< Derived > &variable_values, const T &path_variable_value) const
	Evaluate the system, provided a path variable is defined for the system, in place.
template<typename Derived, typename T>
Vec< T >	Eval (const Eigen::MatrixBase< Derived > &variable_values, const T &path_variable_value) const
	Evaluate the system, provided a path variable is defined for the system.
template<typename T>
Vec< T >	Eval (const Vec< T > &variable_values, const T &path_variable_value) const
	Evaluate the system at the given variable values and path-variable value.
template<typename T>
void	JacobianInPlace (Mat< T > &J) const
	Evaluate the Jacobian matrix of the system, using the previous space and time values, in place.
template<typename T>
Mat< T >	Jacobian () const
	Evaluate the Jacobian matrix of the system, using the previous space and time values.
template<typename T>
void	JacobianInPlace (Mat< T > &J, const Vec< T > &variable_values) const
	Evaluate the Jacobian matrix of the system, provided the system has no path variable defined.
template<typename T>
Mat< T >	Jacobian (const Vec< T > &variable_values) const
	Evaluate the Jacobian matrix of the system, provided the system has no path variable defined.
template<typename Derived, typename T>
void	JacobianInPlace (Mat< T > &J, const Eigen::MatrixBase< Derived > &variable_values, const T &path_variable_value) const
	Evaluate the Jacobian of the system, provided a path variable is defined for the system, in place.
template<typename Derived, typename T>
Mat< T >	Jacobian (const Eigen::MatrixBase< Derived > &variable_values, const T &path_variable_value) const
	Evaluate the Jacobian of the system, provided a path variable is defined for the system.
template<typename T>
Mat< T >	Jacobian (const Vec< T > &variable_values, const T &path_variable_value) const
	Compute the Jacobian of the system at the given variable and path-variable values.
template<typename Derived, typename T>
void	TimeDerivativeInPlace (Vec< T > &ds_dt, const Eigen::MatrixBase< Derived > &variable_values, const T &path_variable_value) const
	Compute the time-derivative of a system.
template<typename Derived, typename T>
Vec< T >	TimeDerivative (const Eigen::MatrixBase< Derived > &variable_values, const T &path_variable_value) const
	Compute the time-derivative of a system.
template<typename Derived, typename T>
void	TimeDerivativeInPlace (Vec< T > &ds_dt, const Eigen::MatrixBase< Derived > &variable_values) const
	Compute the time-derivative of the system in place, after setting the variable values.
template<typename Derived, typename T>
Vec< T >	TimeDerivative (const Eigen::MatrixBase< Derived > &variable_values) const
	Compute the time-derivative of a system.
template<typename T>
void	TimeDerivativeInPlace (Vec< T > &ds_dt) const
	Compute the time-derivative of the system in place, using the currently set variable values.
template<typename T>
Vec< T >	TimeDerivative () const
	Compute the time-derivative of a system.
void	Homogenize ()
	Homogenize the system, adding new homogenizing variables for each VariableGroup defined for the system.
void	Homogenize (VariableGroup const &provided_hom_vars)
	Homogenize the system reusing externally-supplied homogenizing variables – one per affine variable group, in group order – instead of minting fresh ones.
bool	IsHomogeneous () const
	Checks whether a system is homogeneous, overall.
bool	IsPolynomial () const
	Checks whether a system is polynomial, overall.
size_t	NumNaturalFunctions () const
	Get the number of functions in this system, excluding patches.
size_t	NumPatches () const
	Get the number of patches in this system.
size_t	NumTotalFunctions () const
	Get the total number of functions, including patches.
size_t	NumVariables () const
	Get the total number of variables in this system, including homogenizing variables.
size_t	NumNaturalVariables () const
	Get the number of variables in this system, NOT including homogenizing variables.
size_t	NumHomVariables () const
	Get the number of homogenizing variables in this system.
VariableGroup const &	HomogenizingVariables () const
	Get the homogenizing variables, one per affine variable group (in group order), or an empty container if the system is not homogenized.
VariableGroup const &	UngroupedVariables () const
	Get the ungrouped variables: those declared to the system but placed in no affine and no projective group.
size_t	NumTotalVariableGroups () const
	Get the total number of variable groups in the system, including both affine and homogenous.
size_t	NumVariableGroups () const
	Get the number of affine variable groups in the system.
size_t	NumUngroupedVariables () const
	get the number of variables which are ungrouped.
size_t	NumHomVariableGroups () const
	Get the number of homogeneous variable groups in the system.
size_t	NumConstants () const
	Get the number of constants in this system.
size_t	NumParameters () const
	Get the number of explicit parameters in this system.
size_t	NumImplicitParameters () const
	Get the number of implicit parameters in this system.
template<typename T>
void	SetVariables (const Vec< T > &new_values) const
	Set the values of the variables to be equal to the input values.
template<typename T>
void	SetPathVariable (T const &new_value) const
	Set the current value of the path variable.
template<typename T>
void	SetAndReset (Vec< T > const &new_space, T const &new_time) const
	Stage the system's current point (variables and path value) for a subsequent Eval/Jacobian.
template<typename T>
void	SetAndReset (Vec< T > const &new_space) const
	Stage the system's current point (variables only) for a subsequent Eval/Jacobian.
void	AddVariableGroup (VariableGroup const &v)
	Add a variable group to the system.
void	SetVariableGroups (std::vector< VariableGroup > const &groups)
	Replace the entire variable-group structure of the system.
void	AddHomVariableGroup (VariableGroup const &v)
	Add a homogeneous (projective) variable group to the system.
void	AddUngroupedVariable (Var const &v)
	Add variables to the system which are in neither a regular variable group, nor in a homogeneous group.
void	AddUngroupedVariables (VariableGroup const &v)
	Add variables to the system which are in neither a regular variable group, nor in a homogeneous group.
void	AddImplicitParameter (Var const &v)
	Add an implicit parameter to the system.
void	AddImplicitParameters (VariableGroup const &v)
	Add some implicit parameters to the system.
void	AddParameter (NE const &F)
	Add an explicit parameter to the system.
void	AddFunction (Nd const &F)
	Add a function to the system, as a bare expression.
void	AddFunctions (std::vector< Nd > const &F)
	Add some functions to the system.
void	AddBlock (Block b)
	Append an evaluation block (products-of-linears, blend, ...).
std::vector< Block > const &	Blocks () const
	Read-only access to the system's evaluation blocks (in evaluation order).
std::vector< Slice >	Slices () const
	Recover the linear-form slices embedded in this system, one per LinearFormsBlock (empty if the system has none).
void	ClearFunctions ()
	Remove the polynomial block (the System's natural functions), leaving any structured blocks and the variable structure / patch intact.
bool	HasBlocks () const
	Whether this system is evaluated from blocks rather than the function tree.
bool	HasStructuredBlocks () const
	Does the system have any non-polynomial (structured) block – products-of-linears, linear-forms, blend?
void	ClearBlocks ()
	Remove all evaluation blocks (the system reverts to its function-tree functions).
std::string	CanonicalEncodingText () const
	The canonical exact text encoding of this system – the persistent-identity substrate (ADR-0042).
detail::Digest256	ContentDigest () const
	The persistent content digest: SHA-256 of CanonicalEncodingText().
std::size_t	Hash () const
	In-process hash derived from ContentDigest() (its first 8 bytes).
bool	IsSame (System const &other) const
	Content equality: equal ContentDigest().
void	Seal ()
	Seal this system: memoize its ContentDigest() and forbid structural mutation (hashcons-on-freeze, ADR-0042).
bool	IsSealed () const
	Whether this system has been sealed against structural mutation (ADR-0042).
void	ReinternNodes (node::ReinternMemo &memo)
	Re-intern every node this system holds after deserialization (ADR-0042).
System	ExpandToFunctionTree () const
	Build an equivalent pure function-tree System: every block's functions expressed as function-tree nodes, gathered into a single PolynomialBlock, with the same variables, path variable, and patch (the patch is reused, not re-expressed).
std::vector< Nd >	NaturalFunctionsAsNodes () const
	The system's natural (pre-patch) functions as function-tree expression nodes, expanding any structured block.
System	Randomize () const
	Randomize an overdetermined system down to a square one, returning a NEW system.
System	Randomize (int codimension) const
	Randomize down to a chosen number of functions, returning a NEW system.
System	Randomize (Mat< complex_mp > const &R) const
	Randomize using a caller-supplied (exact) coefficient matrix R, leaving the functions in their current order.
Mat< complex_mp >	RandomizationMatrix () const
	The randomization matrix R of a system produced by Randomize() (its first RandomizationBlock's n x N coefficient matrix).
void	AddConstant (NE const &C)
	Add a constant function to the system.
void	AddPathVariable (Var const &v)
	Add a variable as the Path Variable to a System.
bool	HavePathVariable () const
	Query whether a path variable is set for this system.
const Var &	GetPathVariable () const
	Get the system's path variable (throws if none is defined).
std::set< std::string >	VariableNameSet () const
	Collect the names of every variable the user could reference.
VariableGroup	VariableOrdering () const
	Order the variables, by the order in which the groups were added.
const VariableGroup &	Variables () const
	Get the variables in the problem.
VariableGroup const &	AffineVariableGroup (size_t index) const
	Get an affine variable group the class has defined.
std::vector< unsigned >	VariableGroupSizes () const
	Get the sizes of the variable groups, according to the current ordering.
template<typename T>
Vec< T >	DehomogenizePoint (Vec< T > const &x) const
	Dehomogenize a point, using the variable grouping / structure of the system.
template<typename T>
auto	InfinityNormOfDehomogenized (Vec< T > const &x) const
	The infinity norm of a point after dehomogenization.
template<typename T, typename R>
bool	IsFinite (Vec< T > const &x, R const &threshold) const
	Is this point of mine finite, at the given threshold?
template<typename T, typename R>
bool	IsReal (Vec< T > const &x, R const &threshold) const
	Is this point of mine real, at the given threshold?
void	SetAuxiliaryVariableGroups (std::vector< unsigned > groups)
	Declare whole variable groups auxiliary: excluded from every judgement about a point.
void	SetAuxiliaryCoordinates (std::vector< unsigned > coordinates)
	Declare individual coordinates auxiliary, for a system whose grouping does not separate them.
std::vector< unsigned > const &	AuxiliaryVariableGroups () const
	The auxiliary variable groups, by FIFO index.
std::vector< unsigned > const &	AuxiliaryCoordinates () const
	The individually auxiliary coordinates, by index into a user-coordinate point.
bool	HaveAuxiliaryCoordinates () const
	Whether this system has any auxiliary coordinates at all (the fast path: usually not).
bool	CoordinateIsAuxiliary (unsigned index) const
	Whether one coordinate of a user-coordinate point is auxiliary.
size_t	NumAuxiliaryCoordinates () const
	How many of this system's user coordinates are auxiliary (a coordinate covered both by a group and individually counts once).
template<typename T>
Vec< T >	HomogenizePoint (Vec< T > const &x) const
	Take a point in user (dehomogenized) coordinates into this system's internal coordinates.
auto	Function (unsigned index) const
	Get a function by its index, as a function-tree node.
std::vector< Nd >	GetNaturalFunctions () const
	Get the functions as authored, as function-tree nodes, without the patch.
std::vector< Nd >	GetFunctions () const
	Get every row this system evaluates, as function-tree nodes.
std::vector< Nd >	PatchFunctionsAsNodes () const
	The patch equations, as function-tree nodes: one per variable group, or none when the system is unpatched.
void	CopyFunctions (System const &other)
	Append another system's functions to this one (issue #297).
unsigned	FIFOIndexOfGroup (VariableGroup const &g) const
	The FIFO index (0-based) of a variable group – its position in the canonical FIFO ordering (time_order_of_variable_groups_), across affine and projective groups together.
template<typename T>
Vec< T >	CoordinatesOfGroup (Vec< T > const &user_point, unsigned group_fifo_index) const
	Project a user-coordinate point onto one variable group: return just that group's coordinates.
std::pair< unsigned, unsigned >	SpanOfGroup (unsigned group_fifo_index) const
	Where one variable group sits in a user-coordinate point: (offset, size).
auto	VariableGroups () const
	Get the affine variable groups in the problem.
auto	HomVariableGroups () const
	Get the homogeneous (projective) variable groups in the problem.
const Var &	PathVariable () const
	Get the system's path variable node (the raw stored pointer; may be null if unset).
std::vector< Nd >	GetSpaceDerivatives () const
	Get the space derivatives.
std::vector< Nd >	GetTimeDerivatives () const
	Get the time derivatives of all functions.
template<typename NumT>
Eigen::NumTraits< NumT >::Real	CoefficientBound (unsigned num_evaluations=1) const
	Compute an estimate of an upper bound of the absolute values of the coefficients in the system.
int	DegreeBound () const
	Compute an upper bound on the degree of the system.
std::vector< int >	Degrees () const
	Get the degrees of the functions in the system, with respect to all variables.
std::vector< int >	Degrees (VariableGroup const &vars) const
	Get the degrees of the functions in the system, with respect to a group of variables.
void	ReorderFunctionsByDegreeDecreasing ()
	Sort the functions so they are in DEcreasing order by degree.
void	ReorderFunctionsByDegreeIncreasing ()
	Sort the functions so they are in INcreasing order by degree.
void	AutoPatch ()
	Let the system patch itself by the selected variable ordering, using the current variable groups.
void	CopyPatches (System const &other)
	Copy the patches from another system into this one.
Patch	GetPatch () const
	Get a copy of the system's patch.
bool	IsPatched () const
	Query whether a system is patched.
template<typename T>
Vec< T >	RescalePointToFitPatch (Vec< T > const &x) const
	Rescale a point so it lies on the system's patch, returning the rescaled copy.
template<typename T>
void	RescalePointToFitPatchInPlace (Vec< T > &x) const
	Rescale a point in place so it lies on the system's patch.
void	Describe (std::ostream &out, bool verbose=false) const
	Human-facing description of the system, block by block.
void	ClearVariables ()
	Clear the entire structure of variables in a system.
void	CopyVariableStructure (System const &other)
	Copy the entire structure of variables from within one system to another.
void	SimplifyFunctions ()
	Simplify the functions contained in the system.
void	SimplifyDerivatives () const
	Simplify the derivatives / jacobian / etc contained in the system.
void	Simplify ()
	Simplify as many aspects of the system as possible.
System &	operator+= (System const &rhs)
	Add two systems together.
System &	operator*= (Nd const &N)
	Multiply a system by an arbitrary node.

Static Public Member Functions
static System	FromCanonicalEncoding (std::string const &text)
	Rebuild a system from its canonical encoding text – the inverse of CanonicalEncodingText(), and the way an archived system comes back to life.

Friends
class	boost::serialization::access
void	swap (System &a, System &b)
	The free swap function for systems.
std::ostream &	operator<< (std::ostream &out, const System &s)
	Overloaded operator for printing to an arbirtary out stream.
const System	operator+ (System lhs, System const &rhs)
	Add two systems together.
const System	operator* (System s, Nd const &N)
	Multiply a system by an arbitrary node.
const System	operator* (Nd const &N, System const &s)
	Multiply a system by an arbitrary node.

Detailed Description

The fundamental polynomial system class for Bertini2.

Other System types are derived from this, but this class is not abstract.

Member Typedef Documentation

◆ Nd

using bertini::System::Nd = std::shared_ptr<node::Node>

Shorthand for a shared pointer to a generic expression-tree node.

◆ NE

using bertini::System::NE = std::shared_ptr<node::NamedExpression>

Shorthand for a shared pointer to a named expression (a function of the system).

◆ Var

using bertini::System::Var = std::shared_ptr<node::Variable>

Shorthand for a shared pointer to a variable node.

Constructor & Destructor Documentation

◆ System() [1/5]

bertini::System::System ( )

inline

The default constructor for a system.

◆ System() [2/5]

bertini::System::System ( std::vector< Nd > const & functions )

explicit

Construct a system from a list of functions.

The functions are added to the system, the variables appearing in them are automatically discovered (see node::GatherVariables), and those variables are placed into a single affine variable group (ordered alphabetically by name). This is a convenience for programmatically building a system without having to assemble the variable group by hand.

Parameters

functions The functions which define the system.

◆ System() [3/5]

bertini::System::System ( std::string const & input )

inlineexplicit

The copy operator, creates a system from a string using the Bertini parser for Bertini classic syntax.

◆ System() [4/5]

bertini::System::System ( System const & other )

The copy operator.

◆ System() [5/5]

bertini::System::System ( System && other )

inline

The move copy operator.

Member Function Documentation

◆ AddBlock()

void bertini::System::AddBlock ( Block b )

inline

Append an evaluation block (products-of-linears, blend, ...).

A block-composed system evaluates its blocks (in the order added) instead of the function-tree / SLP functions; blocks contribute the leading "natural" rows, with any patch appended after, exactly as for a classic system.

◆ AddConstant()

void bertini::System::AddConstant ( NE const & C )

Add a constant function to the system.

Constants must not depend on anything which can vary – they're constant!

Parameters

C	The constant to add.

◆ AddFunction()

void bertini::System::AddFunction ( Nd const & F )

Add a function to the system, as a bare expression.

Parameters

F	The function to add.

◆ AddFunctions()

void bertini::System::AddFunctions ( std::vector< Nd > const & F )

Add some functions to the system.

Parameters

F	The functions to add.

◆ AddHomVariableGroup()

void bertini::System::AddHomVariableGroup ( VariableGroup const & v )

Add a homogeneous (projective) variable group to the system.

The system must be homogeneous with respect to this group, though this is not verified at the time of this call.

Parameters

v	The variable group to add.

◆ AddImplicitParameter()

void bertini::System::AddImplicitParameter ( Var const & v )

Add an implicit parameter to the system.

Implicit parameters are advanced by the tracker akin to variable advancement.

Parameters

v	The implicit parameter to add.

◆ AddImplicitParameters()

void bertini::System::AddImplicitParameters ( VariableGroup const & v )

Add some implicit parameters to the system.

Implicit parameters are advanced by the tracker akin to variable advancement.

Parameters

v	The implicit parameters to add.

◆ AddParameter()

void bertini::System::AddParameter ( NE const & F )

Add an explicit parameter to the system.

Explicit parameters should depend only on the path variable, though this is not checked in this function.

Parameters

F	The parameter to add.

◆ AddPathVariable()

void bertini::System::AddPathVariable ( Var const & v )

Add a variable as the Path Variable to a System.

Will overwrite any previously declared path variable.

Parameters

v	The new path variable.

◆ AddUngroupedVariable()

void bertini::System::AddUngroupedVariable ( Var const & v )

Add variables to the system which are in neither a regular variable group, nor in a homogeneous group.

This is likely used for user-defined systems, Classic userhomotopy: 1;.

Parameters

v	The variable to add.

◆ AddUngroupedVariables()

void bertini::System::AddUngroupedVariables ( VariableGroup const & v )

Add variables to the system which are in neither a regular variable group, nor in a homogeneous group.

This is likely used for user-defined systems, Classic userhomotopy: 1;.

Parameters

v	The variables to add.

◆ AddVariableGroup()

void bertini::System::AddVariableGroup ( VariableGroup const & v )

Add a variable group to the system.

The system may be homogenized with respect to this variable group, though this is not done at the time of this call.

Parameters

v	The variable group to add.

◆ AffineVariableGroup()

VariableGroup const & bertini::System::AffineVariableGroup ( size_t index ) const

inline

Get an affine variable group the class has defined.

It is up to you to ensure this group exists.

◆ AutoPatch()

void bertini::System::AutoPatch ( )

inline

Let the system patch itself by the selected variable ordering, using the current variable groups.

Homogeneous variable groups and affine variable groups will be supplied a patch equation. Ungrouped variables will not.

◆ AuxiliaryCoordinates()

std::vector< unsigned > const & bertini::System::AuxiliaryCoordinates ( ) const

inline

The individually auxiliary coordinates, by index into a user-coordinate point.

◆ AuxiliaryVariableGroups()

std::vector< unsigned > const & bertini::System::AuxiliaryVariableGroups ( ) const

inline

The auxiliary variable groups, by FIFO index.

◆ Blocks()

std::vector< Block > const & bertini::System::Blocks ( ) const

inline

Read-only access to the system's evaluation blocks (in evaluation order).

For introspection / testing – e.g. reading a RandomizationBlock's matrix; the variant itself stays out of the Python surface.

◆ CanonicalEncodingText()

std::string bertini::System::CanonicalEncodingText ( ) const

The canonical exact text encoding of this system – the persistent-identity substrate (ADR-0042).

Versioned (b2sysenc/1 header, which also pins the session canonicalization settings), exact (coefficients by their exact digits), and deterministic: everything evaluation-relevant is included (functions, variable groups + types + time order, path variable, parameters, patch and randomization/blend coefficients – randomness is identity), and only transient eval state is excluded. Any change to what this emits is digest-breaking: bump the version and the golden fixture in the same commit.

◆ ClearBlocks()

void bertini::System::ClearBlocks ( )

inline

Remove all evaluation blocks (the system reverts to its function-tree functions).

Mainly for testing the block path against the function-tree path.

◆ ClearFunctions()

void bertini::System::ClearFunctions ( )

inline

Remove the polynomial block (the System's natural functions), leaving any structured blocks and the variable structure / patch intact.

Used to turn a copy of a System into a homotopy shell whose rows come from a blend block rather than its own functions (FormHomotopy): h = target; h.ClearFunctions(); h.AddBlock(blend);.

◆ ClearVariables()

void bertini::System::ClearVariables ( )

Clear the entire structure of variables in a system.

Reconstructing it is up to you.

◆ CoefficientBound()

template<typename NumT>

Eigen::NumTraits< NumT >::Real bertini::System::CoefficientBound ( unsigned num_evaluations = 1 ) const

Compute an estimate of an upper bound of the absolute values of the coefficients in the system.

Parameters

num_evaluations The number of times to compute this estimate. Default is 1.

Returns: An upper bound on the absolute values of the coefficients.

◆ ContentDigest()

detail::Digest256 bertini::System::ContentDigest ( ) const

The persistent content digest: SHA-256 of CanonicalEncodingText().

Stable across runs, compilers, and sessions – the L2 identity key a solutions database references systems (and homotopies) by.

◆ CoordinateIsAuxiliary()

bool bertini::System::CoordinateIsAuxiliary ( unsigned index ) const

Whether one coordinate of a user-coordinate point is auxiliary.

Parameters

index The coordinate's index within a point in user coordinates.

Returns: Whether it is excluded from the judgements.

◆ CoordinatesOfGroup()

template<typename T>

Vec< T > bertini::System::CoordinatesOfGroup	(	Vec< T > const &	user_point,
		unsigned	group_fifo_index ) const

inline

Project a user-coordinate point onto one variable group: return just that group's coordinates.

The point is in user (dehomogenized) coordinates – length NumNaturalVariables(), laid out in the FIFO group order. Each group occupies a contiguous slice; this returns the slice for the group at FIFO position group_fifo_index. Affine groups return their (dehomogenized) affine coordinates; projective groups are returned as-is – their coordinates are not dehomogenized. Handy for an augmented system (critical points, deflation) where only one group's coordinates matter.

Template Parameters

T	the point's number type (complex_dbl or complex_mp).

Parameters

user_point	The point, in user coordinates.
group_fifo_index	The FIFO position of the group to extract (see FIFOIndexOfGroup).

◆ CopyFunctions()

void bertini::System::CopyFunctions ( System const & other )

inline

Append another system's functions to this one (issue #297).

Syntactic sugar for AddFunctions(other.GetNaturalFunctions()) – handy for building a new system up from an existing one's equations (e.g. a critical-point system that starts from the original functions). The functions are shared nodes, so the two systems' variables line up.

Parameters

other The system whose functions to copy in.

◆ CopyPatches()

void bertini::System::CopyPatches ( System const & other )

Copy the patches from another system into this one.

◆ CopyVariableStructure()

void bertini::System::CopyVariableStructure ( System const & other )

Copy the entire structure of variables from within one system to another.

This copies everything – ungrouped variables, variable groups, homogenizing variables, the path variable, the ordering of the variables.

Parameters

other Another system from which to copy the variable structure.

This operation does NOT affect the functions in any way. It is up to the user to make the functions actually depend on these variables.

◆ DegreeBound()

int bertini::System::DegreeBound ( ) const

Compute an upper bound on the degree of the system.

This number will be wrong if the system is non-polynomial, because degree for non-polynomial systems is not defined.

◆ Degrees() [1/2]

std::vector< int > bertini::System::Degrees ( ) const

Get the degrees of the functions in the system, with respect to all variables.

Returns: A vector containing the degrees of the functions. Negative numbers indicate the function is non-polynomial.

◆ Degrees() [2/2]

std::vector< int > bertini::System::Degrees ( VariableGroup const & vars ) const

Get the degrees of the functions in the system, with respect to a group of variables.

Returns: A vector containing the degrees of the functions. Negative numbers indicate the function is non-polynomial.

Parameters

vars	A group of variables with respect to which you wish to compute degrees. Needs not be a group with respect to the system.

◆ DehomogenizePoint()

template<typename T>

Vec< T > bertini::System::DehomogenizePoint ( Vec< T > const & x ) const

inline

Dehomogenize a point, using the variable grouping / structure of the system.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Exceptions

std::runtime_error,if there is a mismatch between the number of variables in the input point, and the total number of var

◆ Describe()

void bertini::System::Describe	(	std::ostream &	out,
		bool	verbose = false ) const

Human-facing description of the system, block by block.

Each block describes the rows it owns (labelled f_k in function-vector order). verbose == false (the default, used by operator<< / Python str) shows placeholder symbols for the structured blocks' matrices/coefficients; verbose == true reveals the actual numbers and the underlying functions of randomization / blend blocks. This is for reading, not re-parsing.

◆ Differentiate()

void bertini::System::Differentiate ( ) const

Compute and internally store the symbolic Jacobian of the system.

◆ Eval() [1/5]

template<typename T>

Vec< T > bertini::System::Eval ( ) const

inline

Evaluate the system using the previously set variable (and time) values, creating vector of function values.

It is up to YOU to ensure that the system's variables (and path variable) has been set prior to this function call.

Returns: The function values of the system

◆ Eval() [2/5]

template<typename Derived>

Derived::PlainObject bertini::System::Eval ( const Eigen::MatrixBase< Derived > & variable_values ) const

inline

Evaluate the system, provided the system has no path variable defined.

Causes the current variable values to be set in the system. Resets the function tree's stored numbers.

Exceptions

std::runtime_error,if a path variable IS defined, but you didn't pass it a value. Also throws if the number of variables doesn't match.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

variable_values The values of the variables, for the evaluation.

◆ Eval() [3/5]

template<typename Derived, typename T>

Vec< T > bertini::System::Eval	(	const Eigen::MatrixBase< Derived > &	variable_values,
		const T &	path_variable_value ) const

inline

Evaluate the system, provided a path variable is defined for the system.

Exceptions

std::runtime_error,if a path variable is NOT defined, and you passed it a value. Also throws if the number of variables doesn't match.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

variable_values	The values of the variables, for the evaluation.
path_variable_value	The current value of the path variable.

◆ Eval() [4/5]

template<typename T>

Vec< T > bertini::System::Eval ( const Vec< T > & variable_values ) const

inline

Evaluate the system at the given variable values (no path variable defined).

Template Parameters

T	The number type for evaluation (e.g. complex_dbl or complex_mp).

Parameters

variable_values The values of the variables, for the evaluation.

Returns: The vector of function values.

◆ Eval() [5/5]

template<typename T>

Vec< T > bertini::System::Eval	(	const Vec< T > &	variable_values,
		const T &	path_variable_value ) const

inline

Evaluate the system at the given variable values and path-variable value.

Template Parameters

T	The number type for evaluation (e.g. complex_dbl or complex_mp).

Parameters

variable_values	The values of the variables, for the evaluation.
path_variable_value	The current value of the path variable.

Returns: The vector of function values.

◆ EvalInPlace() [1/3]

template<typename T>

void bertini::System::EvalInPlace ( Vec< T > & function_values ) const

inline

Evaluate the system using the previously set variable (and time) values, in place.

It is up to YOU to ensure that the system's variables (and path variable) has been set prior to this function call.

Parameters

function_values The vector to write the function values into.

◆ EvalInPlace() [2/3]

template<typename T, typename Derived>

void bertini::System::EvalInPlace	(	Vec< T > &	function_values,
		const Eigen::MatrixBase< Derived > &	variable_values ) const

inline

Evaluate the system, provided the system has no path variable defined, in place.

Causes the current variable values to be set in the system. Resets the function tree's stored numbers.

Exceptions

std::runtime_error,if a path variable IS defined, but you didn't pass it a value. Also throws if the number of variables doesn't match.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

function_values	The vector to write the function values into.
variable_values	The values of the variables, for the evaluation.

◆ EvalInPlace() [3/3]

template<typename Derived, typename T>

void bertini::System::EvalInPlace	(	Vec< T > &	function_values,
		const Eigen::MatrixBase< Derived > &	variable_values,
		const T &	path_variable_value ) const

inline

Evaluate the system, provided a path variable is defined for the system, in place.

Exceptions

std::runtime_error,if a path variable is NOT defined, and you passed it a value. Also throws if the number of variables doesn't match.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

function_values	The vector to write the function values into.
variable_values	The values of the variables, for the evaluation.
path_variable_value	The current value of the path variable.

◆ ExpandToFunctionTree()

System bertini::System::ExpandToFunctionTree ( ) const

Build an equivalent pure function-tree System: every block's functions expressed as function-tree nodes, gathered into a single PolynomialBlock, with the same variables, path variable, and patch (the patch is reused, not re-expressed).

This is a verification / interop oracle — the block path exists for performance and precision control, so this is NOT a replacement for block evaluation. It lets the block-composed evaluation be cross-checked against the function-tree path (eval / Jacobian must agree). Scoped to the current block types; a block that cannot be expanded throws.

◆ FIFOIndexOfGroup()

unsigned bertini::System::FIFOIndexOfGroup ( VariableGroup const & g ) const

inline

The FIFO index (0-based) of a variable group – its position in the canonical FIFO ordering (time_order_of_variable_groups_), across affine and projective groups together.

Matches by variable-node identity, so pass a group whose variables are the system's own. Throws if the group is not one of this system's groups.

Parameters

g	The variable group to locate.

◆ FromCanonicalEncoding()

System bertini::System::FromCanonicalEncoding ( std::string const & text )

static

Rebuild a system from its canonical encoding text – the inverse of CanonicalEncodingText(), and the way an archived system comes back to life.

The records archive stores every system and homotopy as this exact text (the digest preimage), so this is what makes a record reloadable: the rebuilt system's ContentDigest() equals the archived digest, which is the proof it is the same object. Every node is rebuilt through the intern tables, every block with its exact coefficients (at their stored precisions), the patch with its coefficients, and operand systems inside randomization and blend blocks recursively.

Refuses loudly (std::runtime_error) an encoding whose version is not the one this build writes, one written under different session canonicalization settings (monomial order, canonicalize-by-default, power-fold: they are in the header because they shape the trees, so decoding under other settings would not reproduce the digest), and any text that does not fit the grammar.

Parameters

text	The canonical encoding, as CanonicalEncodingText() produced it.

Returns: The rebuilt system, unsealed and mutable like a freshly parsed one.

◆ Function()

auto bertini::System::Function ( unsigned index ) const

inline

Get a function by its index, as a function-tree node.

Indexes every row the system evaluates, in evaluation order: the functions as authored, then one patch equation per variable group if the system is patched. Once a system is patched the patch is one of its functions – it is a row of the vector an evaluation returns, and a row of the Jacobian – so it is reachable here rather than being a thing the caller has to know about separately. The count is NumTotalFunctions().

Works for every block type: structured blocks (linear forms, products of linears, randomization, blend) are expanded to their node form on demand.

Parameters

index Which row, in [0, NumTotalFunctions()).

Exceptions

std::out_of_range If the index is past the end.

◆ GetFunctions()

std::vector< Nd > bertini::System::GetFunctions ( ) const

inline

Get every row this system evaluates, as function-tree nodes.

The functions as authored, then one patch equation per variable group when the system is patched – the same rows, in the same order, that Eval returns values for. Agrees with NumTotalFunctions() and with Function(i).

◆ GetNaturalFunctions()

std::vector< Nd > bertini::System::GetNaturalFunctions ( ) const

inline

Get the functions as authored, as function-tree nodes, without the patch.

Expands any structured block (so it agrees with NumNaturalFunctions(), even for systems built purely from a slice / start-system block). For every row the system evaluates, patch included, use GetFunctions().

◆ GetPatch()

Patch bertini::System::GetPatch ( ) const

inline

Get a copy of the system's patch.

◆ GetPathVariable()

const Var & bertini::System::GetPathVariable ( ) const

Get the system's path variable (throws if none is defined).

◆ GetSpaceDerivatives()

std::vector< Nd > bertini::System::GetSpaceDerivatives ( ) const

Get the space derivatives.

These are as computed using the Derivatives method, not Jacobian nodes. They are stored in column-major order, so stride over variables first.

for (int jj = 0; jj < num_vars; ++jj)
   for (int ii = 0; ii < num_functions; ++ii)
       space_derivatives_[ii+jj*num_functions] = functions_[ii]->Differentiate(vars[jj]);

◆ GetTimeDerivatives()

std::vector< Nd > bertini::System::GetTimeDerivatives ( ) const

Get the time derivatives of all functions.

These are as computed using the Derivatives method, not Jacobian nodes. Stored in order of functions.

◆ HasBlocks()

bool bertini::System::HasBlocks ( ) const

inline

Whether this system is evaluated from blocks rather than the function tree.

◆ Hash()

std::size_t bertini::System::Hash ( ) const

In-process hash derived from ContentDigest() (its first 8 bytes).

IsSame(other) implies equal Hash() by construction.

◆ HasStructuredBlocks()

bool bertini::System::HasStructuredBlocks ( ) const

inline

Does the system have any non-polynomial (structured) block – products-of-linears, linear-forms, blend?

Every system has a PolynomialBlock for its functions after the fold, so HasBlocks() is no longer the right test for "needs whole-System blending"; this is. (e.g. an MHom start system has a products block; a total-degree start does not.)

◆ HaveAuxiliaryCoordinates()

bool bertini::System::HaveAuxiliaryCoordinates ( ) const

inline

Whether this system has any auxiliary coordinates at all (the fast path: usually not).

◆ HavePathVariable()

bool bertini::System::HavePathVariable ( ) const

Query whether a path variable is set for this system.

Returns: true if have a path variable, false if not.

◆ Homogenize() [1/2]

void bertini::System::Homogenize ( )

Homogenize the system, adding new homogenizing variables for each VariableGroup defined for the system.

Exceptions

std::runtime_error,if the system is not polynomial, has a mismatch on the number of homogenizing variables and the number of variable groups (this would result from a partially homogenized system), or the homogenizing variable names somehow get screwed up by having duplicates.

◆ Homogenize() [2/2]

void bertini::System::Homogenize ( VariableGroup const & provided_hom_vars )

Homogenize the system reusing externally-supplied homogenizing variables – one per affine variable group, in group order – instead of minting fresh ones.

Used by RandomizationBlock so a wrapped operand system shares the owning system's homogenizing variables (the h-power deficit factors and the operand's functions must live in the same homogeneous coordinates). Otherwise behaves exactly like Homogenize() on a fresh system.

Exceptions

std::runtime_error if the system is non-polynomial, already homogenized, or the number of supplied homogenizing variables does not equal the number of affine variable groups.

◆ HomogenizePoint()

template<typename T>

Vec< T > bertini::System::HomogenizePoint ( Vec< T > const & x ) const

inline

Take a point in user (dehomogenized) coordinates into this system's internal coordinates.

Two steps: (1) insert the homogenizing coordinate, with value 1, for each affine variable group, per the FIFO variable ordering; (2) if the system is patched, rescale the result onto the patch. The result is the projectively-identical point expressed in the coordinates the solver works in – suitable for comparison with internal-coordinate solutions, or as a start point for further tracking re-using this system's patch.

This is the inverse of DehomogenizePoint: DehomogenizePoint(HomogenizePoint(p)) == p. On an unhomogenized, unpatched system this is the identity.

Template Parameters

T	the number-type. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Exceptions

std::runtime_error,if there is a mismatch between the number of variables in the input point, and the number of natural variables of the system.

◆ HomogenizingVariables()

VariableGroup const & bertini::System::HomogenizingVariables ( ) const

inline

Get the homogenizing variables, one per affine variable group (in group order), or an empty container if the system is not homogenized.

◆ HomVariableGroups()

auto bertini::System::HomVariableGroups ( ) const

inline

Get the homogeneous (projective) variable groups in the problem.

◆ InfinityNormOfDehomogenized()

template<typename T>

auto bertini::System::InfinityNormOfDehomogenized ( Vec< T > const & x ) const

inline

The infinity norm of a point after dehomogenization.

This is the single canonical "how big is this point, in user coordinates" measurement. An endpoint going to infinity has its dehomogenized coordinates blow up, so this is what the endgames test against Security::max_norm to detect divergence, and what the zero-dim solver tests against endpoint_finite_threshold to classify finite/infinite endpoints. Routing both through here keeps those decisions consistent: never compare the raw internal (homogenized, on-patch) coordinates, which carry the homogenizing variable and patch scaling.

Template Parameters

T	the number-type of the point. Returns the associated real magnitude type.

◆ IsFinite()

template<typename T, typename R>

bool bertini::System::IsFinite	(	Vec< T > const &	x,
		R const &	threshold ) const

inline

Is this point of mine finite, at the given threshold?

The system owns the judgement, because the system is what knows which of its coordinates the question is about (see SetAuxiliaryVariableGroups). Every caller supplies its own threshold and none of them re-derives the measurement: the tracker's path truncation, the endgame's Security::max_norm divergence test, and the solver's finite/infinite classification are the same question asked with three different amounts of patience.

Template Parameters

T	The point's number type.
R	The threshold's number type.

Parameters

x	The point, in this system's internal (homogenized, on-patch) coordinates.
threshold	The largest coordinate magnitude that still counts as finite.

Returns: Whether the point is finite at that threshold.

◆ IsHomogeneous()

bool bertini::System::IsHomogeneous ( ) const

Checks whether a system is homogeneous, overall.

This means with respect to each variable group (including homogenizing variable if defined), homogeneous variable group, and ungrouped variables, if defined.

Exceptions

std::runtime_error,if the number of homogenizing variables does not match the number of variable_groups.

Returns: true if homogeneous, false if not

◆ IsPatched()

bool bertini::System::IsPatched ( ) const

inline

Query whether a system is patched.

◆ IsPolynomial()

bool bertini::System::IsPolynomial ( ) const

Checks whether a system is polynomial, overall.

This means with respect to each variable group (including homogenizing variable if defined), homogeneous variable group, and ungrouped variables, if defined.

Exceptions

std::runtime_error,if the number of homogenizing variables does not match the number of variable_groups.

Returns: true if polynomial, false if not.

◆ IsReal()

template<typename T, typename R>

bool bertini::System::IsReal	(	Vec< T > const &	x,
		R const &	threshold ) const

inline

Is this point of mine real, at the given threshold?

The companion to IsFinite, over the same coordinates: the largest imaginary part among the coordinates that are not auxiliary. A point whose only complex coordinate is an auxiliary one is real, which is the whole reason auxiliary coordinates exist (b2#403).

Template Parameters

T	The point's number type.
R	The threshold's number type.

Parameters

x	The point, in this system's internal (homogenized, on-patch) coordinates.
threshold	The largest imaginary part that still counts as real.

Returns: Whether the point is real at that threshold.

◆ IsSame()

bool bertini::System::IsSame ( System const & other ) const

Content equality: equal ContentDigest().

Parameters

other The system to compare against.

Returns: true iff the two systems have identical canonical encodings.

◆ IsSealed()

bool bertini::System::IsSealed ( ) const

Whether this system has been sealed against structural mutation (ADR-0042).

◆ Jacobian() [1/4]

template<typename T>

Mat< T > bertini::System::Jacobian ( ) const

inline

Evaluate the Jacobian matrix of the system, using the previous space and time values.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

◆ Jacobian() [2/4]

template<typename Derived, typename T>

Mat< T > bertini::System::Jacobian	(	const Eigen::MatrixBase< Derived > &	variable_values,
		const T &	path_variable_value ) const

inline

Evaluate the Jacobian of the system, provided a path variable is defined for the system.

Exceptions

std::runtime_error,if a path variable is NOT defined, and you passed it a value. Also throws if the number of variables doesn't match.

Returns: The Jacobian matrix.

Parameters

variable_values	The values of the variables, for the evaluation.
path_variable_value	The current value of the path variable.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

◆ Jacobian() [3/4]

template<typename T>

Mat< T > bertini::System::Jacobian ( const Vec< T > & variable_values ) const

inline

Evaluate the Jacobian matrix of the system, provided the system has no path variable defined.

Exceptions

std::runtime_error,if a path variable IS defined, but you didn't pass it a value. Also throws if the number of variables doesn't match.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

variable_values The values of the variables, for the evaluation.

◆ Jacobian() [4/4]

template<typename T>

Mat< T > bertini::System::Jacobian	(	const Vec< T > &	variable_values,
		const T &	path_variable_value ) const

inline

Compute the Jacobian of the system at the given variable and path-variable values.

Template Parameters

T	The number type for evaluation (e.g. complex_dbl or complex_mp).

Parameters

variable_values	The values of the variables.
path_variable_value	The current value of the path variable.

Returns: The Jacobian matrix.

◆ JacobianInPlace() [1/3]

template<typename T>

void bertini::System::JacobianInPlace ( Mat< T > & J ) const

inline

Evaluate the Jacobian matrix of the system, using the previous space and time values, in place.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

This is analogous to J = sys.JacobianInPlace();

The input matrix must have the correct size already

◆ JacobianInPlace() [2/3]

template<typename Derived, typename T>

void bertini::System::JacobianInPlace	(	Mat< T > &	J,
		const Eigen::MatrixBase< Derived > &	variable_values,
		const T &	path_variable_value ) const

inline

Evaluate the Jacobian of the system, provided a path variable is defined for the system, in place.

Exceptions

std::runtime_error,if a path variable is NOT defined, and you passed it a value. Also throws if the number of variables doesn't match.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

J	The matrix to write the Jacobian into.
variable_values	The values of the variables, for the evaluation.
path_variable_value	The current value of the path variable.

◆ JacobianInPlace() [3/3]

template<typename T>

void bertini::System::JacobianInPlace	(	Mat< T > &	J,
		const Vec< T > &	variable_values ) const

inline

Evaluate the Jacobian matrix of the system, provided the system has no path variable defined.

Exceptions

std::runtime_error,if a path variable IS defined, but you didn't pass it a value. Also throws if the number of variables doesn't match.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

J	The matrix to write the Jacobian into.
variable_values	The values of the variables, for the evaluation.

◆ NaturalFunctionsAsNodes()

std::vector< Nd > bertini::System::NaturalFunctionsAsNodes ( ) const

The system's natural (pre-patch) functions as function-tree expression nodes, expanding any structured block.

Used by ExpandToFunctionTree and, recursively, by BlendBlock expansion (a blend is sum_i c_i(t) * operand_i, each operand expanded).

◆ NumAuxiliaryCoordinates()

size_t bertini::System::NumAuxiliaryCoordinates ( ) const

How many of this system's user coordinates are auxiliary (a coordinate covered both by a group and individually counts once).

◆ NumConstants()

size_t bertini::System::NumConstants ( ) const

Get the number of constants in this system.

◆ NumHomVariableGroups()

size_t bertini::System::NumHomVariableGroups ( ) const

Get the number of homogeneous variable groups in the system.

◆ NumHomVariables()

size_t bertini::System::NumHomVariables ( ) const

Get the number of homogenizing variables in this system.

◆ NumImplicitParameters()

size_t bertini::System::NumImplicitParameters ( ) const

Get the number of implicit parameters in this system.

◆ NumNaturalFunctions()

size_t bertini::System::NumNaturalFunctions ( ) const

Get the number of functions in this system, excluding patches.

◆ NumNaturalVariables()

size_t bertini::System::NumNaturalVariables ( ) const

Get the number of variables in this system, NOT including homogenizing variables.

◆ NumParameters()

size_t bertini::System::NumParameters ( ) const

Get the number of explicit parameters in this system.

◆ NumPatches()

size_t bertini::System::NumPatches ( ) const

inline

Get the number of patches in this system.

◆ NumTotalFunctions()

size_t bertini::System::NumTotalFunctions ( ) const

Get the total number of functions, including patches.

◆ NumTotalVariableGroups()

size_t bertini::System::NumTotalVariableGroups ( ) const

Get the total number of variable groups in the system, including both affine and homogenous.

Ignores the ungrouped variables, because they are not in any group.

◆ NumUngroupedVariables()

size_t bertini::System::NumUngroupedVariables ( ) const

get the number of variables which are ungrouped.

◆ NumVariableGroups()

size_t bertini::System::NumVariableGroups ( ) const

Get the number of affine variable groups in the system.

◆ NumVariables()

size_t bertini::System::NumVariables ( ) const

Get the total number of variables in this system, including homogenizing variables.

◆ operator*=()

System & bertini::System::operator*= ( Nd const & N )

Multiply a system by an arbitrary node.

Can be used for defining a coupling of a target and start system through a path variable. Does not affect path variable declaration, or anything else. It is up to you to ensure the system depends on this node properly.

◆ operator+=()

System & bertini::System::operator+= ( System const & rhs )

Add two systems together.

Exceptions

std::runtime_error,if	the systems are not of compatible size – either in number of functions, or variables. Does not check the structure of the variables, just the numbers.
std::runtime_error,if	the patches are not compatible. The patches must be either the same, absent, or present in one system. They propagate to the resulting system.

◆ operator=() [1/2]

System & bertini::System::operator= ( const System & other )

The assignment operator.

◆ operator=() [2/2]

System & bertini::System::operator= ( System && other )

default

The move assignment operator.

◆ PatchFunctionsAsNodes()

std::vector< Nd > bertini::System::PatchFunctionsAsNodes ( ) const

The patch equations, as function-tree nodes: one per variable group, or none when the system is unpatched.

The patch equation for group ii is sum_jj c_jj * x_jj - 1, over that group's variables in the system's variable ordering, which is exactly what the patch evaluates.

◆ PathVariable()

const Var & bertini::System::PathVariable ( ) const

inline

Get the system's path variable node (the raw stored pointer; may be null if unset).

◆ RandomizationMatrix()

Mat< complex_mp > bertini::System::RandomizationMatrix ( ) const

The randomization matrix R of a system produced by Randomize() (its first RandomizationBlock's n x N coefficient matrix).

Exceptions

std::runtime_error if this system carries no randomization block.

◆ Randomize() [1/3]

System bertini::System::Randomize ( ) const

Randomize an overdetermined system down to a square one, returning a NEW system.

An overdetermined system (N natural functions, n variables, N > n) is replaced by n generic combinations whose isolated solutions still contain this system's – the standard squaring-up so the isolated solutions can be found by homotopy continuation (solve the square result, then discard the extraneous solutions by re-evaluating this system).

The returned system carries a single RandomizationBlock wrapping a copy of this system; the combination is g_i = sum_j R_ij f_j (the block applies the homogenizing-variable powers needed when the functions differ in degree). This system is not mutated – any internal degree sorting happens on the copy.

Auto form: for a single affine variable group the functions are sorted by descending degree and R = [I | C] (C random), giving the optimal total-degree path count (the product of the n largest degrees); for several variable groups a dense random R is used with a common target multidegree.

Exceptions

std::runtime_error if the system is underdetermined (fewer functions than variables).

◆ Randomize() [2/3]

System bertini::System::Randomize ( int codimension ) const

Randomize down to a chosen number of functions, returning a NEW system.

Like the auto Randomize(), but instead of squaring to the affine dimension this produces exactly codimension generic combinations of this system's natural functions – the general "randomize down to codimension c" used when studying lower-dimensional components (e.g. in numerical irreducible decomposition), where codimension is the number of functions kept. codimension == 1 yields a single function. The functions are sorted by descending degree (on a copy – this system is not mutated) so the codimension largest-degree functions land on the identity block, keeping the total-degree path count optimal.

Parameters

codimension The number of randomized functions to produce. Must be positive and strictly less than the number of natural functions (randomization must reduce the count).

Exceptions

std::runtime_error if codimension < 1, or if codimension is greater than or equal to the number of natural functions (cannot randomize to the same or more functions).

◆ Randomize() [3/3]

System bertini::System::Randomize ( Mat< complex_mp > const & R ) const

Randomize using a caller-supplied (exact) coefficient matrix R, leaving the functions in their current order.

R has one row per desired randomized function and one column per natural function of this system. Returns a NEW system; this one is not mutated.

Exceptions

std::runtime_error if R's column count does not equal this system's natural-function count.

◆ ReinternNodes()

void bertini::System::ReinternNodes ( node::ReinternMemo & memo )

Re-intern every node this system holds after deserialization (ADR-0042).

Deserialization constructs nodes outside the intern tables, so a loaded system's nodes would fork the intern universe. This remaps functions, constant subfunctions, variable groups, homogenizing variables, path variable, parameters, the pre-homogenization snapshot, and every node-holding block (operand systems recursively) through node::Reintern with ONE shared memo – so group members and in-tree variables remain the same objects. Derived caches referencing old nodes (derivatives, SLPs, the ordering cache) are dropped and recompute on demand.

Content is unchanged (the digest is invariant), so this is allowed on a sealed system. Loading a System from an archive calls this itself (ADR-0068), so a caller rarely needs to; LoadSystemUnified goes one step further and interns the System.

Parameters

memo	The pass's memo; share it when re-interning several loaded objects.

◆ ReorderFunctionsByDegreeDecreasing()

void bertini::System::ReorderFunctionsByDegreeDecreasing ( )

Sort the functions so they are in DEcreasing order by degree.

◆ ReorderFunctionsByDegreeIncreasing()

void bertini::System::ReorderFunctionsByDegreeIncreasing ( )

Sort the functions so they are in INcreasing order by degree.

◆ RescalePointToFitPatch()

template<typename T>

Vec< T > bertini::System::RescalePointToFitPatch ( Vec< T > const & x ) const

inline

Rescale a point so it lies on the system's patch, returning the rescaled copy.

Template Parameters

T	The number type.

Parameters

x	The point to rescale.

Returns: The rescaled point.

◆ RescalePointToFitPatchInPlace()

template<typename T>

void bertini::System::RescalePointToFitPatchInPlace ( Vec< T > & x ) const

inline

Rescale a point in place so it lies on the system's patch.

Template Parameters

T	The number type.

Parameters

[in,out] x The point to rescale.

◆ Seal()

void bertini::System::Seal ( )

Seal this system: memoize its ContentDigest() and forbid structural mutation (hashcons-on-freeze, ADR-0042).

Idempotent.

After sealing, structural mutators (AddFunction, Homogenize, AutoPatch, ...) throw std::logic_error; transient operations (SetVariables, precision, Differentiate, evaluation) remain allowed. Copying a sealed system yields an UNSEALED copy – the copy-on-write escape hatch. ("Seal", not "freeze": ADR-0027's freeze set is evaluation-time input currying, a different concept; they compose.)

◆ SetAndReset() [1/2]

template<typename T>

void bertini::System::SetAndReset ( Vec< T > const & new_space ) const

inline

Stage the system's current point (variables only) for a subsequent Eval/Jacobian.

Template Parameters

T	The number type.

Parameters

new_space The new variable values.

◆ SetAndReset() [2/2]

template<typename T>

void bertini::System::SetAndReset	(	Vec< T > const &	new_space,
		T const &	new_time ) const

inline

Stage the system's current point (variables and path value) for a subsequent Eval/Jacobian.

Formerly also reset the function-tree node caches; node-level evaluation is gone, so there is nothing to reset – the SLP carries its own state.

Template Parameters

T	The number type.

Parameters

new_space	The new variable values.
new_time	The new path-variable value.

◆ SetAuxiliaryCoordinates()

void bertini::System::SetAuxiliaryCoordinates ( std::vector< unsigned > coordinates )

Declare individual coordinates auxiliary, for a system whose grouping does not separate them.

Indices into a point in USER coordinates (length NumNaturalVariables(), the FIFO group order) – the coordinates as the author wrote them, not the internal homogenized ones, so an index survives Homogenize() and AutoPatch(). These are the union with whatever the auxiliary groups cover.

Parameters

coordinates Indices of the auxiliary coordinates; pass an empty vector for none.

Exceptions

std::out_of_range	if an index is not a coordinate of this system.
std::runtime_error	if it would leave no coordinate to judge.

See also: SetAuxiliaryVariableGroups, IsFinite, IsReal

◆ SetAuxiliaryVariableGroups()

void bertini::System::SetAuxiliaryVariableGroups ( std::vector< unsigned > groups )

Declare whole variable groups auxiliary: excluded from every judgement about a point.

An auxiliary coordinate is one this system carries for the construction's sake rather than for the answer's – a null-vector block with its own patch, a slack coordinate – so that its magnitude is not a quantity anybody chose. Declaring it auxiliary says only that: leave it out of IsFinite and IsReal, and therefore out of path truncation, the endgame's divergence check, and the finite/real classification. Bertini attaches no other meaning to it, and the coordinate is tracked, recorded and returned exactly as before.

Which coordinates are auxiliary is part of the system's content identity: a system that says where to judge it is a different question than one that does not, because the tracker will truncate differently. Making every coordinate auxiliary is refused – a point with nothing to judge would be unconditionally finite and real.

Parameters

groups FIFO indices of the auxiliary variable groups; pass an empty vector for none.

Exceptions

std::out_of_range	if a group index does not name a group.
std::runtime_error	if it would leave no coordinate to judge.

See also: SetAuxiliaryCoordinates, IsFinite, IsReal

◆ SetPathVariable()

template<typename T>

void bertini::System::SetPathVariable ( T const & new_value ) const

inline

Set the current value of the path variable.

Exceptions

std::runtime_error,if a path variable is not defined.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Parameters

new_value The new updated values for the path variable.

◆ SetVariableGroups()

void bertini::System::SetVariableGroups ( std::vector< VariableGroup > const & groups )

Replace the entire variable-group structure of the system.

Clears all existing affine, homogeneous, and ungrouped variables (and any homogenizing variables introduced by a prior Homogenize), then installs the supplied groups as the system's affine variable groups, in order. The path variable, if any, is preserved.

Parameters

groups The affine variable groups to install.

◆ SetVariables()

template<typename T>

void bertini::System::SetVariables ( const Vec< T > & new_values ) const

inline

Set the values of the variables to be equal to the input values.

Template Parameters

T	the number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Exceptions

std::runtime_error if the number of variables doesn't match.

The ordering of the variables matters.

The AffHomUng ordering is 1) variable groups, with homogenizing variable first. 2) homogeneous variable groups. 3) ungrouped variables. The FIFO ordering uses the order in which the variable groups were added.

The path variable is not considered a variable for this operation. It is set separately.

Parameters

new_values The new updated values for the variables.

See also: SetPathVariable; Variables

◆ Simplify()

void bertini::System::Simplify ( )

Simplify as many aspects of the system as possible.

Note: This may change any nodes on which the system depends.

◆ SimplifyDerivatives()

void bertini::System::SimplifyDerivatives ( ) const

Simplify the derivatives / jacobian / etc contained in the system.

Note: This may change any nodes on which the system depends.

◆ SimplifyFunctions()

void bertini::System::SimplifyFunctions ( )

Simplify the functions contained in the system.

Note: This may change any nodes on which the system depends.

◆ Slices()

std::vector< Slice > bertini::System::Slices ( ) const

Recover the linear-form slices embedded in this system, one per LinearFormsBlock (empty if the system has none).

Lets a user back out the slice structure of a system built from a slice – the Python-facing alternative to exposing the Block variant. Defined in system.cpp (needs the full Slice type).

◆ SpanOfGroup()

std::pair< unsigned, unsigned > bertini::System::SpanOfGroup ( unsigned group_fifo_index ) const

inline

Where one variable group sits in a user-coordinate point: (offset, size).

The FIFO layout of a point in user coordinates – each group a contiguous slice, in time order. Shared by CoordinatesOfGroup and by the auxiliary coordinates, so both agree about where a group begins without either one re-deriving the layout.

Parameters

group_fifo_index The FIFO position of the group (see FIFOIndexOfGroup).

Returns: The group's (offset, size) within a user-coordinate point.

◆ SymbolicJacobian()

NodeMatrix bertini::System::SymbolicJacobian ( bool usercoordinates = true ) const

The symbolic Jacobian of the system, as a matrix of expression-tree nodes.

Parameters

usercoordinates When true (the default), differentiate the functions as the user authored them with respect to the user-declared variables – the natural (pre-homogenization) functions and the affine / projective variable groups. The solver-added homogenizing variables never appear, and patch rows are omitted. When false, differentiate the functions as currently stored (possibly homogenized) with respect to the full internal variable ordering (homogenizing variables included), and append the patch's Jacobian rows when the system is patched.

This is purely symbolic – it builds expression trees, it does not evaluate. For a homogenized system the user-coordinate Jacobian relies on the natural functions stashed at homogenization time (see pre_homogenization_functions_).

Returns: A NodeMatrix (row-major).

◆ TimeDerivative() [1/3]

template<typename T>

Vec< T > bertini::System::TimeDerivative ( ) const

inline

Compute the time-derivative of a system.

If $S$ is the system, and $t$ is the path variable this computes $\frac{dS}{dt}$ .

Template Parameters

T	The number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Exceptions

std::runtime error if the system does not have a path variable defined.

◆ TimeDerivative() [2/3]

template<typename Derived, typename T>

Vec< T > bertini::System::TimeDerivative ( const Eigen::MatrixBase< Derived > & variable_values ) const

inline

Compute the time-derivative of a system.

If $S$ is the system, and $t$ is the path variable this computes $\frac{dS}{dt}$ .

Template Parameters

T	The number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Exceptions

std::runtime error if the system does not have a path variable defined.

◆ TimeDerivative() [3/3]

template<typename Derived, typename T>

Vec< T > bertini::System::TimeDerivative	(	const Eigen::MatrixBase< Derived > &	variable_values,
		const T &	path_variable_value ) const

inline

Compute the time-derivative of a system.

If $S$ is the system, and $t$ is the path variable this computes $\frac{dS}{dt}$ .

Template Parameters

T	The number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Exceptions

std::runtime error if the system does not have a path variable defined.

◆ TimeDerivativeInPlace() [1/3]

template<typename T>

void bertini::System::TimeDerivativeInPlace ( Vec< T > & ds_dt ) const

inline

Compute the time-derivative of the system in place, using the currently set variable values.

Template Parameters

T	The number type for evaluation (e.g. complex_dbl or complex_mp).

Parameters

[out] ds_dt The vector into which to write dS/dt.

Exceptions

std::runtime_error if no path variable is defined.

◆ TimeDerivativeInPlace() [2/3]

template<typename Derived, typename T>

void bertini::System::TimeDerivativeInPlace	(	Vec< T > &	ds_dt,
		const Eigen::MatrixBase< Derived > &	variable_values ) const

inline

Compute the time-derivative of the system in place, after setting the variable values.

Template Parameters

T	The number type for evaluation (e.g. complex_dbl or complex_mp).

Parameters

[out]	ds_dt	The vector into which to write dS/dt.
	variable_values	The values of the variables.

◆ TimeDerivativeInPlace() [3/3]

template<typename Derived, typename T>

void bertini::System::TimeDerivativeInPlace	(	Vec< T > &	ds_dt,
		const Eigen::MatrixBase< Derived > &	variable_values,
		const T &	path_variable_value ) const

inline

Compute the time-derivative of a system.

If $S$ is the system, and $t$ is the path variable this computes $\frac{dS}{dt}$ .

Template Parameters

T	The number-type for return. Probably complex_dbl=std::complex<double>, or complex_mp=bertini::complex_mp.

Exceptions

std::runtime error if the system does not have a path variable defined.

◆ UngroupedVariables()

VariableGroup const & bertini::System::UngroupedVariables ( ) const

inline

Get the ungrouped variables: those declared to the system but placed in no affine and no projective group.

◆ VariableGroups()

auto bertini::System::VariableGroups ( ) const

inline

Get the affine variable groups in the problem.

◆ VariableGroupSizes()

std::vector< unsigned > bertini::System::VariableGroupSizes ( ) const

inline

Get the sizes of the variable groups, according to the current ordering.

◆ VariableNameSet()

std::set< std::string > bertini::System::VariableNameSet ( ) const

Collect the names of every variable the user could reference.

Gathers names from all variable groups (ungrouped, affine, projective), the homogenizing variables, and the implicit parameters. Reads the raw group members directly, so it is safe on a partially-built or not-yet-homogenized system (unlike VariableOrdering, which throws on a hom-var/affine-group mismatch). The path variable itself is not included.

Used to guarantee an auto-constructed homotopy's path variable never collides with a user variable.

See also: UniquePathVariableName, AddPathVariable.

Returns: The set of variable/parameter names in the system.

◆ VariableOrdering()

VariableGroup bertini::System::VariableOrdering ( ) const

Order the variables, by the order in which the groups were added.

This function returns the variables in First In First Out (FIFO) ordering.

Homogenizing variables precede affine variable groups, so that groups always are grouped together.

This function freshly constructs the ordering every time. If you want to use the cached value,

See also: Variables.

Exceptions

std::runtime_error,if there is a mismatch between the number of homogenizing variables and the number of variable_groups. This would happen if a system is homogenized, and then more stuff is added to it.

◆ Variables()

const VariableGroup & bertini::System::Variables ( ) const

Get the variables in the problem.

Returns the variable ordering, constructing it if necessary.

◆ boost::serialization::access

friend class boost::serialization::access

friend

◆ operator* [1/2]

const System operator*	(	Nd const &	N,
		System const &	s )

friend

Multiply a system by an arbitrary node.

Can be used for defining a coupling of a target and start system through a path variable. Does not affect path variable declaration, or anything else. It is up to you to ensure the system depends on this node properly.

◆ operator* [2/2]

const System operator*	(	System	s,
		Nd const &	N )

friend

Multiply a system by an arbitrary node.

Can be used for defining a coupling of a target and start system through a path variable. Does not affect path variable declaration, or anything else. It is up to you to ensure the system depends on this node properly.

◆ operator+

const System operator+	(	System	lhs,
		System const &	rhs )

friend

Add two systems together.

Exceptions

std::runtime_error,if the systems are not of compatible size – either in number of functions, or variables. Does not check the structure of the variables, just the numbers.

See also: The += operator for System also.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	out,
		const System &	s )

friend

Overloaded operator for printing to an arbirtary out stream.

◆ swap

void swap	(	System &	a,
		System &	b )

friend

The free swap function for systems.

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Nd

◆ NE

◆ Var

Constructor & Destructor Documentation

◆ System() [1/5]

◆ System() [2/5]

◆ System() [3/5]

◆ System() [4/5]

◆ System() [5/5]

Member Function Documentation

◆ AddBlock()

◆ AddConstant()

◆ AddFunction()

◆ AddFunctions()

◆ AddHomVariableGroup()

◆ AddImplicitParameter()

◆ AddImplicitParameters()

◆ AddParameter()

◆ AddPathVariable()

◆ AddUngroupedVariable()

◆ AddUngroupedVariables()

◆ AddVariableGroup()

◆ AffineVariableGroup()

◆ AutoPatch()

◆ AuxiliaryCoordinates()

◆ AuxiliaryVariableGroups()

◆ Blocks()

◆ CanonicalEncodingText()

◆ ClearBlocks()

◆ ClearFunctions()

◆ ClearVariables()

◆ CoefficientBound()

◆ ContentDigest()

◆ CoordinateIsAuxiliary()

◆ CoordinatesOfGroup()

◆ CopyFunctions()

◆ CopyPatches()

◆ CopyVariableStructure()

◆ DegreeBound()

◆ Degrees() [1/2]

◆ Degrees() [2/2]

◆ DehomogenizePoint()

◆ Describe()

◆ Differentiate()

◆ Eval() [1/5]

◆ Eval() [2/5]

◆ Eval() [3/5]

◆ Eval() [4/5]

◆ Eval() [5/5]

◆ EvalInPlace() [1/3]

◆ EvalInPlace() [2/3]

◆ EvalInPlace() [3/3]

◆ ExpandToFunctionTree()

◆ FIFOIndexOfGroup()

◆ FromCanonicalEncoding()

◆ Function()

◆ GetFunctions()

◆ GetNaturalFunctions()

◆ GetPatch()

◆ GetPathVariable()

◆ GetSpaceDerivatives()

◆ GetTimeDerivatives()

◆ HasBlocks()

◆ Hash()

◆ HasStructuredBlocks()

◆ HaveAuxiliaryCoordinates()

◆ HavePathVariable()

◆ Homogenize() [1/2]

◆ Homogenize() [2/2]

◆ HomogenizePoint()

◆ HomogenizingVariables()

◆ HomVariableGroups()

◆ InfinityNormOfDehomogenized()

◆ IsFinite()