# Miscellaneous Functions

There are various other functions in CYTools that don't belong to any particular class. They are defined in different places according to where they most closely belong. Here we list the location of the definitions of these functions as well as their documentation.

## Functions in `cytools.triangulation`

`all_triangulations`

**Description:**
Computes all triangulations of the input point configuration using TOPCOM.
There is the option to only compute fine, regular or fine triangulations.

This function is not intended to be called by the end user. Instead, it is
used by the `all_triangulations`

function
of the `Polytope`

class.

**Arguments:**

`points`

*(array_like)*: The list of points to be triangulated.`only_fine`

*(bool, optional, default=False)*: Restricts to only fine triangulations.`only_regular`

*(bool, optional, default=False)*: Restricts to only regular triangulations.`only_star`

*(bool, optional, default=False)*: Restricts to only star triangulations.`star_origin`

*(int, optional)*: The index of the point that will be used as the star origin. If the polytope is reflexive this is set to 0, but otherwise it must be specified.`backend`

*(str, optional)*: The optimizer used to check regularity computation. The available options are "topcom" and the backends of the`is_solid`

function of the`Cone`

class. If not specified, it will be picked automatically. Note that using TOPCOM to check regularity is slower.`poly`

*(Polytope, optional)*: The ambient polytope. It is constructed if not specified.`raw_output`

*(bool, optional, default=False)*: Return the triangulations as lists of simplices instead of as Triangulation objects.

**Returns:**
*(generator)* A generator of `Triangulation`

objects
with the specified properties. If `raw_output`

is set to True then
numpy arrays are used instead.

**Example**

This function is not intended to be directly used, but it is used in the following example. We construct a polytope and find all of its triangulations. We try picking different restrictions and see how the number of triangulations changes.

`p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-2,-1,-1],[-2,-1,-1,-1]])`

g = p.all_triangulations()

next(g) # Takes some time while TOPCOM finds all the triangulations

# A fine, regular, star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4

next(g) # Produces the next triangulation immediately

# A fine, regular, star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4

len(p.all_triangulations(as_list=True)) # Number of fine, regular, star triangulations

# 2

len(p.all_triangulations(only_regular=False, only_star=False, only_fine=False, as_list=True) )# Number of triangularions, no matter if fine, regular, or star

# 6

`cgal_triangulate`

**Description:**
Computes a regular triangulation using CGAL.

This function is not intended to be called by the end user. Instead, it is
used by the `Triangulation`

class when using CGAL as the
backend.

**Arguments:**

`points`

*(array_like)*: A list of points.`heights`

*(array_like)*: A list of heights defining the regular triangulation.

**Returns:**
*(numpy.ndarray)* A list of simplices defining a regular triangulation.

**Example**

This function is not intended to be directly used, but it is used in the following example. We construct a triangulation using CGAL.

`p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])`

p.triangulate(backend="cgal")

# A fine, star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4

`convert_to_star`

**Description:**
Turns a triangulation into a star triangulation by deleting internal lines
and connecting all points to the origin.

This function is not intended to be called by the end user. Instead, it is
used by the `Triangulation`

class when needed.

This function is only reliable for triangulations of reflexive polytopes and may produce invalid triangulations for other polytopes.

**Arguments:**

`simplices`

*(array_like)*: The list of simplices of the triangulation. Each simplex consists of the list of indices of the points forming its vertices.`facets`

*(list)*: The list of facets of the polytope. Each facet consists of the indices of the points in the facet.`star_origin`

*(int)*: The index of the point that is used as the star origin.

**Returns:**
*(numpy.ndarray)* A list of simplices forming a star triangulation.

**Example**

This function is not intended to be directly used, but it is used in the following example. We input a triangulation that is not star and ask it to turn it into a star triangulation.

`p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])`

p.triangulate(simplices=[[1,2,3,4,6],[1,2,3,5,6],[2,3,4,5,6]]) # The input triangulation is not star

# A non-fine, regular, non-star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4

p.triangulate(simplices=[[1,2,3,4,6],[1,2,3,5,6],[2,3,4,5,6]], make_star=True) # We can turn it into a star triangulation

# A fine, regular, star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4

`qhull_triangulate`

**Description:**
Computes a regular triangulation using QHull.

This function is not intended to be called by the end user. Instead, it is
used by the `Triangulation`

class when using QHull as the
backend.

**Arguments:**

`points`

*(array_like)*: A list of points.`heights`

*(array_like)*: A list of heights defining the regular triangulation.

**Returns:**
*(numpy.ndarray)* A list of simplices defining a regular triangulation.

