Describes the cellular decomposition of a closed orientable surface induced by a 4-valent graph embedded within it. More...

#include <link/modellinkgraph.h>

Inheritance diagram for regina::ModelLinkGraphCells:

Public Types
using	ArcIterator = const ModelLinkGraphArc*
	An iterator type used when traversing the boundary of a 2-cell.

Public Member Functions
size_t	countCells () const
	Returns the total number of 2-cells in this cellular decomposition.

size_t	countEdges () const
	Returns the total number of (undirected) edges in this cellular decomposition.

size_t	countArcs () const
	Returns the total number of directed arcs in the underlying graph.

size_t	countNodes () const
	Returns the total number of vertices in this cellular decomposition; that is, the total number of nodes in the underlying graph.

size_t	countComponents () const
	Returns the number of connected components in this surface.

size_t	genus () const
	Returns the genus of this closed orientable surface.

size_t	size (size_t cell) const
	Returns the number of arcs aloung the boundary of the given 2-cell.

const ModelLinkGraphArc &	arc (size_t cell, size_t which) const
	Returns the given arc along the boundary of the given 2-cell.

auto	arcs (size_t cell) const
	Returns an object that allows iteration through and random access to all arcs along the boundary of the given 2-cell.

ArcIterator	begin (size_t cell) const
	Returns the beginning of an iterator range for walking around the boundary of the given 2-cell.

ArcIterator	end (size_t cell) const
	Returns the end of an iterator range for walking around the boundary of the given 2-cell.

size_t	cell (const ModelLinkGraphArc &arc) const
	Returns the 2-cell that lies to the left of the given arc.

size_t	cellPos (const ModelLinkGraphArc &arc) const
	Returns where the given arc appears along the boundary of the 2-cell to its left.

bool	operator== (const ModelLinkGraphCells &other) const
	Determines if this and the given cellular decomposition are combinatorially identical.

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream.

void	writeTextLong (std::ostream &out) const
	Writes a detailed text representation of this object to the given output stream.

ModelLinkGraphCells &	operator= (const ModelLinkGraphCells &)=delete

std::string	str () const
	Returns a short text representation of this object.

std::string	utf8 () const
	Returns a short text representation of this object using unicode characters.

std::string	detail () const
	Returns a detailed text representation of this object.

Friends
class	ModelLinkGraph

Detailed Description

Describes the cellular decomposition of a closed orientable surface induced by a 4-valent graph embedded within it.

The graph is represented by an object of type ModelLinkGraph, which encodes a local embedding of the graph within the surface (i.e., a cyclic ordering of arcs around each graph node). The nodes and arcs of this graph form the vertices and edges of the cellular decomposition, and the 2-cells are topological discs whose boundaries follow these nodes and arcs according to their local embeddings. The main purpose of this class is to deduce and describe those 2-cells.

As of Regina 7.4, this class can now work with graphs that are non-planar (resulting in a surface with positive genus), disconnected (resulting in a surface that is likewise disconnected), and/or empty (resulting in an empty surface).

Cellular decompositions do not support value semantics: they cannot be copied, swapped, or manually constructed. Instead they are computed properties of model graphs, and are only accessible via const reference through the member function ModelLinkGraph::cells().

Member Typedef Documentation

◆ ArcIterator

using regina::ModelLinkGraphCells::ArcIterator = const ModelLinkGraphArc*

An iterator type used when traversing the boundary of a 2-cell.

Member Function Documentation

◆ arc()

const ModelLinkGraphArc & regina::ModelLinkGraphCells::arc	(	size_t	cell,
		size_t	which ) const

inline

Returns the given arc along the boundary of the given 2-cell.

For each cell, the arcs along the boundary are given in order as you walk anticlockwise around the cell (so the cell is on the left of each arc as you walk around the cell boundary).

Each arc is described in the form of an outgoing arc from some node of the underlying graph (so if the return ModelLinkGraphArc is a then this describes an outgoing arc from a.node()). It follows that, if the underlying graph has n nodes, then each of the 4n possible ModelLinkGraphArc values appears exactly once as arc(cell, which) for some integers cell and which.

Parameters

cell	indicates which cell to query; this must be between 0 and countCells()-1 inclusive.
which	indicates which arc along the boundary of the corresponding cell to return; this must be between 0 and `size(cell)-1` inclusive.

