Represents a set of combinatorial validity constraints for use with polytope vertex enumeration. More...

#include <enumerate/validityconstraints.h>

Inheritance diagram for regina::ValidityConstraints:

Public Member Functions
	ValidityConstraints (int blockSize, size_t nBlocks, size_t reserveLocal=0, size_t reserveGlobal=0)
	Creates an empty set of validity constraints for vectors with the given block structure. More...

	ValidityConstraints (const ValidityConstraints &)=default
	Creates a clone of the given constraint set. More...

	ValidityConstraints (ValidityConstraints &&) noexcept=default
	Moves the contents of the given constraint set into this new constraint set. More...

ValidityConstraints &	operator= (const ValidityConstraints &)=default
	Sets this to be a copy of the given constraint set. More...

ValidityConstraints &	operator= (ValidityConstraints &&) noexcept=default
	Moves the contents of the given constraint set into this constraint set. More...

template<typename iterator >
void	addLocal (iterator begin, iterator end)
	Adds a new family of local constraints to this set. More...

void	addLocal (std::initializer_list< int > pattern)
	Adds a new family of hard-coded local constraints to this set. More...

template<typename iterator >
void	addGlobal (iterator begin, iterator end)
	Adds one new global constraint to this set. More...

void	addGlobal (std::initializer_list< int > pattern)
	Adds one new hard-coded global constraint to this set. More...

void	swap (ValidityConstraints &other) noexcept
	Swaps the contents of this and the given constraint set. More...

template<typename BitmaskType >
std::vector< BitmaskType >	bitmasks (size_t len) const
	Returns the list of all individual validity constraints, each expressed as a bitmask of the given length. More...

template<typename BitmaskType >
std::vector< BitmaskType >	bitmasks () const
	Returns the list of all individual validity constraints, each expressed as a bitmask of the smallest possible length. More...

bool	operator== (const ValidityConstraints &other) const
	Determines whether this and the given set contain the same constraints. More...

bool	operator!= (const ValidityConstraints &other) const
	Determines whether this and the given set do not contain the same constraints. More...

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream. More...

void	writeTextLong (std::ostream &out) const
	Writes a detailed text representation of this object to the given output stream. 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 Attributes
static const ValidityConstraints	none
	An empty set of constraints. More...

Detailed Description

Represents a set of combinatorial validity constraints for use with polytope vertex enumeration.

Vertex enumeration routines such as DoubleDescription::enumerate() take a cone (specifically the non-negative orthant), form the intersection of that cone with a given linear subspace, and return the extremal rays of the new cone that results.

In some cases we are only interested in valid rays of the new cone. The ValidityConstraints class stores a number of "validity constraints"; a ray is then "valid" if it satisfies all of these constraints.

Each individual constraint encodes a subset S of coordinate positions, and requires that a ray can only be non-zero on at most one of those coordinate positions. Equivalently, if we were to assume that the linear subspace is in general position with respect to the coordinate axes (which it is often not), then the ith facet of the cone would come from the hyperplane perpendicular to ith coordinate; such a constraint would then require that a ray can only lie outside at most one of the facets corresponding to the coordinate positions in S.

This class is tailored specifically to constraints that come from normal surfaces and angle structures:

We assume that the coordinate positions are grouped into consecutive blocks, each of the same size. For instance, in standard coordinates for normal surfaces, there is one block per tetrahedron, each of size seven (since each tetrahedron provides four triangle coordinates and three quadrilateral coordinates).
It is okay if there are additional coordinates that appear beyond these blocks (e.g., the final scaling coordinate in angle structure coordinates). However, these additional coordinates cannot be used in any validity constraints.

It is assumed that all constraints are either local or global:

A local constraint involves coordinates within a single block only. It is assumed that, if local constraints are used, then every block will use analogous local constraints (where "analagous" means they use the same coordinate positions relative to the start of each block). An example of a local constraint is the quadrilateral constraints from normal surface theory, which require that each tetrahedron has at most one non-zero quadrilateral coordinate.
A global constraint involves coordinates in every block; moreover, each block must constraint the same coordinates relative to the start of the block. An example of a global constraint is with almost normal surfaces, where we require that the entire surface has at most one non-zero octagonal coordinate.

You can add a full set of local constraints (one for each block) using a single call to addLocal(), and you can add a single global constraint by calling addGlobal().

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Constructor & Destructor Documentation

◆ ValidityConstraints() [1/3]

regina::ValidityConstraints::ValidityConstraints	(	int	blockSize,
		size_t	nBlocks,
		size_t	reserveLocal = `0`,
		size_t	reserveGlobal = `0`
	)

inline

Creates an empty set of validity constraints for vectors with the given block structure.

See the class notes for details on how vector coordinates are assumed to be grouped into nBlocks consecutive blocks, each containing blockSize coordinates (possibly with some additional coordinates beyond this block structure that are not used in any validity constraints).

