Point collections¶

This module was designed as a part of framework for toric varieties (variety, fano_variety).

AUTHORS:

Andrey Novoseltsev (2011-04-25): initial version, based on cone module.
Andrey Novoseltsev (2012-03-06): additions and doctest changes while switching cones to use point collections.

EXAMPLES:

The idea behind point collections is to have a container for points of the same space that

behaves like a tuple without significant performance penalty:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c[1]
N(1, 0, 1)
sage: for point in c: point
N(0, 0, 1)
N(1, 0, 1)
N(0, 1, 1)
N(1, 1, 1)

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c[Integer(1)]
N(1, 0, 1)
>>> for point in c: point
N(0, 0, 1)
N(1, 0, 1)
N(0, 1, 1)
N(1, 1, 1)

prints in a convenient way and with clear indication of the ambient space:

Sage

sage: c
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1),
N(1, 1, 1)
in 3-d lattice N

Python

>>> from sage.all import *
>>> c
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1),
N(1, 1, 1)
in 3-d lattice N

allows (cached) access to alternative representations:

Sage

sage: c.set()
frozenset({N(0, 0, 1), N(0, 1, 1), N(1, 0, 1), N(1, 1, 1)})

Python

>>> from sage.all import *
>>> c.set()
frozenset({N(0, 0, 1), N(0, 1, 1), N(1, 0, 1), N(1, 1, 1)})

allows introduction of additional methods:

Sage

sage: c.basis()
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1)
in 3-d lattice N

Python

>>> from sage.all import *
>>> c.basis()
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1)
in 3-d lattice N

Examples of natural point collections include ray and line generators of cones, vertices and points of polytopes, normals to facets, their subcollections, etc.

Using this class for all of the above cases allows for unified interface and cache sharing. Suppose that \(\Delta\) is a reflexive polytope. Then the same point collection can be linked as

vertices of \(\Delta\);
facet normals of its polar \(\Delta^\circ\);
ray generators of the face fan of \(\Delta\);
ray generators of the normal fan of \(\Delta\).

If all these objects are in use and, say, a matrix representation was computed for one of them, it becomes available to all others as well, eliminating the need to spend time and memory four times.

class sage.geometry.point_collection.PointCollection[source]¶

Bases: SageObject

Create a point collection.

Warning

No correctness check or normalization is performed on the input data. This class is designed for internal operations and you probably should not use it directly.

Point collections are immutable, but cache most of the returned values.

INPUT:

points – an iterable structure of immutable elements of module, if points are already accessible to you as a tuple, it is preferable to use it for speed and memory consumption reasons;
module – an ambient module for points. If None (the default), it will be determined as parent() of the first point. Of course, this cannot be done if there are no points, so in this case you must give an appropriate module directly.

OUTPUT:

a point collection.

basis()[source]¶

Return a linearly independent subset of points of self.

OUTPUT:

a point collection giving a random (but fixed) choice of an \(\RR\)-basis for the vector space spanned by the points of self.

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.basis()
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1)
in 3-d lattice N

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.basis()
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1)
in 3-d lattice N

Calling this method twice will always return exactly the same point collection:

Sage

sage: c.basis().basis() is c.basis()
True

Python

>>> from sage.all import *
>>> c.basis().basis() is c.basis()
True

cardinality()[source]¶

Return the number of points in self.

OUTPUT: integer

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.cardinality()
4

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.cardinality()
4

cartesian_product(other, module=None)[source]¶

Return the Cartesian product of self with other.

INPUT:

other – a point collection;
module – (optional) the ambient module for the result. By default, the direct sum of the ambient modules of self and other is constructed.

OUTPUT: a point collection

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,1,1)]).rays()
sage: c.cartesian_product(c)
N+N(0, 0, 1, 0, 0, 1),
N+N(1, 1, 1, 0, 0, 1),
N+N(0, 0, 1, 1, 1, 1),
N+N(1, 1, 1, 1, 1, 1)
in 6-d lattice N+N

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.cartesian_product(c)
N+N(0, 0, 1, 0, 0, 1),
N+N(1, 1, 1, 0, 0, 1),
N+N(0, 0, 1, 1, 1, 1),
N+N(1, 1, 1, 1, 1, 1)
in 6-d lattice N+N

column_matrix()[source]¶

Return a matrix whose columns are points of self.

OUTPUT: a matrix

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.column_matrix()
[0 1 0 1]
[0 0 1 1]
[1 1 1 1]

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.column_matrix()
[0 1 0 1]
[0 0 1 1]
[1 1 1 1]

dim()[source]¶

Return the dimension of the space spanned by points of self.

Note

You can use either dim() or dimension().

OUTPUT: integer

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,1,1)]).rays()
sage: c.dimension()
2
sage: c.dim()
2

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.dimension()
2
>>> c.dim()
2

