PolytopeFace

Return the dimension of the ambient lattice.

This is the ambient dimension of the ambient polytope, not the dimension of the ambient polytope itself.

Also available as ambient_dim.

Returns:

• int –

  The dimension of the ambient lattice.

Source on GitHub

Return the ambient polytope.

This is the method form of the ambient_poly property.

Returns:

• Polytope –

  The polytope that this is a face of.

Source on GitHub

Return the face as a Polytope object.

The new polytope is built from the lattice points of the face (in the coordinates of the ambient lattice), keeps the labels that the points have in the ambient polytope, and uses the same backend as the ambient polytope. The result is cached.

Also available as as_poly.

Returns:

• Polytope –

  The polytope corresponding to the face.

Examples:

We construct a face object and then convert it into a Polytope object.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(3)[0]  # pick one of the 3-faces
>>> f_poly = f.as_polytope()
>>> print(f_poly)
A 3-dimensional lattice polytope in ZZ^4

Source on GitHub

Return the boundary lattice points of the face.

See labels_bdry for the definition.

Also available as boundary_pts.

Parameters:

• as_indices (bool, default: False ) –

  Whether to return the indices of the points in the full list of points of the ambient polytope instead of their coordinates.

Returns:

• ndarray | list[int] –

  The boundary lattice points of the face, one per row, or a list of their indices if as_indices is true.

Examples:

We construct a face object and find its boundary lattice points.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(3)[0]  # pick one of the 3-faces
>>> f.boundary_points()
array([[-1, -1, -1, -1],
       [ 0,  0,  0,  1],
       [ 0,  0,  1,  0],
       [ 0,  1,  0,  0]])

Source on GitHub

Clear the cached results of any previous computation.

This clears the cached point labels, the face as a Polytope, the dual face, and the subfaces. The ambient polytope, vertices, saturated inequalities, and dimension are kept.

Examples:

We construct a face object and find its lattice points, then we clear the cache and compute the points again.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(3)[0]  # pick one of the 3-faces
>>> pts = f.points()  # find the lattice points
>>> f.clear_cache()  # clears the results of any previous computation
>>> pts = f.points()  # find the lattice points again

Source on GitHub

Return the dimension of the face.

Also available as dim.

Returns:

• int –

  The dimension of the face.

Source on GitHub

Return the dual face of the dual polytope.

For a \(k\)-dimensional face of a \(d\)-dimensional reflexive polytope, the dual face is the \((d-k-1)\)-dimensional face of the dual polytope whose vertices are the normals of the inequalities saturated by this face. The result is cached, and the dual face's own dual face is set to this face.

Also available as dual.

Returns:

• PolytopeFace –

  The dual face.

Raises:

• NotImplementedError –

  If the ambient polytope is not reflexive.

Examples:

We construct a face object from a polytope, then find the dual face in the dual polytope.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(2)[0]  # pick one of the 2-faces
>>> f_dual = f.dual_face()
>>> print(f_dual)
A 1-dimensional face of a 4-dimensional polytope in ZZ^4

Source on GitHub

Return the faces of the face.

The faces are obtained from Polytope.faces of the ambient polytope, so they are faces of the ambient polytope that are contained in this face (including the face itself). The result is cached.

Parameters:

• d (int | None, default: None ) –

  The dimension of the desired faces. If not specified, the faces of all dimensions are returned.

Returns:

• tuple –

  A tuple of PolytopeFace objects of dimension d if d is specified. Otherwise, a tuple of such tuples, where the \(i\)-th entry contains the \(i\)-dimensional faces, for \(i\) from 0 to the dimension of the face.

Raises:

• ValueError –

  If d is not between 0 and the dimension of the face.

Examples:

We construct a face from a polytope and find its 2-faces.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(3)[0]  # pick one of the 3-faces
>>> print(f.faces(2)[0])  # print one of its 2-faces
A 2-dimensional face of a 4-dimensional polytope in ZZ^4
>>> [len(ff) for ff in f.faces()]  # number of faces of each dimension
[4, 6, 4, 1]

Source on GitHub

Return the relative-interior lattice points of the face.

See labels_int for the definition.

Also available as interior_pts.

Parameters:

