Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

regina::NCensus Class Reference
[Census of Triangulations]

A utility class used to form a complete census of 3-manifold triangulations satisfying certain constraints. More...

#include <ncensus.h>

List of all members.

Static Public Member Functions

unsigned long formCensus (NPacket *parent, unsigned nTetrahedra, NBoolSet finiteness, NBoolSet orientability, NBoolSet boundary, int nBdryFaces, int whichPurge, AcceptTriangulation sieve=0, void *sieveArgs=0, NProgressManager *manager=0)
 Fills the given packet with all triangulations in a census of 3-manifold triangulations satisfying the given constraints.

unsigned long formPartialCensus (const NFacePairing *pairing, NPacket *parent, NBoolSet finiteness, NBoolSet orientability, int whichPurge, AcceptTriangulation sieve=0, void *sieveArgs=0)
 Fills the given packet with all triangulations in a partial census of 3-manifold triangulations satisfying the given constraints.

bool mightBeMinimal (NTriangulation *tri, void *ignore)
 Determines whether the given triangulation even has a chance at being minimal.

unsigned long findAllCompletions (NPacket *parent, NTriangulation *base, NBoolSet finiteness, NBoolSet orientability, AcceptTriangulation sieve=0, void *sieveArgs=0, NProgressManager *manager=0)
 Fills the given packet with all completions of the given base triangulation.


Static Public Attributes

const int PURGE_NON_MINIMAL
 Indicates that non-minimal triangulations may be ignored.

const int PURGE_NON_PRIME
 Indicates that any triangulation that is not prime (i.e., can be written as a non-trivial connected sum) and any bounded triangulation that is reducible over a disc may be ignored.

const int PURGE_NON_MINIMAL_PRIME
 Indicates that any triangulation that is not prime (i.e., can be written as a non-trivial connected sum), any bounded triangulation that is reducible over a disc and any triangulation that is non-minimal may be ignored.

const int PURGE_P2_REDUCIBLE
 Indicates that any triangulation containing an embedded two-sided projective plane may be ignored.


Detailed Description

A utility class used to form a complete census of 3-manifold triangulations satisfying certain constraints.

Other tasks (such as finding all completions of a triangulation with boundary) are also offered.

Test:
Test suite contains partial tests.


Member Function Documentation

unsigned long regina::NCensus::findAllCompletions NPacket parent,
NTriangulation base,
NBoolSet  finiteness,
NBoolSet  orientability,
AcceptTriangulation  sieve = 0,
void *  sieveArgs = 0,
NProgressManager manager = 0
[static]
 

Fills the given packet with all completions of the given base triangulation.

The base triangulation should have boundary faces; a completion is simply a new triangulation formed from the base triangulation by gluing all of the boundary faces to each other in some fashion (a completion will have no boundary faces at all).

Each completion of the given base triangulation will appear as a child of the given parent packet.

This routine currently enumerates all completions, regardless of combinatorial isomorphism. This behaviour may change when this routine become more mature.

The set of completions can be optionally restricted to only include triangulations satisfying further constraints (such as orientability and finiteness); see the individual parameter descriptions for further details. In particular, parameter sieve can be used to impose artibrary restrictions that are not hard-coded into this class.

Note that if constraints may be imposed using the hard-coded parameters (such as orientability and finiteness), it is generally better to do this than to use the arbitrary constraint parameter sieve. Hard-coded parameters will be tested earlier, and some (such as orientability) can be incorporated directly into the completion algorithm to give a vast performance increase.

Only valid triangulations will be produced; see NTriangulation::isValid() for further details.

Note that this routine should only be used if the set of completions is small enough to avoid any memory disasters.

If a progress manager is passed, the calculation will run in a new thread and this routine will return immediately. Otherwise the calculation will run in the current thread and this routine will only return once the census is complete.

Todo:
Bug (urgent): This routine currently does nothing!
Python:
Parameters sieve, sieveArgs and manager are not present (and will be treated as 0).
Parameters:
parent the packet beneath which the completions that are constructed will be placed.
base the base triangulation from which completions will be generated.
finiteness determines whether to include finite and/or ideal triangulations. The set should contain true if finite (non-ideal) triangulations are to be included, and should contain false if ideal triangulations are to be included.
orientability determines whether to include orientable and/or non-orientable triangulations. The set should contain true if orientable triangulations are to be included, and should contain false if non-orientable triangulations are to be included.
sieve an additional constraint function that may be used to exclude certain triangulations from the set of results. If this parameter is non-zero, each triangulation produced (after passing all other criteria) will be passed through this function. If this function returns true then the triangulation will be included in the set of results; otherwise it will not. When this function is called, the first (triangulation) argument will be a completion under consideration for inclusion in the results. The second argument will be parameter sieveArgs as passed to findAllCompletions(). Parameter sieve may be passed as null (in which case no additional constraint function will be used).
sieveArgs the pointer to pass as the final parameter for the function sieve which will be called upon each triangulation found. If sieve is null then sieveArgs will be ignored.
manager a progress manager via which progess will be reported, or 0 if no progress reporting is required. If non-zero, manager must point to a progress manager for which NProgressManager::isStarted() is still false.
Returns:
the total number of completions produced, or 0 if a progress manager was passed.