Parameters

blockSize	the number of coordinates in each block. For example, for vectors describing normal surfaces in standard coordinates, this block size would be 7 (representing the three triangle and four quadrilateral coordinates for each tetrahedron).
nBlocks	the number of consecutive blocks of size blockSize. For example, for vectors describing normal surfaces in standard coordinates, this number of blocks would be the number of tetrahedra in the underlying triangulation.
reserveLocal	indicates that we should reserve space for reserveLocal calls to addLocal(). This is purely for optimisation; it is safe to leave this as 0 (the default).
reserveGlobal	indicates that we should reserve space for reserveGlobal calls to addGlobal(). This is purely for optimisation; it is safe to leave this as 0 (the default).

◆ ValidityConstraints() [2/3]

regina::ValidityConstraints::ValidityConstraints ( const ValidityConstraints & )

default

Creates a clone of the given constraint set.

◆ ValidityConstraints() [3/3]

regina::ValidityConstraints::ValidityConstraints ( ValidityConstraints && )

defaultnoexcept

Moves the contents of the given constraint set into this new constraint set.

The constraint set that was passed will no longer be usable.

Member Function Documentation

◆ addGlobal() [1/2]

template<typename iterator >

void regina::ValidityConstraints::addGlobal	(	iterator	begin,
		iterator	end
	)

inline

Adds one new global constraint to this set.

A call to addGlobal() will add a single global constraint, using coordinates from every block. Within each block, the coordinates that are constrained will be those listed in the given iterator range, where these coordinate positions are given relative to the start of each block.

As an example, for almost normal surfaces in standard coordinates, you can encode the constraint that there is at most one octagon in the entire surface by passing an iterator range that encodes the three integers 7, 8, 9.

Precondition: The iterator type iterator, when dereferenced, can be assigned to a native C++ int.

Python: Instead of the iterators begin and end, this routine takes a python list of integers.

Parameters

begin	the beginning of the list of coordinates to constraint within each block, relative to the start of the block, as outlined above.
end	a past-the-end iterator indicating the end of the list of coordinates to constraint within each block.

◆ addGlobal() [2/2]

void regina::ValidityConstraints::addGlobal ( std::initializer_list< int > pattern )

inline

Adds one new hard-coded global constraint to this set.

A call to addGlobal() will add a single global constraint, using coordinates from every block. Within each block, the coordinates that are constrained will be those listed in pattern, where the coordinate positions in pattern are given relative to the start of each block.

As an example, for almost normal surfaces in standard coordinates, you can encode the constraint that there is at most one octagon in the entire surface by calling addGlobal({7, 8, 9}).

Python: Not present. Instead, use the Python version of this function that takes the coordinate pattern as a Python list (which need not be constant).

Parameters

pattern the coordinates to constraint within each block, relative to the start of the block.

◆ addLocal() [1/2]

template<typename iterator >

void regina::ValidityConstraints::addLocal	(	iterator	begin,
		iterator	end
	)

inline

Adds a new family of local constraints to this set.

A single call to addLocal() will effectively add one local constraint for every block. Each local constraint will constraint the coordinates in the given iterator range, where these coordinate positions are given relative to the start of each block.

For example, to encode the quadrilateral constraints for normal surfaces in standard coordinates, you can pass an iterator range that encodes the three integers 4, 5, 6.

Precondition: The iterator type iterator, when dereferenced, can be assigned to a native C++ int.

Python: Instead of the iterators begin and end, this routine takes a python list of integers.

Parameters

begin	the beginning of the list of coordinates to constraint within each block, relative to the start of the block, as outlined above.
end	a past-the-end iterator indicating the end of the list of coordinates to constraint within each block.

◆ addLocal() [2/2]

void regina::ValidityConstraints::addLocal ( std::initializer_list< int > pattern )

inline

Adds a new family of hard-coded local constraints to this set.

A single call to addLocal() will effectively add one local constraint for every block. Each local constraint will constraint the coordinates in pattern, where these coordinate positions are given relative to the start of each block.

For example, to encode the quadrilateral constraints for normal surfaces in standard coordinates, you can make the single call addLocal({4, 5, 6}).

Python: Not present. Instead, use the Python version of this function that takes the coordinate pattern as a Python list (which need not be constant).

Parameters

pattern the coordinates to constraint within each block, relative to the start of the block.

◆ bitmasks() [1/2]

template<typename BitmaskType >

std::vector< BitmaskType > regina::ValidityConstraints::bitmasks

inline

Returns the list of all individual validity constraints, each expressed as a bitmask of the smallest possible length.

Calling bitmasks() is equivalent to calling bitmasks(len), where len is the block size multiplied by the number of blocks.

