Regina Calculation Engine
Classes | Typedefs | Functions | Variables | Friends
Splitting Surfaces

Splitting surfaces in triangulations. More...

Classes

class  regina::SigCensus
 A utility class used by formSigCensus(). More...
 
class  regina::SigPartialIsomorphism
 Represents a partial isomorphism between two splitting surface signatures. More...
 
class  regina::Signature
 Represents a signature of a splitting surface in a closed 3-manifold triangulation. More...
 

Typedefs

typedef std::list< SigPartialIsomorphism * > regina::SigIsoList
 A list of partial isomorphisms on splitting surface signatures. More...
 
typedef void(* regina::UseSignature) (const Signature &, const SigIsoList &, void *)
 A routine used to do arbitrary processing upon a splitting surface signature and its automorphisms. More...
 

Functions

 regina::SigCensus::~SigCensus ()
 Deallocates any memory used specifically by this structure. More...
 
void * regina::SigCensus::run (void *param)
 Runs a complete signature census generation. More...
 
 regina::SigCensus::SigCensus (const SigCensus &)=delete
 
SigCensusregina::SigCensus::operator= (const SigCensus &)=delete
 
unsigned long regina::formSigCensus (unsigned order, UseSignature use, void *useArgs=0)
 Forms a census of all splitting surface signatures of the given order. More...
 
 regina::SigPartialIsomorphism::SigPartialIsomorphism (int newDir)
 Creates a new partial isomorphism that maps no cycles or symbols. More...
 
 regina::SigPartialIsomorphism::SigPartialIsomorphism (const SigPartialIsomorphism &iso)
 Creates a new partial isomorphism that is a clone of the given partial isomorphism. More...
 
 regina::SigPartialIsomorphism::~SigPartialIsomorphism ()
 Destroys this partial isomorphism. More...
 
void regina::SigPartialIsomorphism::makeCanonical (const Signature &sig, unsigned fromCycleGroup=0)
 Rearranges the cycle images so that this isomorphism when applied to the given signature produces a new signature that is in canonical form. More...
 
int regina::SigPartialIsomorphism::compareWith (const Signature &sig, const SigPartialIsomorphism *other, unsigned fromCycleGroup=0) const
 Lexicographically compares the results of applying this and the given isomorphism to the given signature. More...
 
SigPartialIsomorphismregina::SigPartialIsomorphism::operator= (const SigPartialIsomorphism &)=delete
 
 regina::SigPartialIsomorphism::ShorterCycle::ShorterCycle (const Signature &newSig, const SigPartialIsomorphism &newIso)
 Creates a new comparison function. More...
 
bool regina::SigPartialIsomorphism::ShorterCycle::operator() (unsigned cycle1, unsigned cycle2) const
 Determines whether the image of one cycle is lexicographically less than the image of another. More...
 
 regina::Signature::Signature (const Signature &sig)
 Creates a new signature that is a clone of the given signature. More...
 
 regina::Signature::~Signature ()
 Destroys this signature. More...
 
unsigned regina::Signature::order () const
 Returns the order of this signature. More...
 
static Signatureregina::Signature::parse (const std::string &sig)
 Parses the given signature string. More...
 
Triangulation< 3 > * regina::Signature::triangulate () const
 Returns a newly created 3-manifold triangulation corresponding to this splitting surface signature. More...
 
static int regina::Signature::cycleCmp (const Signature &sig1, unsigned cycle1, unsigned start1, int dir1, unsigned *relabel1, const Signature &sig2, unsigned cycle2, unsigned start2, int dir2, unsigned *relabel2)
 Lexicographically compares the results of transformations upon two given cycles. More...
 
void regina::Signature::writeCycles (std::ostream &out, const std::string &cycleOpen, const std::string &cycleClose, const std::string &cycleJoin) const
 Writes a string representation of this signature to the given output stream. More...
 
void regina::Signature::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
Signatureregina::Signature::operator= (const Signature &)=delete
 

Variables

const Signatureregina::SigPartialIsomorphism::ShorterCycle::sig
 The signature containing the cycles to examine. More...
 