**Example**

This function is not intended to be directly used, but it is used in the following example. We construct a triangulation using QHull.

`p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])`

p.triangulate(backend="qhull")

# A fine, star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4

`random_triangulations_fair_generator`

**Description:**
Constructs pseudorandom regular (optionally star)
triangulations of a given point set. Implements Algorithm #3 from the
paper
*Bounding the Kreuzer-Skarke Landscape*
by Mehmet Demirtas, Liam McAllister, and Andres Rios-Tascon.
arXiv:2008.01730

This is a Markov chain Monte Carlo algorithm that involves taking random walks inside the subset of the secondary fan corresponding to fine triangulations and performing random flips. For details, please see Section 4.1 in the paper.

- This function is not intended to be called by the end user. Instead, it
is used by the
`random_triangulations_fair`

function of the`Polytope`

class. - This function is designed mainly for large polytopes where sampling triangulations is challenging. When small polytopes are used it is likely to get stuck.

**Arguments:**

`triang_pts`

*(array_like)*: The list of points to be triangulated.`N`

*(int, optional)*: Number of desired unique triangulations. If not specified, it will generate as many triangulations as it can find until it has to retry more than max_retries times to obtain a new triangulation.`n_walk`

*(int, optional, default=10)*: Number of hit-and-run steps per triangulation.`n_flip`

*(int, optional, default=10)*: Number of random flips performed per triangulation.`initial_walk_steps`

*(int, optional, default=20)*: Number of hit-and-run steps to take before starting to record triangulations. Small values may result in a bias towards Delaunay-like triangulations.`walk_step_size`

*(float, optional, default=1e-2)*: Determines size of random steps taken in the secondary fan. Algorithm may stall if too small.`max_steps_to_wall`

*(int, optional, default=10)*: Maximum number of steps to take towards a wall of the subset of the secondary fan that correspond to fine triangulations. If a wall is not found, a new random direction is selected. Setting this to be very large (>100) reduces performance. If this, or walk_step_size, is set to be too low, the algorithm may stall.`fine_tune_steps`

*(int, optional, default=8)*: Number of steps to determine the location of a wall. Decreasing improves performance, but might result in biased samples.`max_retries`

*(int, optional, default=50)*: Maximum number of attempts to obtain a new triangulation before the process is terminated.`make_star`

*(bool, optional, default=False)*: Converts the obtained triangulations into star triangulations.`backend`

*(str, optional, default="cgal")*: Specifies the backend used to compute the triangulation. The available options are "cgal" and "qhull".`poly`

*(Polytope, optional)*: The ambient polytope. It is constructed if not specified.`seed`

*(int, optional)*: A seed for the random number generator. This can be used to obtain reproducible results.

**Returns:**
*(generator)* A generator of `Triangulation`

objects
with the specified properties.

**Example**

This function is not intended to be directly used, but it is used in the
following example. We construct a polytope and find some random
triangulations. The computation takes considerable time, but they should be
a fair sample from the full set of triangulations (if the parameters are
chosen correctly). For (some) machine learning purposes or when the
fairness of the sample is not crucial, the
`random_triangulations_fast`

function should be used instead.

`p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]]).dual()`

g = p.random_triangulations_fast()

next(g) # Takes a long time (around a minute)

# A fine, regular, star triangulation of a 4-dimensional point configuration with 106 points in ZZ^4

next(g) # Takes slightly shorter (still around a minute)

# A fine, regular, star triangulation of a 4-dimensional point configuration with 106 points in ZZ^4

rand_triangs = p.random_triangulations_fair(N=10, as_list=True) # Produces the list of 10 triangulations, but takes a long time (around 10 minutes)

It is worth noting that the time it takes to obtain each triangulation varies very significantly on the parameters used. The function tries to guess reasonable parameters, but it is better to adjust them to your desired balance between speed and fairness of the sampling.

`random_triangulations_fast_generator`

Constructs pseudorandom regular (optionally fine and star) triangulations of a given point set. This is done by picking random heights around the Delaunay heights from a Gaussian distribution.

This function is not intended to be called by the end user. Instead, it is
used by the
`random_triangulations_fast`

function of the `Polytope`

class.

This function produces random triangulations very quickly, but it does not
produce a fair sample. When a fair sampling is required the
`random_triangulations_fair`

function should be used.

**Arguments:**

`triang_pts`

*(array_like)*: The list of points to be triangulated.`N`

*(int, optional)*: Number of desired unique triangulations. If not specified, it will generate as many triangulations as it can find until it has to retry more than max_retries times to obtain a new triangulation.`c`