As an example, this is appropriate for normal surface coordinate systems, where the normal coordinates incorporate precisely one block for each tetrahedron and nothing more. However, it is not appropriate for angle structure coordinates, where there is an additional "scaling coordinate" that appears after all the blocks.

Each local constraint "pattern" that was added using addLocal() will produce many bitmasks, since there will be one local constraint for every block. Each global constraint that was added using addGlobal() will produce just one bitmask.

The bits corresponding to coordinate positions that are constrained will be set to true; all other bits will be set to false.

Precondition: A bitmask of type BitmaskType is large enough to store len bits, where len is the block size multiplied by the number of blocks. Each bitmask that is returned will be created with this length.

Python: This routine uses the bitmask type regina::Bitmask.

Template Parameters

BitmaskType the bitmask type used to encode each constraint; this must be one of Regina's own bitmask types, such as Bitmask, Bitmask1 or Bitmask2.

Returns: the list of bitmasks describing the full set of validity constraints.

◆ bitmasks() [2/2]

template<typename BitmaskType >

std::vector< BitmaskType > regina::ValidityConstraints::bitmasks ( size_t len ) const

Returns the list of all individual validity constraints, each expressed as a bitmask of the given length.

Each local constraint "pattern" that was added using addLocal() will produce many bitmasks, since there will be one local constraint for every block. Each global constraint that was added using addGlobal() will produce just one bitmask.

The bits corresponding to coordinate positions that are constrained will be set to true; all other bits will be set to false.

Precondition: The given length len is at least the number of blocks multiplied by the block size.; A bitmask of type BitmaskType is large enough to store len bits.

Python: This routine uses the bitmask type regina::Bitmask.

Template Parameters

BitmaskType the bitmask type used to encode each constraint; this must be one of Regina's own bitmask types, such as Bitmask, Bitmask1 or Bitmask2.

Parameters

len	the total number of coordinates in the vectors being constrained. Each bitmask will be created with this length.

Returns: the list of bitmasks describing the full set of validity constraints.

◆ detail()

std::string regina::Output< ValidityConstraints , false >::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.

◆ operator!=()

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

inline

Determines whether this and the given set do not contain the same constraints.

This test compares the number of coordinates in each block, the total number of blocks, the set of local constraints, and the set of global constraints. The local and global constraints may appear in any order, and their individual coordinates may likewise appear in any order; such reorderings will not affect the outcome of this test.

Warning: Because this test allows for reordering, the comparison is not very efficient. It is assumed that this will not be a problem, because typical constraint sets are extremely small.

Parameters

other the constraint set to compare against this.

Returns: true if and only if this and the given set do not contain the same constraints.

◆ operator=() [1/2]

ValidityConstraints & regina::ValidityConstraints::operator= ( const ValidityConstraints & )

default

Sets this to be a copy of the given constraint set.

Returns: a reference to this constraint set.

◆ operator=() [2/2]

ValidityConstraints & regina::ValidityConstraints::operator= ( ValidityConstraints && )

defaultnoexcept

Moves the contents of the given constraint set into this constraint set.

The constraint set that was passed will no longer be usable.

Returns: a reference to this constraint set.

◆ operator==()

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

inline

Determines whether this and the given set contain the same constraints.

This test compares the number of coordinates in each block, the total number of blocks, the set of local constraints, and the set of global constraints. The local and global constraints may appear in any order, and their individual coordinates may likewise appear in any order; such reorderings will not affect the outcome of this test.

Warning: Because this test allows for reordering, the comparison is not very efficient. It is assumed that this will not be a problem, because typical constraint sets are extremely small.

Parameters

other the constraint set to compare against this.

Returns: true if and only if this and the given set contain the same constraints.

◆ str()

std::string regina::Output< ValidityConstraints , false >::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.

◆ swap()

void regina::ValidityConstraints::swap ( ValidityConstraints & other )

inlinenoexcept

Swaps the contents of this and the given constraint set.

Parameters

other the constraint set whose contents should be swapped with this.

◆ utf8()

std::string regina::Output< ValidityConstraints , false >::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::ValidityConstraints::writeTextLong ( std::ostream & out ) const

inline

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

Python: Not present. Use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

void regina::ValidityConstraints::writeTextShort ( std::ostream & out ) const

inline

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

◆ none

const ValidityConstraints regina::ValidityConstraints::none

inlinestatic

An empty set of constraints.

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

enumerate/validityconstraints.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ValidityConstraints() [1/3]

◆ ValidityConstraints() [2/3]

◆ ValidityConstraints() [3/3]

Member Function Documentation

◆ addGlobal() [1/2]

◆ addGlobal() [2/2]

◆ addLocal() [1/2]

◆ addLocal() [2/2]

◆ bitmasks() [1/2]

◆ bitmasks() [2/2]

◆ detail()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ str()

◆ swap()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ none