AUTHORS:
This module implements the basic structure of finite cubical complexes. For full mathematical details, see Kaczynski, Mischaikow, and Mrozek [KMM], for example.
Cubical complexes are topological spaces built from gluing together cubes of various dimensions; the collection of cubes must be closed under taking faces, just as with a simplicial complex. In this context, a “cube” means a product of intervals of length 1 or length 0 (degenerate intervals), with integer endpoints, and its faces are obtained by using the nondegenerate intervals: if \(C\) is a cube – a product of degenerate and nondegenerate intervals – and if \([i,i+1]\) is the \(k\)th nondegenerate factor, then \(C\) has two faces indexed by \(k\): the cubes obtained by replacing \([i, i+1]\) with \([i, i]\) or \([i+1, i+1]\).
So to construct a space homeomorphic to a circle as a cubical complex, we could take for example the four line segments in the plane from \((0,2)\) to \((0,3)\) to \((1,3)\) to \((1,2)\) to \((0,2)\). In Sage, this is done with the following command:
sage: S1 = CubicalComplex([([0,0], [2,3]), ([0,1], [3,3]), ([0,1], [2,2]), ([1,1], [2,3])]); S1
Cubical complex with 4 vertices and 8 cubes
The argument to CubicalComplex is a list of the maximal “cubes” in the complex. Each “cube” can be an instance of the class Cube or a list (or tuple) of “intervals”, and an “interval” is a pair of integers, of one of the two forms \([i, i]\) or \([i, i+1]\). So the cubical complex S1 above has four maximal cubes:
sage: S1.maximal_cells()
{[0,0] x [2,3], [1,1] x [2,3], [0,1] x [3,3], [0,1] x [2,2]}
The first of these, for instance, is the product of the degenerate interval \([0,0]\) with the unit interval \([2,3]\): this is the line segment in the plane from \((0,2)\) to \((0,3)\). We could form a topologically equivalent space by inserting some degenerate simplices:
sage: S1.homology()
{0: 0, 1: Z}
sage: X = CubicalComplex([([0,0], [2,3], [2]), ([0,1], [3,3], [2]), ([0,1], [2,2], [2]), ([1,1], [2,3], [2])])
sage: X.homology()
{0: 0, 1: Z}
Topologically, the cubical complex X consists of four edges of a square in \(\RR^3\): the same unit square as S1, but embedded in \(\RR^3\) with \(z\)coordinate equal to 2. Thus X is homeomorphic to S1 (in fact, they’re “cubically equivalent”), and this is reflected in the fact that they have isomorphic homology groups.
REFERENCES:
[KMM]  Tomasz Kaczynski, Konstantin Mischaikow, and Marian Mrozek, “Computational Homology”, SpringerVerlag (2004). 
Note
This class derives from GenericCellComplex, and so inherits its methods. Some of those methods are not listed here; see the Generic Cell Complex page instead.
Bases: sage.structure.sage_object.SageObject
Define a cube for use in constructing a cubical complex.
“Elementary cubes” are products of intervals with integer endpoints, each of which is either a unit interval or a degenerate (length 0) interval; for example,
is a 3dimensional cube (since one of the intervals is degenerate) embedded in \(\RR^4\).
Parameters:  data – list or tuple of terms of the form (i,i+1) or (i,i) or (i,) – the last two are degenerate intervals. 

Returns:  an elementary cube 
Each cube is stored in a standard form: a tuple of tuples, with a nondegenerate interval [j,j] represented by (j,j), not (j,). (This is so that for any interval I, I[1] will produce a value, not an IndexError.)
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [5,], [6,7], [1, 0]]); C
[1,2] x [5,5] x [6,7] x [1,0]
sage: C.dimension() # number of nondegenerate intervals
3
sage: C.nondegenerate_intervals() # indices of these intervals
[0, 2, 3]
sage: C.face(1, upper=False)
[1,2] x [5,5] x [6,6] x [1,0]
sage: C.face(1, upper=True)
[1,2] x [5,5] x [7,7] x [1,0]
sage: Cube(()).dimension() # empty cube has dimension 1
1
The dimension of this cube: the number of its nondegenerate intervals.
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [5,], [6,7], [1, 0]])
sage: C.dimension()
3
sage: C = Cube([[1,], [5,], [6,], [1,]])
sage: C.dimension()
0
sage: Cube([]).dimension() # empty cube has dimension 1
1
The nth primary face of this cube.
Parameters: 