Returns: the requested arc on the boundary of the given 2-cell.

◆ arcs()

auto regina::ModelLinkGraphCells::arcs ( size_t cell ) const

inline

Returns an object that allows iteration through and random access to all arcs along the boundary of the given 2-cell.

Suppose that the ith cell is a k-gon. Then this object gives access to the k arcs along the boundary of the ith cell in the same order as described by arc(); that is, walking anticlockwise around the cell boundary with the cell to the left of each arc.

The object that is returned is lightweight, and can be happily copied by value. The C++ type of the object is subject to change, so C++ users should use auto (just like this declaration does).

The returned object is guaranteed to be an instance of ListView, which means it offers basic container-like functions and supports range-based for loops. The elements of the list will be read-only objects of type ModelLinkGraphArc, and so your code might look like:

for (const ModelLinkGraphArc& a : cells.arcs(cell)) { ... }

regina::ModelLinkGraphArc

A reference to an outgoing edge from a node of a model graph for a knot or link.

Definition modellinkgraph.h:136

regina::ModelLinkGraphCells::arcs

auto arcs(size_t cell) const

Returns an object that allows iteration through and random access to all arcs along the boundary of t...

Definition modellinkgraph.h:2423

regina::ModelLinkGraphCells::cell

size_t cell(const ModelLinkGraphArc &arc) const

Returns the 2-cell that lies to the left of the given arc.

Definition modellinkgraph.h:2438

Using arcs(cell) is equivalent to iterating over the iterator range (begin(cell), end(cell)). Using arcs() generates a tiny amount of extra overhead, but you may also find it more readable.

Parameters

cell	indicates which cell to query; this must be between 0 and countCells()-1 inclusive.

Returns: access to the list of all arcs along the boundary of the given cell.

◆ begin()

ModelLinkGraphCells::ArcIterator regina::ModelLinkGraphCells::begin ( size_t cell ) const

inline

Returns the beginning of an iterator range for walking around the boundary of the given 2-cell.

Suppose that the ith cell is a k-gon. Then the iterator range described by begin(i) and end(i) will iterate through the k arcs along the boundary of the ith cell in the same order as described by arc(); that is, walking anticlockwise around the cell boundary with the cell to the left of each arc.

Dereferencing the jth iterator in this range gives the same result as calling arc(cell, j), and iterating over the entire range (begin(cell), end(cell)) is equivalent to iterating over arcs(cell).

Python: Not present. Python users can iterate over arcs(cell) instead.

Parameters

cell	indicates which cell to walk around; this must be between 0 and countCells()-1 inclusive.

Returns: the beginning of an iterator range for the boundary of the given cell.

◆ cell()

size_t regina::ModelLinkGraphCells::cell ( const ModelLinkGraphArc & arc ) const

inline

Returns the 2-cell that lies to the left of the given arc.

Specifically, this function returns the number of the cell that lies to the left of the given arc as you walk along it away from arc.node().

For any arc a, calling arc(cell(a), cellPos(a)) will return the same arc a again.

Parameters

arc	the given arc of the underlying graph.

Returns: the number of the cell that lies to the left of the given arc; this will be an integer between 0 and countCells()-1 inclusive.

◆ cellPos()

size_t regina::ModelLinkGraphCells::cellPos ( const ModelLinkGraphArc & arc ) const

inline

Returns where the given arc appears along the boundary of the 2-cell to its left.

Consider the cell c to the left of the given arc as you follow the arc away from arc.node(). The routine arc() can be used to enumerate the sequence of arcs along the boundary of this cell c, in order as you walk anticlockwise around the cell boundary. The purpose of this routine is to identify where in this sequence the given arc occurs.

For any arc a, calling arc(cell(a), cellPos(a)) will return the same arc a again.

Parameters

arc	the given arc of the underlying graph.

Returns: the position of the given arc on the boundary of the cell to its left; this will be an integer between 0 and size(cell(arc))-1 inclusive.

◆ countArcs()

size_t regina::ModelLinkGraphCells::countArcs ( ) const

inline

Returns the total number of directed arcs in the underlying graph.

This is always four times the number of nodes in the graph.

Recall that each undirected edge of the graph corresponds to two directed arcs (one exiting each endpoint of the edge).

Returns: the total number of directed arcs.

◆ countCells()