*(float, optional, default=0.2)*: A contant used as the standard deviation of the Gaussian distribution used to pick the heights. A larger c results in a wider range of possible triangulations, but with a larger fraction of them being non-fine, which slows down the process when using only_fine=True.`max_retries`

*(int, optional, default=50)*: Maximum number of attempts to obtain a new triangulation before the process is terminated.`make_star`

*(bool, optional, default=False)*: Converts the obtained triangulations into star triangulations.`only_fine`

*(bool, optional, default=True)*: Restricts to fine triangulations.`backend`

*(str, optional, default="cgal")*: Specifies the backend used to compute the triangulation. The available options are "cgal" and "qhull".`poly`

*(Polytope, optional)*: The ambient polytope. It is constructed if not specified.`seed`

*(int, optional)*: A seed for the random number generator. This can be used to obtain reproducible results.

**Returns:**
*(generator)* A generator of `Triangulation`

objects
with the specified properties.

**Example**

This function is not intended to be directly used, but it is used in the
following example. We construct a polytope and find some random
triangulations. The triangulations are obtained very quicly, but they are
not a fair sample of the space of triangulations. For a fair sample, the
`random_triangulations_fair`

function should be used.

`p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-1,-1]]).dual()`

g = p.random_triangulations_fast()

next(g) # Runs very quickly

# A fine, regular, star triangulation of a 4-dimensional point configuration with 106 points in ZZ^4

next(g) # Keeps producing triangulations until it has trouble finding more

# A fine, regular, star triangulation of a 4-dimensional point configuration with 106 points in ZZ^4

rand_triangs = p.random_triangulations_fast(N=10, as_list=True) # Produces the list of 10 triangulations very quickly

`topcom_triangulate`

**Description:**
Computes the placing/pushing triangulation using TOPCOM.

This function is not intended to be called by the end user. Instead, it is
used by the `Triangulation`

class when using TOPCOM as the
backend.

**Arguments:**

`points`

*(array_like)*: A list of points.

**Returns:**
*(numpy.ndarray)* A list of simplices defining a triangulation.

**Example**

This function is not intended to be directly used, but it is used in the following example. We construct a triangulation using TOMCOM.

`p = Polytope([[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1],[-1,-1,-6,-9]])`

p.triangulate(backend="topcom")

# A fine, star triangulation of a 4-dimensional point configuration with 7 points in ZZ^4

## Functions in `cytools.cone`

`is_extremal`

**Description:**
Auxiliary function that is used to find the extremal rays of cones. Returns
True if the ray is extremal and False otherwise. It has additional
parameters that are used when parallelizing.

**Arguments:**

`A`

*(array_like)*: A matrix where the columns are rays (excluding b).`b`

*(array_like)*: The vector that will be checked if it can be expressed as a positive linear combination of the columns of A.`i`

*(int, optional)*: An id number that is used when parallelizing.`q`

*(multiprocessing.Queue, optional)*: A queue that is used when parallelizing.`tol`

*(float, optional, default=1e-4)*: The tolerance for determining whether a ray is extremal.

**Returns:**
*(bool or None)* The truth value of the ray being extremal. If the process
fails then it returns nothing.

**Example**

This function is not meant to be directly used by the end user. Instead it
is used by the `extremal_rays`

function. We construct a
cone and find its extremal_rays.

`c = Cone([[0,1],[1,1],[1,0]])`

c.extremal_rays()

# array([[0, 1],

# [1, 0]])

## Functions in `cytools.utils`

`array_float_to_fmpq`

**Description:**
Converts a numpy array with floating-point entries to fmpq entries.

**Arguments:**

`arr`

*(array_like)*: A numpy array with floating-point entries.

**Returns:**
*(numpy.ndarray)* A numpy array with fmpq entries.

**Example**

We convert an float array to an fmpz array.

`from cytools.utils import array_float_to_fmpq`

arr = [[1.1,0,0],[0,0.5,0],[0,0,0.3333333333]]

array_float_to_fmpq(arr)

# array([[11/10, 0, 0],

# [0, 1/2, 0],

# [0, 0, 1/3]], dtype=object)

`array_fmpq_to_float`

**Description:**
Converts a numpy array with fmpq entries to floating-point entries.

**Arguments:**

`arr`

*(array_like)*: A numpy array with fmpq entries.

**Returns:**
*(numpy.ndarray)* A numpy array with floating-point entries.

**Example**

We convert an fmpq array to a float array.

`from cytools.utils import array_fmpq_to_float`

from flint import fmpq

arr = [fmpq(1,2), fmpq(2,5), fmpq(1,3)]