unsigned long regina::NCensus::formCensus NPacket parent,
unsigned  nTetrahedra,
NBoolSet  finiteness,
NBoolSet  orientability,
NBoolSet  boundary,
int  nBdryFaces,
int  whichPurge,
AcceptTriangulation  sieve = 0,
void *  sieveArgs = 0,
NProgressManager manager = 0
[static]
 

Fills the given packet with all triangulations in a census of 3-manifold triangulations satisfying the given constraints.

Each triangulation in the census will appear as a child of the given packet.

This routine will conduct a census of all valid triangulations containing a given number of tetrahedra. All such triangulations are included in the census up to combinatorial isomorphism; given any isomorphism class, exactly one representative will appear in the census.

The census can be optionally restricted to only include triangulations satisfying further constraints (such as orientability and finiteness); see the individual parameter descriptions for further details. In particular, parameter sieve can be used to impose arbitrary restrictions that are not hard-coded into this class.

Note that if constraints may be imposed using the hard-coded parameters (such as orientability and finiteness), it is generally better to do this than to use the arbitrary constraint parameter sieve. Hard-coded parameters will be tested earlier, and some (such as orientability) can be incorporated directly into the census algorithm to give a vast performance increase.

Parameter whichPurge may be used to further avoid constructing triangulations satisfying particular constraints (such as non-minimality). This can significantly speed up the census. In this case however not all such triangulations will be avoided, but it is guaranteed that every triangulation that does not satisfy the constraints defined by whichPurge will be produced.

Only valid triangulations will be produced; see NTriangulation::isValid() for further details.

Note that this routine should only be used if the census contains a small enough total number of triangulations to avoid any memory disasters.

If a progress manager is passed, the calculation will run in a new thread and this routine will return immediately. Otherwise the calculation will run in the current thread and this routine will only return once the census is complete.

Python:
Parameters sieve, sieveArgs and manager are not present (and will be treated as 0).
Parameters:
parent the packet beneath which members of the census will be placed.
nTetrahedra the number of tetrahedra in each triangulation in the census.
finiteness determines whether to include finite and/or ideal triangulations. The set should contain true if finite (non-ideal) triangulations are to be included, and should contain false if ideal triangulations are to be included.
orientability determines whether to include orientable and/or non-orientable triangulations. The set should contain true if orientable triangulations are to be included, and should contain false if non-orientable triangulations are to be included.
boundary determines whether to include triangulations with and/or without boundary faces. The set should contain true if triangulations with boundary faces are to be included, and should contain false if triangulations with only internal faces are to be included.
nBdryFaces specifies the precise number of boundary faces that should be present in the triangulations produced. If this parameter is negative, it is ignored and no additional restriction is imposed. See the documentation for routine NFacePairing::findAllPairings() for details regarding this parameter and how it interacts with parameter boundary.
whichPurge specifies which triangulations we may further avoid constructing (see the function notes above for details). This should be a bitwise OR of purge constants defined in this class, or 0 if no additional pruning should take place. If a variety of purge constants are bitwise ORed together, a triangulation satisfying any of these constraints may be avoided. Note that not all such triangulations will be avoided, but enough are avoided that the performance increase is noticeable.
sieve an additional constraint function that may be used to exclude certain triangulations from the census. If this parameter is non-zero, each triangulation produced (after passing all other criteria) will be passed through this function. If this function returns true then the triangulation will be included in the census; otherwise it will not. When this function is called, the first (triangulation) argument will be a triangulation under consideration for inclusion in the census. The second argument will be parameter sieveArgs as passed to formCensus(). Parameter sieve may be passed as null (in which case no additional constraint function will be used).
sieveArgs the pointer to pass as the final parameter for the function sieve which will be called upon each triangulation found. If sieve is null then sieveArgs will be ignored.
manager a progress manager via which progess will be reported, or 0 if no progress reporting is required. If non-zero, manager must point to a progress manager for which NProgressManager::isStarted() is still false.
Returns:
the number of triangulations produced in the census, or 0 if a progress manager was passed.

unsigned long regina::NCensus::formPartialCensus const NFacePairing pairing,
NPacket parent,
NBoolSet  finiteness,
NBoolSet  orientability,
int  whichPurge,
AcceptTriangulation  sieve = 0,
void *  sieveArgs = 0
[static]
 

Fills the given packet with all triangulations in a partial census of 3-manifold triangulations satisfying the given constraints.

Each triangulation in the partial census will appear as a child of the given packet.

This routine will conduct a census of all valid triangulations that are modelled by the given tetrahedron face pairing. All such triangulations are included in the census up to combinatorial isomorphism; given any isomorphism class, exactly one representative will appear in the census.