Returns:  the cube obtained by replacing the nth nondegenrate interval with either its upper or lower endpoint. 
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [5,], [6,7], [1, 0]]); C
[1,2] x [5,5] x [6,7] x [1,0]
sage: C.face(0)
[2,2] x [5,5] x [6,7] x [1,0]
sage: C.face(0, upper=False)
[1,1] x [5,5] x [6,7] x [1,0]
sage: C.face(1)
[1,2] x [5,5] x [7,7] x [1,0]
sage: C.face(2, upper=False)
[1,2] x [5,5] x [6,7] x [1,1]
sage: C.face(3)
Traceback (most recent call last):
...
ValueError: Can only compute the nth face if 0 <= n < dim.
The list of faces (of codimension 1) of this cube.
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [3,4]])
sage: C.faces()
[[2,2] x [3,4], [1,2] x [4,4], [1,1] x [3,4], [1,2] x [3,3]]
The list of faces (of codimension 1) of this cube, as pairs (upper, lower).
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [3,4]])
sage: C.faces_as_pairs()
[([2,2] x [3,4], [1,1] x [3,4]), ([1,2] x [4,4], [1,2] x [3,3])]
Return True iff this cube is a face of other.
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C1 = Cube([[1,2], [5,], [6,7], [1, 0]])
sage: C2 = Cube([[1,2], [5,], [6,], [1, 0]])
sage: C1.is_face(C2)
False
sage: C1.is_face(C1)
True
sage: C2.is_face(C1)
True
The list of indices of nondegenerate intervals of this cube.
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [5,], [6,7], [1, 0]])
sage: C.nondegenerate_intervals()
[0, 2, 3]
sage: C = Cube([[1,], [5,], [6,], [1,]])
sage: C.nondegenerate_intervals()
[]
Cube obtained by concatenating the underlying tuples of the two arguments.
Parameters:  other – another cube 

Returns:  the product of self and other, as a Cube 
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [3,]])
sage: D = Cube([[4], [0,1]])
sage: C.product(D)
[1,2] x [3,3] x [4,4] x [0,1]
You can also use __add__ or + or __mul__ or *:
sage: D * C
[4,4] x [0,1] x [1,2] x [3,3]
sage: D + C * C
[4,4] x [0,1] x [1,2] x [3,3] x [1,2] x [3,3]
The tuple attached to this cube.
EXAMPLES:
sage: from sage.homology.cubical_complex import Cube
sage: C = Cube([[1,2], [5,], [6,7], [1, 0]])
sage: C.tuple()
((1, 2), (5, 5), (6, 7), (1, 0))
Bases: sage.homology.cell_complex.GenericCellComplex
Define a cubical complex.
Parameters: 


