Regina Calculation Engine
|
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... | |
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.
|
inlinevirtual |
Destroys this object and its internal structures.
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.
tri | the triangulation in which to search for starter blocks. |
|
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).
starter | a newly created structure describing the starter block as it appears within the larger triangulation currently under examination. |
true
if the search for embeddings of starter blocks should continue, or false
if the search should stop immediately.
|
protected |
Keeps track of which tetrahedra have used by the current embedding of the current starter block.
See useStarterBlock() for further details.