size_t regina::ModelLinkGraphCells::countCells ( ) const

inline

Returns the total number of 2-cells in this cellular decomposition.

In the common case where this surface is the 2-sphere (i.e., the underlying graph models a knot diagram), this will be exactly two more than the number of nodes in the underlying graph.

Note: As of Regina 7.4, this routine will only return 0 when the underlying graph is empty (and so this surface is empty also). In previous versions of Regina, this routine also returned 0 if the graph was non-planar (a scenario that was previously unsupported).

Returns: the total number of 2-cells.

◆ countComponents()

size_t regina::ModelLinkGraphCells::countComponents ( ) const

inline

Returns the number of connected components in this surface.

This will be the same as the number of components of the underlying graph.

Returns: the number of connected components.

◆ countEdges()

size_t regina::ModelLinkGraphCells::countEdges ( ) const

inline

Returns the total number of (undirected) edges in this cellular decomposition.

This is always twice the number of nodes in the underlying graph.

Returns: the total number of edges.

◆ countNodes()

size_t regina::ModelLinkGraphCells::countNodes ( ) const

inline

Returns the total number of vertices in this cellular decomposition; that is, the total number of nodes in the underlying graph.

Returns: the total number of nodes.

◆ detail()

std::string regina::Output< ModelLinkGraphCells, false >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns: a detailed text representation of this object.

◆ end()

ModelLinkGraphCells::ArcIterator regina::ModelLinkGraphCells::end ( size_t cell ) const

inline

Returns the end of an iterator range for walking around the boundary of the given 2-cell.

As is usual for iterator ranges, this is a past-the-end value (i.e., this iterator cannot be dereferenced).

Suppose that the ith cell is a k-gon. Then the iterator range described by begin(i) and end(i) will iterate through the k arcs along the boundary of the ith cell in the same order as described by arc(); that is, walking anticlockwise around the cell boundary with the cell to the left of each arc.

Dereferencing the jth iterator in this range gives the same result as calling arc(cell, j), and iterating over the entire range (begin(cell), end(cell)) is equivalent to iterating over arcs(cell).

Python: Not present. Python users can iterate over arcs(cell) instead.

Parameters

cell	indicates which cell to walk around; this must be between 0 and countCells()-1 inclusive.

Returns: the end of an iterator range for the boundary of the given cell.

◆ genus()

size_t regina::ModelLinkGraphCells::genus ( ) const

inline

Returns the genus of this closed orientable surface.

If the surface has multiple components then this will sum the genus over each component.

Returns: the genus of this surface.

◆ operator==()

bool regina::ModelLinkGraphCells::operator== ( const ModelLinkGraphCells & other ) const

Determines if this and the given cellular decomposition are combinatorially identical.

Here "identical" means that both decompositions have the same number of cells, these cells are presented in the same order, and their boundaries enter and exit the same numbered arcs of the same numbered nodes, using the same directions of traversal and the same starting points on each cell boundary.

Parameters

other the cellular decomposition to compare with this.

Returns: true if and only if the two cellular decompositions are combinatorially identical.

◆ size()

size_t regina::ModelLinkGraphCells::size ( size_t cell ) const

inline

Returns the number of arcs aloung the boundary of the given 2-cell.

If the given cell is a k-gon, then this routine returns the integer k.

Parameters

cell	indicates which cell to query; this must be between 0 and countCells()-1 inclusive.

Returns: the size of the correpsonding 2-cell.

◆ str()

std::string regina::Output< ModelLinkGraphCells, false >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python: The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ utf8()

std::string regina::Output< ModelLinkGraphCells, false >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ writeTextLong()

void regina::ModelLinkGraphCells::writeTextLong ( std::ostream & out ) const

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

Python: Not present. Use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

void regina::ModelLinkGraphCells::writeTextShort ( std::ostream & out ) const

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

Python: Not present. Use str() instead.

Parameters

out	the output stream to which to write.

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

link/modellinkgraph.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ ArcIterator

Member Function Documentation

◆ arc()

◆ arcs()

◆ begin()

◆ cell()

◆ cellPos()

◆ countArcs()

◆ countCells()

◆ countComponents()

◆ countEdges()

◆ countNodes()

◆ detail()

◆ end()

◆ genus()

◆ operator==()

◆ size()

◆ str()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()