Regina Calculation Engine
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
regina::NSatBlockStarterSearcher Class Referenceabstract

A helper class for locating and using starter blocks within a triangulation. More...

#include <subcomplex/nsatblockstarter.h>

Public Member Functions

virtual ~NSatBlockStarterSearcher ()
 Destroys this object and its internal structures. More...
 
void findStarterBlocks (NTriangulation *tri)
 Runs a search for every isomorphic embedding of every starter block from the global NSatBlockStarterSet within the given triangulation. More...
 

Protected Member Functions

virtual bool useStarterBlock (NSatBlock *starter)=0
 Used by subclasses to process each starter block embedding that is found. More...
 

Protected Attributes

NSatBlock::TetList usedTets
 Keeps track of which tetrahedra have used by the current embedding of the current starter block. More...
 

Detailed Description

A helper class for locating and using starter blocks within a triangulation.

This class provides a means for searching for each starter block in the global hard-coded NSatBlockStarterSet within a given triangulation. More specifically, given some triangulation t, this class can locate every isomorphic embedding of every starter block in the global NSatBlockStarterSet as a subcomplex of t (see NTriangulation::isContainedIn() for what is meant by "isomorphic embedding").

The routine findStarterBlocks() runs the search. Each time an isomorphic embedding of a starter block is discovered within the given triangulation, the pure virtual routine useStarterBlock() will be called. The block that is passed to useStarterBlock() will be a new block that refers to the particular embedding of the starter block within the given triangulation (as opposed to the original block structure referring to the prebuilt triangulation in NSatBlockStarter).

For each situation that requires searching for starter blocks, a subclass of NSatBlockStarterSearcher will be required. This subclass should override useStarterBlock() to perform whatever action is necessary.

Instead of locating all isomorphic embeddings of all starter blocks in the global set, the search can be made to finish early once certain conditions are met. This is done by implementing useStarterBlock() to return false when the search should quit.

Python:
Not present.

Constructor & Destructor Documentation

regina::NSatBlockStarterSearcher::~NSatBlockStarterSearcher ( )
inlinevirtual

Destroys this object and its internal structures.

Member Function Documentation

void regina::NSatBlockStarterSearcher::findStarterBlocks ( NTriangulation tri)

Runs a search for every isomorphic embedding of every starter block from the global NSatBlockStarterSet within the given triangulation.

Each time an embedding is discovered, the pure virtual routine useStarterBlock() will be called.

See the NSatBlockStarterSearcher class notes for greater detail on what this search does and how it runs.

For subclasses that make use of the usedTets data member, it is worth noting that this routine empties the usedTets list on both entry and exit, as well as every time that useStarterBlock() returns after each new embedding is found.

Parameters
trithe triangulation in which to search for starter blocks.
virtual bool regina::NSatBlockStarterSearcher::useStarterBlock ( NSatBlock starter)
protectedpure virtual

Used by subclasses to process each starter block embedding that is found.

Suppose that the main search routine findStarterBlocks() has been called with some triangulation t. Each time it locates an isomorphic embedding of a starter block within t, it will call useStarterBlock(). Subclasses of NSatBlockStarterSearcher should therefore override useStarterBlock() to process each embedding in whatever way is appropriate for the problem at hand.

The block passed in the argument starter is a newly created structure describing the starter block as it appears within the triangulation t. Thus different embeddings of the same starter block within t will pass different starter arguments to this routine. It is the responsibility of useStarterBlock() to either destroy the new block starter or pass ownership of it elsewhere.

When this routine is called, the data member usedTets will contain a list of all tetrahedra from the triangulation t that appear within the relevant starter block embedding. The reimplementation of useStarterBlock() may modify this list as it pleases, since the main search routine will empty the list anyway when useStarterBlock() returns. One possible use for the usedTets data member is for passing to NSatBlock::isBlock() or NSatRegion::expand() as the list of tetrahedra to avoid in further searches.

This routine must return a boolean; this allows subclasses to immediately terminate the main search once they have found whatever it is they were looking for. A return value of true signifies that the search should continue as normal, whereas a return value of false signifies that the search should end immediately (specifically, that findStarterBlocks() should clean up and return before all remaining embeddings of all starter blocks have been found).

Warning
Subclasses must remember to either destroy or claim ownership of the newly created block starter.
Parameters
startera newly created structure describing the starter block as it appears within the larger triangulation currently under examination.
Returns
true if the search for embeddings of starter blocks should continue, or false if the search should stop immediately.

Member Data Documentation

NSatBlock::TetList regina::NSatBlockStarterSearcher::usedTets
protected

Keeps track of which tetrahedra have used by the current embedding of the current starter block.

See useStarterBlock() for further details.


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

Copyright © 1999-2014, 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@debian.org).