documentation:latest:tropical:cycle

Available versions of this document: latest release, release 4.0, release 3.6, release 3.5, nightly master

Reference documentation for older polymake versions: release 3.4, release 3.3, release 3.2

from application tropical

A tropical cycle is a weighted, balanced, pure polyhedral complex. It is given as a polyhedral complex in tropical projective coordinates. To be precise: Each row of VERTICES and LINEALITY_SPACE has a leading 1 or 0, depending on whether it is a vertex or a ray. The remaining n coordinates are interpreted as an element of Rn modulo (1,..,1). IMPORTANT NOTE: VERTICES are assumed to be normalized such that the first coordinate (i.e. column index 1) is 0. If your input is not of that form, use PROJECTIVE_VERTICES. Note that there is a convenience method thomog, which converts affine coordinates into projective coordinates.

Type Parameters:

Addition: The tropical addition. Warning: There is NO default for this, you have to choose either Max or Min.

derived from:
PolyhedralComplex
Permutations:
CodimPerm:

permuting CODIMENSION_ONE_POLYTOPES

These properties are for input only. They allow redundant information.

PROJECTIVE_VERTICES

A list of (non-redundant) vertices and rays of the complex. Note that VERTICES are supposed to be normalized to a leading 0. If you want to input non-normalized vertices, use this property. VERTICES will be derived from this: Each row of VERTICES is just the corresponding row of PROJECTIVE_VERTICES, with the first coordinate (i.e. column index 1) normalized to 0.

Type:
Matrix<Rational,NonSymmetric>

These properties deal with affine and projective coordinates, conversion between those and properties like dimension that change in projective space.

PROJECTIVE_AMBIENT_DIM

This is the ambient projective dimension, i.e. it is FAN_AMBIENT_DIM-2.

Type:
Int

PROJECTIVE_CODIMENSION

Codimension of the cycle. Same as PROJECTIVE_AMBIENT_DIM - PROJECTIVE_DIM

Type:
Int

PROJECTIVE_DIM

This is the projective dimension of the cycle. Alias for DIM.

Type:
Int

These properties capture combinatorial information of the object. Combinatorial properties only depend on combinatorial data of the object like, e.g., the face lattice.

CODIMENSION_ONE_POLYTOPES

Non-redundant list of all codimension one faces. Indices refer to VERTICES. Does not include any far faces.

Type:
IncidenceMatrix<NonSymmetric>

FACET_NORMALS_BY_PAIRS

This maps an index pair (i,j), where i corresponds to the i-th row of CODIMENSION_ONE_POLYTOPES and j to the j-th row of MAXIMAL_POLYTOPES, to the matching row number in FACET_NORMALS.

Type:
Map<Pair<Int,Int>,Int>

MAXIMAL_AT_CODIM_ONE

Incidence matrix of codimension one polytopes and maximal polytopes. Rows refer to CODIMENSION_ONE_POLYTOPES, columns to MAXIMAL_POLYTOPES.

Type:
IncidenceMatrix<NonSymmetric>

These properties are used to define morphisms or rational functions on a Cycle.

SEPARATED_CODIMENSION_ONE_POLYTOPES

An incidence matrix describing which codimension one polytope in the complex is generated by which vertices. Each row corresponds to a codimension one polytope (More precisely, the i-th element represents the same codim 1 polytope as the i-th element of CODIMENSION_ONE_POLYTOPES). The indices in a row refer to rows of SEPARATED_VERTICES.

Type:
IncidenceMatrix<NonSymmetric>
from extension:

SEPARATED_CONVERSION_VECTOR

A vector with an entry for each row in SEPARATED_VERTICES. More precisely, the i-th entry gives the row index of the ray in VERTICES that is equal to the i-th row of SEPARATED_VERTICES.

Type:
Vector<Int>
from extension:

SEPARATED_MAXIMAL_POLYTOPES

An incidence matrix describing which maximal polytope in the complex us generated by which rays. Each row corresponds to a maximal polytope (More precisely, the i-th element represents the same maximal polytope as the i-th element of MAXIMAL_POLYTOPES). The indices in a row refer to rows of SEPARATED_VERTICES, i.e. the maximal polytope described by the i-th element is generated by the vertices corresponding to these row indices.

Type:
IncidenceMatrix<NonSymmetric>
from extension:

SEPARATED_VERTICES

This is a matrix of vertices of the complex. More precisely, each ray r from VERTICES occurs as a row in this matrix…

1. once, if r_0 = 1
2. k times, if r_0 = 0 and k is the number of equivalence classes of maximal cones

containing r with respect to the following relation: Two maximal cones m, m' containing r are equivalent, if they are equal or there exists a sequence of maximal cones m = m_1,…m_r = m', such that r is contained in each m_i and each intersection m_i cap m_i+1 contains at least one ray s with s_0 = 1. The reason for this is that, when for example specifying a piecewise affine linear function on a polyhedral complex, the same far ray with x0 = 0 might be assigned two different values, if it is contained in two “non-connected” maximal cones (where connectedness is to be understood as described above). If there is a LOCAL_RESTRICTION the above equivalence relation is changed in such a way that the affine ray s with s_0 = 1 that must be contained in the intersection of two subsequent cones must be a compatible ray