const SigPartialIsomorphismregina::SigPartialIsomorphism::ShorterCycle::iso
 The isomorphism to apply to the cycles before they are compared. More...
 

Friends

struct regina::SigPartialIsomorphism::SigPartialIsomorphism::ShorterCycle
 
class regina::SigCensus
 
class regina::SigPartialIsomorphism
 
class regina::SigCensus
 
unsigned long regina::SigCensus::formSigCensus (unsigned order, UseSignature use, void *useArgs)
 Forms a census of all splitting surface signatures of the given order. More...
 

Detailed Description

Splitting surfaces in triangulations.

Typedef Documentation

◆ SigIsoList

A list of partial isomorphisms on splitting surface signatures.

◆ UseSignature

typedef void(* regina::UseSignature) (const Signature &, const SigIsoList &, void *)

A routine used to do arbitrary processing upon a splitting surface signature and its automorphisms.

Such routines are used to process signatures found when running a signature census.

The first parameter passed should be a splitting surface signature. The second parameter should be a list of all automorphisms of this signature. The third parameter may contain arbitrary data as passed to formSigCensus().

Function Documentation

◆ compareWith()

int regina::SigPartialIsomorphism::compareWith ( const Signature sig,
const SigPartialIsomorphism other,
unsigned  fromCycleGroup = 0 
) const

Lexicographically compares the results of applying this and the given isomorphism to the given signature.

Comparisons are done on a cycle-by-cycle basis; comparisons within a cycle are done as described by Signature::cycleCmp(). Comparison will not proceed beyond the cycles mapped by this partial isomorphism.

Precondition
the given partial isomorphism maps at least as many cycles and symbols as this partial isomorphism.
Parameters
sigthe signature to which both this and the given isomorphism will be applied.
otherthe isomorphism to compare with this isomorphism.
fromCycleGroupthe first cycle group whose images should be examined. If it is already known that the cycle images for the first k cycle groups are identical under both isomorphisms, k should be passed in this parameter. This parameter should not exceed the number of cycle groups whose cycles are mapped by this partial isomorphism.
Returns
-1, 1 or 0 if the image of the given signature under this isomorphism is lexicographically less than, greater than or equal to its image under the given isomorphism respectively.

◆ cycleCmp()

static int regina::Signature::cycleCmp ( const Signature sig1,
unsigned  cycle1,
unsigned  start1,
int  dir1,
unsigned *  relabel1,
const Signature sig2,
unsigned  cycle2,
unsigned  start2,
int  dir2,
unsigned *  relabel2 
)
static

Lexicographically compares the results of transformations upon two given cycles.

Even if transformations are specified, the underlying signatures will not be changed.

This comparison is not case-sensitive.

Precondition
The two specified cycles have the same length.
Python:\n Not present.
Parameters
sig1the signature containing the first cycle to examine.
cycle1specifies which cycle to examine in signature sig1. This must be less than the total number of cycles in sig1.
start1allows the first cycle to be transformed by rotation; this parameter is the new starting position of the first cycle. This must be between 0 and sig1.getCycleLength(cycle1)-1 inclusive.
dir1allows the first cycle to be transformed by reversal; this parameter must be positive to use an unreversed cycle or negative to use a reversed cycle.
relabel1allows the first cycle to be transformed by relabelling; this parameter must be an array of size at least sig1.order() mapping old labels 0,1,... (representing letters A,B,...) to new labels (which must also be 0,1,..., possibly in a different order). This parameter may be 0 if no relabelling is to be used.
sig2the signature containing the second cycle to examine.
cycle2specifies which cycle to examine in signature sig2. This must be less than the total number of cycles in sig2.
start2allows the second cycle to be transformed by rotation; this parameter is the new starting position of the second cycle. This must be between 0 and sig2.getCycleLength(cycle2)-1 inclusive.
dir2allows the second cycle to be transformed by reversal; this parameter must be positive to use an unreversed cycle or negative to use a reversed cycle.
relabel2allows the second cycle to be transformed by relabelling; this parameter must be an array of size at least sig2.order() mapping old labels 0,1,... (representing letters A,B,...) to new labels (which must also be 0,1,..., possibly in a different order). This parameter may be 0 if no relabelling is to be used.
Returns
-1, 1 or 0 if the transformed first cycle is lexicographically less than, greater than or equal to the transformed second cycle respectively.

