Class LatticePolytopeClass

Construct a lattice polytope. See \code{LatticePolytope}.

Most tests/examples are also done in LatticePolytope.

TESTS:
    sage: LatticePolytope(matrix(ZZ,[[1,2,3],[4,5,6]]))
    Traceback (most recent call last):
    ...
    ValueError: Points must span the space!
    Given:
    [1 2 3]
    [4 5 6]

Overrides: object.__init__

Reduction function. Does not store data that can be relatively fast
recomputed.

TESTS:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.vertices() == loads(o.dumps()).vertices()
    True

Overrides: object.__reduce__

Restores the state of pickled polytope.

TESTS:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.vertices() == loads(o.dumps()).vertices()
    True

Return a string representation of this polytope.

TESTS:
    sage: o = lattice_polytope.octahedron(3)
    sage: o._repr_()
    'An octahedron: 3-dimensional, 6 vertices.'

Return the dimension of this polytope.

EXAMPLES:
We create a 3-dimensional octahedron and check its dimension:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.dim()
    3

Return the matrix of distances for this polytope or distances for the
given point.

The matrix of distances m gives distances m[i,j] between the i-th facet
(which is also the i-th vertex of the polar polytope in the reflexive
case) and j-th point of this polytope.

If point is specified, integral distances from the point to all facets
of this polytope will be computed.

EXAMPLES:
The matrix of distances for a 3-dimensional octahedron:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.distances()
    [0 0 2 2 2 0 1]
    [2 0 2 0 2 0 1]
    [0 2 2 2 0 0 1]
    [2 2 2 0 0 0 1]
    [0 0 0 2 2 2 1]
    [2 0 0 0 2 2 1]
    [0 2 0 2 0 2 1]
    [2 2 0 0 0 2 1]

Distances from facets to the point (1,2,3):
    sage: o.distances([1,2,3])
    (1, 3, 5, 7, -5, -3, -1, 1)

It is OK to use RATIONAL coordinates:
    sage: o.distances([1,2,3/2])
    (-1/2, 3/2, 7/2, 11/2, -7/2, -3/2, 1/2, 5/2)
    sage: o.distances([1,2,sqrt(2)])
    Traceback (most recent call last):
    ...
    TypeError: unable to convert sqrt(2) to a rational

Return the sequence of edges of this polytope (i.e. faces of dimension 1).

EXAMPLES:
The octahedron has 12 edges:
    sage: o = lattice_polytope.octahedron(3)
    sage: len(o.edges())
    12
    sage: o.edges()
    [[1, 5], [0, 5], [0, 1], [3, 5], [1, 3], [4, 5], [0, 4], [3, 4], [1, 2], [0, 2], [2, 3], [2, 4]]

Return the sequence of faces of this polytope.

If \code{dim} or \code{codim} are specified, returns a sequence of
faces of the corresponding dimension or codimension. Otherwise returns
the sequence of such sequences for all dimensions.

EXAMPLES:
All faces of the 3-dimensional octahedron:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.faces()
    [
    [[5], [1], [0], [3], [4], [2]],
    [[1, 5], [0, 5], [0, 1], [3, 5], [1, 3], [4, 5], [0, 4], [3, 4], [1, 2], [0, 2], [2, 3], [2, 4]],
    [[0, 1, 5], [1, 3, 5], [0, 4, 5], [3, 4, 5], [0, 1, 2], [1, 2, 3], [0, 2, 4], [2, 3, 4]]
    ]

Its faces of dimension one (i.e., edges):
    sage: o.faces(dim=1)
    [[1, 5], [0, 5], [0, 1], [3, 5], [1, 3], [4, 5], [0, 4], [3, 4], [1, 2], [0, 2], [2, 3], [2, 4]]

Its faces of codimension two (also edges):
    sage: o.faces(codim=2)
    [[1, 5], [0, 5], [0, 1], [3, 5], [1, 3], [4, 5], [0, 4], [3, 4], [1, 2], [0, 2], [2, 3], [2, 4]]

It is an error to specify both dimension and codimension at the same
time, even if they do agree:
    sage: o.faces(dim=1, codim=2)
    Traceback (most recent call last):
    ...
    ValueError: Both dim and codim are given!

Return the sequence of facets of this polytope (i.e. faces of codimension 1).

EXAMPLES:
All facets of the 3-dimensional octahedron:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.facets()
    [[0, 1, 5], [1, 3, 5], [0, 4, 5], [3, 4, 5], [0, 1, 2], [1, 2, 3], [0, 2, 4], [2, 3, 4]]

Facets are the same as faces of codimension one:
    sage: o.facets() is o.faces(codim=1)
    True