array_fmpq_to_float(arr)

# array([0.5 , 0.4 , 0.33333333])

`array_fmpz_to_int`

**Description:**
Converts a numpy array with fmpz entries to 64-bit integer entries.

**Arguments:**

`arr`

*(array_like)*: A numpy array with fmpz entries.

**Returns:**
*(numpy.ndarray)* A numpy array with 64-bit integer entries.

**Example**

We convert an fmpz array to an int array.

`from cytools.utils import array_fmpz_to_int`

from flint import fmpz

arr = [fmpz(1), fmpz(2), fmpz(3)]

array_fmpz_to_int(arr)

# array([1, 2, 3])

`array_int_to_fmpz`

**Description:**
Converts a numpy array with 64-bit integer entries to fmpz entries.

**Arguments:**

`arr`

*(array_like)*: A numpy array with 64-bit integer entries.

**Returns:**
*(numpy.ndarray)* A numpy array with fmpz entries.

**Example**

We convert an integer array to an fmpz array.

`from cytools.utils import array_int_to_fmpz`

arr = [[1,0,0],[0,2,0],[0,0,3]]

array_int_to_fmpz(arr)

# array([[1, 0, 0],

# [0, 2, 0],

# [0, 0, 3]], dtype=object)

`fetch_polytopes`

**Description:**
Fetches reflexive polytopes from the Kreuzer-Skarke database or from the
Schöller-Skarke database. The data is fetched from the websites
http://hep.itp.tuwien.ac.at/~kreuzer/CY/ and
http://rgc.itp.tuwien.ac.at/fourfolds/ respectively.

The Kreuzer-Skarke database does not store favorability data. Thus, when setting favorable to True or False it fetches additional polytopes so that after filtering by favorability it can saturate the requested limit. However, it may happen that fewer polytopes than requested are returned even though more exist. To verify that no more polytopes with the requested conditions exist one can increase the limit significantly and check if more polytopes are returned.

**Arguments:**

`h11`

*(int, optional)*: Specifies the Hodge number $h^{1,1}$ of the Calabi-Yau hypersurface.`h12`

*(int, optional)*: Specifies the Hodge number $h^{1,2}$ of the Calabi-Yau hypersurface.`h13`

*(int, optional)*: Specifies the Hodge number $h^{1,3}$ of the Calabi-Yau hypersurface.`h21`

*(int, optional)*: Specifies the Hodge number $h^{2,1}$ of the Calabi-Yau hypersurface. This is equivalent to the h12 parameter.`h22`

*(int, optional)*: Specifies the Hodge number $h^{2,2}$ of the Calabi-Yau hypersurface.`h31`

*(int, optional)*: Specifies the Hodge number $h^{3,1}$ of the Calabi-Yau hypersurface. This is equivalent to the h13 parameter.`chi`

*(int, optional)*: Specifies the Euler characteristic of the Calabi-Yau hypersurface.`lattice`

*(str, optional)*: Specifies the lattice on which the polytope is defined. Options are "N" and "M". Has to be specified if the Hodge numbers or the Euler characteristic is specified.`dim`

*(int, optional, default=4)*: The dimension of the polytope. The only available options are 4 and 5.`n_points`

*(int, optional)*: Specifies the number of lattice points of the desired polytopes.`n_vertices`

*(int, optional)*: Specifies the number of vertices of the desired polytopes.`n_dual_points`

*(int, optional)*: Specifies the number of points of the dual polytopes of the desired polytopes.`n_facets`

*(int, optional)*: Specifies the number of facets of the desired polytopes.`limit`

*(int, optional, default=1000)*: Specifies the maximum number of fetched polytopes.`timeout`

*(int, optional, default=60)*: Specifies the maximum number of seconds to wait for the server to return the data.`as_list`

*(bool, optional, default=False)*: Return the list of polytopes instead of a generator.`backend`

*(str, optional)*: A string that specifies the backend used for the`Polytope`

class.`dualize`

*(bool, optional, default=False)*: Flag that indicates whether to dualize all the polytopes before yielding them.`favorable`

*(bool, optional)*: Yield or return only polytopes that are favorable when set to True, or non-favorable when set to False. If not specified then it yields both favorable and non-favorable polytopes.

**Returns:**
*(generator or list)* A generator of `Polytope`

objects,
or the full list when `as_list`

is set to True.

**Example**

We fetch polytopes from the Kreuzer-Skarke and Schöller-Skarke databases with a few different parameters.

`from cytools import fetch_polytopes # Note that it can directly be imported from the root`

