regina::BanConstraintBase Class Reference

A base class for additional banning and marking constraints that we can place on tree traversal algorithms. More...

#include <enumerate/treeconstraint.h>

Inheritance diagram for regina::BanConstraintBase:

Public Member Functions
template<class LPConstraint >
	BanConstraintBase (const LPInitialTableaux< LPConstraint > &init)
	Constructs a new set of banning and marking constraints. More...
	~BanConstraintBase ()
	Destroys this object and all associated data. More...
template<class LPConstraint , typename IntType >
void	enforceBans (LPData< LPConstraint, IntType > &lp) const
	Enforces all bans described by this class in the given tableaux. More...
bool	marked (size_t column) const
	Identifies whether the given column of the tableaux corresponds to a marked coordinate (e.g., a marked normal disc type). More...
bool	operator== (const BanConstraintBase &other) const
	Determines if this and the given object ban and mark the same tableaux coordinates as each other. More...
bool	operator!= (const BanConstraintBase &other) const
	Determines if this and the given object do not ban and mark the same tableaux coordinates as each other. More...
void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream. More...
	BanConstraintBase (const BanConstraintBase &)=delete
BanConstraintBase &	operator= (const BanConstraintBase &)=delete
void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output. More...
std::string	str () const
	Returns a short text representation of this object. More...
std::string	utf8 () const
	Returns a short text representation of this object using unicode characters. More...
std::string	detail () const
	Returns a detailed text representation of this object. More...

Static Public Member Functions
static bool	supported (NormalEncoding enc)
	Indicates whether the given coordinate system is supported by this constraint class. More...

Protected Attributes
const Triangulation< 3 > &	tri_
	The triangulation with which we are working. More...
LPSystem	system_
	The broad class of vector encodings that our enumeration task is working with. More...
bool *	banned_
	Indicates which columns of a tableaux correspond to banned coordinates (e.g., banned normal disc types). More...
bool *	marked_
	Indicates which columns of a tableaux correspond to marked coordinates (e.g., marked normal disc types). More...

Detailed Description

A base class for additional banning and marking constraints that we can place on tree traversal algorithms.

This is used with TreeEnumeration, TreeSingleSoln and related algorithms for enumerating and locating normal surfaces and angle structures in a 3-manifold triangulation.

This class adds constraints of two types:

• Banning constraints, which ensure that certain coordinates are set to zero;
• Marking constraints, which are more flexible and can be used in different ways by different algorithms.

All of these constraints operate only on normal or angle structure coordinates in the underlying tableaux (and in particular not the additional variables introduced by additional linear constraints, as described by LPConstraintBase and its subclasses).

Currently marking is used in the following ways:

• The TreeEnumeration and TautEnumeration algorithms do not use marking at all.
• In the TreeSingleSoln algorithm, marking affects what is considered a non-trivial normal surface. Normally, a non-trivial surface is defined to be one in which some triangle coordinate is zero. With marking, a non-trivial surface is redefined to be one in which some unmarked triangle coordinate is zero. In other words, marked triangle types are effectively ignored when determining whether a surface is non-trivial or not.

At present, marking is not used at all for quadrilateral coordinates or angle structures. However, marking is a very new feature, and this concept may be expanded in future versions of Regina.

This class does not record disc types in the order of their normal or angle structure coordinates; instead it records them in the order of their columns in a tableaux for linear programming (as used in LPInitialTableaux). This means that there is a little more work required in setting up the initial lists of banned and marked columns, but then these lists are easy to use on the fly during tree traversal algorithms.

Bear in mind that the tableaux that these constraints are working with will not necessarily use the same coordinates as the underlying enumeration task (e.g., the tableaux will never include separate columns for octagon coordinates). See LPInitialTableaux for a more detailed discussion of this.

This base class provides limited functionality (as documented below). Subclasses must implement a constructor (which, like this base class, takes an initial tableaux and determines which coordinates are banned and/or marked), and must implement supported(), which indicates which normal or angle structure coordinate system this constraint class can work with. The constructor may take additional arguments beyond the initial tableaux; if so, then the tree traversal classes (mentioned below) will forward these arguments at runtime from their own class constructors.

These ban 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 ban constraint class, pass it as a template parameter to one of the tree traversal subclasses (e.g., TreeEnumeration, TreeSingleSolution, or TautEnumeration).

Python

This base class is not present, but all subclasses are available. However, as noted above, it is rare that you would need to access any of these ban constraint classes directly through Python. Instead, to use a ban constraint class, you would typically create a tree traversal object with the appropriate class suffix (e.g., one such Python class is TreeEnumeration_BanBoundary).

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.

Constructor & Destructor Documentation

BanConstraintBase()

template<class LPConstraint >

regina::BanConstraintBase::BanConstraintBase ( const LPInitialTableaux< LPConstraint > &  init )

inline

Constructs a new set of banning and marking constraints.

This base class constructor will create banned_ and marked_ arrays of the correct size, and will initialise their contents to be entirely false. This means that there will be no banned or marked disc types at all.

