Splitting Surfaces

## 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...
typedef SigCensus | regina::NSigCensus
| Deprecated typedef for backward compatibility. More...
typedef SigIsoList | regina::NSigIsoList
| Deprecated typedef for backward compatibility. More...
typedef SigPartialIsomorphism | regina::NSigPartialIsomorphism
| Deprecated typedef for backward compatibility. More...
typedef Signature | regina::NSignature
| Deprecated typedef for backward compatibility. 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...
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...
| 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 Signature * | regina::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...

## Variables

const Signature & | regina::SigPartialIsomorphism::ShorterCycle::sig
| The signature containing the cycles to examine. More...
const SigPartialIsomorphism & | regina::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

## NSigCensus

typedef SigCensus regina::NSigCensus

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NSigCensus has now been renamed to SigCensus.

## NSigIsoList

typedef SigIsoList regina::NSigIsoList

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The typedef NSigIsoList has now been renamed to SigIsoList.

## NSignature

typedef Signature regina::NSignature

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NSignature has now been renamed to Signature.

## NSigPartialIsomorphism

typedef SigPartialIsomorphism regina::NSigPartialIsomorphism

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
  The class NSigPartialIsomorphism has now been renamed to SigPartialIsomorphism.

## SigIsoList

typedef std::list<SigPartialIsomorphism*> regina::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

  sig | the signature to which both this and the given isomorphism will be applied.
  other | the isomorphism to compare with this isomorphism.
  fromCycleGroup | the 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

  sig1 | the signature containing the first cycle to examine.
  cycle1 | specifies which cycle to examine in signature sig1. This must be less than the total number of cycles in sig1.
  start1 | allows 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.
  dir1 | allows 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.
  relabel1 | allows 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.
  sig2 | the signature containing the second cycle to examine.
  cycle2 | specifies which cycle to examine in signature sig2. This must be less than the total number of cycles in sig2.
  start2 | allows 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.
  dir2 | allows 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.
  relabel2 | allows 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

  order | the order of signatures to generate.
  use | the 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.
  useArgs | the 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

  sig | the signature to which this isomorphism will be applied.
  fromCycleGroup | the 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

  cycle1 | the 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.
  cycle2 | the 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

  sig | a 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

  param | this parameter is ignored.

Returns
  0.

## ShorterCycle()

regina::SigPartialIsomorphism::ShorterCycle::ShorterCycle | ( | const Signature & | newSig,
|  | const SigPartialIsomorphism & | newIso
| ) |  |

inline

Creates a new comparison function.

Parameters

  newSig | the signature containing the cycles that this function will examine.
  newIso | the 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

  sig | the 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

  iso | the 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

  newDir | positive 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

  out | the output stream to which to write.
  cycleOpen | the text to write at the beginning of a cycle (such as `"("`).
  cycleClose | the text to write at the end of a cycle (such as `")"`).
  cycleJoin | the 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

  out | the 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

  order | the order of signatures to generate.
  use | the 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.
  useArgs | the 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-2016, 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).