Returns:  a cubical complex 
maximal_faces should be a list or tuple or set (or anything which may be converted to a set) of “cubes”: instances of the class Cube, or lists or tuples suitable for conversion to cubes. These cubes are the maximal cubes in the complex.
In addition, maximal_faces may be a cubical complex, in which case that complex is returned. Also, maximal_faces may instead be any object which has a _cubical_ method (e.g., a simplicial complex); then that method is used to convert the object to a cubical complex.
If maximality_check is True, check that each maximal face is, in fact, maximal. In this case, when producing the internal representation of the cubical complex, omit those that are not. It is highly recommended that this be True; various methods for this class may fail if faces which are claimed to be maximal are in fact not.
EXAMPLES:
The empty complex, consisting of one cube, the empty cube:
sage: CubicalComplex()
Cubical complex with 0 vertices and 1 cube
A “circle” (four edges connecting the vertices (0,2), (0,3), (1,2), and (1,3)):
sage: S1 = CubicalComplex([([0,0], [2,3]), ([0,1], [3,3]), ([0,1], [2,2]), ([1,1], [2,3])])
sage: S1
Cubical complex with 4 vertices and 8 cubes
sage: S1.homology()
{0: 0, 1: Z}
A set of five points and its product with S1:
sage: pts = CubicalComplex([([0],), ([3],), ([6],), ([12],), ([5],)])
sage: pts
Cubical complex with 5 vertices and 5 cubes
sage: pts.homology()
{0: Z x Z x Z x Z}
sage: X = S1.product(pts); X
Cubical complex with 20 vertices and 40 cubes
sage: X.homology()
{0: Z x Z x Z x Z, 1: Z^5}
Converting a simplicial complex to a cubical complex:
sage: S2 = simplicial_complexes.Sphere(2)
sage: C2 = CubicalComplex(S2)
sage: all([C2.homology(n) == S2.homology(n) for n in range(3)])
True
You can get the set of maximal cells or a dictionary of all cells:
sage: X.maximal_cells()
{[0,0] x [2,3] x [12,12], [0,1] x [3,3] x [5,5], [0,1] x [2,2] x [3,3], [0,1] x [2,2] x [0,0], [0,1] x [3,3] x [6,6], [1,1] x [2,3] x [0,0], [0,1] x [2,2] x [12,12], [0,0] x [2,3] x [6,6], [1,1] x [2,3] x [12,12], [1,1] x [2,3] x [5,5], [0,1] x [2,2] x [5,5], [0,1] x [3,3] x [3,3], [1,1] x [2,3] x [3,3], [0,0] x [2,3] x [5,5], [0,1] x [3,3] x [0,0], [1,1] x [2,3] x [6,6], [0,1] x [2,2] x [6,6], [0,0] x [2,3] x [0,0], [0,0] x [2,3] x [3,3], [0,1] x [3,3] x [12,12]}
sage: S1.cells()
{0: set([[1,1] x [2,2], [0,0] x [2,2], [1,1] x [3,3], [0,0] x [3,3]]), 1: set([[0,1] x [3,3], [1,1] x [2,3], [0,0] x [2,3], [0,1] x [2,2]]), 1: set([])}
Chain complexes, homology, and cohomology:
sage: T = S1.product(S1); T
Cubical complex with 16 vertices and 64 cubes
sage: T.chain_complex()
Chain complex with at most 3 nonzero terms over Integer Ring
sage: T.homology(base_ring=QQ)
{0: Vector space of dimension 0 over Rational Field,
1: Vector space of dimension 2 over Rational Field,
2: Vector space of dimension 1 over Rational Field}
sage: RP2 = cubical_complexes.RealProjectivePlane()
sage: RP2.cohomology(dim=[1, 2], base_ring=GF(2))
{1: Vector space of dimension 1 over Finite Field of size 2,
2: Vector space of dimension 1 over Finite Field of size 2}
Joins are not implemented:
sage: S1.join(S1)
Traceback (most recent call last):
...
NotImplementedError: Joins are not implemented for cubical complexes.
Therefore, neither are cones or suspensions.
The cells of this cubical complex, in the form of a dictionary: the keys are integers, representing dimension, and the value associated to an integer d is the list of dcells.
If the optional argument subcomplex is present, then return only the faces which are not in the subcomplex.
Parameters:  subcomplex (a cubical complex; optional, default None) – a subcomplex of this cubical complex 

Returns:  cells of this complex not contained in subcomplex 
Return type:  dictionary 
EXAMPLES:
sage: S2 = cubical_complexes.Sphere(2)
sage: S2.cells()[2]
set([[1,1] x [0,1] x [0,1], [0,1] x [0,0] x [0,1], [0,1] x [1,1] x [0,1], [0,0] x [0,1] x [0,1], [0,1] x [0,1] x [1,1], [0,1] x [0,1] x [0,0]])
The chain complex associated to this cubical complex.
Parameters: 


Note
If subcomplex is nonempty, then the argument augmented has no effect: the chain complex relative to a nonempty subcomplex is zero in dimension \(1\).
EXAMPLES:
sage: S2 = cubical_complexes.Sphere(2)
sage: S2.chain_complex()
Chain complex with at most 3 nonzero terms over Integer Ring
sage: Prod = S2.product(S2); Prod
Cubical complex with 64 vertices and 676 cubes
sage: Prod.chain_complex()
Chain complex with at most 5 nonzero terms over Integer Ring
sage: Prod.chain_complex(base_ring=QQ)
Chain complex with at most 5 nonzero terms over Rational Field
sage: C1 = cubical_complexes.Cube(1)
sage: S0 = cubical_complexes.Sphere(0)
sage: C1.chain_complex(subcomplex=S0)
Chain complex with at most 1 nonzero terms over Integer Ring
sage: C1.homology(subcomplex=S0)
{0: 0, 1: Z}
The cone on this cubical complex.
NOT IMPLEMENTED
The cone is the complex formed by taking the join of the original complex with a onepoint complex (that is, a 0dimensional cube). Since joins are not implemented for cubical complexes, neither are cones.
EXAMPLES:
sage: C1 = cubical_complexes.Cube(1)
sage: C1.cone()
Traceback (most recent call last):
...
NotImplementedError: Cones are not implemented for cubical complexes.
Return the connected sum of self with other.
Parameters:  other – another cubical complex 