Return the index of this polytope in the internal database of 2- or
3-dimensional reflexive polytopes. Databases are stored in the directory
of the package.

NOTE: The first call to this function for each dimension can take
a second or so while the dictionary of all polytopes is loaded, but
after that it is cached and fast.

EXAMPLES:
We check what is the index of the "diamond" in the database:
    sage: o = lattice_polytope.octahedron(2)
    sage: o.index()
    3

Note that polytopes with the same index are not necessarily the same:
    sage: o.vertices()
    [ 1  0 -1  0]
    [ 0  1  0 -1]
    sage: lattice_polytope.ReflexivePolytope(2,3).vertices()
    [ 1  0  0 -1]
    [ 0  1 -1  0]

But they are in the same $GL(Z^n)$ orbit and have the same normal form:
    sage: o.normal_form()
    [ 1  0  0 -1]
    [ 0  1 -1  0]
    sage: lattice_polytope.ReflexivePolytope(2,3).normal_form()
    [ 1  0  0 -1]
    [ 0  1 -1  0]

Return True if this polytope is reflexive.

EXAMPLES:
The 3-dimensional octahedron is reflexive (and 4318 other 3-polytopes):
    sage: o = lattice_polytope.octahedron(3)
    sage: o.is_reflexive()
    True

But not all polytopes are reflexive:
    sage: m = matrix(ZZ, [[1, 0, 0, -1,  0,  0],
    ...                   [0, 1, 0,  0, -1,  0],
    ...                   [0, 0, 0,  0,  0, -1]])
    ...
    sage: p = LatticePolytope(m)
    sage: p.is_reflexive()
    False

Return all vectors $m_{i,f}$, grouped into matrices.

INPUT:
    partition -- NEF-partition (instance of class NEFPartition)

OUTPUT:
    A sequence of matrices, one for each facet f of this polytope.
    Each row of each matrix corresponds to a part of the NEF-partition.

EXAMPLES:
We compute $m_{i,f}$ matrices for one of the nef-partitions of
the 3-dimensional octahedron:
    sage: o = lattice_polytope.octahedron(3)
    sage: nefp = o.nef_partitions()[0]
    sage: o.mif(nefp)
    [
    [ 0  0  1]
    [-1 -1  0],
    [ 0  0  1]
    [ 1 -1  0],
    [ 0  1  1]
    [-1  0  0],
    [0 1 1]
    [1 0 0],
    [ 0  0 -1]
    [-1 -1  0],
    [ 0  0 -1]
    [ 1 -1  0],
    [ 0  1 -1]
    [-1  0  0],
    [ 0  1 -1]
    [ 1  0  0]
    ]

Return the sequence of NEF-partitions for this polytope.

INPUT:
    keep_symmetric -- (default: False) if True, "-s" option will be
            passed to nef.x in order to keep symmetric partitions;
    keep_products -- (default: True) if True, "-D" option will be
            passed to nef.x in order to keep product partitions;
    keep_projections -- (default: True) if True, "-P" option will be
            passed to nef.x in order to keep projection partitions;
    hodge_numbers -- (default: False) if False, "-p" option will be
            passed to nef.x in order to skip Hodge numbers computation,
            which takes a lot of time.

EXAMPLES:
NEF-partitions of the 4-dimensional octahedron:
    sage: o = lattice_polytope.octahedron(4)
    sage: o.nef_partitions()
    [
    [1, 1, 0, 0, 1, 1, 0, 0] (direct product),
    [1, 1, 1, 0, 1, 0, 0, 0],
    [1, 1, 1, 0, 1, 1, 0, 0],
    [1, 1, 1, 0, 1, 1, 1, 0] (direct product),
    [1, 1, 1, 1, 0, 0, 0, 0],
    [1, 1, 1, 1, 1, 0, 0, 0],
    [1, 1, 1, 1, 1, 1, 0, 0],
    [1, 1, 1, 1, 1, 1, 1, 0] (projection)
    ]

Now we omit projections:
    sage: o.nef_partitions(keep_projections=False)
    [
    [1, 1, 0, 0, 1, 1, 0, 0] (direct product),
    [1, 1, 1, 0, 1, 0, 0, 0],
    [1, 1, 1, 0, 1, 1, 0, 0],
    [1, 1, 1, 0, 1, 1, 1, 0] (direct product),
    [1, 1, 1, 1, 0, 0, 0, 0],
    [1, 1, 1, 1, 1, 0, 0, 0],
    [1, 1, 1, 1, 1, 1, 0, 0]
    ]