Type:
Matrix<Rational,NonSymmetric>
from extension:

These are general properties related to intersection theory.

DEGREE

The degree of the tropical variety, i.e. the weight of the intersection product with a uniform tropical linear space of complementary dimension.

Type:
Integer
from extension:

These properties are used for doing computations locally around a specified part of a Cycle, given via a nontrivial LOCAL_RESTRICTION.

LOCAL_RESTRICTION

This contains a list of sets of ray indices (referring to VERTICES). All of these sets should describe polyhedra of the polyhedral complex (though not necessarily maximal ones). A polyhedron is now called compatible with this property, if it contains one of these polyhedra If this list is not empty, all computations will be done only on (or around) compatible cones. The documentation of each property will explain in what way this restriction is enforced. If this list is empty or not defined, there is no restriction. Careful: The implementation assumes that ALL maximal cones are compatible. If in doubt, you can create a complex with a local restriction from a given complex by using one of the “local_…” creation methods This list is assumed to be irredundant, i.e. there are no doubles (though this should not break anything, it is simply less efficient). It is, however, possible that one element is a subset of another.

Type:
IncidenceMatrix<NonSymmetric>
from extension:

These properties relate to the weights of a tropical cycle.

BALANCED_FACES

A vector whose entries correspond to the rows of CODIMENSION_ONE_POLYTOPES. The i-th entry is true, if and only if the complex is balanced at that face TODO: DEPRECATED, replace with user_function

Type:
Array<Bool>
from extension:

IS_BALANCED

Whether the cycle is balanced. As many functions in a-tint can deal with non-balanced complexes, we include this as a property.

Type:
Bool
from extension:

IS_IRREDUCIBLE

Whether this complex is irreducible.

Type:
Bool
from extension:

LATTICE_BASES

This incidence matrix gives a lattice basis for each maximal polytope. More precisely it gives a lattice basis whose span contains the lattice of the maximal polytope. Row i corresponds to cone i and gives lattice generator indices referring to LATTICE_GENERATORS. If this property is computed via rules, it does indeed give a lattice basis for the cone lattice, but when it is computed during an operation like refinement or divisor it will in general be larger. If this property exists, lattice normals might be computed faster.

Type:
IncidenceMatrix<NonSymmetric>
from extension:

LATTICE_GENERATORS

This is an irredundant list of all lattice generators of all maximal polyhedra. If this property exists, lattice normals might be computed faster

Type:
Matrix<Integer,NonSymmetric>
from extension:

LATTICE_NORMALS

The lattice normals of codimension one faces with respect to adjacent maximal cells. It maps a pair of indices (i,j) to the lattice normal of the codimension one face given by row i in CODIMENSION_ONE_POLYTOPES in the maximal cell given by row j in MAXIMAL_POLYTOPES. The lattice normal is a representative of a generator of the quotient of the saturated lattice of the maximal cell by the saturated lattice of the codimension one face. It is chosen such that it “points into the maximal cell” and is only unique modulo the lattice spanned by the codimension one cell.

Type:
Map<Pair<Int,Int>,Vector<Integer>>

LATTICE_NORMAL_FCT_VECTOR

For each lattice normal vector, this gives a vector of length (number of rays) + (lineality dim.), such that if a rational function is given by values on the rays and lin space generators, the value of the corresponding normal LATTICE_NORMALS→{i}→{j} can be computed by multiplying the function value vector with the vector LATTICE_NORMAL_FCT_VECTOR→{i}→{j}. This is done in the following way: We use the generating system (and indices refer to SEPARATED_VERTICES) <(r_i-r_0)_i>0, s_j, l_k>, where r_0 is the ray of the maximal cone with the lowest index in SEPARATED_VERTICES, such that it fulfills x0 = 1, r_i are the remaining rays with x0 = 1, ordered according to their index in SEPARATED_VERTICES, s_j are the rays of the cone with x0 = 0 and l_k are the lineality space generators. We will then store the coefficients a_i of (r_i - r_0) at the index of r_i, then - sum(a_i) at the index of r_0 and the remaining coefficients at the appropriate places. In particular, the value of a lattice normal under a rational function can be computed simply by taking the scalar product of RAY_VALUES | LIN_VALUES with this FCT_VECTOR

Type:
Map<Pair<Int,Int>,Vector<Rational>>
from extension:

LATTICE_NORMAL_SUM

Rows of this matrix correspond to CODIMENSION_ONE_POLYTOPES, and each row contains the weighted sum: sum_{cone > codim-1-face}( weight(cone) * LATTICE_NORMALS→{codim-1-face}→{cone})

Type:
Matrix<Rational,NonSymmetric>
from extension:

LATTICE_NORMAL_SUM_FCT_VECTOR

