A class to keep information about faces of a polyhedron - Combinatorial and Discrete Geometry

Skip to content
Back to top
View this page
Edit this page

# A class to keep information about faces of a polyhedron

This module gives you a tool to work with the faces of a polyhedron and their relative position. First, you need to find the faces. To get the faces in a particular dimension, use the `face()` method:

Sage

    sage: P = polytopes.cross_polytope(3)
    sage: P.faces(3)
    (A 3-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 6 vertices,)
    sage: [f.ambient_V_indices() for f in P.facets()]
    [(3, 4, 5),
     (2, 4, 5),
     (1, 3, 5),
     (1, 2, 5),
     (0, 3, 4),
     (0, 2, 4),
     (0, 1, 3),
     (0, 1, 2)]
    sage: [f.ambient_V_indices() for f in P.faces(1)]
    [(4, 5),
     (3, 5),
     (2, 5),
     (1, 5),
     (3, 4),
     (2, 4),
     (0, 4),
     (1, 3),
     (0, 3),
     (1, 2),
     (0, 2),
     (0, 1)]

Python

    >>> from sage.all import *
    >>> P = polytopes.cross_polytope(Integer(3))
    >>> P.faces(Integer(3))
    (A 3-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 6 vertices,)
    >>> [f.ambient_V_indices() for f in P.facets()]
    [(3, 4, 5),
     (2, 4, 5),
     (1, 3, 5),
     (1, 2, 5),
     (0, 3, 4),
     (0, 2, 4),
     (0, 1, 3),
     (0, 1, 2)]
    >>> [f.ambient_V_indices() for f in P.faces(Integer(1))]
    [(4, 5),
     (3, 5),
     (2, 5),
     (1, 5),
     (3, 4),
     (2, 4),
     (0, 4),
     (1, 3),
     (0, 3),
     (1, 2),
     (0, 2),
     (0, 1)]

or `face_lattice()` to get the whole face lattice as a poset:

Sage

    sage: P.face_lattice()                                                              # needs sage.combinat
    Finite lattice containing 28 elements

[Python]

    >>> from sage.all import *
    >>> P.face_lattice()                                                              # needs sage.combinat
    Finite lattice containing 28 elements

The faces are printed in shorthand notation where each integer is the index of a vertex/ray/line in the same order as the containing Polyhedron’s `Vrepresentation()`

Sage

    sage: face = P.faces(1)[8];  face
    A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices
    sage: face.ambient_V_indices()
    (0, 3)
    sage: P.Vrepresentation(0)
    A vertex at (-1, 0, 0)
    sage: P.Vrepresentation(3)
    A vertex at (0, 0, 1)
    sage: face.vertices()
    (A vertex at (-1, 0, 0), A vertex at (0, 0, 1))

Python

    >>> from sage.all import *
    >>> face = P.faces(Integer(1))[Integer(8)];  face
    A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices
    >>> face.ambient_V_indices()
    (0, 3)
    >>> P.Vrepresentation(Integer(0))
    A vertex at (-1, 0, 0)
    >>> P.Vrepresentation(Integer(3))
    A vertex at (0, 0, 1)
    >>> face.vertices()
    (A vertex at (-1, 0, 0), A vertex at (0, 0, 1))

The face itself is not represented by Sage’s `sage.geometry.polyhedron.constructor.Polyhedron()` class, but by an auxiliary class to keep the information. You can get the face as a polyhedron with the `PolyhedronFace.as_polyhedron()` method:

Sage

    sage: face.as_polyhedron()
    A 1-dimensional polyhedron in ZZ^3 defined as the convex hull of 2 vertices
    sage: _.equations()
    (An equation (0, 1, 0) x + 0 == 0,
     An equation (1, 0, -1) x + 1 == 0)

[Python]

    >>> from sage.all import *
    >>> face.as_polyhedron()
    A 1-dimensional polyhedron in ZZ^3 defined as the convex hull of 2 vertices
    >>> _.equations()
    (An equation (0, 1, 0) x + 0 == 0,
     An equation (1, 0, -1) x + 1 == 0)