• as_indices (bool, default: False ) –

  Whether to return the indices of the points in the full list of points of the ambient polytope instead of their coordinates.

Returns:

• ndarray | list[int] –

  The interior lattice points of the face, one per row, or a list of their indices if as_indices is true.

Examples:

We construct a face object and find its interior lattice points.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
>>> f = p.faces(3)[3]  # pick one of the 3-faces
>>> f.interior_points()
array([[ 0,  0, -1, -2],
       [ 0,  0,  0, -1]])

Source on GitHub

Return the lattice points of the face.

The points are ordered as in the ambient polytope (see Polytope.points).

Also available as pts.

Parameters:

• which (list | None, default: None ) –

  Which points to return, specified by a list of labels (not indices). The labels must be labels of points of the face. If not specified, all points of the face are returned.

• optimal (bool, default: False ) –

  Whether to return the points in optimal coordinates. If the face is not full-dimensional in the ambient lattice, the points are translated so that the first returned point is at the origin and are then LLL-reduced to coordinates in a lattice of the same dimension as the face. Otherwise, the optimal coordinates of the ambient polytope are used.

• as_indices (bool, default: False ) –

  Whether to return the indices of the points in the full list of points of the ambient polytope instead of their coordinates. Takes precedence over optimal.

Returns:

• ndarray | list[int] –

  The lattice points of the face, one per row, or a list of their indices if as_indices is true.

Raises:

• ValueError –

  If which contains labels that are not labels of points of the face.

Examples:

We construct a face object and find its lattice points.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(3)[0]  # pick one of the 3-faces
>>> f.points()
array([[-1, -1, -1, -1],
       [ 0,  0,  0,  1],
       [ 0,  0,  1,  0],
       [ 0,  1,  0,  0]])
>>> f.points(optimal=True)
array([[0, 0, 0],
       [0, 0, 1],
       [0, 1, 0],
       [1, 0, 0]])

Source on GitHub

Return a single regular triangulation of the face.

This is a simple wrapper around the Triangulation constructor that triangulates all lattice points of the face (including points interior to facets of the ambient polytope) and never makes it star. See also Polytope.triangulate.

Parameters:

• heights (list | None, default: None ) –

  The heights specifying the regular triangulation, one per lattice point of the face, in the order of labels. If not specified, the Delaunay triangulation is returned when using CGAL, a triangulation obtained from random heights near the Delaunay heights when using QHull, or the placing triangulation when using TOPCOM. Heights can only be specified when using CGAL or QHull as the backend.

• simplices (ArrayLike | None, default: None ) –

  The simplices specifying the triangulation, each given as a list of point labels. This is useful when a triangulation was previously computed and needs to be used again.

• check_input_simplices (bool, default: True ) –

  Whether to check if the input simplices define a valid triangulation.

• backend (str, default: 'cgal' ) –

  The backend used to compute the triangulation. The options are "cgal", "qhull", and "topcom". CGAL is the default as it is very fast and robust.

• verbosity (int, default: 0 ) –

  The verbosity level.

• seed (int | None, default: None ) –

  Seed for the height perturbation used by the QHull backend. Only that backend perturbs its heights, so this has no effect for CGAL or TOPCOM. If not specified, the perturbation is drawn afresh each time and the triangulation is not reproducible.

Returns:

• Triangulation –

  A triangulation of the lattice points of the face.

Examples:

We triangulate one of the 3-faces of a polytope.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(3)[0]  # pick one of the 3-faces
>>> t = f.triangulate()
>>> t.simplices()
array([[1, 2, 3, 4]], dtype=uint8)

Source on GitHub

Return the vertices of the face.

Parameters:

• as_indices (bool, default: False ) –

  Whether to return the indices of the vertices in the full list of points of the ambient polytope instead of their coordinates.

Returns:

• ndarray | list[int] –

  The vertices of the face, one per row, or a list of their indices if as_indices is true.

Examples:

We construct a face from a polytope and find its vertices.

>>> p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
>>> f = p.faces(2)[0]  # pick one of the 2-faces
>>> f.vertices()
array([[-1, -1, -1, -1],
       [ 0,  0,  0,  1],
       [ 0,  0,  1,  0]])

Source on GitHub