This website uses Javascript to render markdown documents in your browser, apply syntax highlighting to code fragments and render $\LaTeX$ formulas. Below is the markdown source code of this page. You can either read that or enable Javascript to have it rendered to HTML.

# NAME

CInet::Cube - The ground set of a CInet::Relation

# SYNOPSIS

    my $cube = Cube(5);  # ground set 1..5

    # Print the permuted ordering of 2-faces.
    my $p = [4,1,3,5,2];
    for my $ijK ($cube->squares) {
        my $pijK = $cube->permute($p => $ijK);
        say $cube->pack($ijK), ' -> ', $cube->pack($pijK);
    }

# DESCRIPTION

A `CInet::Cube` object represents a finite ground set and provides access
to related combinatorial data in the form of the face lattice of the cube.
For example, all subsets of the ground set are available as `->vertices`,
or all CI statements on a random vector indexed by the ground set are `-> squares`.
This object bundles this data and implements transformations on them and
provides a common geometric language to talk about them.

In addition, the cube implements the _proper ordering_ of each set of
fixed-dimensional faces. These orderings are used in [CInet::Relation](/doc/CInet%3A%3ARelation)
and topical `CInet::*` modules whenever combinatorial objects must be
mapped to a contiguous sequence of integers `1 .. k` usually to allocate
variables in a domain-specific solver that computes a certain property
of the CI structure.

The proper, agreed-upon ordering allows to write problem descriptions
which are mutually consistent. It also allows to serialize a [CInet::Relation](/doc/CInet%3A%3ARelation)
to a unique string that can be read in by other programs implementing the
same canonical ordering.

## Methods

### new

    my $cube = CInet::Cube->new($n);
    my $cube = CInet::Cube->new($set);

Create a new cube object on the given ground set. If the argument is an
arrayref `$set`, then that is the ground set. The caller is responsible
for ensuring that it is properly sorted and deduplicated. Otherwise the
ground set is taken to be `1 .. $n`.

### dim

    my $dim = $cube->dim;

Returns the dimension, that is the size of the ground set, of this cube.

### set

    my $set = $cube->set;

Returns the ground set of this cube, which are axis labels.

### faces, vertices, edges, squares

    my @all_faces  = $cube->faces;
    my @some_faces = $cube->faces(0, 2, $cube->dim - 1);

Returns faces of the cube. If no arguments are given, all faces are returned
in order of ascending dimension and each fixed-dimensional slice in its
proper order.

When specific dimensions are asked for in the arguments to this method, only
these faces are returned.

Each cube object computes the array of d-dimensional faces only on demand.
Once computed, the array is cached. Other methods besides [faces](#faces)
which can cause the face array to be reified are [pack](#pack) and
[unpack](#unpack).

There are predefined accessors for faces which are often used:

    my @vertices = $cube->vertices;  # ->faces(0)
    my @edges    = $cube->edges;     # ->faces(1)
    my @squares  = $cube->squares;   # ->faces(2)

These methods return, respectively, the zero-, one- and two-dimensional
faces.

### squares

    # Get all squares in cube
    my @squares = $cube->squares;

    # Convert global to local CI statements
    my @elems = $cube->squares([[1,2],[3,4],[5,6,7]]);
    my @shorter = $cube->squares([[1,2],[3,4],[5,6,7]], graphoid => 1);

This method, if called with no arguments, returns all squares in the
invocant `$cube`.

An alternate use is to get all the local (or elementary) CI statements
corresponding to a global (or non-elementary) CI statement. By default,
semigraphoid semantics apply. That is, `(A,B|C)` is translated into
the elementary statements of the form `(ab|D)` where `a ∈ A`,
`b ∈ B` and `C ⊆ D ⊆ ABC \ ab`.

Setting the `graphoid` option to a true value instead uses the more
compact graphoid semantics where `(A,B|C)` is translated into
`(ab|C)` with `a ∈ A` and `b ∈ B`.

### pack

    my $nr = $cube->pack($face);

Maps a (d-dimensional) face to its 1-based position in the proper ordering
of d-dimensional faces of the cube. If the face was not found, an exception
is thrown.

### unpack

    my $face = $cube->unpack($d => $nr);

The opposite of the [pack](#pack) method, takes a dimension and 1-based
position number and returns the corresponding face object, or dies.

### permute

    my $pface = $cube->permute($p => $face);

The symmetric group on `$cube->set` acts on the axes of the cube
and gives rise to _permutation symmetries_ of the face lattice. Given
a permutation and a face, this method returns the corresponding face
on the permuted cube.

The permutation is given in "one-line notation", that is the i-th entry
gives the image of the i-th element of the ground set.

### dual

    my $dface = $cube->dual($face);

The cube has a distinguished symmetry by which all mirror symmetries are
applied simultaneously. This is referred to as _duality_.

This is the same as calling [swap](#swap) with `$Z = $cube->set`.

### swap

    my $Zface = $cube->swap($Z => $face);

For each subset `$Z` of the axes of the cube, there is a mirror symmetry
which applies simultaneously all the reflections orthogonal to each axis
in `$Z`. This is called _swapping_ and it generalizes the operation of
[dual](#dual).

### description

    my $str = $cube->description;

Returns a human-readable description of the object.

## Exports

### Cube :Export(:DEFAULT)

    my $cube = Cube($n);
    my $cube = Cube($set);
    my $cube = Cube($object);

This is not only a shorthand for the `CInet::Cube->new` constructor,
but it also keeps a cache of cube objects indexed by ground sets and it
tries harder to extract a cube from its input arguments:

- If the argument is a [CInet::Cube](/doc/CInet%3A%3ACube), return that.
- If the argument has a `cube` method, return that value.
- Otherwise pass all arguments to the [new](#new) constructor.

Prefer this function for getting cubes that you often use. Many gears
of CInet already use this function for convenience.

This sub is exported by default.

# AUTHOR

Tobias Boege <tobs@taboege.de>

# COPYRIGHT AND LICENSE

This software is copyright (C) 2020 by Tobias Boege.

This is free software; you can redistribute it and/or
modify it under the terms of the Artistic License 2.0.