Rows of this matrix correspond to SEPARATED_CODIMENSION_ONE_POLYTOPES and each row contains a function vector for the corresponding row of LATTICE_NORMAL_SUM. This function vector is computed in the same way as described under LATTICE_NORMAL_FCT_VECTOR. Note that for any codim-1-faces at which the complex is not balanced, the corresponding row is a zero row. If a face is balanced can be checked under UNBALANCED_FACES.

Type:
Matrix<Rational,NonSymmetric>
from extension:

UNBALANCED_FACES

Indexes of faces in CODIMENSION_ONE_POLYTOPES the complex is not balanced at.

Type:
Set<Int>
from extension:

WEIGHTS

These are the integer weights associated to the maximal cells of the complex. Entries correspond to (rows of) MAXIMAL_POLYTOPES.

Type:
Vector<Integer>

WEIGHT_CONE

The intersection of WEIGHT_SPACE with the positive orthant.

Type:
Cone<Rational>
from extension:

WEIGHT_SPACE

A Z-basis (as rows) for the space of weight distributions on this tropical cycle making it balanced (i.e. this cycle is irreducible, if and only if WEIGHT_SPACE has only one row and the gcd of WEIGHTS is 1.

Type:
Matrix<Rational,NonSymmetric>
from extension:

WEIGHT_SYSTEM

The dual of WEIGHT_SPACE.

Type:
Matrix<Rational,NonSymmetric>
from extension:

These methods deal with affine and projective coordinates, conversion between those and properties like dimension that change in projective space.

affine_chart(Int chart)

This produces a version of the cycle in the coordinates of a standard tropical chart, i.e. one coordinate is set to 0. It is returned as an ordinary polyhedral complex (which can, for example, be used for visualization).

Parameters:

Int chart: The coordinate which should be set to 0. Indexed from 0 to AMBIENT_DIM-1 and 0 by default.

Returns:
PolyhedralComplex<Rational>

These methods provide basic functionality related to polyhedral geometry, but not necessarily to tropical geometry

is_fan(Bool allow_translations)

Checks whether this polyhedral structure is a fan, i.e. has only a single vertex at the origin.

Parameters:

Bool allow_translations: . Optional and false by default. If true, a shifted fan is also accepted.

Returns:
Bool
from extension:

These methods capture combinatorial information of the object. Combinatorial properties only depend on combinatorial data of the object like, e.g., the face lattice.

facet_normal(Int i, Int j)

Convenience function to ask for FACET_NORMALS_BY_PAIRS→{new Pair<Int,Int>(i,i)}

Parameters:

Int i: Row index in CODIMENSION_ONE_POLYTOPES.

Int j: Row index in MAXIMAL_POLYTOPES.

Returns:
Int

These methods are used for doing computations locally around a specified part of a Cycle, given via a nontrivial LOCAL_RESTRICTION.

delocalize()

Returns the cycle without its LOCAL_RESTRICTION (Note that only the defining properties are kept. All derived information is lost).

Returns:
Cycle
from extension:

These methods are for visualization.

BB_VISUAL()

Same as VISUAL. Kept for backwards compatibility.

Options:
option list Visual::Cycle::BoundingDecorations
from extension:

VISUAL()

Displays a (possibly weighted) polyhedral complex by intersecting it with a bounding polytope described by BoundingFacets. If BoundingFacets are not explicitly given one may use the MakeCube and BoundingOffset keywords for further settings of the automatically created bounding box.

Options:

Int Chart: Which affine chart to visualize, i.e. which coordinate to shift to 0. This is 0 by default.

String WeightLabels: If “hidden”, no weight labels are displayed. Not hidden by default.

String CoordLabels: If “show”, coordinate labels are displayed at vertices. Hidden by default.

Rational BoundingOffset: The distance from a bounding facet to the nearest bounded vertex

Matrix<Rational> BoundingFacets: describing the bounding polytope

option list Visual::Cycle::BoundingDecorations
from extension:

bounding_box(Int chart)

Takes a chart as input and computes the column-wise minimum and maximum of the coordinates of the nonfar vertices in homogeneous coordinates (the two opposing vertices of a bounding box). One can extend such a bounding box $bb1 with another$bb2 by using extend_bounding_box($bb1,$bb2).

Parameters:

Int chart: . The chart to be used for the computation.

from extension:

bounding_box_facets(Int offset, Int chart)

Takes offset and a chart as input and computes the facets of a bounding box. \

Parameters:

Int offset: . The offset of a facet from the nearest bounded vertex in the affine chart

Int chart: . The chart to be used for the computation.

from extension:

These methods relate to the weights of a tropical cycle.

CURVE_EDGE_LENGTHS()

For a onedimensional cycle, this produces the lengths of the MAXIMAL_POLYTOPES, as multiples of the corresponding LATTICE_NORMALS. The i-th entry is the length of cell i. For unbounded cells this number is inf

Returns:
Array<Rational>

lattice_normal(Int i, Int j)

Convenience function to ask for LATTICE_NORMALS→{new Pair<Int,Int>(i,j)}

Parameters:

Int i: Row index in CODIMENSION_ONE_POLYTOPES.

Int j: Row index in MAXIMAL_POLYTOPES.

Returns:
Vector<Integer>

• documentation/latest/tropical/cycle.txt