The census can be optionally restricted to only include triangulations satisfying further constraints (such as orientability and finiteness); see the individual parameter descriptions for further details. In particular, parameter sieve can be used to impose arbitrary restrictions that are not hard-coded into this class.

Note that if constraints may be imposed using the hard-coded parameters (such as orientability and finiteness), it is generally better to do this than to use the arbitrary constraint parameter sieve. Hard-coded parameters will be tested earlier, and some (such as orientability) can be incorporated directly into the census algorithm to give a vast performance increase.

Parameter whichPurge may be used to further avoid constructing triangulations satisfying particular constraints (such as non-minimality). The use of this parameter, combined with parameters finiteness and orientability, can significantly speed up the census. For some combinations of these parameters entirely different algorithms are used.

Note however that not all triangulations described by parameter whichPurge will be avoided. It is guaranteed however that every triangulation that does not satisfy the constraints defined by whichPurge will be produced.

Only valid triangulations will be produced; see NTriangulation::isValid() for further details.

Note that this routine should only be used if the partial census contains a small enough total number of triangulations to avoid any memory disasters.

The partial census will run in the current thread. This routine will only return once the partial census is complete.

Precondition:
The given face pairing is connected, i.e., it is possible to reach any tetrahedron from any other tetrahedron via a series of matched face pairs.

The given face pairing is in canonical form as described by NFacePairing::isCanonical(). Note that all face pairings constructed by NFacePairing::findAllPairings() are of this form.

Python:
Parameters sieve and sieveArgs are not present (and will be treated as 0).
Parameters:
pairing the tetrahedron face pairing that triangulations in this partial census must be modelled by.
parent the packet beneath which members of the partial census will be placed.
finiteness determines whether to include finite and/or ideal triangulations. The set should contain true if finite (non-ideal) triangulations are to be included, and should contain false if ideal triangulations are to be included.
orientability determines whether to include orientable and/or non-orientable triangulations. The set should contain true if orientable triangulations are to be included, and should contain false if non-orientable triangulations are to be included.
whichPurge specifies which triangulations we may further avoid constructing (see the function notes above for details). This should be a bitwise OR of purge constants defined in this class, or 0 if no additional pruning should take place. If a variety of purge constants are bitwise ORed together, a triangulation satisfying any of these constraints may be avoided. Note that not all such triangulations will be avoided, but enough are avoided that the performance increase is noticeable.
sieve an additional constraint function that may be used to exclude certain triangulations from the census. If this parameter is non-zero, each triangulation produced (after passing all other criteria) will be passed through this function. If this function returns true then the triangulation will be included in the census; otherwise it will not. When this function is called, the first (triangulation) argument will be a triangulation under consideration for inclusion in the census. The second argument will be parameter sieveArgs as passed to formPartialCensus(). Parameter sieve may be passed as null (in which case no additional constraint function will be used).
sieveArgs the pointer to pass as the final parameter for the function sieve which will be called upon each triangulation found. If sieve is null then sieveArgs will be ignored.
Returns:
the number of triangulations produced in the partial census.

bool regina::NCensus::mightBeMinimal NTriangulation tri,
void *  ignore
[static]
 

Determines whether the given triangulation even has a chance at being minimal.

This routine can be passed as parameter sieve to routine NCensus::formCensus() to exclude obviously non-minimal triangulations from a census.

A variety of tests will be performed; these tests are subject to change between Regina releases. Currently this routine counts vertices and also tries to simplify the triangulation using NTriangulation::simplifyToLocalMinimum().

Currently this routine is only useful for triangulations whose faces are all internal; if the given triangulation has boundary faces then this routine will simply return true.

Python:
Parameter ignore is not present (and will be treated as 0).
Parameters:
tri the triangulation to examine.
ignore a parameter that is ignored.
Returns:
false if the given triangulation is known to be non-minimal, or true if minimality of the given triangulation has not been determined.


Member Data Documentation

const int regina::NCensus::PURGE_NON_MINIMAL [static]
 

Indicates that non-minimal triangulations may be ignored.

const int regina::NCensus::PURGE_NON_MINIMAL_PRIME [static]
 

Indicates that any triangulation that is not prime (i.e., can be written as a non-trivial connected sum), any bounded triangulation that is reducible over a disc and any triangulation that is non-minimal may be ignored.

Note that this is simply a combination of the constants PURGE_NON_MINIMAL and PURGE_NON_PRIME.

const int regina::NCensus::PURGE_NON_PRIME [static]
 

Indicates that any triangulation that is not prime (i.e., can be written as a non-trivial connected sum) and any bounded triangulation that is reducible over a disc may be ignored.

const int regina::NCensus::PURGE_P2_REDUCIBLE [static]
 

Indicates that any triangulation containing an embedded two-sided projective plane may be ignored.


The documentation for this class was generated from the following file:
Copyright © 1999-2004, Ben Burton
This software is released under the GNU General Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).