Subclass constructors should identify which coordinates to ban and mark, and adjust the contents of the banned_ and marked_ arrays accordingly.

Parameters

init	the original starting tableaux being used for this enumeration task.

~BanConstraintBase()

regina::BanConstraintBase::~BanConstraintBase ( )

inline

Destroys this object and all associated data.

Member Function Documentation

detail()

std::string regina::Output< BanConstraintBase , supportsUtf8 >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns

a detailed text representation of this object.

enforceBans()

template<class LPConstraint , typename IntType >

void regina::BanConstraintBase::enforceBans ( LPData< LPConstraint, IntType > &  lp ) const

inline

Enforces all bans described by this class in the given tableaux.

Specifically, for each banned coordinate, this routine calls LPData::constrainZero() on the corresponding coordinate column.

Parameters

lp	the tableaux in which to enforce the bans.

marked()

bool regina::BanConstraintBase::marked ( size_t  column ) const

inline

Identifies whether the given column of the tableaux corresponds to a marked coordinate (e.g., a marked normal disc type).

Parameters

column

a column of the tableaux. This must be one of the columns corresponding to a normal or angle structure coordinate, not one of the extra columns induced by an LPConstraint parameter for the tree traversal class.

Returns

true if and only if the given column corresponds to a marked coordinate.

operator!=()

bool regina::BanConstraintBase::operator!= ( const BanConstraintBase &  other ) const

inline

Determines if this and the given object do not ban and mark the same tableaux coordinates as each other.

Even if this and the given object are of different subclasses of BanConstraintBase, as long as they ban the same coordinates and mark the same coordinates, they will compare as equal (i.e., this inequality comparison will return false).

It does not matter whether the two objects use the same underlying tableaux. However, if the underlying tableaux use triangulations of different sizes and/or different broad classes of vector encodings (as described by LPSystem), then these two objects will compare as not equal.

Parameters

other

the object to compare with this.

Returns

true if and only if this and the object do not ban and mark the same tableaux coordinates, as described above.

operator==()

bool regina::BanConstraintBase::operator== ( const BanConstraintBase &  other ) const

inline

Determines if this and the given object ban and mark the same tableaux coordinates as each other.

Even if this and the given object are of different subclasses of BanConstraintBase, as long as they ban the same coordinates and mark the same coordinates, they will compare as equal.

It does not matter whether the two objects use the same underlying tableaux. However, if the underlying tableaux use triangulations of different sizes and/or different broad classes of vector encodings (as described by LPSystem), then these two objects will compare as not equal.

Parameters

other

the object to compare with this.

Returns

true if and only if this and the object ban and mark the same tableaux coordinates, as described above.

str()

std::string regina::Output< BanConstraintBase , supportsUtf8 >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python

The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.

Returns

a short text representation of this object.

supported()

static bool regina::BanConstraintBase::supported ( NormalEncoding  enc )

static

Indicates whether the given coordinate system is supported by this constraint class.

This routine assumes that the given system is already known to be supported by the generic tree traversal infrastructure, and only returns false if there are additional prerequisites imposed by this particular constraint class that the given system does not satisfy. If this constraint class does not impose any of its own additional conditions, this routine may simply return true.

The only features of the encoding that this routine should examine are what coordinates are stored (e.g., NormalEncoding::storesTriangles()). In particular, this routine will not look at any "semantic guarantees" (e.g. NormalEncoding::couldBeNonCompact()).

Parameters

enc	the vector encoding being queried. This must be one of the vector encodings known to be supported by the generic TreeTraversal infrastructure, and in particular it may be the special angle structure encoding.

Returns

true if and only if this vector encoding is also supported by this specific constraint class.

utf8()

std::string regina::Output< BanConstraintBase , supportsUtf8 >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns

a short text representation of this object.

writeTextLong()

void regina::ShortOutput< BanConstraintBase , false >::writeTextLong ( std::ostream &  out ) const

inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python

Not present. Instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the output stream to which to write.

writeTextShort()

void regina::BanConstraintBase::writeTextShort

(

std::ostream &

out

)

const

Writes a short text representation of this object to the given output stream.

Python

Not present. Use str() instead.

Parameters

out	the output stream to which to write.

Member Data Documentation

banned_

bool* regina::BanConstraintBase::banned_

protected

Indicates which columns of a tableaux correspond to banned coordinates (e.g., banned normal disc types).

The size of this array is the number of normal or angle structure coordinates (so we explicitly exclude extra columns that arise from the template parameter LPConstraint.

marked_

bool* regina::BanConstraintBase::marked_

protected

Indicates which columns of a tableaux correspond to marked coordinates (e.g., marked normal disc types).

The size of this array is the number of normal or angle structure coordinates (so we explicitly exclude extra columns that arise from the template parameter LPConstraint.

system_

LPSystem regina::BanConstraintBase::system_

protected

The broad class of vector encodings that our enumeration task is working with.

tri_

const Triangulation<3>& regina::BanConstraintBase::tri_

protected

The triangulation with which we are working.

---

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

• enumerate/treeconstraint.h