At present, Hodge numbers cannot be computed for a given NEF-partition:
    sage: o.nef_partitions()[1].hodge_numbers()
    Traceback (most recent call last):
    ...
    NotImplementedError: use nef_partitions(hodge_numbers=True)!

But they can be obtained from nef.x for all partitions at once.
Partitions will be exactly the same:
    sage: o.nef_partitions(hodge_numbers=True)
    [
    [1, 1, 0, 0, 1, 1, 0, 0] (direct product),
    [1, 1, 1, 0, 1, 0, 0, 0],
    [1, 1, 1, 0, 1, 1, 0, 0],
    [1, 1, 1, 0, 1, 1, 1, 0] (direct product),
    [1, 1, 1, 1, 0, 0, 0, 0],
    [1, 1, 1, 1, 1, 0, 0, 0],
    [1, 1, 1, 1, 1, 1, 0, 0],
    [1, 1, 1, 1, 1, 1, 1, 0] (projection)
    ]

Now it is possible to get Hodge numbers:
    sage: o.nef_partitions(hodge_numbers=True)[1].hodge_numbers()
    [20]

Since NEF-partitions are cached, Hodge numbers are accessible after the
first request, even if you do not specify hodge_numbers anymore:
    sage: o.nef_partitions()[1].hodge_numbers()
    [20]

We illustrate removal of symmetric partitions on a diamond:
    sage: o = lattice_polytope.octahedron(2)
    sage: o.nef_partitions()
    [
    [1, 0, 1, 0] (direct product),
    [1, 1, 0, 0],
    [1, 1, 1, 0] (projection)
    ]
    sage: o.nef_partitions(keep_symmetric=True)
    [
    [1, 1, 0, 1] (projection),
    [1, 0, 1, 1] (projection),
    [1, 0, 0, 1],
    [0, 1, 1, 1] (projection),
    [0, 1, 0, 1] (direct product),
    [0, 0, 1, 1],
    [1, 1, 1, 0] (projection)
    ]

NEF-partitions can be computed only for reflexive polytopes:
    sage: m = matrix(ZZ, [[1, 0, 0, -1,  0,  0],
    ...                   [0, 1, 0,  0, -1,  0],
    ...                   [0, 0, 2,  0,  0, -1]])
    ...
    sage: p = LatticePolytope(m)
    sage: p.nef_partitions()
    Traceback (most recent call last):
    ...
    ValueError: The given polytope is not reflexive!
    Polytope: A lattice polytope: 3-dimensional, 6 vertices.

Run nef.x wilth given \code{keys} on vertices of this polytope.

INPUT:
    keys -- a string of options passed to nef.x. The key "-f" is added
            automatically.

OUTPUT:
    the output of nef.x as a string.

EXAMPLES:
This call is used internally for computing NEF-partitions:
    sage: o = lattice_polytope.octahedron(3)
    sage: s = o.nef_x("-N -V -p")
    sage: s                      # output contains random time
    M:27 8 N:7 6  codim=2 #part=5
    3 6  Vertices of P:
        1    0    0   -1    0    0
        0    1    0    0   -1    0
        0    0    1    0    0   -1
     P:0 V:2 4 5       0sec  0cpu
     P:2 V:3 4 5       0sec  0cpu
     P:3 V:4 5       0sec  0cpu
    np=3 d:1 p:1    0sec     0cpu

Return the number of facets of this polytope.

EXAMPLES:
The number of facets of the 3-dimensional octahedron:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.nfacets()
    8

Return the normal form of vertices of the polytope.

Two lattice polytopes are in the same GL(Z)-orbit if and only if their
normal forms are the same.

EXAMPLES:
We compute the normal form of the "diamond":
    sage: o = lattice_polytope.octahedron(2)
    sage: o.vertices()
    [ 1  0 -1  0]
    [ 0  1  0 -1]
    sage: o.normal_form()
    [ 1  0  0 -1]
    [ 0  1 -1  0]

The diamond is the 3rd polytope in the internal database...
    sage: o.index()
    3
    sage: lattice_polytope.ReflexivePolytope(2,3).vertices()
    [ 1  0  0 -1]
    [ 0  1 -1  0]

Return the number of lattice points of this polytope.

EXAMPLES:
The number of lattice points of the 3-dimensional octahedron and its
polar cube:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.npoints()
    7
    sage: cube = o.polar()
    sage: cube.npoints()
    27

Return the number of vertices of this polytope.

EXAMPLES:
The number of vertices of the 3-dimensional octahedron and its
polar cube:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.nvertices()
    6
    sage: cube = o.polar()
    sage: cube.nvertices()
    8

Return the set of all lattice polytopes.

