Triangulation Class
This class handles triangulations of lattice polytopes. It can compute various properties of the triangulation, as well as construct a ToricVariety or CalabiYau object if the triangulation is suitable.
Generally, objects of this class should not be constructed directly by the
end user. Instead, they should be created by various functions of the
Polytope
class.
Constructor
cytools.triangulation.Triangulation
Description:
Constructs a Triangulation
object describing a triangulation of a lattice
polytope. This is handled by the hidden __init__
function.
If you construct a triangulation object directly by inputting a list of
points they may be reordered to match the ordering of the points from the
Polytope
class. This is to ensure that computations of
toric varieties and Calabi-Yau manifolds are correct. To avoid this
subtlety we discourage users from constructing Triangulation objects
directly, and instead use the triangulation functions in the
Polytope
class.
Arguments:
triang_pts
(array_like): The list of points to be triangulated.poly
(Polytope, optional): The ambient polytope of the points to be triangulated. If not specified, it is constructed as the convex hull of the given points.heights
(array_like, optional): A list of heights specifying the regular triangulation. When not specified, it will return the Delaunay triangulation when using CGAL, a triangulation obtained from random heights near the Delaunay when using QHull, or the placing triangulation when using TOPCOM. Heights can only be specified when using CGAL or QHull as the backend.make_star
(bool, optional, default=False): Indicates whether to turn the triangulation into a star triangulation by deleting internal lines and connecting all points to the origin, or equivalently, by decreasing the height of the origin until it is much lower than all other heights.simplices
(array_like, optional): A list of simplices specifying the triangulation. Each simplex is a list of point indices. This is useful when a triangulation was previously computed and it needs to be used again. Note that the ordering of the points needs to be consistent.check_input_simplices
(bool, optional, default=True): Flag that specifies whether to check if the input simplices define a valid triangulation.backend
(str, optional, default="cgal"): Specifies the backend used to compute the triangulation. The available options are "qhull", "cgal", and "topcom". CGAL is the default one as it is very fast and robust.
Example
We construct a triangulation of a polytope. Since this class is not intended
to by initialized by the end user, we create it via the
triangulate
function of the
Polytope
class. In this example the polytope is reflexive,
so by default the triangulation is fine, regular, and star. Also, since the
polytope is reflexive then by default only the lattice points not interior
to facets are included in the triangulation.
from cytools import Polytope
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
print(t)
# A fine, regular, star triangulation of a 4-dimensional point
# configuration with 7 points in ZZ^4
Functions
ambient_dimension
Description: Returns the dimension of the ambient lattice.
Arguments: None.
Returns: (int) The dimension of the ambient lattice.
Aliases:
ambient_dim
.
Example
We construct a triangulation and find its ambient dimension.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.ambient_dim()
# 4
automorphism_orbit
Description: Returns all of the triangulations of the polytope that can be obtained by applying one or more polytope automorphisms to the triangulation. It also has the option of restricting the simplices to faces of the polytope of a particular dimension or codimension. This restriction is useful for checking CY equivalences from different triangulations.
Depending on how the point configuration was constructed, it may be the case that the automorphism group of the point configuration is larger or smaller than the one from the polytope. This function only uses the subset of automorphisms of the polytope that are also automorphisms of the point configuration.
Arguments:
automorphism
(int or array_like): The index of list of indices of the polytope automorphisms to use. If not specified it uses all automorphisms.on_faces_dim
(int, optional): Restrict the simplices to faces of the polytope of a given dimension.on_faces_codim
(int, optional): Restrict the simplices to faces of the polytope of a given codimension.
Returns: (numpy.ndarray) The list of triangulations obtained by performing automorphisms transformations.
Example
We construct a triangulation and find some of its automorphism orbits.
p = Polytope([[-1,0,0,0],[-1,1,0,0],[-1,0,1,0],[2,-1,0,-1],[2,0,-1,-1],[2,-1,-1,-1],[-1,0,0,1],[-1,1,0,1],[-1,0,1,1]])
t = p.triangulate()
orbit_all_autos = t.automorphism_orbit()
print(len(orbit_all_autos))
# 36
orbit_all_autos_2faces = t.automorphism_orbit(on_faces_dim=2)
print(len(orbit_all_autos_2faces))
# 36
orbit_sixth_auto = t.automorphism_orbit(automorphism=5)
print(len(orbit_sixth_auto))
# 2
orbit_list_autos = t.automorphism_orbit(automorphism=[5,6,9])
print(len(orbit_list_autos))
# 12
clear_cache
Description: Clears the cached results of any previous computation.
Arguments:
recursive
(bool, optional, default=False): Whether to also clear the cache of the ambient polytope.
Returns: Nothing.
Example
We construct a triangulation, compute its GKZ vector, clear the cache and then compute it again.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
gkz_phi = t.gkz_phi() # Computes the GKZ vector
t.clear_cache()
gkz_phi = t.gkz_phi() # The GKZ vector is recomputed
dimension
Description: Returns the dimension of the triangulated point configuration.
Arguments: None.
Returns: (int) The dimension of the triangulation.
Aliases:
dim
.
Example
We construct a triangulation and find its dimension.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.dimension()
# 4
get_cy
Description: Returns a CalabiYau object corresponding to the anti-canonical hypersurface on the toric variety defined by the fine, star, regular triangulation. If a nef-partition is specified then it returns the complete intersection Calabi-Yau that it specifies.
Only Calabi-Yau 3-fold hypersurfaces are fully supported. Other dimensions and CICYs require enabling the experimental features of CYTools. See experimental features for more details.
Arguments:
nef_partition
(list, optional): A list of tuples of indices specifying a nef-partition of the polytope, which correspondingly defines a complete intersection Calabi-Yau.
Returns: (CalabiYau) The Calabi-Yau arising from the triangulation.
Example
We construct a triangulation and obtain the Calabi-Yau hypersurface in the resulting toric variety.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
t.get_cy()
# A Calabi-Yau 3-fold hypersurface with h11=2 and h21=272 in a 4-dimensional toric variety
get_toric_variety
Description: Returns a ToricVariety object corresponding to the fan defined by the triangulation.
Arguments: None.
Returns: (ToricVariety) The toric variety arising from the triangulation.
Example
We construct a triangulation and obtain the resulting toric variety.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
t.get_toric_variety()
# A simplicial compact 4-dimensional toric variety with 9 affine patches
gkz_phi
Description: Returns the GKZ phi vector of the triangulation. The -th component is defined to be the sum of the volumes of the simplices that have the -th point as a vertex.
Arguments: None.
Returns: (numpy.ndarray) The GKZ phi vector of the triangulation.
Example
We construct a triangulation and find its GKZ vector.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
t.gkz_phi()
# array([18, 12, 9, 12, 12, 12, 15])
heights
Description: Returns the a height vector if the triangulation is regular. An exception is raised if a height vector could not be found either because the optimizer failed or because the triangulation is not regular.
Arguments:
integral
(bool, optional, default=False): Whether to find an integral height vector.backend
(str, optional): The optimizer used for the computation. The available options are the backends of thefind_interior_point
function of theCone
class. If not specified, it will be picked automatically.
Returns: (numpy.ndarray) A height vector giving rise to the triangulation.
Example
We construct a triangulation and find a height vector that generates it.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.heights()
# array([0., 0., 0., 0., 0., 1.])
is_equivalent
Description: Compares two triangulations with or without allowing automorphism transformations and with the option of restricting to faces of a particular dimension.
Arguments:
other
(Triangulation): The other triangulation that is being compared.use_automorphisms
(bool, optional, default=True): Whether to check the equivalence using automorphism transformations. This flag is ignored for point configurations that are not full dimensional.on_faces_dim
(int, optional): Restrict the simplices to faces of the polytope of a given dimension.on_faces_codim
(int, optional): Restrict the simplices to faces of the polytope of a given codimension.
Returns: (bool) The truth value of the triangulations being equivalent under the specified parameters.
Example
We construct two triangulations and check whether they are equivalent under various conditions.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[-1,1,1,0],[0,-1,-1,0],[0,0,0,1],[1,-2,1,1],[-2,2,1,-1],[1,1,-1,-1]])
triangs_gen = p.all_triangulations()
t1 = next(triangs_gen)
t2 = next(triangs_gen)
t1.is_equivalent(t2)
# False
t1.is_equivalent(t2, on_faces_dim=2)
# True
t1.is_equivalent(t2, on_faces_dim=2, use_automorphisms=False)
# True
is_fine
Description: Returns True if the triangulation is fine (all the points are used), and False otherwise. Note that this only checks if it is fine with respect to the point configuration, not with respect to the full set of lattice points of the polytope.
Arguments: None.
Returns: (bool) The truth value of the triangulation being fine.
Example
We construct a triangulation and check if it is fine.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.is_fine()
# True
is_regular
Description: Returns True if the triangulation is regular and False otherwise.
Arguments:
backend
(str, optional): The optimizer used for the computation. The available options are the backends of theis_solid
function of theCone
class. If not specified, it will be picked automatically.
Returns: (bool) The truth value of the triangulation being regular.
Example
We construct a triangulation and check if it is regular.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.is_regular()
# True
is_star
Description:
Returns True if the triangulation is star and False otherwise. The star
origin is assumed to be the origin, so for polytopes that don't contain
the origin this function will always return False unless star_origin
is specified.
Arguments:
star_origin
(int, optional): The index of the origin of the star triangulation
Returns: (bool) The truth value of the triangulation being star.
Example
We construct a triangulation and check if it is star.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.is_star()
# True
is_valid
Description: Returns True if the presumed triangulation meets all requirements to be a triangulation. The simplices must cover the full volume of the convex hull, and they cannot intersect at full-dimensional regions.
Arguments:
backend
(str, optional): The optimizer used for the computation. The available options are the backends of theis_solid
function of theCone
class. If not specified, it will be picked automatically.
Returns: (bool) The truth value of the triangulation being valid.
Example
This function is useful when constructing a triangulation from a given set of simplices. We show this in this example.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate(simplices=[[0,1,2,3,4],[0,1,2,3,5],[0,1,2,4,5],[0,1,3,4,5],[0,2,3,4,5]]) # It is already used here unless using check_input_simplices=False
t.is_valid()
# True
neighbor_triangulations
Description: Returns the list of triangulations that differ by one bistellar flip from the current triangulation. The computation is performed with a modified version of TOPCOM. There is the option of limiting the flips to fine, regular, and star triangulations. An additional backend is used to check regularity, as checking this with TOPCOM is very slow for large polytopes.
Arguments:
only_fine
(bool, optional, default=False): Restricts to fine triangulations.only_regular
(bool, optional, default=False): Restricts the to regular triangulations.only_star
(bool, optional, default=False): Restricts to star triangulations.backend
(str, optional, default=None): The backend used to check regularity. The options are any backend available for theis_solid
function of theCone
class. If not specified, it will be picked automatically.
Returns: (list) The list of triangulations that differ by one bistellar flip from the current triangulation.
Example
We construct a triangulation and find its neighbor triangulations.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]]).dual()
t = p.triangulate()
triangs = t.neighbor_triangulations()
len(triangs) # Print how many triangulations it found
# 263
points
Description: Returns the points of the triangulation. Note that these are not necessarily equal to the lattice points of the polytope they define.
Arguments: None.
Returns: (numpy.ndarray) The points of the triangulation.
Aliases:
pts
.
Example
We construct a triangulation and print the points in the point configuration. Note that since the polytope is reflexive, then by default only the lattice points not interior to facets were used.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
t.points()
# array([[ 0, 0, 0, 0],
# [-1, -1, -6, -9],
# [ 0, 0, 0, 1],
# [ 0, 0, 1, 0],
# [ 0, 1, 0, 0],
# [ 1, 0, 0, 0],
# [ 0, 0, -2, -3]])
points_to_indices
Description: Returns the list of indices corresponding to the given points. It also accepts a single point, in which case it returns the corresponding index. Note that these indices are not necessarily equal to the corresponding indices in the polytope.
Arguments:
points
(array_like): A point or a list of points.
Returns: (numpy.ndarray or int) The list of indices corresponding to the given points, or the index of the point if only one is given.
Example
We construct a triangulation and find the indices of some of its points.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
t.points_to_indices([-1,-1,-6,-9]) # We input a single point, so a single index is returned
# 1
t.points_to_indices([[-1,-1,-6,-9],[0,0,0,0],[0,0,1,0]]) # We input a list of points, so a list of indices is returned
# array([1, 0, 3])
polytope
Description: Returns the polytope being triangulated.
Arguments: None.
Returns: (Polytope) The ambient polytope.
Example
We construct a triangulation and check that the polytope that this function returns is the same as the one we used to construct it.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.polytope() is p
# True
random_flips
Description: Returns a triangulation obtained by performing N random bistellar flips. The computation is performed with a modified version of TOPCOM. There is the option of limiting the flips to fine, regular, and star triangulations. An additional backend is used to check regularity, as checking this with TOPCOM is very slow for large polytopes.
Arguments:
N
(int): The number of bistellar flips to perform.only_fine
(bool, optional): Restricts to flips to fine triangulations. If not specified, it is set to True if the triangulation is fine, and False otherwise.only_regular
(bool, optional): Restricts the flips to regular triangulations. If not specified, it is set to True if the triangulation is regular, and False otherwise.only_star
(bool, optional): Restricts the flips to star triangulations. If not specified, it is set to True if the triangulation is star, and False otherwise.backend
(str, optional, default=None): The backend used to check regularity. The options are any backend available for theis_solid
function of theCone
class. If not specified, it will be picked automatically.seed
(int, optional): A seed for the random number generator. This can be used to obtain reproducible results.
Returns: (Triangulation) A new triangulation obtained by performing N random flips.
Example
We construct a triangulation and perform 5 random flips to find a new triangulation.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]]).dual()
t = p.triangulate()
t.random_flips(5) # Takes a few seconds
# A fine, star triangulation of a 4-dimensional point configuration
# with 106 points in ZZ^4
secondary_cone
Description: Computes the secondary cone of the triangulation (also called the cone of strictly convex piecewise linear functions). It is computed by finding the defining hyperplane equations. The triangulation is regular if and only if this cone is solid (i.e. full-dimensional), in which case the points in the interior correspond to heights that give rise to the triangulation.
Arguments:
backend
(str, optional): Specifies how the cone is computed. Options are "native", which uses a native implementation of an algorithm by Berglund, Katz and Klemm, or "topcom" which uses differences of GKZ vectors for the computation.include_points_not_in_triangulation
*(bool, optional, default=True): This flag allows the exclusion of points that are not part of the triangulation. This can be done to check regularity faster, but this cannot be used if the actual cone in the secondary fan is needed.
Returns: (Cone) The secondary cone.
Aliases:
cpl_cone
.
Example
We construct a triangulation and find its secondary cone.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
t.secondary_cone()
# A rational polyhedral cone in RR^7 defined by 3 hyperplanes normals
simplices
Description: Returns the simplices of the triangulation. It also has the option of restricting the simplices to faces of the polytope of a particular dimension or codimension. This restriction is useful for checking CY equivalences from different triangulations.
Arguments:
on_faces_dim
(int, optional): Restrict the simplices to faces of the polytope of a given dimension.on_faces_codim
(int, optional): Restrict the simplices to faces of the polytope of a given codimension.
Returns: (numpy.ndarray) The simplices of the triangulation.
Example
We construct a triangulation and find its simplices. We also find the simplices the lie on 2-faces of the polytope.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
t.simplices()
# array([[0, 1, 2, 3, 4],
# [0, 1, 2, 3, 5],
# [0, 1, 2, 4, 5],
# [0, 1, 3, 4, 5],
# [0, 2, 3, 4, 5]])
t.simplices(on_faces_dim=2)
# [[1 2 3]
# [1 2 4]
# [1 2 5]
# [1 3 4]
# [1 3 5]
# [1 4 5]
# [2 3 4]
# [2 3 5]
# [2 4 5]
# [3 4 5]]
sr_ideal
Description: Returns the Stanley-Reisner ideal if the triangulation is star.
Arguments: None.
Returns: (tuple) The Stanley-Reisner ideal of the triangulation.
Example
We construct a triangulation and find its SR ideal.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
t.sr_ideal()
# array([[1, 4, 5],
# [2, 3, 6]])
triangulation_to_polytope_indices
Description: Takes a list of indices of points of the triangulation and it returns the corresponding indices of the polytope. It also accepts a single entry, in which case it returns the corresponding index.
Arguments:
points
(array_like): A list of indices of points.
Returns: (numpy.ndarray or int) The list of indices corresponding to the given points. Or the index of the point if only one is given.
Example
We construct a triangulation and convert from indices of the triangulation to indices of the polytope. Since the indices of the two classes usually match, we will construct a triangulation that does not include the origin, so that indices will be shifted by one.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate(points=[1,2,3,4,5,6,7,8,9]) # We exclude point 0, which is the origin
t.points_to_indices([-1,-1,-6,-9]) # We get the index of a point in the triangulation
# 0
p.points_to_indices([-1,-1,-6,-9]) # The same point corresponds to a different index in the polytope
# 1
t.triangulation_to_polytope_indices(0) # We can convert an index with this function
# 1
t.triangulation_to_polytope_indices([0,1,2,3,4,5,6,7,8]) # And we can convert multiple indices in the same way
# array([1, 2, 3, 4, 5, 6, 7, 8, 9])
Hidden Functions
__eq__
Description: Implements comparison of triangulations with ==.
Arguments:
other
(Triangulation): The other triangulation that is being compared.
Returns: (bool) The truth value of the triangulations being equal.
Example
We construct two triangulations and compare them.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t1 = p.triangulate(backend="qhull")
t2 = p.triangulate(backend="topcom")
t1 == t2
# True
__hash__
Description: Implements the ability to obtain hash values from triangulations.
Arguments: None.
Returns: (int) The hash value of the triangulation.
Example
We compute the hash value of a triangulation. Also, we construct a set and a dictionary with a triangulation, which make use of the hash function.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t = p.triangulate()
h = hash(t) # Obtain hash value
d = {t: 1} # Create dictionary with triangulation keys
s = {t} # Create a set of triangulations
__init__
Description:
Initializes a Triangulation
object.
Arguments:
triang_pts
: The list of points to be triangulated.poly
: The ambient polytope of the points to be triangulated. If not specified, it's constructed as the convex hull of the given points.heights
: The heights specifying the regular triangulation. When not specified, construct based off of the backend:Heights can only be specified when using CGAL or QHull as the backend.- (CGAL) Delaunay triangulation,
- (QHULL) triangulation from random heights near Delaunay, or
- (TOPCOM) placing triangulation.make_star
: Whether to turn the triangulation into a star triangulation by deleting internal lines and connecting all points to the origin, or equivalently, by decreasing the height of the origin until it is much lower than all other heights.simplices
: Array-like of simplices specifying the triangulation. Each simplex is a list of point indices. This is useful when a triangulation was previously computed and it needs to be used again. Note that the ordering of the points needs to be consistent.check_input_simplices
: Whether to check if the input simplices define a valid triangulation.backend
: The backend used to compute the triangulation. Options are "qhull", "cgal", and "topcom". CGAL is the default as it is very fast and robust.
Returns: Nothing.
Example
This is the function that is called when creating a new
Triangulation
object. In this example the polytope is reflexive, so
by default the triangulation is fine, regular, and star. Also, since
the polytope is reflexive then by default only the lattice points not
interior to facets are included in the triangulation.
from cytools import Polytope
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
print(t)
# A fine, regular, star triangulation of a 4-dimensional point
# configuration with 7 points in ZZ^4
__ne__
Description: Implements comparison of triangulations with !=.
Arguments:
other
(Triangulation): The other triangulation that is being compared.
Returns: (bool) The truth value of the triangulations being different.
Example
We construct two triangulations and compare them.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]])
t1 = p.triangulate(backend="qhull")
t2 = p.triangulate(backend="topcom")
t1 != t2
# False
__repr__
Description: Returns a string describing the triangulation.
Arguments: None.
Returns: (str) A string describing the triangulation.
Example
This function can be used to convert the triangulation to a string or to print information about the triangulation.
p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])
t = p.triangulate()
poly_info = str(t) # Converts to string
print(t) # Prints triangulation info
# A fine, regular, star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4