Returns:  the connected sum self # other 
Warning
This does not check that self and other are manifolds, only that their facets all have the same dimension. Since a (more or less) random facet is chosen from each complex and then glued together, this method may return random results if applied to nonmanifolds, depending on which facet is chosen.
EXAMPLES:
sage: T = cubical_complexes.Torus()
sage: S2 = cubical_complexes.Sphere(2)
sage: T.connected_sum(S2).cohomology() == T.cohomology()
True
sage: RP2 = cubical_complexes.RealProjectivePlane()
sage: T.connected_sum(RP2).homology(1)
Z x Z x C2
sage: RP2.connected_sum(RP2).connected_sum(RP2).homology(1)
Z x Z x C2
The disjoint union of this cubical complex with another one.
Parameters:  right – the other cubical complex (the righthand factor) 

Algorithm: first embed both complexes in ddimensional Euclidean space. Then embed in (1+d)dimensional space, calling the new axis \(x\), and putting the first complex at \(x=0\), the second at \(x=1\).
EXAMPLES:
sage: S1 = cubical_complexes.Sphere(1)
sage: S2 = cubical_complexes.Sphere(2)
sage: S1.disjoint_union(S2).homology()
{0: Z, 1: Z, 2: Z}
The 1skeleton of this cubical complex, as a graph.
EXAMPLES:
sage: cubical_complexes.Sphere(2).graph()
Graph on 8 vertices
True iff this cubical complex is pure: that is, all of its maximal faces have the same dimension.
Warning
This may give the wrong answer if the cubical complex was constructed with maximality_check set to False.
EXAMPLES:
sage: S4 = cubical_complexes.Sphere(4)
sage: S4.is_pure()
True
sage: C = CubicalComplex([([0,0], [3,3]), ([1,2], [4,5])])
sage: C.is_pure()
False
Return True if self is a subcomplex of other.
Parameters:  other – a cubical complex 

Each maximal cube of self must be a face of a maximal cube of other for this to be True.
EXAMPLES:
sage: S1 = cubical_complexes.Sphere(1)
sage: C0 = cubical_complexes.Cube(0)
sage: C1 = cubical_complexes.Cube(1)
sage: cyl = S1.product(C1)
sage: end = S1.product(C0)
sage: end.is_subcomplex(cyl)
True
sage: cyl.is_subcomplex(end)
False
The embedding of the cubical complex is important here:
sage: C2 = cubical_complexes.Cube(2)
sage: C1.is_subcomplex(C2)
False
sage: C1.product(C0).is_subcomplex(C2)
True
C1 is not a subcomplex of C2 because it’s not embedded in \(\RR^2\). On the other hand, C1 x C0 is a face of C2. Look at their maximal cells:
sage: C1.maximal_cells()
{[0,1]}
sage: C2.maximal_cells()
{[0,1] x [0,1]}
sage: C1.product(C0).maximal_cells()
{[0,1] x [0,0]}
The join of this cubical complex with another one.
NOT IMPLEMENTED.
Parameters:  other – another cubical complex 

EXAMPLES:
sage: C1 = cubical_complexes.Cube(1)
sage: C1.join(C1)
Traceback (most recent call last):
...
NotImplementedError: Joins are not implemented for cubical complexes.
The set of maximal cells (with respect to inclusion) of this cubical complex.
Returns:  Set of maximal cells 

This just returns the set of cubes used in defining the cubical complex, so if the complex was defined with no maximality checking, none is done here, either.
EXAMPLES:
sage: interval = cubical_complexes.Cube(1)
sage: interval
Cubical complex with 2 vertices and 3 cubes
sage: interval.maximal_cells()
{[0,1]}
sage: interval.product(interval).maximal_cells()
{[0,1] x [0,1]}
The set of cubes of dimension n of this cubical complex. If the optional argument subcomplex is present, then return the ndimensional cubes which are not in the subcomplex.
Parameters: 


Returns:  cells in dimension n 
Return type:  set 
EXAMPLES:
sage: C = cubical_complexes.Cube(3)
sage: C.n_cubes(3)
set([[0,1] x [0,1] x [0,1]])
sage: C.n_cubes(2)
set([[1,1] x [0,1] x [0,1], [0,1] x [0,0] x [0,1], [0,1] x [1,1] x [0,1], [0,0] x [0,1] x [0,1], [0,1] x [0,1] x [1,1], [0,1] x [0,1] x [0,0]])
The nskeleton of this cubical complex.
Parameters:  n (nonnegative integer) – dimension 