EXAMPLES:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.parent()
    Set of all Lattice Polytopes

Draw a 3d picture of the polytope.

INPUT:
    self -- polytope of dimension 3.
    camera_center -- (default: random) location of center of
    the camera (i.e., viewer)

OUTPUT:
    -- a tachyon 3d raytracer plot of the polytope

The face colors are random.

AUTHORS:
    -- William Stein and Tom Boothby

EXAMPLES:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.plot().show()

Overrides: structure.sage_object.SageObject.plot

Return a 3d-plot of a 3-dimensional polytope.

By default, everything is shown with more or less pretty combination
of size and color parameters.

INPUT:
Most of the parameters are self-explanatory:
    show_facets     -- (default:True)
    facet_opacity   -- (default:0.5)
    facet_color     -- (default:(0,1,0))
    show_edges      -- (default:True) whether to draw edges as lines
    edge_thickness  -- (default:3)
    edge_color      -- (default:(0.5,0.5,0.5))
    show_vertices   -- (default:True) whether to draw vertices as balls
    vertex_size     -- (default:10)
    vertex_color    -- (default:(1,0,0))
    show_points     -- (default:True) whether to draw other poits as balls
    point_size      -- (default:10)
    point_color     -- (default:(0,0,1))
    show_vindices   -- (default:same as show_vertices) whether to show indices of vertices
    vindex_color    -- (default:(0,0,0)) color for vertex labels
    show_pindices   -- (default:same as show_points) whether to show indices of other points
    pindex_color    -- (default:(0,0,0)) color for point labels
    index_shift     -- (default:1.1)) if 1, labels are placed exactly at
                        the corresponding points. Otherwise the label position
                        is computed as a multiple of the point position vector.

EXAMPLES:
The default plot of a cube:
    sage: c = lattice_polytope.octahedron(3).polar()
    sage: c.plot3d()

Plot without facets and points, shown without the frame:
    sage: c.plot3d(show_facets=false,show_points=false).show(frame=False)

TESTS:
    sage: m = matrix([[0,0,0],[0,1,1],[1,0,1],[1,1,0]]).transpose()
    sage: p = LatticePolytope(m, compute_vertices=True)
    sage: p.plot3d()

Draw a 3d picture of the polytope.

See self.plot? for more details.

EXAMPLES:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.show()

Return the i-th point of this polytope, i.e. the i-th column of the
matrix returned by points().

EXAMPLES:
First few points are actually vertices:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.vertices()
    [ 1  0  0 -1  0  0]
    [ 0  1  0  0 -1  0]
    [ 0  0  1  0  0 -1]
    sage: o.point(1)
    (0, 1, 0)

The only other point in the octahedron is the origin:
    sage: o.point(6)
    (0, 0, 0)
    sage: o.points()
    [ 1  0  0 -1  0  0  0]
    [ 0  1  0  0 -1  0  0]
    [ 0  0  1  0  0 -1  0]

Return all lattice points of this polytope as columns of a matrix.

EXAMPLES:
The lattice points of the 3-dimensional octahedron and its polar cube:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.points()
    [ 1  0  0 -1  0  0  0]
    [ 0  1  0  0 -1  0  0]
    [ 0  0  1  0  0 -1  0]
    sage: cube = o.polar()
    sage: cube.points()
    [-1  1 -1  1 -1  1 -1  1 -1 -1 -1 -1 -1  0  0  0  0  0  0  0  0  0  1  1  1  1  1]
    [-1 -1  1  1 -1 -1  1  1 -1  0  0  0  1 -1 -1 -1  0  0  0  1  1  1 -1  0  0  0  1]
    [ 1  1  1  1 -1 -1 -1 -1  0 -1  0  1  0 -1  0  1 -1  0  1 -1  0  1  0 -1  0  1  0]

Return the polar polytope, if this polytope is reflexive.

EXAMPLES:
The polar polytope to the 3-dimensional octahedron:
    sage: o = lattice_polytope.octahedron(3)
    sage: cube = o.polar()
    sage: cube
    A polytope polar to An octahedron: 3-dimensional, 8 vertices.

The polar polytope "remembers" the original one:
    sage: cube.polar()
    An octahedron: 3-dimensional, 6 vertices.
    sage: cube.polar().polar() is cube
    True

Only reflexive polytopes have polars:
    sage: m = matrix(ZZ, [[1, 0, 0, -1,  0,  0],
    ...                   [0, 1, 0,  0, -1,  0],
    ...                   [0, 0, 2,  0,  0, -1]])
    ...
    sage: p = LatticePolytope(m)
    sage: p.polar()
    Traceback (most recent call last):
    ...
    ValueError: The given polytope is not reflexive!
    Polytope: A lattice polytope: 3-dimensional, 6 vertices.