dimension()[source]¶

Return the dimension of the space spanned by points of self.

Note

You can use either dim() or dimension().

OUTPUT: integer

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,1,1)]).rays()
sage: c.dimension()
2
sage: c.dim()
2

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.dimension()
2
>>> c.dim()
2

dual_module()[source]¶

Return the dual of the ambient module of self.

OUTPUT:

a module. If possible (that is, if the ambient module() \(M\) of self has a dual() method), the dual module is returned. Otherwise, \(R^n\) is returned, where \(n\) is the dimension of \(M\) and \(R\) is its base ring.

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.dual_module()
3-d lattice M

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.dual_module()
3-d lattice M

index(*args)[source]¶

Return the index of the first occurrence of point in self.

INPUT:

point – a point of self
start – (optional) an integer, if given, the search will start at this position
stop – (optional) an integer, if given, the search will stop at this position

OUTPUT: an integer if point is in self[start:stop], otherwise a ValueError exception is raised

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.index((0,1,1))
Traceback (most recent call last):
...
ValueError: tuple.index(x): x not in tuple

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.index((Integer(0),Integer(1),Integer(1)))
Traceback (most recent call last):
...
ValueError: tuple.index(x): x not in tuple

Note that this was not a mistake: the tuple (0,1,1) is not a point of c! We need to pass actual element of the ambient module of c to get their indices:

Sage

sage: N = c.module()
sage: c.index(N(0,1,1))
2
sage: c[2]
N(0, 1, 1)

Python

>>> from sage.all import *
>>> N = c.module()
>>> c.index(N(Integer(0),Integer(1),Integer(1)))
2
>>> c[Integer(2)]
N(0, 1, 1)

matrix()[source]¶

Return a matrix whose rows are points of self.

OUTPUT: a matrix

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.matrix()
[0 0 1]
[1 0 1]
[0 1 1]
[1 1 1]

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.matrix()
[0 0 1]
[1 0 1]
[0 1 1]
[1 1 1]

module()[source]¶

Return the ambient module of self.

OUTPUT: a module

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.module()
3-d lattice N

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.module()
3-d lattice N

static output_format(format=None)[source]¶

Return or set the output format for ALL point collections.

INPUT:

format – (optional) if given, must be one of the strings
- “default” – output one point per line with vertical alignment of coordinates in text mode, same as “tuple” for LaTeX;
- “tuple” – output tuple(self) with lattice information;
- “matrix” – output matrix() with lattice information;
- “column matrix” – output column_matrix() with lattice information;
- “separated column matrix” – same as “column matrix” for text mode, for LaTeX separate columns by lines (not shown by jsMath).

OUTPUT:

a string with the current format (only if format was omitted).

This function affects both regular and LaTeX output.

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1),
N(1, 1, 1)
in 3-d lattice N
sage: c.output_format()
'default'
sage: c.output_format("tuple")
sage: c
(N(0, 0, 1), N(1, 0, 1), N(0, 1, 1), N(1, 1, 1))
in 3-d lattice N
sage: c.output_format("matrix")
sage: c
[0 0 1]
[1 0 1]
[0 1 1]
[1 1 1]
in 3-d lattice N
sage: c.output_format("column matrix")
sage: c
[0 1 0 1]
[0 0 1 1]
[1 1 1 1]
in 3-d lattice N
sage: c.output_format("separated column matrix")
sage: c
[0 1 0 1]
[0 0 1 1]
[1 1 1 1]
in 3-d lattice N

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1),
N(1, 1, 1)
in 3-d lattice N
>>> c.output_format()
'default'
>>> c.output_format("tuple")
>>> c
(N(0, 0, 1), N(1, 0, 1), N(0, 1, 1), N(1, 1, 1))
in 3-d lattice N
>>> c.output_format("matrix")
>>> c
[0 0 1]
[1 0 1]
[0 1 1]
[1 1 1]
in 3-d lattice N
>>> c.output_format("column matrix")
>>> c
[0 1 0 1]
[0 0 1 1]
[1 1 1 1]
in 3-d lattice N
>>> c.output_format("separated column matrix")
>>> c
[0 1 0 1]
[0 0 1 1]
[1 1 1 1]
in 3-d lattice N

Note that the last two outputs are identical, separators are only inserted in the LaTeX mode:

Sage

sage: latex(c)
\left(\begin{array}{r|r|r|r}
0 & 1 & 0 & 1 \\
0 & 0 & 1 & 1 \\
1 & 1 & 1 & 1
\end{array}\right)_{N}

Python

>>> from sage.all import *
>>> latex(c)
\left(\begin{array}{r|r|r|r}
0 & 1 & 0 & 1 \\
0 & 0 & 1 & 1 \\
1 & 1 & 1 & 1
\end{array}\right)_{N}

Since this is a static method, you can call it for the class directly:

Sage

