Regina 7.3 Calculation Engine
Public Types | Static Public Member Functions | Static Public Attributes | List of all members
regina::LPConstraintEulerPositive Class Reference

A class that constraints the tableaux of normal surface matching equations to ensure that Euler characteristic is strictly positive. More...

#include <enumerate/treeconstraint.h>

Inheritance diagram for regina::LPConstraintEulerPositive:
regina::LPConstraintBase

Public Types

using Coefficient = int
 

Static Public Member Functions

static void addRows (LPCol< regina::LPConstraintEulerPositive > *col, const LPInitialTableaux< LPConstraintEulerPositive > &init)
 
template<typename IntType >
static void constrain (LPData< regina::LPConstraintEulerPositive, IntType > &lp, size_t numCols)
 
static bool verify (const NormalSurface &s)
 
static bool verify (const AngleStructure &)
 
static bool supported (NormalEncoding enc)
 
static void addRows (LPCol< LPConstraintBase > *col, const LPInitialTableaux< LPConstraintBase > &init)
 Explicitly constructs equations for the linear function(s) constrained by this class. More...
 
template<typename IntType >
static void constrain (LPData< LPConstraintNone, IntType > &lp, size_t numCols)
 Explicitly constraints each of these linear functions to an equality or inequality in the underlying tableaux. More...
 

Static Public Attributes

static constexpr int nConstraints = 1
 
static constexpr Coefficient octAdjustment = -1
 

Detailed Description

A class that constraints the tableaux of normal surface matching equations to ensure that Euler characteristic is strictly positive.

There are many ways of writing Euler characteritic as a linear function. The function constructed here has integer coefficients, but otherwise has no special properties of note.

This constraint can work with either normal or almost normal coordinates. In the case of almost normal coordinates, the function is modified to measure Euler characteristic minus the number of octagons (a technique of Casson, also employed by Jaco and Rubinstein, that is used to ensure we do not have more than two octagons when searching for a normal or almost normal sphere in the 3-sphere recognition algorithm).

See the LPConstraintBase class notes for details on all member functions.

These linear constraint classes are designed mainly to act as C++ template arguments, and end users will typically not need to construct their own object of these classes. Instead, to use a linear constraint class, pass it as a template parameter to one of the tree traversal subclasses (e.g., TreeEnumeration, TreeSingleSolution, or TautEnumeration).

Precondition
We are working with a normal or almost normal vector encoding that includes triangle coordinates (i.e., the encoding for standard normal or standard almost normal coordinates).
Python
It is rare that you would need to access this class directly through Python. Instead, to use a linear constraint class, you would typically create a tree traversal object with the appropriate class suffix (e.g., one such Python class is TreeSingleSolution_EulerPositive). See the LPConstraintBase class notes for further details.
Warning
The API for this class or function has not yet been finalised. This means that the interface may change in new versions of Regina, without maintaining backward compatibility. If you use this class directly in your own code, please check the detailed changelog with each new release to see if you need to make changes to your code.

Member Function Documentation

◆ addRows()

static void regina::LPConstraintBase::addRows ( LPCol< LPConstraintBase > *  col,
const LPInitialTableaux< LPConstraintBase > &  init 
)
staticinherited

Explicitly constructs equations for the linear function(s) constrained by this class.

Specifically, this routine takes an array of columns in the initial tableaux and fills in the necessary coefficient data.

More precisely: recall that, for each linear function, the initial tableaux acquires one new variable x_i that evaluates this linear function f(x). This routine must create the corresponding row that sets f(x) - x_i = 0. Thus it must construct the coefficients of f(x) in the columns corresponding to normal coordinates, and it must also set a coefficient of -1 in the column for the corresponding new variable.

As described in the LPInitialTableaux class notes, it might not be possible to construct the linear functions (since the underlying triangulation might not satisfy the necessary requirements). In such cases this routine should throw an exception, as described below, and the corresponding constraint class must mention this possibility in its class documentation.

If you are implementing this routine in a subclass that works with angle structure coordinates, remember that your linear constraints must not interact with the scaling coordinate (the final angle structure coordinate that is used to projectivise the angle structure polytope into a polyhedral cone). Your implementation of this routine must ensure that your linear constraints all have coefficient zero in this column.

The precise form of the linear function(s) will typically depend upon the underlying triangulation, as well as the permutation that indicates which columns of the initial tableaux correspond to which normal or angle structure coordinates. All of this information is read from the given initial tableaux init.

Note that the tableaux init may still be under construction (and indeed, the column array col to be filled will typically be the internal column array from init itself). This routine should not read any of the tableaux entries; it should only access the underlying triangulation (LPInitialTableaux.tri()) and the permutation of columns (LPInitialTableaux.columnPerm()).

For each subclass Sub of LPConstraintBase, the array col must be an array of objects of type LPCol<Sub>, and the tableaux init must be of type LPInitialTableaux<Sub>.

This routine should only write to the coefficients stored in LPCol::extra. You may assume that these coefficients have all been initialised to zero by the LPCol constructor.

Precondition
For all columns in the array col, the members LPCol::extra have all been initialised to zero.
Exceptions
InvalidArgumentIt was not possible to create the linear functions for these constraints, due to an error which should have been preventable with the right checks in advance. Any constraint class that could throw exceptions in this way must describe this behaviour in its own class documentation.
UnsolvedCaseIt was not possible to create the linear functions for these constraints, due to an error that was "genuinely" unforseeable. Again, any constraint class that could throw exceptions in this way must describe this behaviour in its own class documentation.
Python
The argument col is not present, since LPCol is only designed to be used as part of the internal data storage for LPInitialTableaux. Instead, this routine returns a Python list of constraints, where each constraint is presented as a Python list of coefficients. Each of these inner lists will have size init.columns().
Parameters
colthe array of columns as stored in the initial tableaux (i.e., the data member LPInitialTableaux::col_).
initthe tableaux through which this routine can acces the underlying triangulation and permutation of columns. Typically this will be the tableaux holding the column array col.

◆ constrain()

template<typename IntType >
static void regina::LPConstraintBase::constrain ( LPData< LPConstraintNone, IntType > &  lp,
size_t  numCols 
)
staticinherited

Explicitly constraints each of these linear functions to an equality or inequality in the underlying tableaux.

This will typically consist of a series of calls to LPData::constrainZero() and/or LPData::constrainPositive().

The variables for these extra linear functions are stored in columns numCols - nConstraints, ..., numCols - 1 of the given tableaux, and so your calls to LPData::constrainZero() and/or LPData::constrainPositive() should operate on these (and only these) columns.

Precondition
These column coefficients belong to the initial starting tableaux (LPInitialTableaux) from which the given tableaux is derived.
Parameters
lpthe tableaux in which to constrain these linear functions.
numColsthe number of columns in the given tableaux.

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

Copyright © 1999-2023, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).