Run poly.x with given \code{keys} on vertices of this polytope.

INPUT:
    keys -- a string of options passed to poly.x. The key "f" is added
            automatically.

OUTPUT:
    the output of poly.x as a string.

EXAMPLES:
This call is used for determining if a polytope is reflexive or not:
    sage: o = lattice_polytope.octahedron(3)
    sage: print o.poly_x("e")
    8 3  Vertices of P-dual <-> Equations of P
      -1  -1   1
       1  -1   1
      -1   1   1
       1   1   1
      -1  -1  -1
       1  -1  -1
      -1   1  -1
       1   1  -1

Since PALP has limits on different parameters determined during
compilation, the following code is likely to fail, unless you change
default settings of PALP:
    sage: BIGO = lattice_polytope.octahedron(7)
    sage: BIGO
    An octahedron: 7-dimensional, 14 vertices.
    sage: BIGO.poly_x("e")      # possibly different output depending on your system
    Traceback (most recent call last):
    ...
    ValueError: Error executing "poly.x -fe" for the given polytope!
    Polytope: An octahedron: 7-dimensional, 14 vertices.
    Vertices:
    [ 1  0  0  0  0  0  0 -1  0  0  0  0  0  0]
    [ 0  1  0  0  0  0  0  0 -1  0  0  0  0  0]
    [ 0  0  1  0  0  0  0  0  0 -1  0  0  0  0]
    [ 0  0  0  1  0  0  0  0  0  0 -1  0  0  0]
    [ 0  0  0  0  1  0  0  0  0  0  0 -1  0  0]
    [ 0  0  0  0  0  1  0  0  0  0  0  0 -1  0]
    [ 0  0  0  0  0  0  1  0  0  0  0  0  0 -1]
    Output:
    increase POLY_Dmax!

Return the graph of the one-skeleton of this polytope.

EXAMPLES:
We construct the one-skeleton graph for the "diamond":
    sage: o = lattice_polytope.octahedron(2)
    sage: g = o.skeleton()
    sage: g
    Graph on 4 vertices
    sage: g.edges()
    [(0, 1, None), (0, 3, None), (1, 2, None), (2, 3, None)]

Return the increasing list of indices of lattice points in k-skeleton
of the polytope (k is 1 by default).

EXAMPLES:
We compute all skeleton points for the cube:
    sage: o = lattice_polytope.octahedron(3)
    sage: c = o.polar()
    sage: c.skeleton_points()
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 15, 19, 21, 22, 23, 25, 26]

The default was 1-skeleton:
    sage: c.skeleton_points(k=1)
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 15, 19, 21, 22, 23, 25, 26]

0-skeleton just lists all vertices:
    sage: c.skeleton_points(k=0)
    [0, 1, 2, 3, 4, 5, 6, 7]

2-skeleton lists all points except for the origin (point \#17):
    sage: c.skeleton_points(k=2)
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 19, 20, 21, 22, 23, 24, 25, 26]

3-skeleton includes all points:
    sage: c.skeleton_points(k=3)
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26]

It is OK to compute higher dimensional skeletons - you will get the list of all points:
    sage: c.skeleton_points(k=100)
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26]

Show the graph of one-skeleton of this polytope.

Works only for 3-dimensional polytopes.

INPUT:
    normal -- a 3-dimensional vector (can be given as a list), which
        should be perpendicular to the screen. If not given, will be
        selected randomly (new each time and it may be far from "nice").

EXAMPLES:
Show a pretty picture of the octahedron:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.skeleton_show([1,2,4])

Return the i-th vertex of this polytope, i.e. the i-th column of the
matrix returned by vertices().

EXAMPLES:
Note that numeration starts with zero:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.vertices()
    [ 1  0  0 -1  0  0]
    [ 0  1  0  0 -1  0]
    [ 0  0  1  0  0 -1]
    sage: o.vertex(3)
    (-1, 0, 0)

Return vertices of this polytope as columns of a matrix.

EXAMPLES:
The lattice points of the 3-dimensional octahedron and its polar cube:
    sage: o = lattice_polytope.octahedron(3)
    sage: o.vertices()
    [ 1  0  0 -1  0  0]
    [ 0  1  0  0 -1  0]
    [ 0  0  1  0  0 -1]
    sage: cube = o.polar()
    sage: cube.vertices()
    [-1  1 -1  1 -1  1 -1  1]
    [-1 -1  1  1 -1 -1  1  1]
    [ 1  1  1  1 -1 -1 -1 -1]