g = fetch_polytopes(h11=27, lattice="N") # Constructs a generator of polytopes

next(g)

# A 4-dimensional reflexive lattice polytope in ZZ^4

l = fetch_polytopes(h11=27, lattice="N", as_list=True, limit=100) # Constructs a generator of polytopes

print(f"Fetched {len(l)} polytopes")

# Fetched 100 polytopes

g_5d = fetch_polytopes(h11=1000, lattice="N", dim=5, limit=100) # Generator of 5D polytopes

next(g_5d)

# A 5-dimensional reflexive lattice polytope in ZZ^5

`filter_tensor_indices`

**Description:**
Selects a specific subset of indices from a tensor. The tensor is
reindexed so that indices are in the range 0..len(indices) with the
ordering specified by the input indices. This function can be used to
convert the tensor of intersection numbers to a given basis.

**Arguments:**

`tensor`

*(dict)*: The input symmetric sparse tensor of the form of a dictionary {(a,b,...,c):M_ab...c, ...}.`indices`

*(array_like)*: The list of indices that will be preserved.

**Returns:**
*(dict)* A dictionary describing a tensor in the same format as the input,
but only with the desired indices.

**Example**

We construct a simple tensor and then filter some of the indices. We also give a concrete example of when this is used for intersection numbers.

`from cytools.utils import filter_tensor_indices`

tensor = {(0,1):0, (1,1):1, (1,2):2, (1,3):3, (2,3):4}

filter_tensor_indices(tensor, [1,3])

# {(0, 0): 1, (0, 1): 3}

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()

v = t.get_toric_variety()

intnums_nobasis = v.intersection_numbers(in_basis=False)

intnums_inbasis = v.intersection_numbers(in_basis=True)

intnums_inbasis == filter_tensor_indices(intnums_nobasis, v.divisor_basis())

# True

`find_new_affinely_independent_points`

**Description:**
Finds new points that are affinely independent to the input list of
points. This is useful when one wants to turn a polytope that is not
full-dimensional into one that is, without affecting the structure of
the triangulations.

**Arguments:**

`points`

*(array_like)*: A list of points.

**Returns:**
*(numpy.ndarray)* A list of affinely independent points with respect to
the ones inputted.

**Example**

We construct a list of points and then find a set of affinely independent points.

`pts = [[1,0,1],[0,0,1],[0,1,1]]`

find_new_affinely_independent_points(pts)

array([[1, 0, 2]])

`float_to_fmpq`

**Description:**
Converts a float to an fmpq.

**Arguments:**

`c`

*(float)*: The input number.

**Returns:**
*(flint.fmpq)* The rational number that most reasonably approximates the
input.

**Example**

We convert a few floats to rational numbers.

`from cytools.utils import float_to_fmpq`

float_to_fmpq(0.1), float_to_fmpq(0.333333333333), float_to_fmpq(2.45)

# (1/10, 1/3, 49/20)

`fmpq_to_float`

**Description:**
Converts an fmpq to a float.

**Arguments:**

`c`

*(flint.fmpq)*: The input rational number.

**Returns:**
*(float)* The number as a float.

**Example**

We convert a few rational numbers to floats.

`from cytools.utils import fmpq_to_float`

from flint import fmpq

fmpq_to_float(fmpq(1,2)), fmpq_to_float(fmpq(1,3)), fmpq_to_float(fmpq(49,20))

# (0.5, 0.3333333333333333, 2.45)

`gcd_float`

**Description:**
Compute the greatest common (floating-point) divisor of a and b.

**Arguments:**

`a`

*(float)*: The first number.`b`

*(float)*: The second number.`tol`

*(float, optional, default=1e-5)*: The tolerance for rounding.

**Returns:**
*(float)* The gcd of a and b.

**Example**

We compute the gcd of two floats. This function is useful since the standard gcd functions raise an error for non-integer values.

`from cytools.utils import gcd_float`

gcd_float(0.2, 0.5) # Should be 0.1, but there are small rounding errors

# 0.09999999999999998

`gcd_list`

**Description:**
Compute the greatest common divisor of the elements in an array.

**Arguments:**

`arr`

*(array_like)*: A list of floating-point numbers.

**Returns:**
*(float)* The gcd of all the elements in the input list.

**Example**

We compute the gcd of a list of floats This function is useful since the standard gcd functions raise an error for non-integer values.

`from cytools.utils import gcd_list`

gcd_list([0.2, 0.5, 1.4, 6.05, 3.45]) # Should be 0.05, but there are small rounding errors

# 0.04999999999999882

`polytope_generator`

