Point collections¶
This module was designed as a part of framework for toric varieties
(variety
,
fano_variety
).
AUTHORS:
 Andrey Novoseltsev (20110425): initial version, based on cone module.
 Andrey Novoseltsev (20120306): 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: 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)
prints in a convenient way and with clear indication of the ambient space:
sage: c N(0, 0, 1), N(1, 0, 1), N(0, 1, 1), N(1, 1, 1) in 3d lattice N
allows (cached) access to alternative representations:
sage: 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: c.basis() N(0, 0, 1), N(1, 0, 1), N(0, 1, 1) in 3d 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
¶ Bases:
sage.structure.sage_object.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 ofmodule
, ifpoints
are already accessible to you as atuple
, it is preferable to use it for speed and memory consumption reasons;module
– an ambient module forpoints
. IfNone
, it will be determined asparent()
of the first point. Of course, this cannot be done if there are no points, so in this case you must give an appropriatemodule
directly. Note thatNone
is not the default value  you always must give this argument explicitly, even if it isNone
.
OUTPUT:
 a point collection.

basis
()¶ 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 ofself
.
EXAMPLES:
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 3d lattice N
Calling this method twice will always return exactly the same point collection:
sage: c.basis().basis() is c.basis() True
 a

cardinality
()¶ Return the number of points in
self
.OUTPUT:
 an integer.
EXAMPLES:
sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays() sage: c.cardinality() 4

cartesian_product
(other, module=None)¶ Return the Cartesian product of
self
withother
.INPUT:
other
– apoint collection
;module
– (optional) the ambient module for the result. By default, the direct sum of the ambient modules ofself
andother
is constructed.
OUTPUT:
EXAMPLES:
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 6d lattice N+N

column_matrix
()¶ Return a matrix whose columns are points of
self
.OUTPUT:
 a
matrix
.
EXAMPLES:
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]
 a

dim
()¶ Return the dimension of the space spanned by points of
self
.Note
You can use either
dim()
ordimension()
.OUTPUT:
 an integer.
EXAMPLES:
sage: c = Cone([(0,0,1), (1,1,1)]).rays() sage: c.dimension() 2 sage: c.dim() 2

dimension
()¶ Return the dimension of the space spanned by points of
self
.Note
You can use either
dim()
ordimension()
.OUTPUT:
 an integer.
EXAMPLES:
sage: c = Cone([(0,0,1), (1,1,1)]).rays() sage: c.dimension() 2 sage: c.dim() 2

dual_module
()¶ Return the dual of the ambient module of
self
.OUTPUT:
 a
module
. If possible (that is, if the ambientmodule()
\(M\) ofself
has adual()
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: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays() sage: c.dual_module() 3d lattice M
 a

index
(*args)¶ Return the index of the first occurrence of
point
inself
.INPUT:
point
– a point ofself
;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 inself[start:stop]
, otherwise aValueError
exception is raised.
EXAMPLES:
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
Note that this was not a mistake: the tuple
(0,1,1)
is not a point ofc
! We need to pass actual element of the ambient module ofc
to get their indices:sage: N = c.module() sage: c.index(N(0,1,1)) 2 sage: c[2] N(0, 1, 1)

matrix
()¶ Return a matrix whose rows are points of
self
.OUTPUT:
 a
matrix
.
EXAMPLES:
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]
 a

module
()¶ Return the ambient module of
self
.OUTPUT:
 a
module
.
EXAMPLES:
sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]).rays() sage: c.module() 3d lattice N
 a

static
output_format
(format=None)¶ 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: 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 3d 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 3d lattice N sage: c.output_format("matrix") sage: c [0 0 1] [1 0 1] [0 1 1] [1 1 1] in 3d lattice N sage: c.output_format("column matrix") sage: c [0 1 0 1] [0 0 1 1] [1 1 1 1] in 3d lattice N sage: c.output_format("separated column matrix") sage: c [0 1 0 1] [0 0 1 1] [1 1 1 1] in 3d lattice N
Note that the last two outputs are identical, separators are only inserted in the LaTeX mode:
sage: latex(c) \left(\begin{array}{rrrr} 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: 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 3d lattice N

set
()¶ Return points of
self
as afrozenset
.OUTPUT:
 a
frozenset
.
EXAMPLES:
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)})
 a

write_for_palp
(f)¶ Write
self
into an open filef
in PALP format.INPUT:
f
– a file opened for writing.
EXAMPLES:
sage: o = lattice_polytope.cross_polytope(3) sage: from six 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

sage.geometry.point_collection.
is_PointCollection
(x)¶ Check if
x
is apoint collection
.INPUT:
x
– anything.
OUTPUT:
True
ifx
is a point collection andFalse
otherwise.
EXAMPLES:
sage: from sage.geometry.point_collection import is_PointCollection sage: is_PointCollection(1) False sage: c = Cone([(0,0,1), (1,0,1), (0,1,1), (1,1,1)]) sage: is_PointCollection(c.rays()) True

sage.geometry.point_collection.
read_palp_point_collection
(f, lattice=None, permutation=False)¶ 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, thetoric lattice
\(M\) of dimension \(n\) will be used.permutation
– (default:False
) ifTrue
, 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: 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 six 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 2d lattice M sage: read_palp_point_collection(f) M(1, 4), M(2, 5), M(3, 6) in 2d lattice M sage: read_palp_point_collection(f) is None True