sage: from sage.geometry.point_collection import PointCollection
sage: PointCollection.output_format("default")
sage: c
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1),
N(1, 1, 1)
in 3-d lattice N

Python

>>> from sage.all import *
>>> from sage.geometry.point_collection import PointCollection
>>> PointCollection.output_format("default")
>>> c
N(0, 0, 1),
N(1, 0, 1),
N(0, 1, 1),
N(1, 1, 1)
in 3-d lattice N

set()[source]¶

Return points of self as a frozenset.

OUTPUT: a frozenset

EXAMPLES:

Sage

sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays()
sage: c.set()
frozenset({N(0, 0, 1), N(0, 1, 1), N(1, 0, 1), N(1, 1, 1)})

Python

>>> from sage.all import *
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))]).rays()
>>> c.set()
frozenset({N(0, 0, 1), N(0, 1, 1), N(1, 0, 1), N(1, 1, 1)})

write_for_palp(f)[source]¶

Write self into an open file f in PALP format.

INPUT:

f – a file opened for writing

EXAMPLES:

Sage

sage: o = lattice_polytope.cross_polytope(3)
sage: from io import StringIO
sage: f = StringIO()
sage: o.vertices().write_for_palp(f)
sage: print(f.getvalue())
6 3
1 0 0
0 1 0
0 0 1
-1 0 0
0 -1 0
0 0 -1

Python

>>> from sage.all import *
>>> o = lattice_polytope.cross_polytope(Integer(3))
>>> from io import StringIO
>>> f = StringIO()
>>> o.vertices().write_for_palp(f)
>>> print(f.getvalue())
6 3
1 0 0
0 1 0
0 0 1
-1 0 0
0 -1 0
0 0 -1

sage.geometry.point_collection.is_PointCollection(x)[source]¶

Check if x is a point collection.

INPUT:

x – anything

OUTPUT: True if x is a point collection and False otherwise

EXAMPLES:

Sage

sage: from sage.geometry.point_collection import PointCollection
sage: isinstance(1, PointCollection)
False
sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)])
sage: isinstance(c.rays(), PointCollection)
True

Python

>>> from sage.all import *
>>> from sage.geometry.point_collection import PointCollection
>>> isinstance(Integer(1), PointCollection)
False
>>> c = Cone([(Integer(0),Integer(0),Integer(1)), (Integer(1),Integer(0),Integer(1)), (Integer(0),Integer(1),Integer(1)), (Integer(1),Integer(1),Integer(1))])
>>> isinstance(c.rays(), PointCollection)
True

sage.geometry.point_collection.read_palp_point_collection(f, lattice=None, permutation=False)[source]¶

Read and return a point collection from an opened file.

Data must be in PALP format:

the first input line starts with two integers \(m\) and \(n\), the number of points and the number of components of each;

the rest of the first line may contain a permutation;

the next \(m\) lines contain \(n\) numbers each.

Note

If \(m\) < \(n\), it is assumed (for compatibility with PALP) that the matrix is transposed, i.e. that each column is a point.

INPUT:

f – an opened file with PALP output
lattice – the lattice for points. If not given, the toric lattice \(M\) of dimension \(n\) will be used.
permutation – boolean (default: False); if True, try to retrieve the permutation. This parameter makes sense only when PALP computed the normal form of a lattice polytope.

OUTPUT:

a point collection, optionally followed by a permutation. None if EOF is reached.

EXAMPLES:

Sage

sage: data = "3 2 regular\n1 2\n3 4\n5 6\n2 3 transposed\n1 2 3\n4 5 6"
sage: print(data)
3 2 regular
1 2
3 4
5 6
2 3 transposed
1 2 3
4 5 6
sage: from io import StringIO
sage: f = StringIO(data)
sage: from sage.geometry.point_collection \
....:     import read_palp_point_collection
sage: read_palp_point_collection(f)
M(1, 2),
M(3, 4),
M(5, 6)
in 2-d lattice M
sage: read_palp_point_collection(f)
M(1, 4),
M(2, 5),
M(3, 6)
in 2-d lattice M
sage: read_palp_point_collection(f) is None
True

Python

>>> from sage.all import *
>>> data = "3 2 regular\n1 2\n3 4\n5 6\n2 3 transposed\n1 2 3\n4 5 6"
>>> print(data)
3 2 regular
1 2
3 4
5 6
2 3 transposed
1 2 3
4 5 6
>>> from io import StringIO
>>> f = StringIO(data)
>>> from sage.geometry.point_collection     import read_palp_point_collection
>>> read_palp_point_collection(f)
M(1, 2),
M(3, 4),
M(5, 6)
in 2-d lattice M
>>> read_palp_point_collection(f)
M(1, 4),
M(2, 5),
M(3, 6)
in 2-d lattice M
>>> read_palp_point_collection(f) is None
True