regina::NClosedPrimeMinSearcher Class Reference
[Census of Triangulations]

A gluing permutation search class that offers a specialised search algorithm for when (i) only closed prime minimal P2-irreducible triangulations are required, and (ii) the given face pairing has order at least three. More...

#include <ngluingpermsearcher.h>

Inheritance diagram for regina::NClosedPrimeMinSearcher:

regina::NGluingPermSearcher regina::NGluingPerms List of all members.

Public Member Functions

 NClosedPrimeMinSearcher (const NFacePairing *pairing, const NFacePairingIsoList *autos, bool orientableOnly, UseGluingPerms use, void *useArgs=0)
 Creates a new search manager for use when (i) only closed prime minimal P2-irreducible triangulations are required, and (ii) the given face pairing has order at least three.
 NClosedPrimeMinSearcher (std::istream &in, UseGluingPerms use, void *useArgs=0)
 Initialises a new search manager based on data read from the given input stream.
virtual ~NClosedPrimeMinSearcher ()
 Destroys this search manager and all supporting data structures.
virtual void dumpData (std::ostream &out) const
 Dumps all internal data in a plain text format to the given output stream.
virtual void runSearch (long maxDepth=-1)
 Generates all possible gluing permutation sets that satisfy the current search criteria.
virtual bool completePermSet () const
 Determines whether this search manager holds a complete gluing permutation set or just a partially completed search state.

Static Public Attributes

static const char dataTag_
 A character used to identify this class when reading and writing tagged data in text format.

Protected Member Functions

virtual char dataTag () const
 Returns the character used to identify this class when storing tagged data in text format.

Classes

struct  TetEdgeState
 A structure used to track equivalence classes of tetrahedron edges as the gluing permutation is constructed.
struct  TetVertexState
 A structure used to track equivalence classes of tetrahedron vertices as the gluing permutation is constructed.

Detailed Description

A gluing permutation search class that offers a specialised search algorithm for when (i) only closed prime minimal P2-irreducible triangulations are required, and (ii) the given face pairing has order at least three.

The search algorithm is significantly different from the default algorithm provided by NGluingPermSearcher. It is heavily optimised and takes advantage of a number of results regarding the underlying face pairing graph.

Note that additional unwanted triangulations (e.g., non-prime or non-minimal triangulations) may still be produced by this search. However, significantly fewer unwanted triangulations will be produced when using this class instead of NGluingPermSearcher.

Python:
Not present.


Constructor & Destructor Documentation

regina::NClosedPrimeMinSearcher::NClosedPrimeMinSearcher ( const NFacePairing pairing,
const NFacePairingIsoList autos,
bool  orientableOnly,
UseGluingPerms  use,
void *  useArgs = 0 
)

Creates a new search manager for use when (i) only closed prime minimal P2-irreducible triangulations are required, and (ii) the given face pairing has order at least three.

Note that other unwanted triangulations may still be produced (e.g., non-prime or non-minimal triangulations), but there will be far fewer of these than when using the NGluingPermSearcher class directly.

For details on how a search manager is used, see the NGluingPermSearcher documentation. Note in particular that this class will be automatically used by NGluingPermSearcher::findAllPerms() if possible, so there is often no need for an end user to instantiate this class directly.

All constructor arguments are the same as for the NGluingPermSearcher constructor, though some arguments (such as finiteOnly and whichPurge) are not needed here since they are already implied by the specialised search context.

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.

The given face pairing has no boundary faces and has at least three tetrahedra.

regina::NClosedPrimeMinSearcher::NClosedPrimeMinSearcher ( std::istream &  in,
UseGluingPerms  use,
void *  useArgs = 0 
)

Initialises a new search manager based on data read from the given input stream.

This may be a new search or a partially completed search.

This routine reads data in the format written by dumpData(). If you wish to read data whose precise class is unknown, consider using dumpTaggedData() and readTaggedData() instead.

If the data found in the input stream is invalid or incorrectly formatted, the routine inputError() will return true but the contents of this object will be otherwise undefined.

The arguments use and useArgs are the same as for the NGluingPermSearcher constructor.

Warning:
The data format is liable to change between Regina releases. Data in this format should be used on a short-term temporary basis only.
Parameters:
in the input stream from which to read.

regina::NClosedPrimeMinSearcher::~NClosedPrimeMinSearcher (  )  [inline, virtual]

Destroys this search manager and all supporting data structures.


Member Function Documentation

bool regina::NClosedPrimeMinSearcher::completePermSet (  )  const [inline, virtual]

Determines whether this search manager holds a complete gluing permutation set or just a partially completed search state.

This may assist the use_ routine when running partial depth-based searches. See runSearch() for further details.

Returns:
true if a complete gluing permutation set is held, or false otherwise.

Reimplemented from regina::NGluingPermSearcher.

char regina::NClosedPrimeMinSearcher::dataTag (  )  const [inline, protected, virtual]

Returns the character used to identify this class when storing tagged data in text format.

Returns:
the class tag.

Reimplemented from regina::NGluingPermSearcher.

virtual void regina::NClosedPrimeMinSearcher::dumpData ( std::ostream &  out  )  const [virtual]

Dumps all internal data in a plain text format to the given output stream.

This object can be recreated from this text data by calling the input stream constructor for this class.

This routine may be useful for transferring objects from one processor to another.

Note that subclass data is written after superclass data, so it is safe to dump data from a subclass and then recreate a new superclass object from that data (though subclass-specific information will of course be lost).

Warning:
The data format is liable to change between Regina releases. Data in this format should be used on a short-term temporary basis only.
Parameters:
out the output stream to which the data should be written.

Reimplemented from regina::NGluingPermSearcher.

virtual void regina::NClosedPrimeMinSearcher::runSearch ( long  maxDepth = -1  )  [virtual]

Generates all possible gluing permutation sets that satisfy the current search criteria.

The search criteria are specified in the class constructor, or through the static method findAllPerms().

Each set of gluing permutations will be produced precisely once up to equivalence, where equivalence is defined by the given set of automorphisms of the given face pairing.

For each permutation set that is generated, routine use_ (as passed to the class constructor) will be called with that permutation set as an argument.

Once the generation of permutation sets has finished, routine use_ will be called once more, this time with null as its first (permutation set) argument.

Subclasses corresponding to more specialised search criteria should override this routine to use a better optimised algorithm where possible.

It is possible to run only a partial search, branching to a given depth but no further. In this case, rather than producing complete gluing permutation sets, the search will produce a series of partially-complete NGluingPermSearcher objects. These partial searches may then be restarted by calling runSearch() once more (usually after being frozen or passed on to a different processor). If necessary, the use_ routine may call completePermSet() to distinguish between a complete set of gluing permutations and a partial search state.

Note that a restarted search will never drop below its initial depth. That is, calling runSearch() with a fixed depth can be used to subdivide the overall search space into many branches, and then calling runSearch() on each resulting partial search will complete each of these branches without overlap.

Todo:
Feature: Allow cancellation of permutation set generation.
Parameters:
maxDepth the depth of the partial search to run, or a negative number if a full search should be run (the default).

Reimplemented from regina::NGluingPermSearcher.


Member Data Documentation

const char regina::NClosedPrimeMinSearcher::dataTag_ [static]

A character used to identify this class when reading and writing tagged data in text format.

Reimplemented from regina::NGluingPermSearcher.


The documentation for this class was generated from the following file:
Copyright © 1999-2006, 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).