**Description:**
Reads polytopes from a file or a string. The polytopes can be specified
with their vertices, as used in the Kreuzer-Skarke database, or from a
weight system.

This function is not intended to be called by the end user. Instead, it is
used by the `read_polytopes`

and
`fetch_polytopes`

functions.

**Arguments:**

`input`

*(str)*: Specifies the name of the file to read or the string containing the polytopes.`input_type`

*(str, optional, default="file")*: Specifies whether to read from a file or from the input string. Options are "file" or "str".`format`

*(str, optional, default="ks")*: Specifies the format to read. The options are "ks", which is the format used in the KS database, and "ws", if the polytopes should be constructed from weight systems.`backend`

*(str, optional)*: A string that specifies the backend used for the`Polytope`

class.`dualize`

*(bool, optional, default=False)*: Flag that indicates whether to dualize all the polytopes before yielding them.`favorable`

*(bool, optional)*: Yield only polytopes that are favorable when set to True, or non-favorable when set to False. If not specified then it yields both favorable and non-favorable polytopes.`lattice`

*(str, optional)*: The lattice to use when checking favorability. This parameter is only required when`favorable`

is specified. Options are "M" and "N".`limit`

*(int, optional)*: Sets a maximum numbers of polytopes to yield.

**Returns:**
*(generator)* A generator of `Polytope`

objects.

**Example**

Since this function should not be used directly, we show an example of it
being used with the `read_polytopes`

function. We
take a string obtained from the KS database and read the polytope it
specifies.

`from cytools import read_polytopes # Note that it can directly be imported from the root`

poly_data = '''4 5 M:10 5 N:376 5 H:272,2 [540]

1 0 0 0 -9

0 1 0 0 -6

0 0 1 0 -1

0 0 0 1 -1

'''

read_polytopes(poly_data, input_type="str", as_list=True)

# [A 4-dimensional reflexive lattice polytope in ZZ^4]

`read_polytopes`

**Description:**
Reads polytopes from a file or a string. The polytopes can be specified
with their vertices, as used in the Kreuzer-Skarke database, or from a
weight system.

**Arguments:**

`input`

*(str)*: Specifies the name of the file to read or the string containing the polytopes.`input_type`

*(str, optional, default="file")*: Specifies whether to read from a file or from the input string. Options are "file" or "str".`format`

*(str, optional, default="ks")*: Specifies the format to read. The options are "ks", which is the format used in the KS database, and "ws", if the polytopes should be constructed from weight systems.`backend`

*(str, optional)*: A string that specifies the backend used for the`Polytope`

class.`as_list`

*(bool, optional, default=False)*: Return the list of polytopes instead of a generator.`dualize`

*(bool, optional, default=False)*: Flag that indicates whether to dualize all the polytopes before yielding them.`favorable`

*(bool, optional)*: Yield or return only polytopes that are favorable when set to True, or non-favorable when set to False. If not specified then it yields both favorable and non-favorable polytopes.`lattice`

*(str, optional)*: The lattice to use when checking favorability. This parameter is only required when`favorable`

is specified. Options are "M" and "N".`limit`

*(int, optional)*: Sets a maximum numbers of polytopes to yield.

**Returns:**
*(generator or list)* A generator of `Polytope`

objects,
or the full list when `as_list`

is set to True.

**Example**

We take a string obtained from the KS database and read the polytope it specifies.

`from cytools import read_polytopes # Note that it can directly be imported from the root`

poly_data = '''4 5 M:10 5 N:376 5 H:272,2 [540]

1 0 0 0 -9

0 1 0 0 -6

0 0 1 0 -1

0 0 0 1 -1

'''

read_polytopes(poly_data, input_type="str", as_list=True)

# [A 4-dimensional reflexive lattice polytope in ZZ^4]

`set_curve_basis`

**Description:**
Specifies a basis of curves of the toric variety, which in turn
specifies a dual basis of divisors. This can be done with a vector
specifying the indices of the dual prime toric divisors or as a matrix
with the rows being the basis curves, and the entries are the intersection
numbers with the prime toric divisors. Note that when using a vector it is
equivalent to using the same vector in the
`set_divisor_basis`

function.

This function should generally not be called directly by the user. Instead,
it is called by the `set_curve_basis`

function of the `ToricVariety`

class, or the
`set_curve_basis`

function of the `CalabiYau`

class.

Only integral bases are supported by CYTools, meaning that all toric curves must be able to be written as an integral linear combination of the basis curves.

**Arguments:**

`tv_or_cy`

*(ToricVariety or CalabiYau)*: The toric variety or Calabi-Yau whose basis will be set.`basis`

