This assertion is checked only in the INDEX_CHECKS compilation mode.
(Average, maximal, actual) dimension of a facet, that is, number of vertices in it.
Either a functor class satisfying the extended requirements for binary operations, or an untyped template of such a class wrapped into BuildBinary or BuildBinaryIt (preferably expressed via the convenience typedef from namespace polymake::operations.
(Average, maximal) degree of a vertex, that is, number of facets containing it.
This assertion is checked only in the AVL_CHECKS compilation mode.
Either a functor class satisfying the extended requirements for unary operations, or an untyped template of such a class wrapped into BuildUnary or BuildUnaryIt (preferably expressed via the convenience typedef from namespace polymake::operations.

Prerequisits

#include <FacetList.h>
using namespace polymake; 

Introduction

class FacetList;

This is a collection of sets of integral numbers from a closed contiguous range [0..n-1], as one usually has to deal with when modeling simplicial complexes and related mathematical objects. Thus we will refer to the contained sets as facets, and to the set elements as vertices.

The main invariant is that all facets are mutually inclusion-free. The primary design goal of this class is effective search, insertion, and removal of facets included in or including a given vertex set.

The data structure is a rectangular grid, similar to a vertex-facet incidence matrix, interwoven with a forest of suffix trees, indexed with the vertex number. This also provides the lexicographical facet ordering as a pleasant side effect. The whole thing is attached to a smart pointer with reference counting.

Construction

explicit FacetList (int n_vertices=0);
Create an empty list. Allocate the internal data structures capable of handling sets of vertices from the range [0 .. n_vertices-1] in advance. The vertex range can be dynamically expanded later, by insert* and push_back operations, with reallocation costs O(n_vertices).
template <typename Iterator> FacetList (Iterator src, end_sensitive);
Initialize the facets from the input sequence. The items obtained by dereferencing src must be sets of cardinals.
The only purpose of the dummy argument end_sensitive is to signal that the first argument src has to be treated as an end-sensitive iterator. A template constructor with a single argument would shadow all other constructors away!
template <typename Iterator> FacetList (int n_vertices, Iterator src);
As above, but avoiding reallocation during the construction. The facets supplied by src may not contain vertices outside the range [0, n_vertices-1].
template <typename PowerSet> FacetList (const GenericSet<PowerSet>&);
Initialize the facets from the elements of a given set. Obviously, it should be a set of integral sets kept in lexicographical order.
template <typename PowerSet> FacetList (int n_vertices, const GenericSet<PowerSet>&);
As above, but avoiding reallocation during the construction. The facets from the input may not contain vertices outside the range [0, n_vertices-1].
void push_back (const GenericSet&);
Add a facet to the list. This method is primarily thought of as an construction aid, if none of the explicit constructors above suites, and enables the use of the convenient std::back_inserter. The operation costs are O(d);
The given facet must be lexicographically greater than all facets added before.

Modification

void std::swap(FacetList&, FacetList&);
Swap the contents of two lists in a most efficient way.
void clear();
Make the list empty, release all allocated resources.
void squeeze(); template <typename IndexConsumer> void squeeze(IndexConsumer index_consumer);
Each facet passed to the constructor or one of insertion methods described below gets an unique integer index (id). Even if the is not included eventually, the id assigned to it doesn't get recycled (well, as long as the machine integer doesn't overflow.) Thus the numbering can contain gaps.
These methods renumber the facets consequently, starting with 0, eliminating the gaps. You can gather the old ids passing an index_consumer output iterator.
void insert (const GenericSet&);
Add a new facet without checking the inclusion relation to the existing facets. It should be guaranteed by the application logic, that the non-inclusion invariant is not violated! There is no debugging mode that could detect this.
The operation costs are O(d + D).
void erase (const iterator&);
Remove the facet pointed to by the given iterator.
int erase (const GenericSet&);
Find the facet equal to the given vertex set and remove it from the list. Returns 1 if a facet was removed or 0 if no matching facet was found.
The operation costs are O(d + D).
bool insertMax (const GenericSet&); template <typename FacetConsumer> bool insertMax (const GenericSet&, FacetConsumer);
Add a new facet if and only if there are no facets including it. If this holds, remove also all facets that are included in the new one. Return true if the new facet was really included.
The average operation costs are O(d2 D).
The second optional argument can be used to gather the facets removed by the operation. It must implement the output iterator interface; its value_type must be either int, if it is collecting the facet id's, or GenericSet<...,int> , if it is collecting the complete facets.
bool insertMin (const GenericSet&); template <typename FacetConsumer> bool insertMin (const GenericSet&, FacetConsumer);
The opposite of insertMax: add a new facet if and only if there are no facets included in it, remove all facets including the new facet.
bool replaceMax (const GenericSet&); bool replaceMin (const GenericSet&); template <typename FacetConsumer> bool replaceMax (const GenericSet&, FacetConsumer); template <typename FacetConsumer> bool replaceMin (const GenericSet&, FacetConsumer);
Slightly optimized versions of insertMax and insertMin. They assume that the FacetList object already has all columns corresponding to the vertices of a new facet, and therefore does not need to be expanded.
int eraseMax (const GenericSet&); int eraseMin (const GenericSet&); template <typename FacetConsumer> int eraseMax (const GenericSet&, FacetConsumer); template <typename FacetConsumer> int eraseMin (const GenericSet&, FacetConsumer);
The same as insertMax and insertMin, but without adding any new facet. Return the number of facets actually removed.

Element access

FacetList implements the Reversible Container interface. During the iteration the facets appear in the chronological order, that is, as they were added to the list. Unlike std::list, the size() method runs in constant time.

The elements of the list (facets) belong to the GenericSet and implement the Reversible Container interface too.

const FacetList::LexOrdered& lex_ordered (const FacetList&);
Another view on the list, visiting the facets in lexicographical order. The result type is a masquerade reference; it is a set of sets of integer.
const FacetList::col_type& col (int v) const;
Return a list of facets incident to the given vertex. It can be thought of as a column of the vertex-facet incidence matrix, hence the name. The list is a Forward Container; for technical reasons, the facets are visited in the reversed chronological order.
The iterator over the column has index() method returning the id of the facet being visited.
The vertex number should lie in the valid range.
const Cols<FacetList>& cols (const FacetList&);
Return a masquerade reference to the sequence of columns in the increasing vertex order.
iterator find (const GenericSet&);
Find the facet equal to the given set and return an iterator pointing to it, or end() if not found.
The operation costs are O( + ).
FacetList::iteratorMax findMax (const GenericSet&);
Create an end-sensitive iterator visiting all facets that include the given vertex set.
The iterator has index() method returning the id of the facet being visited.
template <typename Set> FacetList::iteratorMin<Set> findMin (const GenericSet<Set>&);
Create an end-sensitive iterator visiting all facets included in the given vertex set.
Note that the result type, unlike in findMax, depends on the operand type.
The iterator has index() method returning the id of the facet being visited.