◆ formSigCensus()

unsigned long regina::formSigCensus ( unsigned  order,
UseSignature  use,
void *  useArgs = 0 
)

Forms a census of all splitting surface signatures of the given order.

The order of a signature is the number of quads in the corresponding splitting surface.

Each signature will be produced precisely once up to equivalence. Signatures are considered equivalent if they are related by some combination of:

  • relabelling symbols;
  • rotating an individual cycle;
  • inverting an individual cycle (i.e., reversing the cycle and changing the case of each symbol in the cycle);
  • reversing all cycles without changing the case of any symbols.

Each signature produced will have its cycles ordered by decreasing length. Each cycle will have at least half of its symbols lower-case.

For each signature that is generated, routine use (as passed to this function) will be called with that signature and its automorphisms as arguments.

Warning
Currently upper-case symbols in signatures are not supported by this routine; only signatures whose symbols are all lower-case will be produced.
Todo:
Feature: Add support for symbols of differing case.
Python:\n Not present.
Parameters
orderthe order of signatures to generate.
usethe function to call upon each signature that is found. The first parameter passed to this function will be a splitting surface signature. The second parameter will be a list of all its automorphisms. The third parameter will be parameter useArgs as was passed to this routine.
useArgsthe pointer to pass as the final parameter for the function use which will be called upon each signature found.
Returns
the total number of non-equivalent signatures that were found.

◆ makeCanonical()

void regina::SigPartialIsomorphism::makeCanonical ( const Signature sig,
unsigned  fromCycleGroup = 0 
)

Rearranges the cycle images so that this isomorphism when applied to the given signature produces a new signature that is in canonical form.

The result of this routine is dependent upon the symbol map defined by this isomorphism (this symbol map will not be changed).

Parameters
sigthe signature to which this isomorphism will be applied.
fromCycleGroupthe first cycle group whose images may be rearranged. If it is already known that the cycle images for the first k cycle groups are correct, k should be passed in this parameter. This parameter should not exceed the number of cycle groups whose cycles are mapped by this partial isomorphism.

◆ operator()()

bool regina::SigPartialIsomorphism::ShorterCycle::operator() ( unsigned  cycle1,
unsigned  cycle2 
) const
inline

Determines whether the image of one cycle is lexicographically less than the image of another.

See the class notes for further details on how this comparison is done.

Parameters
cycle1the index of the first cycle to examine; this must be less than the total number of cycles mapped by the isomorphism concerned and less than the total number of cycles in the signature concerned.
cycle2the index of the second cycle to examine; this must be less than the total number of cycles mapped by the isomorphism concerned and less than the total number of cycles in the signature concerned.
Returns
true if and only if the image of the first cycle is less than the image of the second cycle.

◆ order()

unsigned regina::Signature::order ( ) const
inline

Returns the order of this signature.

The order is the number of quads in the corresponding splitting surface.

Returns
the order of this signature.

◆ parse()

static Signature* regina::Signature::parse ( const std::string &  sig)
static

Parses the given signature string.

Punctuation characters in the given string will be interpreted as separating cycles. All whitespace will be ignored.

Examples of valid signatures are "(ab)(bC)(Ca)" and "AAb-bc-C". See the class notes for further details on what constitutes a valid signature.

Precondition
The given string contains at least one letter.
Parameters
siga string representation of a splitting surface signature.
Returns
a corresponding newly created signature, or 0 if the given string was invalid.

◆ run()

void* regina::SigCensus::run ( void *  param)

Runs a complete signature census generation.

At most one copy of this routine should be running at any given time for a particular SigCensus.

Parameters
paramthis parameter is ignored.
Returns
0.

◆ ShorterCycle()

regina::SigPartialIsomorphism::ShorterCycle::ShorterCycle ( const Signature newSig,
const SigPartialIsomorphism newIso 
)
inline