*(array_like)*: Vector or matrix specifying a basis. When a vector is used, the entries will be taken as indices of the standard basis of the dual to the lattice of prime toric divisors. When a matrix is used, the rows are taken as linear combinations of the aforementioned elements.`include_origin`

*(bool, optional, default=True)*: Whether to interpret the indexing specified by the input vector as including the origin.

**Returns:**
Nothing.

**Example**

This function is not intended to be directly used, but it is used in the following example. We consider a simple toric variety with two independent curves. We first find the default basis of curves it picks and then set a basis of our choice.

`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()

v = t.get_toric_variety()

v.curve_basis() # We haven't set any basis

# array([1, 6])

v.set_curve_basis([5,6]) # Here we set a basis

v.curve_basis() # We get the basis we set

# array([5, 6])

v.curve_basis(as_matrix=True) # We get the basis in matrix form

# array([[-18, 1, 9, 6, 1, 1, 0],

# [ -6, 0, 3, 2, 0, 0, 1]])

Note that when setting a curve basis in this way, the function behaves
exactly the same as `set_divisor_basis`

. For
a more advanced example involving generic bases these two functions
differ. An example can be found in the
experimental features section.

`set_divisor_basis`

**Description:**
Specifies a basis of divisors for the toric variety or Calabi-Yau manifold,
which in turn specifies a dual basis of curves. This can be done with a
vector specifying the indices of the prime toric divisors, or as a matrix
where each row is a linear combination of prime toric divisors.

This function should generally not be called directly by the user. Instead,
it is called by the `set_divisor_basis`

function of the `ToricVariety`

class, or the
`set_divisor_basis`

function of the `CalabiYau`

class.

Only integral bases are supported by CYTools, meaning that all prime toric divisors must be able to be written as an integral linear combination of the basis divisors.

**Arguments:**

`tv_or_cy`

*(ToricVariety or CalabiYau)*: The toric variety or Calabi-Yau whose basis will be set.`basis`

*(array_like)*: Vector or matrix specifying a basis. When a vector is used, the entries will be taken as the indices of points of the polytope or prime divisors of the toric variety. When a matrix is used, the rows are taken as linear combinations of the aforementioned divisors.`include_origin`

*(bool, optional, default=True)*: Whether to interpret the indexing specified by the input vector as including the origin.

**Returns:**
Nothing.

**Example**

This function is not intended to be directly used, but it is used in the following example. We consider a simple toric variety with two independent divisors. We first find the default basis it picks and then we set a basis of our choice.

`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()

v = t.get_toric_variety()

v.divisor_basis() # We haven't set any basis

# array([1, 6])

v.set_divisor_basis([5,6]) # Here we set a basis

v.divisor_basis() # We get the basis we set

# array([5, 6])

v.divisor_basis(as_matrix=True) # We get the basis in matrix form

# array([[0, 0, 0, 0, 0, 1, 0],

# [0, 0, 0, 0, 0, 0, 1]])

An example for more generic basis choices can be found in the experimental features section.

`solve_linear_system`

**Description:**
Solves the sparse linear system M*x+C=0.

**Arguments:**

`M`

*(scipy.sparse.csr_matrix)*: A scipy csr_matrix.`C`

*(array_like)*: A vector of floats.`backend`

*(str, optional, default="all")*: The sparse linear solver to use. Options are "all", "sksparse" and "scipy". When set to "all" it tries all available backends.`check`

*(bool, optional, default=True)*: Whether to explicitly check the solution to the linear system.`backend_error_tol`

*(float, optional, default=1e-4)*: Error tolerance for the solution of the linear system.`verbose`

*(int, optional, default=0)*: The verbosity level.- verbose = 0: Do not print anything.
- verbose = 1: Print warnings when backends fail.

**Returns:**
*(numpy.ndarray)* Floating-point solution to the linear system.

**Example**

We solve a very simple linear equation.

`from cytools.utils import to_sparse, solve_linear_system`

id_array = [[0,0,1],[1,1,1],[2,2,1],[3,3,1],[4,4,1]]

M = to_sparse(id_array, sparse_type="csr")

C = [1,1,1,1,1]

solve_linear_system(M, C)

# array([-1., -1., -1., -1., -1.])

`symmetric_dense_to_sparse`

**Description:**
Converts a dense symmetric tensor to a sparse tensor of the form
{(a,b,...,c):M_ab...c,...}. Optionally, it applies a basis transformation.

**Arguments:**

`tensor`

*(array_like)*: A dense symmetric tensor.`basis`