class sage.geometry.polyhedron.face.PolyhedronFace(polyhedron, V_indices, H_indices)

  Bases: `ConvexSet_closed`

  A face of a polyhedron.

  This class is for use in `face_lattice()`.

  INPUT:

  No checking is performed whether the H/V-representation indices actually determine a face of the polyhedron. You should not manually create `PolyhedronFace` objects unless you know what you are doing.

  OUTPUT: a `PolyhedronFace`

  EXAMPLES:

  Sage

      sage: octahedron = polytopes.cross_polytope(3)
      sage: inequality = octahedron.Hrepresentation(2)
      sage: face_h = tuple([ inequality ])
      sage: face_v = tuple( inequality.incident() )
      sage: face_h_indices = [ h.index() for h in face_h ]
      sage: face_v_indices = [ v.index() for v in face_v ]
      sage: from sage.geometry.polyhedron.face import PolyhedronFace
      sage: face = PolyhedronFace(octahedron, face_v_indices, face_h_indices)
      sage: face
      A 2-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 3 vertices
      sage: face.dim()
      2
      sage: face.ambient_V_indices()
      (0, 1, 2)
      sage: face.ambient_Hrepresentation()
      (An inequality (1, 1, 1) x + 1 >= 0,)
      sage: face.ambient_Vrepresentation()
      (A vertex at (-1, 0, 0), A vertex at (0, -1, 0), A vertex at (0, 0, -1))

  Python

      >>> from sage.all import *
      >>> octahedron = polytopes.cross_polytope(Integer(3))
      >>> inequality = octahedron.Hrepresentation(Integer(2))
      >>> face_h = tuple([ inequality ])
      >>> face_v = tuple( inequality.incident() )
      >>> face_h_indices = [ h.index() for h in face_h ]
      >>> face_v_indices = [ v.index() for v in face_v ]
      >>> from sage.geometry.polyhedron.face import PolyhedronFace
      >>> face = PolyhedronFace(octahedron, face_v_indices, face_h_indices)
      >>> face
      A 2-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 3 vertices
      >>> face.dim()
      2
      >>> face.ambient_V_indices()
      (0, 1, 2)
      >>> face.ambient_Hrepresentation()
      (An inequality (1, 1, 1) x + 1 >= 0,)
      >>> face.ambient_Vrepresentation()
      (A vertex at (-1, 0, 0), A vertex at (0, -1, 0), A vertex at (0, 0, -1))

  affine_tangent_cone()

    Return the affine tangent cone of `self` as a polyhedron.

    It is equal to the sum of `self` and the cone of feasible directions at any point of the relative interior of `self`.

    OUTPUT: a polyhedron

    EXAMPLES:

    Sage

        sage: half_plane_in_space = Polyhedron(ieqs=[(0,1,0,0)], eqns=[(0,0,0,1)])
        sage: line = half_plane_in_space.faces(1)[0]; line
        A 1-dimensional face of a
         Polyhedron in QQ^3 defined as the convex hull of 1 vertex and 1 line
        sage: T_line = line.affine_tangent_cone()
        sage: T_line == half_plane_in_space
        True

        sage: c = polytopes.cube()
        sage: edge = min(c.faces(1))
        sage: edge.vertices()
        (A vertex at (1, -1, -1), A vertex at (1, 1, -1))
        sage: T_edge = edge.affine_tangent_cone()
        sage: T_edge.Vrepresentation()
        (A line in the direction (0, 1, 0),
         A ray in the direction (0, 0, 1),
         A vertex at (1, 0, -1),
         A ray in the direction (-1, 0, 0))

    Python

        >>> from sage.all import *
        >>> half_plane_in_space = Polyhedron(ieqs=[(Integer(0),Integer(1),Integer(0),Integer(0))], eqns=[(Integer(0),Integer(0),Integer(0),Integer(1))])
        >>> line = half_plane_in_space.faces(Integer(1))[Integer(0)]; line
        A 1-dimensional face of a
         Polyhedron in QQ^3 defined as the convex hull of 1 vertex and 1 line
        >>> T_line = line.affine_tangent_cone()
        >>> T_line == half_plane_in_space
        True

        >>> c = polytopes.cube()
        >>> edge = min(c.faces(Integer(1)))
        >>> edge.vertices()
        (A vertex at (1, -1, -1), A vertex at (1, 1, -1))
        >>> T_edge = edge.affine_tangent_cone()
        >>> T_edge.Vrepresentation()
        (A line in the direction (0, 1, 0),
         A ray in the direction (0, 0, 1),
         A vertex at (1, 0, -1),
         A ray in the direction (-1, 0, 0))

  ambient()

    alias of `polyhedron()`.

  ambient_H_indices()

    Return the indices of the H-representation objects of the ambient polyhedron that make up the H-representation of `self`.

    See also `ambient_Hrepresentation()`.

    OUTPUT: tuple of indices

    EXAMPLES:

    Sage

        sage: Q = polytopes.cross_polytope(3)
        sage: F = Q.faces(1)
        sage: [f.ambient_H_indices() for f in F]
        [(4, 5),
         (5, 6),
         (4, 7),
         (6, 7),
         (0, 5),
         (3, 4),
         (0, 3),
         (1, 6),
         (0, 1),
         (2, 7),
         (2, 3),
         (1, 2)]

    Python

        >>> from sage.all import *
        >>> Q = polytopes.cross_polytope(Integer(3))
        >>> F = Q.faces(Integer(1))
        >>> [f.ambient_H_indices() for f in F]
        [(4, 5),
         (5, 6),
         (4, 7),
         (6, 7),
         (0, 5),
         (3, 4),
         (0, 3),
         (1, 6),
         (0, 1),
         (2, 7),
         (2, 3),
         (1, 2)]

  ambient_Hrepresentation(index=None)

    Return the H-representation objects of the ambient polytope defining the face.

    INPUT:

    - `index` – integer or `None` (default)

    OUTPUT:

    If the optional argument is not present, a tuple of H-representation objects. Each entry is either an inequality or an equation.

    If the optional integer `index` is specified, the `index`-th element of the tuple is returned.

    EXAMPLES:

    Sage

        sage: square = polytopes.hypercube(2)
        sage: for face in square.face_lattice():                                    # needs sage.combinat
        ....:     print(face.ambient_Hrepresentation())
        (An inequality (-1, 0) x + 1 >= 0, An inequality (0, -1) x + 1 >= 0,
         An inequality (1, 0) x + 1 >= 0, An inequality (0, 1) x + 1 >= 0)
        (An inequality (-1, 0) x + 1 >= 0, An inequality (0, 1) x + 1 >= 0)
        (An inequality (-1, 0) x + 1 >= 0, An inequality (0, -1) x + 1 >= 0)
        (An inequality (-1, 0) x + 1 >= 0,)
        (An inequality (0, -1) x + 1 >= 0, An inequality (1, 0) x + 1 >= 0)
        (An inequality (0, -1) x + 1 >= 0,)
        (An inequality (1, 0) x + 1 >= 0, An inequality (0, 1) x + 1 >= 0)
        (An inequality (0, 1) x + 1 >= 0,)
        (An inequality (1, 0) x + 1 >= 0,)
        ()

    Python

        >>> from sage.all import *
        >>> square = polytopes.hypercube(Integer(2))
        >>> for face in square.face_lattice():                                    # needs sage.combinat
        ...     print(face.ambient_Hrepresentation())
        (An inequality (-1, 0) x + 1 >= 0, An inequality (0, -1) x + 1 >= 0,
         An inequality (1, 0) x + 1 >= 0, An inequality (0, 1) x + 1 >= 0)
        (An inequality (-1, 0) x + 1 >= 0, An inequality (0, 1) x + 1 >= 0)
        (An inequality (-1, 0) x + 1 >= 0, An inequality (0, -1) x + 1 >= 0)
        (An inequality (-1, 0) x + 1 >= 0,)
        (An inequality (0, -1) x + 1 >= 0, An inequality (1, 0) x + 1 >= 0)
        (An inequality (0, -1) x + 1 >= 0,)
        (An inequality (1, 0) x + 1 >= 0, An inequality (0, 1) x + 1 >= 0)
        (An inequality (0, 1) x + 1 >= 0,)
        (An inequality (1, 0) x + 1 >= 0,)
        ()

  ambient_V_indices()

    Return the indices of the V-representation objects of the ambient polyhedron that make up the V-representation of `self`.

    See also `ambient_Vrepresentation()`.

    OUTPUT: tuple of indices

    EXAMPLES:

    Sage

        sage: P = polytopes.cube()
        sage: F = P.faces(2)
        sage: [f.ambient_V_indices() for f in F]
        [(0, 3, 4, 5),
         (0, 1, 5, 6),
         (4, 5, 6, 7),
         (2, 3, 4, 7),
         (1, 2, 6, 7),
         (0, 1, 2, 3)]

    Python

        >>> from sage.all import *
        >>> P = polytopes.cube()
        >>> F = P.faces(Integer(2))
        >>> [f.ambient_V_indices() for f in F]
        [(0, 3, 4, 5),
         (0, 1, 5, 6),
         (4, 5, 6, 7),
         (2, 3, 4, 7),
         (1, 2, 6, 7),
         (0, 1, 2, 3)]

  ambient_Vrepresentation(index=None)

    Return the V-representation objects of the ambient polytope defining the face.

    INPUT:

    - `index` – integer or `None` (default)

    OUTPUT:

    If the optional argument is not present, a tuple of V-representation objects. Each entry is either a vertex, a ray, or a line.

    If the optional integer `index` is specified, the `index`-th element of the tuple is returned.

    EXAMPLES:

    Sage

        sage: square = polytopes.hypercube(2)
        sage: for fl in square.face_lattice():                                      # needs sage.combinat
        ....:     print(fl.ambient_Vrepresentation())
        ()
        (A vertex at (1, -1),)
        (A vertex at (1, 1),)
        (A vertex at (1, -1), A vertex at (1, 1))
        (A vertex at (-1, 1),)
        (A vertex at (1, 1), A vertex at (-1, 1))
        (A vertex at (-1, -1),)
        (A vertex at (1, -1), A vertex at (-1, -1))
        (A vertex at (-1, 1), A vertex at (-1, -1))
        (A vertex at (1, -1), A vertex at (1, 1),
         A vertex at (-1, 1), A vertex at (-1, -1))

    Python

        >>> from sage.all import *
        >>> square = polytopes.hypercube(Integer(2))
        >>> for fl in square.face_lattice():                                      # needs sage.combinat
        ...     print(fl.ambient_Vrepresentation())
        ()
        (A vertex at (1, -1),)
        (A vertex at (1, 1),)
        (A vertex at (1, -1), A vertex at (1, 1))
        (A vertex at (-1, 1),)
        (A vertex at (1, 1), A vertex at (-1, 1))
        (A vertex at (-1, -1),)
        (A vertex at (1, -1), A vertex at (-1, -1))
        (A vertex at (-1, 1), A vertex at (-1, -1))
        (A vertex at (1, -1), A vertex at (1, 1),
         A vertex at (-1, 1), A vertex at (-1, -1))

  ambient_dim()

    Return the dimension of the containing polyhedron.

    EXAMPLES:

    Sage

        sage: P = Polyhedron(vertices = [[1,0,0,0],[0,1,0,0]])
        sage: face = P.faces(1)[0]
        sage: face.ambient_dim()
        4

    Python

        >>> from sage.all import *
        >>> P = Polyhedron(vertices = [[Integer(1),Integer(0),Integer(0),Integer(0)],[Integer(0),Integer(1),Integer(0),Integer(0)]])
        >>> face = P.faces(Integer(1))[Integer(0)]
        >>> face.ambient_dim()
        4

  ambient_vector_space(base_field=None)

    Return the ambient vector space.

    It is the ambient free module of the containing polyhedron tensored with a field.

    INPUT:

    - `base_field` – a field (default: the fraction field of the base ring)

    EXAMPLES:

    Sage

        sage: half_plane = Polyhedron(ieqs=[(0,1,0)])
        sage: line = half_plane.faces(1)[0]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        sage: line.ambient_vector_space()
        Vector space of dimension 2 over Rational Field
        sage: line.ambient_vector_space(AA)                                         # needs sage.rings.number_field
        Vector space of dimension 2 over Algebraic Real Field

    Python

        >>> from sage.all import *
        >>> half_plane = Polyhedron(ieqs=[(Integer(0),Integer(1),Integer(0))])
        >>> line = half_plane.faces(Integer(1))[Integer(0)]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        >>> line.ambient_vector_space()
        Vector space of dimension 2 over Rational Field
        >>> line.ambient_vector_space(AA)                                         # needs sage.rings.number_field
        Vector space of dimension 2 over Algebraic Real Field

  as_polyhedron(**kwds)

    Return the face as an independent polyhedron.

    OUTPUT: a polyhedron

    EXAMPLES:

    Sage

        sage: P = polytopes.cross_polytope(3);  P
        A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 6 vertices
        sage: face = P.faces(2)[3]; face
        A 2-dimensional face of a
         Polyhedron in ZZ^3 defined as the convex hull of 3 vertices
        sage: face.as_polyhedron()
        A 2-dimensional polyhedron in ZZ^3 defined as the convex hull of 3 vertices

        sage: P.intersection(face.as_polyhedron()) == face.as_polyhedron()
        True

    Python

        >>> from sage.all import *
        >>> P = polytopes.cross_polytope(Integer(3));  P
        A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 6 vertices
        >>> face = P.faces(Integer(2))[Integer(3)]; face
        A 2-dimensional face of a
         Polyhedron in ZZ^3 defined as the convex hull of 3 vertices
        >>> face.as_polyhedron()
        A 2-dimensional polyhedron in ZZ^3 defined as the convex hull of 3 vertices

        >>> P.intersection(face.as_polyhedron()) == face.as_polyhedron()
        True

  contains(point)

    Test whether the polyhedron contains the given `point`.

    INPUT:

    - `point` – a point or its coordinates

    EXAMPLES:

    Sage

        sage: half_plane = Polyhedron(ieqs=[(0,1,0)])
        sage: line = half_plane.faces(1)[0]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        sage: line.contains([0, 1])
        True

    Python

        >>> from sage.all import *
        >>> half_plane = Polyhedron(ieqs=[(Integer(0),Integer(1),Integer(0))])
        >>> line = half_plane.faces(Integer(1))[Integer(0)]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        >>> line.contains([Integer(0), Integer(1)])
        True

    As a shorthand, one may use the usual `in` operator:

    Sage

        sage: [5, 7] in line
        False

    [Python]

        >>> from sage.all import *
        >>> [Integer(5), Integer(7)] in line
        False

  dim()

    Return the dimension of the face.

    OUTPUT: integer

    EXAMPLES:

    Sage

        sage: fl = polytopes.dodecahedron().face_lattice()                          # needs sage.combinat sage.rings.number_field
        sage: sorted(x.dim() for x in fl)                                           # needs sage.combinat sage.rings.number_field
        [-1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
          1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
          1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 3]

    Python

        >>> from sage.all import *
        >>> fl = polytopes.dodecahedron().face_lattice()                          # needs sage.combinat sage.rings.number_field
        >>> sorted(x.dim() for x in fl)                                           # needs sage.combinat sage.rings.number_field
        [-1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
          1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
          1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 3]

  is_compact()

    Return whether `self` is compact.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: half_plane = Polyhedron(ieqs=[(0,1,0)])
        sage: line = half_plane.faces(1)[0]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        sage: line.is_compact()
        False

    Python

        >>> from sage.all import *
        >>> half_plane = Polyhedron(ieqs=[(Integer(0),Integer(1),Integer(0))])
        >>> line = half_plane.faces(Integer(1))[Integer(0)]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        >>> line.is_compact()
        False

  is_relatively_open()

    Return whether `self` is relatively open.

    OUTPUT: boolean

    EXAMPLES:

    Sage

        sage: half_plane = Polyhedron(ieqs=[(0,1,0)])
        sage: line = half_plane.faces(1)[0]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        sage: line.is_relatively_open()
        True

    Python

        >>> from sage.all import *
        >>> half_plane = Polyhedron(ieqs=[(Integer(0),Integer(1),Integer(0))])
        >>> line = half_plane.faces(Integer(1))[Integer(0)]; line
        A 1-dimensional face of a
         Polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line
        >>> line.is_relatively_open()
        True

  line_generator()

    Return a generator for the lines of the face.

    EXAMPLES:

    Sage

        sage: pr = Polyhedron(rays = [[1,0],[-1,0],[0,1]], vertices = [[-1,-1]])
        sage: face = pr.faces(1)[0]
        sage: next(face.line_generator())
        A line in the direction (1, 0)

    Python

        >>> from sage.all import *
        >>> pr = Polyhedron(rays = [[Integer(1),Integer(0)],[-Integer(1),Integer(0)],[Integer(0),Integer(1)]], vertices = [[-Integer(1),-Integer(1)]])
        >>> face = pr.faces(Integer(1))[Integer(0)]
        >>> next(face.line_generator())
        A line in the direction (1, 0)

  lines()

    Return all lines of the face.

    OUTPUT: a tuple of lines

    EXAMPLES:

    Sage

        sage: p = Polyhedron(rays = [[1,0],[-1,0],[0,1],[1,1]], vertices = [[-2,-2],[2,3]])
        sage: p.lines()
        (A line in the direction (1, 0),)

    Python

        >>> from sage.all import *
        >>> p = Polyhedron(rays = [[Integer(1),Integer(0)],[-Integer(1),Integer(0)],[Integer(0),Integer(1)],[Integer(1),Integer(1)]], vertices = [[-Integer(2),-Integer(2)],[Integer(2),Integer(3)]])
        >>> p.lines()
        (A line in the direction (1, 0),)

  n_ambient_Hrepresentation()

    Return the number of objects that make up the ambient H-representation of the polyhedron.

    See also `ambient_Hrepresentation()`.

    OUTPUT: integer

    EXAMPLES:

    Sage

        sage: p = polytopes.cross_polytope(4)
        sage: face = p.face_lattice()[5]; face                                      # needs sage.combinat
        A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices
        sage: face.ambient_Hrepresentation()                                        # needs sage.combinat
        (An inequality (1, -1, 1, -1) x + 1 >= 0,
         An inequality (1, 1, 1, 1) x + 1 >= 0,
         An inequality (1, 1, 1, -1) x + 1 >= 0,
         An inequality (1, -1, 1, 1) x + 1 >= 0)
        sage: face.n_ambient_Hrepresentation()                                      # needs sage.combinat
        4

    Python

        >>> from sage.all import *
        >>> p = polytopes.cross_polytope(Integer(4))
        >>> face = p.face_lattice()[Integer(5)]; face                                      # needs sage.combinat
        A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices
        >>> face.ambient_Hrepresentation()                                        # needs sage.combinat
        (An inequality (1, -1, 1, -1) x + 1 >= 0,
         An inequality (1, 1, 1, 1) x + 1 >= 0,
         An inequality (1, 1, 1, -1) x + 1 >= 0,
         An inequality (1, -1, 1, 1) x + 1 >= 0)
        >>> face.n_ambient_Hrepresentation()                                      # needs sage.combinat
        4

  n_ambient_Vrepresentation()

    Return the number of objects that make up the ambient V-representation of the polyhedron.

    See also `ambient_Vrepresentation()`.

    OUTPUT: integer

    EXAMPLES:

    Sage

        sage: p = polytopes.cross_polytope(4)
        sage: face = p.face_lattice()[5]; face                                      # needs sage.combinat
        A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices
        sage: face.ambient_Vrepresentation()                                        # needs sage.combinat
        (A vertex at (-1, 0, 0, 0), A vertex at (0, 0, -1, 0))
        sage: face.n_ambient_Vrepresentation()                                      # needs sage.combinat
        2

    Python

        >>> from sage.all import *
        >>> p = polytopes.cross_polytope(Integer(4))
        >>> face = p.face_lattice()[Integer(5)]; face                                      # needs sage.combinat
        A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices
        >>> face.ambient_Vrepresentation()                                        # needs sage.combinat
        (A vertex at (-1, 0, 0, 0), A vertex at (0, 0, -1, 0))
        >>> face.n_ambient_Vrepresentation()                                      # needs sage.combinat
        2

  n_lines()

    Return the number of lines of the face.

    OUTPUT: integer

    EXAMPLES:

    Sage

        sage: p = Polyhedron(rays = [[1,0],[-1,0],[0,1],[1,1]], vertices = [[-2,-2],[2,3]])
        sage: p.n_lines()
        1

    Python

        >>> from sage.all import *
        >>> p = Polyhedron(rays = [[Integer(1),Integer(0)],[-Integer(1),Integer(0)],[Integer(0),Integer(1)],[Integer(1),Integer(1)]], vertices = [[-Integer(2),-Integer(2)],[Integer(2),Integer(3)]])
        >>> p.n_lines()
        1

  n_rays()

    Return the number of rays of the face.

    OUTPUT: integer

    EXAMPLES:

    Sage

        sage: p = Polyhedron(ieqs = [[0,0,0,1],[0,0,1,0],[1,1,0,0]])
        sage: face = p.faces(2)[0]
        sage: face.n_rays()
        2

    Python

        >>> from sage.all import *
        >>> p = Polyhedron(ieqs = [[Integer(0),Integer(0),Integer(0),Integer(1)],[Integer(0),Integer(0),Integer(1),Integer(0)],[Integer(1),Integer(1),Integer(0),Integer(0)]])
        >>> face = p.faces(Integer(2))[Integer(0)]
        >>> face.n_rays()
        2

  n_vertices()

    Return the number of vertices of the face.

    OUTPUT: integer

    EXAMPLES:

    Sage

        sage: Q = polytopes.cross_polytope(3)
        sage: face = Q.faces(2)[0]
        sage: face.n_vertices()
        3

    Python

        >>> from sage.all import *
        >>> Q = polytopes.cross_polytope(Integer(3))
        >>> face = Q.faces(Integer(2))[Integer(0)]
        >>> face.n_vertices()
        3

  normal_cone(direction='outer')

    Return the polyhedral cone consisting of normal vectors to hyperplanes supporting `self`.

    INPUT:

    - `direction` – string (default: `'outer'`); the direction in which to consider the normals. The other allowed option is `'inner'`.

    OUTPUT: a polyhedron

    EXAMPLES:

    Sage

        sage: p = Polyhedron(vertices=[[1,2], [2,1], [-2,2], [-2,-2], [2,-2]])
        sage: for v in p.face_generator(0):
        ....:     vect = v.vertices()[0].vector()
        ....:     nc = v.normal_cone().rays_list()
        ....:     print("{} has outer normal cone spanned by {}".format(vect,nc))
        ....:
        (2, 1) has outer normal cone spanned by [[1, 0], [1, 1]]
        (1, 2) has outer normal cone spanned by [[0, 1], [1, 1]]
        (2, -2) has outer normal cone spanned by [[0, -1], [1, 0]]
        (-2, -2) has outer normal cone spanned by [[-1, 0], [0, -1]]
        (-2, 2) has outer normal cone spanned by [[-1, 0], [0, 1]]

        sage: for v in p.face_generator(0):
        ....:     vect = v.vertices()[0].vector()
        ....:     nc = v.normal_cone(direction='inner').rays_list()
        ....:     print("{} has inner normal cone spanned by {}".format(vect,nc))
        ....:
        (2, 1) has inner normal cone spanned by [[-1, -1], [-1, 0]]
        (1, 2) has inner normal cone spanned by [[-1, -1], [0, -1]]
        (2, -2) has inner normal cone spanned by [[-1, 0], [0, 1]]
        (-2, -2) has inner normal cone spanned by [[0, 1], [1, 0]]
        (-2, 2) has inner normal cone spanned by [[0, -1], [1, 0]]

    Python

        >>> from sage.all import *
        >>> p = Polyhedron(vertices=[[Integer(1),Integer(2)], [Integer(2),Integer(1)], [-Integer(2),Integer(2)], [-Integer(2),-Integer(2)], [Integer(2),-Integer(2)]])
        >>> for v in p.face_generator(Integer(0)):
        ...     vect = v.vertices()[Integer(0)].vector()
        ...     nc = v.normal_cone().rays_list()
        ...     print("{} has outer normal cone spanned by {}".format(vect,nc))
        ....:
        (2, 1) has outer normal cone spanned by [[1, 0], [1, 1]]
        (1, 2) has outer normal cone spanned by [[0, 1], [1, 1]]
        (2, -2) has outer normal cone spanned by [[0, -1], [1, 0]]
        (-2, -2) has outer normal cone spanned by [[-1, 0], [0, -1]]
        (-2, 2) has outer normal cone spanned by [[-1, 0], [0, 1]]

        >>> for v in p.face_generator(Integer(0)):
        ...     vect = v.vertices()[Integer(0)].vector()
        ...     nc = v.normal_cone(direction='inner').rays_list()
        ...     print("{} has inner normal cone spanned by {}".format(vect,nc))
        ....:
        (2, 1) has inner normal cone spanned by [[-1, -1], [-1, 0]]
        (1, 2) has inner normal cone spanned by [[-1, -1], [0, -1]]
        (2, -2) has inner normal cone spanned by [[-1, 0], [0, 1]]
        (-2, -2) has inner normal cone spanned by [[0, 1], [1, 0]]
        (-2, 2) has inner normal cone spanned by [[0, -1], [1, 0]]

    The function works for polytopes that are not full-dimensional:

    Sage

        sage: p = polytopes.permutahedron(3)
        sage: f1 = p.faces(0)[0]
        sage: f2 = p.faces(1)[0]
        sage: f3 = p.faces(2)[0]
        sage: f1.normal_cone()
        A 3-dimensional polyhedron in ZZ^3 defined as
         the convex hull of 1 vertex, 2 rays, 1 line
        sage: f2.normal_cone()
        A 2-dimensional polyhedron in ZZ^3 defined as
         the convex hull of 1 vertex, 1 ray, 1 line
        sage: f3.normal_cone()
        A 1-dimensional polyhedron in ZZ^3 defined as
         the convex hull of 1 vertex and 1 line

    [Python]

        >>> from sage.all import *
        >>> p = polytopes.permutahedron(Integer(3))
        >>> f1 = p.faces(Integer(0))[Integer(0)]
        >>> f2 = p.faces(Integer(1))[Integer(0)]
        >>> f3 = p.faces(Integer(2))[Integer(0)]
        >>> f1.normal_cone()
        A 3-dimensional polyhedron in ZZ^3 defined as
         the convex hull of 1 vertex, 2 rays, 1 line
        >>> f2.normal_cone()
        A 2-dimensional polyhedron in ZZ^3 defined as
         the convex hull of 1 vertex, 1 ray, 1 line
        >>> f3.normal_cone()
        A 1-dimensional polyhedron in ZZ^3 defined as
         the convex hull of 1 vertex and 1 line

    Normal cones are only defined for non-empty faces:

    Sage

        sage: f0 = p.faces(-1)[0]
        sage: f0.normal_cone()
        Traceback (most recent call last):
        ...
        ValueError: the empty face does not have a normal cone

    Python

        >>> from sage.all import *
        >>> f0 = p.faces(-Integer(1))[Integer(0)]
        >>> f0.normal_cone()
        Traceback (most recent call last):
        ...
        ValueError: the empty face does not have a normal cone

  polyhedron()

    Return the containing polyhedron.

    EXAMPLES:

    Sage

        sage: P = polytopes.cross_polytope(3); P
        A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 6 vertices
        sage: face = P.facets()[3]; face
        A 2-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 3 vertices
        sage: face.polyhedron()
        A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 6 vertices

    Python

        >>> from sage.all import *
        >>> P = polytopes.cross_polytope(Integer(3)); P
        A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 6 vertices
        >>> face = P.facets()[Integer(3)]; face
        A 2-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 3 vertices
        >>> face.polyhedron()
        A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 6 vertices

  ray_generator()

    Return a generator for the rays of the face.

    EXAMPLES:

    Sage

        sage: pi = Polyhedron(ieqs = [[1,1,0],[1,0,1]])
        sage: face = pi.faces(1)[1]
        sage: next(face.ray_generator())
        A ray in the direction (1, 0)

    Python

        >>> from sage.all import *
        >>> pi = Polyhedron(ieqs = [[Integer(1),Integer(1),Integer(0)],[Integer(1),Integer(0),Integer(1)]])
        >>> face = pi.faces(Integer(1))[Integer(1)]
        >>> next(face.ray_generator())
        A ray in the direction (1, 0)

  rays()

    Return the rays of the face.

    OUTPUT: a tuple of rays

    EXAMPLES:

    Sage

        sage: p = Polyhedron(ieqs = [[0,0,0,1],[0,0,1,0],[1,1,0,0]])
        sage: face = p.faces(2)[2]
        sage: face.rays()
        (A ray in the direction (1, 0, 0), A ray in the direction (0, 1, 0))

    Python

        >>> from sage.all import *
        >>> p = Polyhedron(ieqs = [[Integer(0),Integer(0),Integer(0),Integer(1)],[Integer(0),Integer(0),Integer(1),Integer(0)],[Integer(1),Integer(1),Integer(0),Integer(0)]])
        >>> face = p.faces(Integer(2))[Integer(2)]
        >>> face.rays()
        (A ray in the direction (1, 0, 0), A ray in the direction (0, 1, 0))

  stacking_locus()

    Return the polyhedron containing the points that sees every facet containing `self`.

    OUTPUT: a polyhedron

    EXAMPLES:

    Sage

        sage: cp = polytopes.cross_polytope(4)
        sage: facet = cp.facets()[0]
        sage: facet.stacking_locus().vertices()
        (A vertex at (1/2, 1/2, 1/2, 1/2),
         A vertex at (1, 0, 0, 0),
         A vertex at (0, 0, 0, 1),
         A vertex at (0, 0, 1, 0),
         A vertex at (0, 1, 0, 0))
        sage: face = cp.faces(2)[0]
        sage: face.stacking_locus().vertices()
        (A vertex at (0, 1, 0, 0),
         A vertex at (0, 0, 1, 0),
         A vertex at (1, 0, 0, 0),
         A vertex at (1, 1, 1, 0),
         A vertex at (1/2, 1/2, 1/2, 1/2),
         A vertex at (1/2, 1/2, 1/2, -1/2))

    Python

        >>> from sage.all import *
        >>> cp = polytopes.cross_polytope(Integer(4))
        >>> facet = cp.facets()[Integer(0)]
        >>> facet.stacking_locus().vertices()
        (A vertex at (1/2, 1/2, 1/2, 1/2),
         A vertex at (1, 0, 0, 0),
         A vertex at (0, 0, 0, 1),
         A vertex at (0, 0, 1, 0),
         A vertex at (0, 1, 0, 0))
        >>> face = cp.faces(Integer(2))[Integer(0)]
        >>> face.stacking_locus().vertices()
        (A vertex at (0, 1, 0, 0),
         A vertex at (0, 0, 1, 0),
         A vertex at (1, 0, 0, 0),
         A vertex at (1, 1, 1, 0),
         A vertex at (1/2, 1/2, 1/2, 1/2),
         A vertex at (1/2, 1/2, 1/2, -1/2))

  vertex_generator()

    Return a generator for the vertices of the face.

    EXAMPLES:

    Sage

        sage: triangle = Polyhedron(vertices=[[1,0],[0,1],[1,1]])
        sage: face = triangle.facets()[0]
        sage: for v in face.vertex_generator(): print(v)
        A vertex at (1, 0)
        A vertex at (1, 1)
        sage: type(face.vertex_generator())
        <... 'generator'>

    Python

        >>> from sage.all import *
        >>> triangle = Polyhedron(vertices=[[Integer(1),Integer(0)],[Integer(0),Integer(1)],[Integer(1),Integer(1)]])
        >>> face = triangle.facets()[Integer(0)]
        >>> for v in face.vertex_generator(): print(v)
        A vertex at (1, 0)
        A vertex at (1, 1)
        >>> type(face.vertex_generator())
        <... 'generator'>

  vertices()

    Return all vertices of the face.

    OUTPUT: a tuple of vertices

    EXAMPLES:

    Sage

        sage: triangle = Polyhedron(vertices=[[1,0],[0,1],[1,1]])
        sage: face = triangle.faces(1)[2]
        sage: face.vertices()
        (A vertex at (0, 1), A vertex at (1, 0))

    Python

        >>> from sage.all import *
        >>> triangle = Polyhedron(vertices=[[Integer(1),Integer(0)],[Integer(0),Integer(1)],[Integer(1),Integer(1)]])
        >>> face = triangle.faces(Integer(1))[Integer(2)]
        >>> face.vertices()
        (A vertex at (0, 1), A vertex at (1, 0))

sage.geometry.polyhedron.face.combinatorial_face_to_polyhedral_face(polyhedron, combinatorial_face)

  Convert a combinatorial face to a face of a polyhedron.

  INPUT:

  - `polyhedron` – a polyhedron containing `combinatorial_face`

  - `combinatorial_face` – a `CombinatorialFace`

  OUTPUT: a `PolyhedronFace`

  EXAMPLES:

  Sage

      sage: from sage.geometry.polyhedron.face import combinatorial_face_to_polyhedral_face
      sage: P = polytopes.simplex()
      sage: C = P.combinatorial_polyhedron()
      sage: it = C.face_iter()
      sage: comb_face = next(it)
      sage: combinatorial_face_to_polyhedral_face(P, comb_face)
      A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 3 vertices

  Python

      >>> from sage.all import *
      >>> from sage.geometry.polyhedron.face import combinatorial_face_to_polyhedral_face
      >>> P = polytopes.simplex()
      >>> C = P.combinatorial_polyhedron()
      >>> it = C.face_iter()
      >>> comb_face = next(it)
      >>> combinatorial_face_to_polyhedral_face(P, comb_face)
      A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 3 vertices