Creates a new comparison function.

Parameters
newSigthe signature containing the cycles that this function will examine.
newIsothe partial isomorphism to apply to the cycles before they are compared.

◆ Signature()

regina::Signature::Signature ( const Signature sig)

Creates a new signature that is a clone of the given signature.

Parameters
sigthe signature to clone.

◆ SigPartialIsomorphism() [1/2]

regina::SigPartialIsomorphism::SigPartialIsomorphism ( const SigPartialIsomorphism iso)

Creates a new partial isomorphism that is a clone of the given partial isomorphism.

Parameters
isothe partial isomorphism to clone.

◆ SigPartialIsomorphism() [2/2]

regina::SigPartialIsomorphism::SigPartialIsomorphism ( int  newDir)
inline

Creates a new partial isomorphism that maps no cycles or symbols.

This empty isomorphism is designed to be extended at some later point.

Parameters
newDirpositive if this isomorphism specifies that all cycles are reversed, or negative if this isomorphism specifies that all cycles keep their original direction.

◆ triangulate()

Triangulation<3>* regina::Signature::triangulate ( ) const

Returns a newly created 3-manifold triangulation corresponding to this splitting surface signature.

Returns
the corresponding triangulation.

◆ writeCycles()

void regina::Signature::writeCycles ( std::ostream &  out,
const std::string &  cycleOpen,
const std::string &  cycleClose,
const std::string &  cycleJoin 
) const

Writes a string representation of this signature to the given output stream.

Python:\n The parameter out does not exist; standard
output will be used.
Parameters
outthe output stream to which to write.
cycleOpenthe text to write at the beginning of a cycle (such as "(").
cycleClosethe text to write at the end of a cycle (such as ")").
cycleJointhe text to write between two cycles.

◆ writeTextShort()

void regina::Signature::writeTextShort ( std::ostream &  out) const
inline

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

Python:\n Not present.
Parameters
outthe output stream to which to write.

◆ ~SigCensus()

regina::SigCensus::~SigCensus ( )
inline

Deallocates any memory used specifically by this structure.

◆ ~Signature()

regina::Signature::~Signature ( )
inline

Destroys this signature.

◆ ~SigPartialIsomorphism()

regina::SigPartialIsomorphism::~SigPartialIsomorphism ( )
inline

Destroys this partial isomorphism.

Variable Documentation

◆ iso

const SigPartialIsomorphism& regina::SigPartialIsomorphism::ShorterCycle::iso

The isomorphism to apply to the cycles before they are compared.

◆ sig

const Signature& regina::SigPartialIsomorphism::ShorterCycle::sig

The signature containing the cycles to examine.

Friends

◆ formSigCensus

unsigned long formSigCensus ( unsigned  order,
UseSignature  use,
void *  useArgs 
)
friend

Forms a census of all splitting surface signatures of the given order.

The order of a signature is the number of quads in the corresponding splitting surface.

Each signature will be produced precisely once up to equivalence. Signatures are considered equivalent if they are related by some combination of:

  • relabelling symbols;
  • rotating an individual cycle;
  • inverting an individual cycle (i.e., reversing the cycle and changing the case of each symbol in the cycle);
  • reversing all cycles without changing the case of any symbols.

Each signature produced will have its cycles ordered by decreasing length. Each cycle will have at least half of its symbols lower-case.

For each signature that is generated, routine use (as passed to this function) will be called with that signature and its automorphisms as arguments.

Warning
Currently upper-case symbols in signatures are not supported by this routine; only signatures whose symbols are all lower-case will be produced.
Todo:
Feature: Add support for symbols of differing case.
Python:\n Not present.
Parameters
orderthe order of signatures to generate.
usethe function to call upon each signature that is found. The first parameter passed to this function will be a splitting surface signature. The second parameter will be a list of all its automorphisms. The third parameter will be parameter useArgs as was passed to this routine.
useArgsthe pointer to pass as the final parameter for the function use which will be called upon each signature found.
Returns
the total number of non-equivalent signatures that were found.

Copyright © 1999-2018, 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@maths.uq.edu.au).