*(array_like, optional)*: A matrix where the rows are the basis elements.

**Returns:**
*(dict)* A sparse tensor of the form {(a,b,...,c):M_ab...c,...}.

**Example**

We construct a simple tensor and then convert it to a dense array. We
consider the same example as for the
`filter_tensor_indices`

function, but now we
have to specify the basis in matrix form.

`from cytools.utils import symmetric_dense_to_sparse`

tensor = [[1,2],[2,3]]

symmetric_dense_to_sparse(tensor)

# {(0, 0): 1, (0, 1): 2, (1, 1): 3}

`symmetric_sparse_to_dense`

**Description:**
Converts a symmetric sparse tensor of the form {(a,b,...,c):M_ab...c, ...}
to a dense tensor. Optionally, it then applies a basis transformation.

**Arguments:**

`tensor`

*(dict)*: A sparse tensor of the form {(a,b,...,c):M_ab...c, ...}.`basis`

*(array_like, optional)*: A matrix where the rows are the basis elements.

**Returns:**
*(numpy.ndarray)* A dense tensor.

**Example**

We construct a simple tensor and then convert it to a dense array. We
consider the same example as for the
`filter_tensor_indices`

function, but now we
have to specify the basis in matrix form.

`from cytools.utils import symmetric_sparse_to_dense_in_basis`

tensor = {(0,1):0, (1,1):1, (1,2):2, (1,3):3, (2,3):4}

basis = [[0,1,0,0],[0,0,0,1]]

symmetric_sparse_to_dense(tensor, basis)

# array([[1, 3],

# [3, 0]])

`to_sparse`

**Description:**
Converts an matrix of the form [[a,b,M_ab],...] or a dictionary of the
form [(a,b):M_ab, ...] to a dok_matrix or to a csr_matrix.

**Arguments:**

`rule_arr_in`

*(dict or array_like)*: A list of the form [[a,b,M_ab],...] or a dictionary of the form [(a,b):M_ab,...].`sparse_type`

*(str, optional, default="dok")*: The type of sparse matrix to return. The options are "dok" and "csr".

**Returns:**
*(scipy.sparse.dok_matrix or scipy.sparse.csr_matrix)* The sparse matrix in
dok_matrix or csr_matrix format.

**Example**

We convert the 5x5 identity matrix into a sparse matrix.

`from cytools.utils import to_sparse`

id_array = [[0,0,1],[1,1,1],[2,2,1],[3,3,1],[4,4,1]]

to_sparse(id_array)

# <5x5 sparse matrix of type '<class 'numpy.float64'>'

# with 5 stored elements in Dictionary Of Keys format>

to_sparse(id_array, sparse_type="csr")

# <5x5 sparse matrix of type '<class 'numpy.float64'>'

# with 5 stored elements in Compressed Sparse Row format>

## Functions in `cytools.config`

`check_mosek_license`

**Description:**
Checks if the Mosek license is valid. If it is not, it prints the reason.

**Arguments:**
None.

**Returns:**
Nothing.

**Example**

The Mosek license should be automatically checked, but it can also be checked as follows.

`import cytools`

cytools.config.check_mosek_license()

# It will print an error if it is not working, and if nothing is printed then it is working correctly

`enable_experimental_features`

**Description:**
Enables the experimental features of CYTools. For more information read the
experimental features page.

**Arguments:**
None.

**Returns:**
Nothing.

**Example**

We enable the experimental features.

`import cytools`

cytools.config.enable_experimental_features()

`set_mosek_path`

**Description:**
Sets a custom path to the Mosek license. This is useful if the Docker image
was built without the license, but it is stored somewhere in your computer.
The license will be checked after the new path is set.

**Arguments:**

`path`

*(str)*: The path to the Mosek license. Note that the mounted directory on the Docker container is`/home/cytools/mounted_volume/`

.

**Returns:**
Nothing.

**Example**

We set the path to the original one for illustation purposes, and show how to set the path to a directory on the host computer.

`import cytools`

cytools.config.set_mosek_path("/opt/cytools/external/mosek/mosek.lic") # Original path

cytools.config.set_mosek_path("/home/cytools/mounted_volume/[path-to-license]") # If not in the Docker image

## Functions in `cytools.__init__`

`check_for_updates`

**Description:**
Checks for updates of CYTools. It prints a message if a new version is
avaiable, and displays a warning if the current version has a serious bug.

**Arguments:**
None.

**Returns:**
Nothing.

**Example**

We check for updates of CYTools. This is done automatically, so there is usually no need to do this.

`import cytools`

cytools.check_for_updates()