Returns:  cubical complex 
EXAMPLES:
sage: S2 = cubical_complexes.Sphere(2)
sage: C3 = cubical_complexes.Cube(3)
sage: S2 == C3.n_skeleton(2)
True
The product of this cubical complex with another one.
Parameters:  other – another cubical complex 

EXAMPLES:
sage: RP2 = cubical_complexes.RealProjectivePlane()
sage: S1 = cubical_complexes.Sphere(1)
sage: RP2.product(S1).homology()[1]
Z x C2
The suspension of this cubical complex.
NOT IMPLEMENTED
Parameters:  n (positive integer; optional, default 1) – suspend this many times 

The suspension is the complex formed by taking the join of the original complex with a twopoint complex (the 0sphere). Since joins are not implemented for cubical complexes, neither are suspensions.
EXAMPLES:
sage: C1 = cubical_complexes.Cube(1)
sage: C1.suspension()
Traceback (most recent call last):
...
NotImplementedError: Suspensions are not implemented for cubical complexes.
The wedge (onepoint union) of this cubical complex with another one.
Parameters:  right – the other cubical complex (the righthand factor) 

Algorithm: if self is embedded in \(d\) dimensions and other in \(n\) dimensions, embed them in \(d+n\) dimensions: self using the first \(d\) coordinates, other using the last \(n\), translating them so that they have the origin as a common vertex.
Note
This operation is not welldefined if self or other is not pathconnected.
EXAMPLES:
sage: S1 = cubical_complexes.Sphere(1)
sage: S2 = cubical_complexes.Sphere(2)
sage: S1.wedge(S2).homology()
{0: 0, 1: Z, 2: Z}
Some examples of cubical complexes.
Here are the available examples; you can also type “cubical_complexes.” and hit TAB to get a list:
Sphere
Torus
RealProjectivePlane
KleinBottle
SurfaceOfGenus
Cube
EXAMPLES:
sage: cubical_complexes.Torus() # indirect doctest
Cubical complex with 16 vertices and 64 cubes
sage: cubical_complexes.Cube(7)
Cubical complex with 128 vertices and 2187 cubes
sage: cubical_complexes.Sphere(7)
Cubical complex with 256 vertices and 6560 cubes
A cubical complex representation of an \(n\)dimensional cube.
Parameters:  n (nonnegative integer) – the dimension 

EXAMPLES:
sage: cubical_complexes.Cube(0)
Cubical complex with 1 vertex and 1 cube
sage: cubical_complexes.Cube(3)
Cubical complex with 8 vertices and 27 cubes
A cubical complex representation of the Klein bottle, formed by taking the connected sum of the real projective plane with itself.
EXAMPLES:
sage: cubical_complexes.KleinBottle()
Cubical complex with 42 vertices and 168 cubes
A cubical complex representation of the real projective plane. This is taken from the examples from CHomP, the Computational Homology Project: http://chomp.rutgers.edu/.
EXAMPLES:
sage: cubical_complexes.RealProjectivePlane()
Cubical complex with 21 vertices and 81 cubes
A cubical complex representation of the \(n\)dimensional sphere, formed by taking the boundary of an \((n+1)\)dimensional cube.
Parameters:  n (nonnegative integer) – the dimension of the sphere 

EXAMPLES:
sage: cubical_complexes.Sphere(7)
Cubical complex with 256 vertices and 6560 cubes
A surface of genus g as a cubical complex.
Parameters: 


In the orientable case, return a sphere if \(g\) is zero, and otherwise return a \(g\)fold connected sum of a torus with itself.
In the nonorientable case, raise an error if \(g\) is zero. If \(g\) is positive, return a \(g\)fold connected sum of a real projective plane with itself.
EXAMPLES:
sage: cubical_complexes.SurfaceOfGenus(2)
Cubical complex with 32 vertices and 134 cubes
sage: cubical_complexes.SurfaceOfGenus(1, orientable=False)
Cubical complex with 21 vertices and 81 cubes
A cubical complex representation of the torus, obtained by taking the product of the circle with itself.
EXAMPLES:
sage: cubical_complexes.Torus()
Cubical complex with 16 vertices and 64 cubes