Table of Contents

application common

This artificial application gathers functionality shared by many “real” applications. While most users can probably do without looking into this, you may find some useful functions here.

Objects

Functions

Arithmetic

These are functions that perform arithmetic computations.


ceil(Rational a)

The ceiling function. Returns the smallest integral number not smaller than a.

Parameters:
Returns:

denominator(Rational a)

Returns the denominator of a in a reduced representation.

Parameters:
Returns:
denominator(RationalFunction f)

Returns the denominator of a RationalFunction f.

Parameters:
Returns:
denominator(PuiseuxFraction f)

Returns the denominator of a PuiseuxFraction f.

Parameters:
Returns:

div(Scalar a, Scalar b)

Compute the quotient and remainder of a and b in one operation.

Parameters:

Scalar a

Scalar b

Returns:
Div<Scalar>
Example:

 > $d = div(10,3);
 > print $d->quot;
 3
 > print $d->rem;
 1


div_exact(Integer a, Integer b)

Computes the ratio of two given integral numbers under the assumption that the dividend is a multiple of the divisor.

Parameters:

Integer b: a divisor of a

Returns:
Example:

 > print div_exact(10,5);
 2


ext_gcd(Scalar a, Scalar b)

Compute the greatest common divisor of two numbers (a,b) and accompanying co-factors.

Parameters:

Scalar a

Scalar b

Returns:
Example:

 > $GCD = ext_gcd(15,6);

The GCD of the numbers can then be accessed like this:

 > print $GCD->g;
 3

The ExtGCD type also stores the Bezout coefficients (thus integers p and q such that g=a*p+b*q)…

 > print $GCD->p;
 1
 > print $GCD->q;
 -2

…and the quotients k1 of a and k2 of b by g.

 > print $GCD->k1;
 5
 > print $GCD->k2;
 2


fac(Int n)

Computes the factorial n! = n·(n-1)·(n-2)·…·2·1.

Parameters:

Int n: >=0

Returns:

floor(Rational a)

The floor function. Returns the smallest integral number not larger than a.

Parameters:
Returns:
Example:

 > print floor(1.8);
 1


gcd(Int a, Int b)

Computes the greatest common divisor of two integers.

Parameters:

Int a

Int b

Returns:
Int
Example:

 > print gcd(6,9);
 3
gcd(Vector<Scalar> v)

Compute the greatest common divisor of the elements of the given vector.

Parameters:

Vector<Scalar> v

Returns:
Scalar
Example:
 > $v = new Vector<Int>(3,6,9);
 > print gcd($v);
 3
gcd(UniPolynomial p, UniPolynomial q)

Returns the greatest common divisor of two univariate polynomials.

Parameters:
Returns:
Example:

We create two UniPolynomials with said coefficient and exponent type:

 > $p = new UniPolynomial<Rational,Int>([2,2],[3,2]);
 > $q = new UniPolynomial<Rational,Int>([6,4],[4,2]);

Printing them reveals what the constructor does:

 > print $p;
 2*x^3 + 2*x^2
 > print $q;
 6*x^4 + 4*x^2

Now we can calculate their gcd:

 > print gcd($p,$q);
 x^2


get_var_names()

Get the current list of variable names used for pretty printing and string parsing of the given polynomial class

Returns:

is_one(Scalar s)

Compare with the one (1) value of the corresponding data type.

Parameters:

Scalar s

Returns:

is_zero(Scalar s)

Compare with the zero (0) value of the corresponding data type.

Parameters:

Scalar s

Returns:

isfinite(Scalar a)

Check whether the given number has a finite value.

Parameters:

Scalar a

Returns:
Example:

 > print isfinite('inf');
 false
 > print isfinite(23);
 true


isinf(Scalar a)

Check whether the given number has an infinite value. Return -1/+1 for infinity and 0 for all finite values.

Parameters:

Scalar a

Returns:
Int
Example:

 > print isinf('inf');
 1
 > print isinf(23);
 0


lcm(Int a, Int b)

Computes the least common multiple of two integers.

Parameters:

Int a

Int b

Returns:
Int
Example:

 > print lcm(6,9);
 18
lcm(Vector<Scalar> v)

Compute the least common multiple of the elements of the given vector.

Parameters:

Vector<Scalar> v

Returns:
Scalar
Example:
 > $v = new Vector<Integer>(1,3,6,9);
 > print lcm($v);
 18


local_var_names(String names …)

Set the list of variable names for given polynomial class temporarily. The existing name list or the default scheme is restored at the end of the current user cycle, similarly to prefer_now.

Parameters:

String names …: variable names, see set_var_names.


monomials<Coefficient, Exponent>(Int n)

Create degree one monomials of the desired polynomial type.

Type Parameters:

Coefficient: The polynomial coefficient type. Rational by default.

Exponent: The exponent type. Int by default.

Parameters:

Int n: The number of variables

Returns:
UniPolynomial<Coefficient,Exponent>

numerator(Rational a)

Returns the numerator of a in a reduced representation.

Parameters:
Returns:
numerator(RationalFunction f)

Returns the numerator of a RationalFunction f.

Parameters:
Returns:
numerator(PuiseuxFraction f)

Returns the numerator of a PuiseuxFraction f.

Parameters:
Returns:

set_var_names(String names …)

Set the list of variable names used for pretty printing and string parsing of the given polynomial class When the number of variables in a polynomial is greater than the size of the name list, the excess variable names are produced from a template “${last_var_name}_{EXCESS}”, where EXCESS starts at 0 for the variable corresponding to the last name in the list. If the last name already has a form “{Name}_{Number}”, the following variables are enumerated starting from that Number plus 1. The default naming scheme consists of a single letter “x”, “y”, “z”, “u”, “v”, or “w” chosen according to the nesting depth of polynomial types in the coefficient type. That is, variables of simple polynomials (those with pure numerical coefficients) are named x_0, x_1, …, variables of polynomials with simple polynomial coefficients are named y_0, y_1, etc.

Parameters:

String names …: variable names; may also be bundled in an array an empty list resets to the default naming scheme


sum_of_square_roots_naive(Array<Rational> input_array)

Make a naive attempt to sum the square roots of the entries of the input array.

Parameters:

Array<Rational> input_array: a list of rational numbers (other coefficents are not implemented).

Returns:
Example:

To obtain sqrt{3/4} + sqrt{245}, type

 > print sum_of_square_roots_naive(new Array<Rational>([3/4, 245]));
 {(3 1/2) (5 7)}

This output represents sqrt{3}/2 + 7 sqrt{5}. If you are not satisfied with the result, please use a symbolic algebra package.


Combinatorics

Combinatorial functions.


all_permutations(Int n)

Returns a list of all permutations of the set {0…n-1} as a perl-array

Parameters:

Int n

Returns:
Example:

 > print all_permutations(3);
 0 1 2
 1 0 2
 2 0 1
 0 2 1
 1 2 0
 2 1 0


are_permuted(Array a, Array b)

Determine whether two arrays a and b are permuted copies of each other.

Parameters:

Array a

Array b

Returns:
Example:

 > print are_permuted([1,8,3,4],[3,8,4,1]);
 true


binomial(Int n, Int k)

Computes the binomial coefficient n choose k. Negative values of n (and k) are supported.

Parameters:

Int n

Int k

Returns:
Int
Example:

Print 6 choose 4 like this:

 > print binomial(6,4);
 15


find_permutation(Array a, Array b)

Returns the permutation that maps a to b.

Parameters:

Array a

Array b

Returns:
Example:

 > $p = find_permutation([1,8,3,4],[3,8,4,1]);
 > print $p;
 2 1 3 0


n_fixed_points(Array<Int> p)

Returns the number of fixed points of the permutation given by p.

Parameters:

Array<Int> p

Returns:
Int
Example:

 > print n_fixed_points([1,0,2,4,3]);
 1


permutation_cycle_lengths(Array<Int> p)

Returns the sorted cycle lengths of a permutation

Parameters:

Array<Int> p

Returns:
Example:

 > print permutation_cycle_lengths(new Array<Int>([1,2,0,4,3]));
 2 3


permutation_cycles(Array<Int> p)

Returns the cycles of a permutation given by p.

Parameters:

Array<Int> p

Returns:
ARRAY
Example:

 > print permutation_cycles([1,0,3,2]);
 {0 1}{2 3}


permutation_matrix<Scalar>(Array<Int> p)

Returns the permutation matrix of the permutation given by p.

Type Parameters:

Scalar: default: Int

Parameters:

Array<Int> p

Returns:
Matrix<Scalar>
Example:

The following prints the permutation matrix in sparse representation.

 > print permutation_matrix([1,0,3,2]);
 (4) (1 1)
 (4) (0 1)
 (4) (3 1)
 (4) (2 1)


permutation_order(Array<Int> p)

Returns the order of a permutation

Parameters:

Array<Int> p

Returns:
Int
Example:

 > print permutation_order(new Array<Int>([1,2,0,4,3]));
 6


permutation_sign(Array<Int> p)

Returns the sign of the permutation given by p.

Parameters:

Array<Int> p

Returns:
Int
Example:

 > print permutation_sign([1,0,3,2]);
 1


Data Conversion

This contains functions for data conversions and type casts.


cast<Target>(Core::Object object)

Change the type of the polymake object to one of its base types (aka ancestor in the inheritance hierarchy). The object loses all properties that are unknown in the target type.

Type Parameters:

Target: the desired new type

Parameters:

Core::Object object: to be modified

Returns:

cols

UNDOCUMENTED

cols(Matrix A)

Returns an array containing the columns of A.

Parameters:

Matrix A

Returns:
Example:

The following saves the columns of the vertex matrix of a square in the variable $w and then prints its contents using a foreach loop and concatenating each entry with the string “ ”.

 > $w = cols(polytope::cube(2)->VERTICES);
 > foreach( @$w ){
 > print @{$_}, "  ";
 > }
 1111  -11-11  -1-111


concat_rows(Matrix A)

Concatenates the rows of A.

Parameters:

Matrix A

Returns:
Example:

Make a vector out of the rows of the vertex matrix of a cube:

 > $v = concat_rows(polytope::cube(2)->VERTICES);
 > print $v;
 1 -1 -1 1 1 -1 1 -1 1 1 1 1
Example:

For a sparse matrix, the resulting vector is sparse, too.

 > $vs = concat_rows(unit_matrix(3));
 > print $vs;
 (9) (0 1) (4 1) (8 1)


convert_to<Target>(Scalar s)

Explicit conversion to a different scalar type.

Type Parameters:

Target

Parameters:

Scalar s

Returns:
Target
convert_to<Target>(Vector v)

Explicit conversion to a different element type.

Type Parameters:

Target

Parameters:

Vector v

Returns:
Vector<Target>
Example:

 > $v = new Vector<Rational>(1/2,2/3,3/4);
 > $vf = convert_to<Float>($v);
 > print $vf;
 0.5 0.6666666667 0.75
convert_to<Target>(Matrix m)

Explicit conversion to a different element type.

Type Parameters:

Target

Parameters:

Matrix m

Returns:
Matrix<Target>
Example:
 > $M = new Matrix<Rational>([1/2,2],[3,2/3]);
 > $Mf = convert_to<Float>($M);
 > print $Mf;
 0.5 2
 3 0.6666666667
convert_to<Target>(Polynomial m)

Explicit conversion to a different coefficient type.

Type Parameters:

Target

Parameters:
Returns:
Polynomial<Target>
convert_to<Target>(UniPolynomial m)

Explicit conversion to a different coefficient type.

Type Parameters:

Target

Parameters:
Returns:
UniPolynomial<Target>


dense(Vector v)

Return the input vector (which is already in dense form).

Parameters:

Vector v

Returns:
dense(Matrix m)

Return the input matrix (which is already in dense form).

Parameters:

Matrix m

Returns:
dense<Element>(SparseVector<Element> v)

Convert to an equivalent dense vector of the same element type.

Type Parameters:

Element

Parameters:

SparseVector<Element> v

Returns:
Vector<Element>
dense<Element>(SparseMatrix<Element> m)

Convert to an equivalent dense matrix of the same element type.

Type Parameters:

Element

Parameters:

SparseMatrix<Element> m

Returns:
Matrix<Element>
dense(IncidenceMatrix m)

Convert to a dense 0/1 matrix.

Parameters:
Returns:
dense(Set s, Int dim)

Convert to a dense 0/1 vector of a given dimension.

Parameters:

Set s

Int dim

Returns:

index_matrix(SparseMatrix m)

Get the positions of non-zero entries of a sparse matrix.

Parameters:
Returns:
Example:

 > $S = new SparseMatrix([1,2,0,0,0,0],[0,0,5,0,0,32]);
 > print index_matrix($S);
 {0 1}
 {2 5}


indices(SparseVector v)

Get the positions of non-zero entries of a sparse vector.

Parameters:
Returns:
Set<Int>
Example:

 > $v = new SparseVector(0,1,1,0,0,0,2,0,3);
 > print indices($v);
 {1 2 6 8}


lex_ordered(FacetList f)

Visit the facets of f sorted lexicographically.

Parameters:
Returns:
Example:

 > $f = new FacetList(polytope::cube(2)->VERTICES_IN_FACETS);
 > print lex_ordered($f);
 {{0 1} {0 2} {1 3} {2 3}}


repeat_col(Vector v, Int i)

Create a Matrix by repeating the given Vector as cols.

Parameters:

Vector v

Int i

Example:

 > $v = new Vector(23,42,666);
 > $M = repeat_col($v,3);
 > print $M;
 23 23 23
 42 42 42
 666 666 666


repeat_row(Vector v, Int i)

Create a Matrix by repeating the given Vector as rows.

Parameters:

Vector v

Int i

Example:

 > $v = new Vector(23,42,666);
 > $M = repeat_row($v,3);
 > print $M;
 23 42 666
 23 42 666
 23 42 666


rows

UNDOCUMENTED

rows(Matrix A)

Returns an array containing the rows of A.

Parameters:

Matrix A

Returns:
Example:

The following saves the rows of the vertex matrix of a square in the variable $w and then prints its contents using a foreach loop and concatenating each entry with the string “ ”.

 > $w = rows(polytope::cube(2)->VERTICES);
 > foreach( @$w ){
 > print @{$_}, "  ";
 > }
 1-1-1  11-1  1-11  111


support(Vector v)

Get the positions of non-zero entries of a vector.

Parameters:

Vector v

Returns:
Set<Int>
Example:

 > print support(new Vector(0,23,0,0,23,0,23,0,0,23));
 {1 4 6 9}


toMatrix<Scalar>(IncidenceMatrix A)

Convert an IncidenceMatrix to a SparseMatrix.

Type Parameters:

Scalar

Parameters:
Returns:
SparseMatrix<Scalar>
Example:

 > $M = toMatrix<Int>(polytope::cube(2)->VERTICES_IN_FACETS);
 > print $M->type->full_name;
 SparseMatrix<Int, NonSymmetric>


toTropicalPolynomial(String s, String vars)

This converts a string into a tropical polynomial. The syntax for the string is as follows: It is of the form “min(…)” or “max(…)” or “min{…}” or “max{…}”, where … is a comma-separated list of sums of the form “a + bx + c + dy + …”, where a,c are rational numbers, b,d are Ints and x,y are variables. Such a sum can contain several such terms for the same variable and they need not be in any order. Any text that starts with a letter and does not contain any of +-*,(){} or whitespace can be a variable. A term in a sum can be of the form “3x”, “3*x”, but “x3”will be interpreted as 1 * “x3”. Coefficients should not contain letters and there is no evaluation of arithmetic, i.e. “(2+4)*x” does not work (though “2x+4x” would be fine). In fact, further brackets should only be used (but are not necessary!) for single coefficienst, e.g. “(-3)*x”. Warning: The parser will remove all brackets before parsing the individual sums. If no further arguments are given, the function will take the number of occuring variables as total number of variables and create a ring for the result. The variables will be sorted alphabetically.

Parameters:

String s: The string to be parsed

String vars: Optional list of variables. If this is given, all variables used in s must match one of the variables in this list.

Returns:

toVector<Scalar>(Set S, Int d)

Create a sparse vector having 1's at positions contained in the given set

Type Parameters:

Scalar: type of apparent 1's

Parameters:

Set S

Int d: dimension of the result

Returns:
SparseVector<Scalar>

vector2col(Vector v)

Convert a Vector to a Matrix with a single column.

Parameters:

Vector v

Returns:
Example:

This converts a vector into a column and prints it and its type:

 > $v = new Vector([1,2,3,4]);
 > $V = vector2col($v);
 > print $V;
 1
 2
 3
 4
 > print $V->type->full_name;
 Matrix<Rational, NonSymmetric>


vector2row(Vector v)

Convert a Vector to a Matrix with a single row.

Parameters:

Vector v

Returns:
Example:

This converts a vector into a row and prints it and its type:

 > $v = new Vector([1,2,3,4]);
 > $V = vector2row($v);
 > print $V;
 1 2 3 4
 > print $V->type->full_name;
 Matrix<Rational, NonSymmetric>


Database

Here you can find the functions to access the polymake database.


db_count(HASH query)

Returns the number of objects in the database db in collection that match the query.

Parameters:

HASH query

Options:

String db: name of the database, see here or db_info for available databases

String collection: name of the collection, see here or db_info for available collections

Bool local: set to 1 if you want to use a local database (on localhost), default 0

String username: Some databases might have access control.

String password: Some databases might have access control.

MongoClient client

Returns:
Int

db_cursor(HASH query)

Returns a cursor on the entries for the database db in collection that match the query.

Parameters:

HASH query: database query

Options:

String db: database name

String collection: collection name

Int skip: skip the first elements, default: 0

Int limit: limit the number of objects that will be returned (default: no limit)

HASH sort_by: sorting of the entries, default by _id

String username

String password

MongoClient client

Bool local: set to 1 if you want to use a local database (on localhost), default 0

Returns:

db_get_list_col_for_db()

Returns a list of available collections in a database.

Options:

String db: name of the database

Bool local: set to 1 if you want to use a local database (on localhost), default 0

String username: necessary if reading a database with access control

Returns:

db_get_list_db()

Returns a list of available databases.

Options:

Bool local: set to 1 if you want to use a local database (on localhost), default 0

String username: necessary if reading a database with access control

Returns:

db_get_list_db_col()

Returns a list of available databases and collections (in the form db.collection).

Options:

String db: name of the database, default: all available databases

String collection: name of the collection, default: all available collections

Bool local: set to 1 if you want to use a local database (on localhost), default 0

String username: necessary if reading a database with access control

Returns:

db_ids(HASH query)

Returns the IDs of all objects in the database db in collection that match the query. This is only recommended for a reasonably small number of matching objects. If you expect many such objects you should instead construct a DBCursor.

Parameters:

HASH query

Options:

String db: name of the database, see here or db_info for available databases

String collection: name of the collection, see here or db_info for available collections

Bool local: set to 1 if you want to use a local database (on localhost), default 0

Int limit: limit the number of objects that will be returned (default: no limit)

HASH sort_by: specify a sorting order

Int skip: skip the first elements, default: 0

String username: Some databases might have access control.

String password: Some databases might have access control.

MongoClient client

Returns:

db_info()

Print information about available databases and collections.

Options:

String db: name of the database, default: all available databases

String collection: name of the collection, default: all available collections

Bool local: set to 1 if you want to use a local database (on localhost), default 0

String username: necessary if reading a database with access control


db_metadata(Core::Object p)

Retrieve the metadata of an object

Parameters:

Core::Object p: the polyDB object

Returns:
HASH

db_print_metadata(Core::Object p)

print the metadata of an object

Parameters:

Core::Object p: the polyDB object


db_query(HASH query)

Returns all objects in the database db in collection that match the query. This is only recommended for a reasonably small number of matching objects. If you expect many such objects you should instead use a database cursor.

Parameters:

HASH query

Options:

String db: name of the database, see here or db_info for available databases

String collection: name of the collection, see here or db_info for available collections

Bool local: set to 1 if you want to use a local database (on localhost), default 0

Int limit: limit the number of objects that will be returned (default: no limit)

String username: Some databases might have access control.

String password: Some databases might have access control.

MongoClient client

Int skip: skip the first elements, default: 0

HASH sort_by: specify a sorting order

Returns:

db_searchable_fields(String db, String collection)

Return the list of property names that can be searched in the database for a given database db, collection col and optional template key.

Parameters:

String db: name of the database, see here or db_info for available databases

String collection: name of the collection, see here or db_info for available collections

Options:

Bool local: set to 1 if you want to use a local database (on localhost), default 0

Returns:

db_write_collection_info()

Add documentation for a collection You need write access for this.

Options:

String db: name of the database the description applies to

String collection: name of the collection the description applies to

Bool local: set to 1 if you want to use a local database (on localhost), default 0

Bool replace: whether an existing documentation should be updated or replaced

String file: a file with the documentation in json format, only one of file and documentation is allowed

HASH documentation: a perl hash with the documentation, only one of documentation and file is allowed

String username

String password

String polydb_version: version number

Bool verbose: verbose mode


db_write_db_info(String db)

Add a db documentation. You need write access for this.

Parameters:

String db: name of the database the description applies to

Options:

Bool local: set to 1 if you want to use a local database (on localhost), default 0

Bool replace: whether an existing documentation should be updated or replaced

String file: a file with the documentation in json format, only one of file and documentation is allowed

HASH documentation: a perl hash with the documentation, only one of documentation and file is allowed

String username

String password

String polydb_version: version number

Bool verbose: verbose mode


Database Admin

These are administrative functions. You need admin access to the database for these. This category also contains functions that I want to hide from the public because they are not yet completely presentable.


db_set_type_information()

Set or update type (and template) information for collection col in the database db. Note that you need write access to the type database for this.

Options:

String db: database name

String col: collection name

String key: the key of the type information

Bool replace: type information for this database, collection and key already exists and should be replaced

String file: a filename containing the type information as json document (only one of file and type_information allowed)

HASH type_information: the type information as per hash (only one of file and type_information allowed)

String username

String password

String polyDB_version: the version of polyDB this type information applies to

Bool verbose


Database Write Access

These are the functions to insert and update objects. You need write access to the database for these.


db_insert(Core::Object obj)

Adds an object obj to the collection col in the database db. Note that you need write access to the database for this.

Parameters:
Options:

String db: name of the database

String collection: name of the collection

String id: unique identifier, this is set to the name of the object, a different name should only be used in exceptional cases. This option is only valid if a single object is added.

String contributor: set the contributor

Bool local: set to 1 if you want to use a local database (on localhost), default 0

String username

String password

Bool use_type_information: set to 1 to match properties with a template object

HASH type_information: object template specifying the properties to store

String type_information_key: template name to load from the database

Bool nonew: set to 1 if you don't want to compute missing properties but only delete surplus ones (only takes effect if use_type_info is also set to 1)

Bool keep_all_props: keep all properties present in the polymake object in the stored xml. Does not effect representation in the db. For this, provide a type information without a property mask

Bool noinsert: dont insert anything, just try evaluate the template

MongoClient client

Returns:

db_remove(String id)

Removes the object with a given id from the collection col in the database db. Note that you need write access to the database for this.

Parameters:

String id

Options:

String db: name of the database

String collection: name of the collection

Bool local: set to 1 if you want to use a local database (on localhost), default 0

String username

String password

MongoClient client

Returns:

Formatting

Functions for pretty printing, labels or latex output of polymake types.


labeled(Vector data, Array<String> elem_labels)

Prepares a vector for printing, prepends each element with a label and a colon.

Parameters:

Vector data: to be printed

Array<String> elem_labels: optional labels for elements; if data is a Set, or similar, each element will be replaced by its label.

Returns:
Example:

 > $v = new Vector(0,1,2);
 > print labeled($v,["zeroth","first","second"]);
 zeroth:0 first:1 second:2


latex(Matrix data, Array<String> elem_labels)

LaTeX output of a matrix.

Parameters:

Matrix data: to be printed

Array<String> elem_labels: optional labels for elements; if data is an IncidenceMatrix, common, or similar, each element will be replaced by its label.

Returns:

numbered(Vector data)

Equivalent to labeled with omitted elem_labels argument.

Parameters:

Vector data: to be printed

Returns:
Example:

 > $data = new Vector(23,42,666);
 > print numbered($data);
 0:23 1:42 2:666


print_constraints(Matrix<Scalar> M)

Write the rows of a matrix M as inequalities (equations=0) or equations (equations=1) in a readable way. It is possible to specify labels for the coordinates via an optional array coord_labels.

Parameters:

Matrix<Scalar> M: the matrix whose rows are to be written

Options:

Array<String> coord_labels: changes the labels of the coordinates

Array<String> row_labels: changes the labels of the rows

Bool homogeneous: false if the first coordinate should be interpreted as right hand side

Bool equations: true if the rows represent equations instead of inequalities

Example:

 > $M = new Matrix([1,2,3],[4,5,23]);
 > print_constraints($M,equations=>1);
 0: 2 x1 + 3 x2 = -1
 1: 5 x1 + 23 x2 = -4


rows_labeled(Matrix data, Array<String> row_labels, Array<String> elem_labels)

Prepares a matrix for printing, prepends each row with a label and a colon.

Parameters:

Matrix data: to be printed

Array<String> row_labels: labels for the rows

Array<String> elem_labels: optional labels for elements; if data is an IncidenceMatrix, common, or similar, each element will be replaced by its label.

Returns:
Example:

 > print rows_labeled(polytope::cube(2)->VERTICES,['a','b','c','d']);
 a:1 -1 -1
 b:1 1 -1
 c:1 -1 1
 d:1 1 1
rows_labeled(Graph graph, Array<String> elem_labels)

Like above, but specialized for Graphs (defined for convenience: a PTL Graph is not a container)

Parameters:

Graph graph: to be printed

Array<String> elem_labels: labels for the elements

Returns:
Example:
 > print rows_labeled(graph::cycle_graph(4)->ADJACENCY, ['a','b','c','d']);
 a:b d
 b:a c
 c:b d
 d:a c


rows_numbered(Matrix data)

Equivalent to rows_labeled with omitted row_labels argument. Formerly called “numbered”.

Parameters:

Matrix data: to be printed

Returns:
Example:

 > print rows_numbered(polytope::cube(2)->VERTICES);
 0:1 -1 -1
 1:1 1 -1
 2:1 -1 1
 3:1 1 1


Graph Operations

Operations on graphs.


adjacency_matrix(Graph graph)

Returns the adjacency matrix of graph nodes. For a normal graph, it will be a kind of IncidenceMatrix, for multigraph, it will be a common, with entries encoding the number of parallel edges between two nodes.

Parameters:

Graph graph

Returns:

edges(Graph graph)

Returns the sequence of all edges of a graph. The edges will appear in ascending order of their tail and head nodes. In the Undirected case, the edges will appear once, ordered by the larger index of their incident nodes.

Parameters:

Graph graph

Returns:

induced_subgraph(Graph graph, Set set)

Creates an induced subgraph for the given subset of nodes.

Parameters:

Graph graph

Set set: indices of selected nodes

Returns:
Example:

 > $g = new props::Graph(graph::cycle_graph(5)->ADJACENCY);
 > $s1 = new Set(1,2,3);
 > print induced_subgraph($g,$s1);
 (5)
 (1 {2})
 (2 {1 3})
 (3 {2})


node_edge_incidences<Coord>(Graph graph)

Returns the node-edge incidence matrix of a graph.

Type Parameters:

Coord: coordinate type for the resulting matrix, default: Int

Parameters:

Graph graph

Returns:
SparseMatrix<Coord>
Example:

 > print node_edge_incidences(graph::cycle_graph(5)->ADJACENCY);
 (5) (0 1) (3 1)
 (5) (0 1) (1 1)
 (5) (1 1) (2 1)
 (5) (2 1) (4 1)
 (5) (3 1) (4 1)


nodes(Graph graph)

Returns the sequence of all valid nodes of a graph.

Parameters:

Graph graph

Returns:
Set<Int>
Example:

 > print nodes(graph::cycle_graph(5)->ADJACENCY);
 {0 1 2 3 4}


Lattice Tools

Functions for lattice related computations.


eliminate_denominators(Vector v)

Scale a vector with the least common multiple of the denominators of its coordinates.

Parameters:

Vector v

Returns:
Example:

 > $v = new Vector(1/2,1/3,1/4,1/5);
 > $ve = eliminate_denominators($v);
 > print $ve;
 30 20 15 12


eliminate_denominators_entire(Matrix v)

Scales entire matrix with the least common multiple of the denominators of its coordinates.

Parameters:

Matrix v

Returns:
Example:

 > $M = new Matrix([1/2,1/3],[1/5,7],[1/4,4/3]);
 > $Me = eliminate_denominators_entire($M);
 > print $Me;
 30 20
 12 420
 15 80


eliminate_denominators_entire_affine(Matrix v)

Scales entire matrix with the least common multiple of the denominators of its coordinates (ignore first column).

Parameters:

Matrix v

Returns:
Example:

 > $M = new Matrix([1,1/2,1/3],[1,1/5,7],[1,1/4,4/3]);
 > $Me = eliminate_denominators_entire_affine($M);
 > print $Me;
 1 30 20
 1 12 420
 1 15 80


eliminate_denominators_in_rows(Matrix M)

Scale a matrix row-wise with the least common multiple of the denominators of its coordinates.

Parameters:

Matrix M

Returns:
Example:

 > $M = new Matrix([1/2,1/3],[1/5,7],[1/4,4/3]);
 > $Me = eliminate_denominators_in_rows($M);
 > print $Me;
 3 2
 1 35
 3 16


is_integral(Vector v)

Checks whether all coordinates of a rational vector are integral.

Parameters:

Vector v

Returns:
Example:

This rational vector has only integral entries:

 > $v = new Vector<Rational>(1,2,3,4);

polytope > print is_integral($v);

But if we append 1/2, it isn't anymore:

 > print is_integral($v|1/2);
 false
is_integral(Matrix m)

Checks whether all coordinates of a rational matrix are integral.

Parameters:

Matrix m

Returns:
Example:

This rational matrix has only integral entries:

 > $m = new Matrix<Rational>([1,2],[3,4]);
 > print is_integral($m);
 true

But if we multiply it with 1/2, that is not the case anymore.

 > print is_integral(1/2 * $m);
 false


primitive(Vector v)

Scales the vector to a primitive integral vector.

Parameters:

Vector v

Returns:
Example:

 > print primitive(new Vector(3,3/2,3,3));
 2 1 2 2
primitive(Matrix M)

Scales each row of the matrix to a primitive integral vector.

Parameters:

Matrix M

Returns:
Example:
 > print primitive(new Matrix([1,3/2],[3,1]));
 2 3
 3 1


primitive_affine(Vector v)

Scales the affine part of a vector to a primitive integral vector.

Parameters:

Vector v

Returns:
Example:

 > print primitive_affine(new Vector(1,3/2,1,1));
 1 3 2 2
primitive_affine(Matrix M)

Scales the affine part of each row of the matrix to a primitive integral vector.

Parameters:

Matrix M

Returns:
Example:
 > print primitive_affine(new Matrix([1,1,3/2],[1,3,1]));
 1 2 3
 1 3 1


Linear Algebra

These functions are for algebraic computations and constructions of special matrices.


anti_diag(Vector d)

Produces a SparseMatrix from its anti-diagonal.

Parameters:

Vector d: the anti-diagonal entries

Returns:
Example:

Try this:

 > $M = anti_diag(new Vector([0,1,2]));
 > print $M;
 (3) (2 2)
 (3) (1 1)
 (3)

To print a more human-readable representation, use the dense() function:

 > print dense($M);
 0 0 2
 0 1 0
 0 0 0
anti_diag(Matrix m1, Matrix m2)

Returns a block anti-diagonal matrix with blocks m1 and m2.

Parameters:

Matrix m1

Matrix m2

Returns:
Example:

Try this:

 > $M = anti_diag(unit_matrix(2),unit_matrix(3));
 > print $M;
 (5) (2 1)
 (5) (3 1)
 (5) (4 1)
 (5) (0 1)
 (5) (1 1)


barycenter(Matrix A)

Calculate the average over the rows of a matrix.

Parameters:

Matrix A

Returns:
Example:

 > $A = new Matrix([3,0,0],[0,3,0],[0,0,3]);
 > print barycenter($A);
 1 1 1


basis(Matrix A)

Computes subsets of the rows and columns of A that form a basis for the linear space spanned by A.

Parameters:

Matrix A

Returns:
Example:

Here we have a nice matrix:

 > $M = new Matrix([[1,0,0,0],[2,0,0,0],[0,1,0,0],[0,0,1,0]]);

Let's print bases for the row and column space:

 > ($row,$col) = basis($M);
 > print $M->minor($row,All);
 1 0 0 0
 0 1 0 0
 0 0 1 0
 > print $M->minor(All,$col);
 1 0 0
 2 0 0
 0 1 0
 0 0 1


basis_affine(Matrix A)

Does the same as basis ignoring the first column of the matrix.

Parameters:

Matrix A

Returns:

basis_cols(Matrix A)

Computes a subset of the columns of A that form a basis for the linear space spanned by A.

Parameters:

Matrix A

Returns:
Set<Int>
Example:

Here we have a nice matrix:

 > $M = new Matrix([[1,0,0,0],[2,0,0,0],[0,1,0,0],[0,0,1,0]]);

Let's print a basis of its column space:

 > print $M->minor(All,basis_cols($M));
 1 0 0
 2 0 0
 0 1 0
 0 0 1


basis_rows(Matrix A)

Computes a subset of the rows of A that form a basis for the linear space spanned by A.

Parameters:

Matrix A

Returns:
Set<Int>
Example:

Here we have a nice matrix:

 > $M = new Matrix([[1,0,0,0],[2,0,0,0],[0,1,0,0],[0,0,1,0]]);

Let's print a basis of its row space:

 > print $M->minor(basis_rows($M),All);
 1 0 0 0
 0 1 0 0
 0 0 1 0


basis_rows_integer(Matrix A)

Computes a lattice basis of the span of the rows of A.

Parameters:

Matrix A

Returns:
Set<Int>

cramer(Matrix A, Vector b)

Computes the solution of the system Ax = b by applying Cramer's rule

Parameters:

Matrix A: must be invertible

Vector b

Returns:
Example:

from the Wikipedia:

 > $A = new Matrix([3,2,-1],[2,-2,4],[-1,1/2,-1]);
 > $b = new Vector(1,-2,0);
 > print cramer($A,$b);
 1 -2 -2


det(Matrix<Scalar> A)

Computes the determinant of a matrix using Gaussian elimination. If Scalar is not of field type, but element of a Euclidean ring R, type upgrade to element of the quotient field is performed. The result is recast as a Scalar, which is possible without roundoff since the so-computed determinant is an element of the (embedded) ring R.

Parameters:

Matrix<Scalar> A

Returns:
Scalar
Example:

 > print det(unit_matrix(3));
 1
Example:
 > $p = new UniPolynomial<Rational,Int>("x2+3x");
 > $M = new Matrix<UniPolynomial<Rational,Int>>([[$p, $p+1],[$p+1,$p]]);
 > print det($M);
 -2*x^2 -6*x - 1


diag(Vector d)

Produces a SparseMatrix from its diagonal.

Parameters:

Vector d: the diagonal entries

Returns:
Example:

 > $v = new Vector(1,2,3,4);
 > $D = diag($v);
 > print $D;
 (4) (0 1)
 (4) (1 2)
 (4) (2 3)
 (4) (3 4)
diag(Matrix m1, Matrix m2)

Returns a block diagonal matrix with blocks m1 and m2.

Parameters:

Matrix m1

Matrix m2

Returns:
Example:
 > $m1 = new Matrix([1,2],[3,4]);
 > $m2 = new Matrix([1,0,2],[3,4,0]);
 > $D = diag($m1,$m2);
 > print $D;
 (5) (0 1) (1 2)
 (5) (0 3) (1 4)
 0 0 1 0 2
 0 0 3 4 0


eigenvalues(Matrix<Float> A)

Eigenvalues of a matrix

Parameters:
Returns:

equal_bases(Matrix M1, Matrix M2)

Check whether both matrices are bases of the same linear subspace. Note: It is assumed that they are *bases* of the row space.

Parameters:

Matrix M1

Matrix M2

Returns:
Example:

 > $M1 = new Matrix([1,1,0],[1,0,1],[0,0,1]);
 > $M2 = new Matrix([1,0,0],[0,1,0],[0,0,1]);
 > print equal_bases($M1,$M2);
 true


hadamard_product(Matrix M1, Matrix M2)

Compute the Hadamard product of two matrices with same dimensions.

Parameters:

Matrix M1

Matrix M2

Returns:

hermite_normal_form(Matrix M)

Computes the (column) Hermite normal form of an integer matrix. Pivot entries are positive, entries to the left of a pivot are non-negative and strictly smaller than the pivot.

Parameters:

Matrix M: matrix to be transformed.

Options:

Bool reduced: If this is false, entries to the left of a pivot are left untouched. True by default

Returns:
Example:

The following stores the result for a small matrix M in H and then prints both hnf and companion:

 > $M = new Matrix<Integer>([1,2],[2,3]);
 > $H = hermite_normal_form($M);
 > print $H->hnf;
 1 0
 0 1
 > print $H->companion;
 -3 2
 2 -1


householder_trafo(Vector<Float> b)

Householder transformation of Vector b. Only the orthogonal matrix reflection H is returned.

Parameters:
Returns:

inv(Matrix A)

Computes the inverse A-1 of an invertible matrix A using Gauss elimination.

Parameters:

Matrix A

Returns:
Example:

We save the inverse of a small matrix M in the variable $iM:

 > $M = new Matrix([1,2],[3,4]);
 > $iM = inv($M);

To print the result, type this:

 > print $iM;
 -2 1
 3/2 -1/2

As we can see, that is in fact the inverse of M.

 > print $M * $iM;
 1 0
 0 1


lin_solve(Matrix A, Vector b)

Computes the vector x that solves the system Ax = b

Parameters:

Matrix A: must be invertible

Vector b

Returns:
Example:

from the Wikipedia:

 > $A = new Matrix([3,2,-1],[2,-2,4],[-1,1/2,-1]);
 > $b = new Vector(1,-2,0);
 > print lin_solve($A,$b);
 1 -2 -2


lineality_space(Matrix A)

Compute the lineality space of a matrix A.

Parameters:

Matrix A

Returns:
Example:

 > $M = new Matrix([1,1,0,0],[1,0,1,0]);
 > print lineality_space($M);
 0 0 0 1


moore_penrose_inverse(Matrix M)

Moore-Penrose Inverse of a Matrix

Parameters:

Matrix M

Returns:

normalized(Matrix<Float> A)

Normalize a matrix by dividing each row by its length (l2-norm).

Parameters:
Returns:
Example:

 > $A = new Matrix<Float>([1.5,2],[2.5,2.5]);
 > print normalized($A);
 0.6 0.8
 0.7071067812 0.7071067812


null_space(Matrix A)

Compute the null space of a matrix A.

Parameters:

Matrix A

Returns:
Example:

 > $A = new Matrix([1,2,0],[2,0,2]);
 > print null_space($A);
 -1 1/2 1
null_space(Vector b)

Compute the null space of a vector b.

Parameters:

Vector b

Returns:
Example:
 > $b = new Vector(1,2,3);
 > print null_space($b);
 -2 1 0
 -3 0 1


null_space_integer(Matrix A)

Computes the lattice null space of the integer matrix A.

Parameters:

Matrix A

Returns:

ones_matrix<Element>(Int m, Int n)

Creates a matrix with all elements equal to 1.

Type Parameters:

Element: default: Rational.

Parameters:

Int m: number of rows

Int n: number of columns

Returns:
Matrix<Element>
Example:

The following creates an all-ones matrix with Rational coefficients.

 > $M = ones_matrix<Rational>(2,3);
 > print $M;
 1 1 1
 1 1 1


ones_vector<Element>(Int d)

Creates a vector with all elements equal to 1.

Type Parameters:

Element: default: Rational.

Parameters:

Int d: vector dimension. If omitted, a vector of dimension 0 is created, which can adjust itself when involved in a block matrix operation.

Returns:
Vector<Element>
Example:

To create the all-ones Int vector of dimension 3, do this:

 > $v = ones_vector<Int>(3);

You can print the result using the print statement:

 > print $v;
 1 1 1


pluecker(Matrix V)

Compute the vector of maximal minors of a matrix. WARNING: interpretation different in lifted_pluecker

Parameters:

Matrix V

Returns:

project_to_orthogonal_complement(Matrix points, Matrix orthogonal)

Projects points into the orthogonal complement of a subspace given via an orthogonal basis. The given points will be overwitten.

Parameters:

Matrix points: will be changed to orthogonal ones

Matrix orthogonal: basis of the subspace


qr_decomp(Matrix<Float> M)

QR decomposition of a Matrix M with rows > cols

Parameters:
Returns:
Example:

 > $M = new Matrix<Float>([23,4],[6,42]);
 > $qr = qr_decomp($M);
 > print $qr->first;
 0.9676172724 0.2524218971
 0.2524218971 -0.9676172724
 > print $qr->second;
 23.76972865 14.47218877
 0 -39.63023785
 > print $qr->first * $qr->second ;
 23 4
 6 42


rank(Matrix A)

Computes the rank of a matrix.

Parameters:

Matrix A

Returns:
Int

reduce(Matrix A, Vector b)

Reduce a vector with a given matrix using Gauss elimination.

Parameters:

Matrix A

Vector b

Returns:

remove_zero_rows(Matrix m)

Remove all zero rows from a matrix.

Parameters:

Matrix m

Returns:

singular_value_decomposition(Matrix<Float> M)

SVD decomposition of a Matrix. Computes the SVD of a matrix into a diagonal Marix (S), orthogonal square Matrix (U), orthogonal square Matrix (V), such that U*S*V^T=M The first element of the output array is S, the second U and the thrid V.

Parameters:
Returns:
Example:

 > $M = new Matrix<Float>([1,2],[23,24]);
 > $SVD = singular_value_decomposition($M);

The following prints the three matrices, seperated by newline characters.

 > print $SVD->left_companion ,"\n", $SVD->sigma ,"\n", $SVD->right_companion;
 0.06414638608 0.9979404998
 0.9979404998 -0.06414638608
 
 33.31011547 0
 0 0.6604600341
 
 0.6909846321 -0.7228694476
 0.7228694476 0.6909846321


smith_normal_form(Matrix M, Bool inv)

Compute the Smith normal form of a given matrix M. M = L*S*R in normal case, or S = L*M*R in inverted case.

Parameters:

Matrix M: must be of integer type

Bool inv: if true, the companion matrices in the result will be inverted

Returns:
Example:

 > $M = new Matrix<Integer>([1,2],[23,24]);
 > $SNF = smith_normal_form($M);

The following line prints the three matrices seperated by newline characters.

 > print $SNF->left_companion ,"\n", $SNF->form ,"\n", $SNF->right_companion;
 1 0
 23 1
 
 1 0
 0 -22
 
 1 2
 0 1


smith_normal_form_flint(Matrix M)

Compute the Smith normal form of a given matrix M via flint.

Parameters:

Matrix M: must be of integer type

Returns:
from extension:
Example:

 > $M = new Matrix<Integer>([1,2],[23,24]);
 > $SNF = smith_normal_form_flint($M);
 > print $SNF;
 1 0
 0 22


solve_left(Matrix A, Matrix B)

Computes a matrix X that solves the system XA = B. This is useful, for instance, for computing the coordinates of some vectors with respect to a basis. The rows of the matrix solve_left(B,V) are the coordinates of the rows of V with respect to the rows of B.

Parameters:

Matrix A

Matrix B

Returns:
Example:

Define the matrices

 > $V = new Matrix([[-4,2,2],[3,-2,-1]]);
 > $B = new Matrix([[-1,1,0],[0,-1,1]]);

so that the rows of B are a basis of the subspace of vectors with zero coordinate sum. Then the rows of

 > print solve_left($B, $V);
 4 2
 -3 -1

contain the coordinates of the rows of V with respect to the rows of B.


solve_right(Matrix A, Matrix B)

Computes a matrix X that solves the system AX = B

Parameters:

Matrix A

Matrix B

Returns:
Example:

A non-degenerate example:

 > $A = new Matrix([[1,0,0],[1,1,0],[1,0,1],[1,1,1]]);
 > $B = new Matrix([[1,0,0],[1,0,1],[1,1,0],[1,1,1]]);
 > print solve_right($A,$B);
 1 0 0
 0 0 1
 0 1 0
Example:

A degenerate example:

 > $A = new Matrix([[1,0,0,0,0],[0,1,0,0,0],[1,0,1,0,0],[0,1,1,0,0]]);
 > $B = new Matrix([[0,1,0,0,0],[1,0,0,0,0],[0,1,1,0,0],[1,0,1,0,0]]);
 > print solve_right($A,$B);
 0 1 0 0 0
 1 0 0 0 0
 0 0 1 0 0
 0 0 0 0 0
 0 0 0 0 0


sqr(Vector<Scalar> v)

Return the sum of the squared entries of a vector v.

Parameters:

Vector<Scalar> v

Returns:
Scalar

totally_unimodular(Matrix A)

The matrix A is totally unimodular if the determinant of each square submatrix equals 0, 1, or -1. This is the naive test (exponential in the size of the matrix). For a better implementation try Matthias Walter's polymake extension at https://github.com/xammy/unimodularity-test/wiki/Polymake-Extension.

Parameters:

Matrix A

Returns:
Example:

 > $M = new Matrix<Int>([-1,-1,0,0,0,1],[1,0,-1,-1,0,0],[0,1,1,0,-1,0],[0,0,0,1,1,-1]);
 > print totally_unimodular($M);
 true


trace(Matrix A)

Computes the trace of a matrix.

Parameters:

Matrix A

Returns:
Int
Example:

 > $M = new Matrix([1,2,3],[23,24,25],[0,0,1]);
 > print trace($M);
 26


transpose(IncidenceMatrix A)

Computes the transpose AT of an incidence matrix A, i.e., (aT)ij = aji.

Parameters:
Returns:
transpose(Matrix A)

Computes the transpose AT of a matrix A, i.e., (aT)ij = aji.

Parameters:

Matrix A

Returns:
Example:

 > $M = new Matrix([1,2,23],[23,22,21]);
 > $Mt = transpose($M);
 > print $Mt;
 1 23
 2 22
 23 21


unit_matrix<Element>(Int d)

Creates a unit matrix of given dimension

Type Parameters:

Element: default: Rational

Parameters:

Int d: dimension of the matrix

Returns:
SparseMatrix<Element>
Example:

The following stores the 3-dimensional unit matrix (ones on the diagonal and zeros otherwise) in a variable and prints it:

 > $M = unit_matrix(3);
 > print $M;
 (3) (0 1)
 (3) (1 1)
 (3) (2 1)
Example:

The following stores the 3-dimensional unit matrix (ones on the diagonal and zeros otherwise) from type Int in a variable and prints it:

 > $M = unit_matrix<Int>(3);
 > print $M->type->full_name;
 SparseMatrix<Int, Symmetric>


unit_vector<Element>(Int d, Int pos)

Creates a SparseVector of given length d with a one entry at position pos and zeroes elsewhere.

Type Parameters:

Element: default: Rational

Parameters:

Int d: the dimension of the vector

Int pos: the position of the 1

Returns:
SparseVector<Element>
Example:

The following stores a vector of dimension 5 with a single 1 (as a Int) at position 2:

 > $v = unit_vector<Int>(5,2);
 > print $v->type->full_name;
 SparseVector<Int>
Example:

The following concatenates a unit vector of dimension 3 with a 1 at position 2 and a unit vector of dimension 2 with a 1 at position 1:

 > $v = unit_vector(3,2) | unit_vector(2,1);
 > print $v;
 (5) (2 1) (4 1)


zero_matrix<Element>(Int i, Int j)

Creates a zero matrix of given dimensions

Type Parameters:

Element: default: Rational

Parameters:

Int i: number of rows

Int j: number of columns

Returns:
SparseMatrix<Element>
Example:

The following stores a 2×3 matrix with 0 as entries (from type Rational) in a variable and prints it:

 > $M = zero_matrix(2,3);
 > print $M;
 0 0 0
 0 0 0
Example:

The following stores a 2×3 matrix with 0 as entries from type Int in a variable and prints its type:

 > $M = zero_matrix<Int>(2,3);
 > print $M->type->full_name;
 Matrix<Int, NonSymmetric>


zero_vector<Element>(Int d)

Creates a vector with all elements equal to zero.

Type Parameters:

Element: default: Rational

Parameters:

Int d: vector dimension. If omitted, a vector of dimension 0 is created, which can adjust itself when involved in a block matrix operation.

Returns:
Vector<Element>
Example:

The following stores a vector of dimension 5 with 0 as entries (from type Rational) in a variable and prints it:

 > $v = zero_vector(5);
 > print $v;
 0 0 0 0 0
Example:

The following stores a vector of dimension 5 with 0 as entries from type Int in a variable and prints its type:

 > $v = zero_vector<Int>(5);
 > print $v->type->full_name;
 Vector<Int>
Example:

The following concatenates a vector of dimension 2 of ones and a vector of length 2 of zeros:

 > $v = ones_vector(2) | zero_vector(2);
 > print $v;
 1 1 0 0


Set Operations

This category contains functions performing operations on Sets.


all_subsets_of_k(Any c, Int k)

Returns all subsets of size k of a given container as perl-array.

Parameters:

Any c: any container type, e.g. Set or Array

Int k: size of the subsets

Returns:
Array<Array<Any>>

incl(Set s1, Set s2)

Analyze the inclusion relation of two sets.

Parameters:

Set s1

Set s2

Returns:
Int
Example:

 > $s1 = new Set(1,2,3);
 > $s2 = $s1 - 1;
 > print incl($s1, $s2);
 1
 > print incl($s2, $s1);
 -1
 > print incl($s1, $s1);
 0
 > print incl($s2, $s1-$s2);
 2


range(Int a, Int b)

Create the Set {a, a+1, …, b-1, b} for ab. See also: sequence

Parameters:

Int a: minimal element of the set

Int b: maximal element of the set

Returns:
Set<Int>
Example:

 > print range(23,27);
 {23 24 25 26 27}


range_from(Int a)

Create an index range starting at a, the last index is implied by the context. To be used with minor, slice, and similar methods selecting a subset of elements.

Parameters:

Int a: start index

Returns:
Set<Int>
Example:

 > $v=new Vector<Int>(10,20,30,40);
 > print $v->slice(range_from(2));
 30 40


scalar2set(Scalar s)

Returns the singleton set {s}.

Parameters:

Scalar s

Returns:
Set<Scalar>
Example:

 > print scalar2set(23);
 {23}


select_subset(Set s, Set<Int> indices)

Returns the subset of s given by the indices.

Parameters:

Set s

Set<Int> indices

Returns:
Set
Example:

 > $s = new Set<Int>(23,42,666,789);
 > $ind = new Set<Int>(0,2);
 > $su = select_subset($s,$ind);
 > print $su;
 {23 666}


sequence(Int a, Int c)

Create the Set {a, a+1, …, a+c-1}. See also: range

Parameters:

Int a: the smallest element

Int c: the cardinality

Returns:
Set<Int>
Example:

 > print sequence(23,6);
 {23 24 25 26 27 28}


Utilities

Miscellaneous functions.


average(ARRAY array)

Returns the average value of the array elements.

Parameters:

ARRAY array

Example:

 > print average([1,2,3]);
 2


bounding_box(Matrix m)

Compute the column-wise bounds for the given Matrix m.

Parameters:

Matrix m

Returns:

distance_matrix(Matrix S, CODE d)

Given a metric, return a triangle matrix whose (i,j)-entry contains the distance between point i and j of the point set S for i<j. All entrys below the diagonal are zero. The metric is passed as a perl subroutine mapping two input vectors to a real value.

Parameters:

Matrix S

CODE d

Returns:
Example:

The following defines the perl subroutine dist as the euclidean metric and then saves the distance matrix of the 3-cubes vertices in the variable $M:

 > sub dist($$) {
 >    my $v = $_[0] - $_[1];
 >    return sqrt(new Float($v*$v)); }
 > $M = distance_matrix(polytope::cube(3)->VERTICES, \&dist);


fibonacci(Int m)

Returns the first m Fibonacci numbers.

Parameters:

Int m

Returns:
ARRAY

histogram(ARRAY data)

Produce a histogram of an array: each different element value is mapped on the number of its occurences.

Parameters:

ARRAY data

Returns:
Map<Any,Int>
Example:

 > $H = histogram([1,1,2,2,2,3,3,2,3,3,1,1,1,3,2,3]);
 > print $H;
 {(1 5) (2 5) (3 6)}


index_of(Array<Set<Int>> array)

Return a map indexing an array of sets

Parameters:

Array<Set<Int>> array

Returns:
Example:

 > $s1 = new Set(1,2,3);
 > $s2 = $s1 - 1;
 > $a = new Array<Set>($s1,$s2,$s1);
 > print index_of($a);
 {({1 2 3} 2) ({2 3} 1)}


is_nonnegative(ARRAY data)

Checks if a given sequence is nonnegative

Parameters:

ARRAY data

Returns:
Example:

 > print is_nonnegative([1,0,3]);
 1


is_unimodal(ARRAY data)

Checks if a given sequence is unimodal

Parameters:

ARRAY data

Returns:
Example:

 > print is_unimodal([1,1,2,3,3,2,2,1]);
 1                     
 > print is_unimodal([3,3,2,-1]);
 1
 > print is_unimodal([1,3,2,3]);
 0


maximum(ARRAY array)

Returns the maximal element of an array.

Parameters:

ARRAY array

Example:

 > print maximum([1,2,3,4,5,6,7,23]);
 23


median(ARRAY array)

Returns the median value of the array elements.

Parameters:

ARRAY array

Example:

 > print median([1,2,3,9]);
 2.5


minimum(ARRAY array)

Returns the minimal element of an array.

Parameters:

ARRAY array

Example:

 > print minimum([23,42,666]);
 23


perturb_matrix(Matrix M, Float eps, Bool not_hom)

Perturb a given matrix M by adding a random matrix. The random matrix consists of vectors that are uniformly distributed on the unit sphere. Optionally, the random matrix can be scaled by a factor eps.

Parameters:

Matrix M

Float eps: the factor by which the random matrix is multiplied default value: 1

Bool not_hom: if set to 1, the first column will also be perturbed; otherwise the first columns of the input matrix M and the perturbed one coincide (useful for working with homogenized coordinates); default value: 0 (homogen. coords)

Options:

Int seed: controls the outcome of the random number generator; fixing a seed number guarantees the same outcome.

Returns:

rand_perm(Int n)

gives a random permutation

Parameters:

Int n

Options:

Int Seed

Returns:

Visualization

These functions are for visualization.


compose(Visual::Object vis_obj …)

Create a composite drawing of several objects.

Parameters:

Visual::Object vis_obj …: objects to be drawn together

Options:

String Title: name of the whole drawing; per default the name of the first Object is taken.

Returns:
Example:

Draw a pretty 8-pointed star:

 > compose(cube(2)->VISUAL, cross(2,sqrt(2))->VISUAL, Title=>"A pretty star.", VertexLabels=>"hidden");
compose(Visual::Container vis_container, Visual::Object vis_obj …)

Add new objects to a composite drawing.

Parameters:

Visual::Container vis_container: drawing produced by some visualization function

Visual::Object vis_obj …: objects to be added

Options:

String Title: new name for the drawing

Any decorations: to be applied to all components as default values.

Returns:

geomview(Visual::Object vis_obj …)

Run geomview to display given visual objects.

Parameters:

Visual::Object vis_obj …: objects to display

Options:

String File: “filename” or “AUTO” Store the objects in a gcl (geomview control language) file instead of starting the interactive GUI. The geometric data in OFF format is embedded in the Lisp-style commands, but can be easily extracted using any text editor, if needed. The .gcl suffix is automatically added to the file name. Specify AUTO if you want the filename be automatically derived from the drawing title. You can also use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe.


javaview(Visual::Object vis_obj …)

Run JavaView with the given visual objects.

Parameters:

Visual::Object vis_obj …: objects to display

Options:

String File: “filename” or “AUTO” Store the object description in a JVX file without starting the interactive GUI. The .jvx suffix is automatically added to the file name. Specify AUTO if you want the filename be automatically derived from the drawing title. You can also use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe.

from extension:

jreality(Visual::Object vis_obj …)

Run jReality to display given visual objects.

Parameters:

Visual::Object vis_obj …: objects to display

Options:

String File: “filename” or “AUTO” Store the object description in a bean shell source file without starting the interactive GUI. The .bsh suffix is automatically added to the file name. Specify AUTO if you want the filename be automatically derived from the drawing title. You can also use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe.

from extension:

postscript(Visual::Object vis_obj …)

Create a Postscript ™ drawing with the given visual objects.

Parameters:

Visual::Object vis_obj …: objects to draw

Options:

String File: “filename” or “AUTO” Store the drawing in a file without starting the viewer. The .ps suffix is automatically added to the file name. Specify AUTO if you want the filename be automatically derived from the drawing title. You can also use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe.


povray(Visual::Object vis_obj …)

Run POVRAY to display given visual objects.

Parameters:

Visual::Object vis_obj …: objects to display

Options:

String File: “filename” or “AUTO” Store the object description in a POVRAY source file without actual rendering. The .pov suffix is automatically added to the file name. Specify AUTO if you want the filename be automatically derived from the drawing title. You can also use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe.


sketch(Visual::Object vis_obj …)

Produce a Sketch input file with given visual objects.

Parameters:

Visual::Object vis_obj …: objects to display

Options:

String File: “filename” or “AUTO” For the file name you can use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe. Real file names are automatically completed with the .sk suffix if needed. An automatically generated file name is displayed in the verbose mode.


static(Visual::Object vis_obj)

Suppress creation of dynamic (interactive) scenes.

Parameters:

Visual::Object vis_obj: drawing, e.g. created by VISUAL_GRAPH or SCHLEGEL.

Returns:

svg(Visual::Object vis_obj …)

Create a Svg drawing with the given visual objects.

Parameters:

Visual::Object vis_obj …: objects to draw

Options:

String File: “filename” or “AUTO” Store the drawing in a file without starting the viewer. The .svg suffix is automatically added to the file name. Specify AUTO if you want the filename be automatically derived from the drawing title. You can also use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe.


threejs(Visual::Object vis_obj)

Produce an html file with given visual objects.

Parameters:

Visual::Object vis_obj: object to display

Options:

String File: “filename” or “AUTO” For the file name you can use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe. Real file names are automatically completed with the .html suffix if needed. An automatically generated file name is displayed in the verbose mode.


tikz(Visual::Object vis_obj)

Produce a TikZ file with given visual objects.

Parameters:

Visual::Object vis_obj: object to display

Options:

String File: “filename” or “AUTO” For the file name you can use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe. Real file names are automatically completed with the .tikz suffix if needed. An automatically generated file name is displayed in the verbose mode.


x3d(Visual::Object vis_obj …)

Create an X3D drawing with the given visual objects.

Parameters:

Visual::Object vis_obj …: objects to draw

Options:

String File: “filename” or “AUTO” Store the drawing in a file without starting the viewer. The .x3d suffix is automatically added to the file name. Specify AUTO if you want the filename be automatically derived from the drawing title. You can also use any expression allowed for the open function, including “-” for terminal output, “&HANDLE” for an already opened file handle, or “| program” for a pipe.


no category

db_aggregate

UNDOCUMENTED


db_get_type_information

20171204: Made type_information_key undef by default to allow users to pass the key “default” explicitly, otherwise default keys have the form “default.<collection>” as there may be more than one collection in the db with a default type information entry


db_print_searchable_fields

UNDOCUMENTED


Small Object Types

Algebraic Types

This category contains all “algebraic” types, such as matrices, vectors, polynomials, rings, …


Matrix<Element, Sym>
Type Parameters:

Element: default: Rational

Sym: default: NonSymmetric

Methods of Matrix:
anti_diagonal(Int i)

Returns the anti-diagonal of the matrix.

Parameters:

Int i: i=0: the main anti_diagonal (optional)

> i>0: the i-th anti_diagonal below the main anti_diagonal

      > //i//<0: the //i//-th anti_diagonal __above__ the main anti_diagonal
      ? Returns:
      :''[[.:common#Vector |Vector]]<Element>''
    ?  **''clear([[.:common#Int |Int]] r, [[.:common#Int |Int]] c)''**
    :: Change the dimensions setting all elements to 0.
      ? Parameters:
      :: ''[[.:common#Int |Int]]'' ''r'': new number of rows
      :: ''[[.:common#Int |Int]]'' ''c'': new number of columns
    ?  **''col([[.:common#Int |Int]] i)''**
    :: Returns the //i//-th column.
      ? Parameters:
      :: ''[[.:common#Int |Int]]'' ''i''
      ? Returns:
      :''[[.:common#Vector |Vector]]<Element>''
    ?  **''cols()''**
    :: Returns the number of columns.
      ? Returns:
      :''[[.:common#Int |Int]]''
    ?  **''diagonal([[.:common#Int |Int]] i)''**
    :: Returns the __diagonal__ of the matrix.
      ? Parameters:
      :: ''[[.:common#Int |Int]]'' ''i'': //i//=0: the main diagonal (optional)
      > //i//>0: the //i//-th diagonal __below__ the main diagonal
      > //i//<0: the //i//-th diagonal __above__ the main diagonal
      ? Returns:
      :''[[.:common#Vector |Vector]]<Element>''
    ?  **''div_exact([[.:common#Int |Int]] a)''**
    :: Divides every entry by //a// (assuming that every entry is divisible by //a//).
      ? Parameters:
      :: ''[[.:common#Int |Int]]'' ''a''
      ? Returns:
      :''[[.:common#Matrix |Matrix]]''
    ?  **''elem([[.:common#Int |Int]] r, [[.:common#Int |Int]] c)''**
    :: Returns an element of the matrix. The return value is an `lvalue', that is, it can be modified if the matrix object is mutable.
      ? Parameters:
      :: ''[[.:common#Int |Int]]'' ''r'': the row index
      :: ''[[.:common#Int |Int]]'' ''c'': the column index
      ? Returns:
      :''Element''
    ?  **''minor([[.:common#Set |Set]] r, [[.:common#Set |Set]] c)''**
    :: Returns a __minor__ of the matrix containing the rows in //r// and the columns in //c//. You can pass [[.:common#all_rows_or_cols |All]] if you want all rows or columns and ~ for the complement of a set. E.g.
      ? Parameters:
      :: ''[[.:common#Set |Set]]'' ''r'': the rows
      :: ''[[.:common#Set |Set]]'' ''c'': the columns
      ? Returns:
      :''[[.:common#Matrix |Matrix]]''
      ? Example:
      ::  The following will give you the minor of a matrix containing all rows and all but the 0-th column.
      :: <code perl> > print unit_matrix(3)->minor(All, ~[0]);
   (2)
   1 0
   0 1
  </code>
    ?  **''resize([[.:common#Int |Int]] r, [[.:common#Int |Int]] c)''**
    :: Change the dimensions; when growing, set added elements to 0.
      ? Parameters:
      :: ''[[.:common#Int |Int]]'' ''r'': new number of rows
      :: ''[[.:common#Int |Int]]'' ''c'': new number of columns
    ?  **''row([[.:common#Int |Int]] i)''**
    :: Returns the //i//-th row.
      ? Parameters:
      :: ''[[.:common#Int |Int]]'' ''i''
      ? Returns:
      :''[[.:common#Vector |Vector]]<Element>''
    ?  **''rows()''**
    :: Returns the number of rows.
      ? Returns:
      :''[[.:common#Int |Int]]''

Plucker<Scalar>
Type Parameters:

Scalar: default: Rational

Methods of Plucker:
coordinates

UNDOCUMENTED

permuted

UNDOCUMENTED


Polynomial<Coefficient, Exponent>
Type Parameters:

Coefficient: default: Rational

Exponent: default: Int

Methods of Polynomial:
coefficients_as_vector()

The vector of all coefficients. The sorting agrees with monomials_as_matrix.

Returns:
Vector<Coefficient>
constant_coefficient()

The constant coefficient.

Returns:
Int
deg()

The degree of the polynomial

Returns:
Int
embed(Int nvars)

Embed the Polynomial in a polynomial ring with the given number of variables. The old variables will be put at the beginning, for more control use mapvars.

Parameters:

Int nvars: new number of variables

Returns:
Example:

 > $pm = new Polynomial("1+x_0^2*x_3+x_1+3*x_3");
     > print $pm->project([1,3]);
     x_0 + 4*x_1 + 1
 
get_var_names

set the variable names

initial_form(Vector<Exponent> v)

The initial form with respect to a weight-vector v

Parameters:

Vector<Exponent> v: weights

Returns:
lc()

The leading coefficient.

Returns:
Int
lm()

The exponent of the leading monomial.

Returns:
Int
mapvars(Array<Int> indices, Int nvars)

Map the variables of the Polynomial to the given indices. The same index may bei given multiple times and also some may be omitted for embedding with a higher number of variables. The length of the given Array must be the same as the number of variables of the original polynomial.

Parameters:

Array<Int> indices: indices of the target variables

Int nvars: new number of variables, default: maximal index

Returns:
Example:
 > $pm = new Polynomial("1+x_0^2*x_3+x_1+3*x_3");
     > print $pm->mapvars([0,1,1,4],6);
     x_0^2*x_4 + x_1 + 3*x_4 + 1
 
monomial(Int var_index, Int n_vars)

construct a monomial of degree 1 with a given variable

Parameters:

Int var_index: index of the variable

Int n_vars: number of variables

monomials_as_matrix()

The matrix of all exponent vectors (row-wise). The sorting agrees with coefficients_as_vector.

Returns:
SparseMatrix<Exponent>
n_vars()

Number of variables

Returns:
Int
print_ordered(Matrix m)

Print a polynomial with terms sorted according to a given Matrix m.

Parameters:

Matrix m

project()

Project the Polynomial to the given list of variables. The number of variables will be reduced to the number of indices, i.e. the variables will be renamed. Keeping the names of the variables is possible by using substitute with a Map.

Returns:
Example:
 > $pm = new Polynomial("1+x_0^2*x_3+x_1+3*x_3");
     > print $pm->project([1,3]);
     x_0 + 4*x_1 + 1
 
reset_var_names

reset the variable names according to the default naming scheme

set_var_names

set the variable names

substitute

Substitute a list of values in a Polynomial with Int exponents. Either with an array of values, or with a Map mapping variable indices to values.

Example:
 > $pm = new Polynomial("1+x_0^2*x_3+x_1+3*x_3");
     > print $pm->substitute([0,11,2,3]);
     21
 
 > $map = new Map<Int,Rational>([0,5/2],[1,1/5],[2,new Rational(7/3)]);
     > print $pm->substitute($map);
     37/4*x_3 + 6/5
 
trivial()

The polynomial is zero.

Returns:

PuiseuxFraction<MinMax, Coefficient, Exponent>
Type Parameters:

MinMax: type of tropical addition: either Min or Max

Coefficient: default: Rational

Exponent: default: Rational

Methods of PuiseuxFraction:
evaluate(Matrix m, Coefficient x, Int exp)

Evaluate all PuiseuxFractions in a Matrix at a Rational number (x^exp). Let explcm be the lcm of the denominators of all exponents. If there are no denominators or explcm divides exp, then the evaluation is computed exactly. Otherwise, some rational number close to the root (x^exp)^-explcm will be chosen via an intermediate floating point number.

Parameters:

Matrix m

Coefficient x

Int exp: (default: 1)

Returns:
Matrix<Coefficient>
Example:

The evaluation can also be applied to containers, unfortunately static methods dont play nicely with the perl interface but the following can be used:

 > $m = long_and_winding(2)->FACETS;
     > print ((typeof PuiseuxFraction<Max>)->pkg->evaluate($m,2,4));
     (5) (0 256) (1 -1)
     (5) (0 16) (2 -1)
     (5) (1 16) (3 -1)
     (5) (2 16) (3 -1)
     0 4 4 0 -1
     (5) (3 1)
     (5) (4 1)
 
evaluate(Vector v, Coefficient x, Int exp)

Evaluate all PuiseuxFractions in a Vector at a Rational number (x^exp). Let explcm be the lcm of the denominators of all exponents. If there are no denominators or explcm divides exp, then the evaluation is computed exactly. Otherwise, some rational number close to the root (x^exp)^-explcm will be chosen via an intermediate floating point number.

Parameters:

Vector v

Coefficient x

Int exp: (default: 1)

Returns:
Vector<Coefficient>
evaluate(Coefficient x, Int exp)

Evaluate a PuiseuxFraction at a Rational number (x^exp). Let explcm be the lcm of the denominators of all exponents. If there are no denominators or explcm divides exp, then the evaluation is computed exactly. Otherwise, some rational number close to the root (x^exp)^-explcm will be chosen via an intermediate floating point number.

Parameters:

Coefficient x

Int exp: (default: 1)

Returns:
Coefficient
evaluate_float(Float x)

Approximate evaluation at x

Parameters:

Float x

Returns:
evaluate_float(Matrix m, Float x)

Approximate evaluation of a Matrix at x

Parameters:

Matrix m

Float x

Returns:
evaluate_float(Vector v, Float x)

Approximate evaluation of a Vector at x

Parameters:

Vector v

Float x

Returns:
val()

The valuation.

Returns:
TropicalNumber<MinMax>
Example:
 > $x = monomials<Rational,Rational>(1);
     > print new PuiseuxFraction<Max>(2*$x*$x-$x+2)->val;
     2
 
Example:

The valuation can also be applied to Containers via convert_to

 > $m = long_and_winding(3)->FACETS;
     > print convert_to<TropicalNumber<Max>>($m);
     (7) (0 2) (1 0)
     (7) (0 1) (2 0)
     (7) (1 1) (3 0)
     (7) (2 1) (3 0)
     (7) (1 1/2) (2 1/2) (4 0)
     (7) (3 1) (5 0)
     (7) (4 1) (5 0)
     (7) (3 3/4) (4 3/4) (6 0)
     (7) (5 0)
     (7) (6 0)
 


RationalFunction<Coefficient, Exponent>

the same with type deduction

Type Parameters:

Coefficient: default: Rational

Exponent: default: Int


SparseMatrix<Element, Sym>

A SparseMatrix is a special form of a Matrix optimized for large matrices with few non-zero elements. Physically it is stored as a two-dimensional grid of balanced binary trees with row and column indexes as search keys. Use dense to convert a sparsematric into the dense form.

Type Parameters:

Element

Sym: one of Symmetric or NonSymmetric, default: NonSymmetric

derived from:
Example:

construct a SparseMatrix from a list of row vectors. Each row can be specified in a dense or sparse form. Number of columns is determined by the size of dense rows or by the maximal index value in sparse rows.

 > $A = new SparseMatrix<Integer>(
 >  [0, 1, 0, 0, 0],
 >  {4 => 2},
 >  {},
 >  [3, -1, 0, 0, 0]);
 > print $A;
 (5) (1 1)
 (5) (4 2)
 (5)
 (5) (0 3) (1 -1)
Example:

construct a SparseMatrix with explicitly given number of columns:

 > $A = new SparseMatrix<Integer>(
 >   {1 => 10},
 >   {2 => 20},
 >   {cols => 5});
 > print $A;
 (5) (1 10)
 (5) (2 20)
Methods of SparseMatrix:
resize(Int r, Int c)

Resize the matrix All elements in added rows and/or columns are implicit zeros.

Parameters:

Int r: new number of rows

Int c: new number of columns

squeeze

Removes empty rows and columns. The remaining rows and columns are renumbered without gaps.

squeeze_cols

Removes empty columns. The remaining columns are renumbered without gaps.

squeeze_rows

Removes empty rows. The remaining rows are renumbered without gaps.


SparseVector<Element>

A SparseVector is a special form of a Vector optimized for large vectors with few non-zero elements. Physically it is stored as a balanced binary tree with element index as a search key. The printable representation of a SparseVector looks like a sequence (l) (p1 v1) … (pk vk), where l is the dimension of the vector and each pair (pi vi) denotes an entry with value vi at position pi. All other entries are zero. Use dense to convert a sparse vector into the dense form.

Type Parameters:

Element

derived from:
Example:

construct a SparseVector from a contiguous list of scalars; zero values are filtered out automatically:

 > $v = new SparseVector<Integer>(0, 1, 2, 0, 0, 0);
 > print $v, "\n";
 (6) (1 1) (2 2)
Example:

construct a SparseVector from a hash map with non-zero values; dimension is provided explicitly:

 > $v = new SparseVector<Integer>({ 1 => 1, 2 => 2, _dim => 6 });
 > print $v, "\n";
 (6) (1 1) (2 2)
Methods of SparseVector:
size()

The number of non-zero entries.

Returns:
Int


UniPolynomial<Coefficient, Exponent>

A class for univariate polynomials.

Type Parameters:

Coefficient: default: Rational

Exponent: default: Int

Methods of UniPolynomial:
coefficients_as_vector()

The vector of all coefficients. The sorting agrees with monomials_as_vector.

Returns:
Vector<Coefficient>
constant_coefficient()

The constant coefficient.

Returns:
Int
deg()

The highest degree occuring in the polynomial.

Returns:
Exponent
evaluate(Coefficient x, Exponent exp)

Evaluate a UniPolynomial at a number (x^exp). Note that for non-integral exponents this may require intermediate floating point computations depending on the input: Let explcm be the lcm of the denominators of all exponents. If there are no denominators or explcm divides exp, then the evaluation is computed exactly. Otherwise, some rational number close to the root (x^exp)^-explcm will be chosen via an intermediate floating point number.

Parameters:

Coefficient x

Exponent exp: (default: 1)

Returns:
Coefficient
evaluate_float(Float x)

Approximate evaluation of the polynomial at a Float x.

Parameters:

Float x

Returns:
get_var_names

get the variable name

lc()

The leading coefficient.

Returns:
Int
lower_deg()

The lowest degree occuring in the polynomial.

Returns:
Exponent
monomial

create a monomial of degree 1

monomials_as_vector()

The vector of all exponents. The order agrees with coefficients_as_vector.

Returns:
Vector<Exponent>
n_vars

Number of variables

print_ordered(Exponent x)

Print a polynomial with terms sorted according to exponent*x.

Parameters:

Exponent x

reset_var_names

reset the variable name according to the default naming scheme

set_var_names

set the variable name

substitute

Substitute some value in a UniPolynomial with Int exponents. When all exponents are positive the argument can be any scalar, matrix or polynomial type. With negative exponents, polynomials are not supported (use RationalFunction instead) and any given matrix must be invertible


Vector<Element>

A type for vectors with entries of type Element. You can perform algebraic operations such as addition or scalar multiplication.

Type Parameters:

Element

Example:

You can create a new Vector by entering its elements, e.g.:

 > $v = new Vector<Int>(1,2,3);

or

 >$v = new Vector<Int>([1,2,3]);
Methods of Vector:
dim()

The length of the vector

Returns:
Int
div_exact(Int a)

Divides every entry by a (assuming that every entry is divisible by a).

Parameters:

Int a

Returns:
slice(Set s)

Returns a Vector containing all entries whose index is in a Set s.

Parameters:

Set s: indices to select from the vector

Returns:

all_rows_or_cols

Use the keyword “All” for all rows or columns, e.g. when constructing a minor.


Arithmetic

These types are needed as return types of arithmetic computations.


Div<Scalar>

The complete result of an integral division

Type Parameters:

Scalar: type supporting modulo division, e.g. Integer or UniPolynomial

Methods of Div:
quot()

the quotient

Returns:
Scalar
rem()

the remainder

Returns:
Scalar

ExtGCD<Scalar>

The complete result of the calculation of the greatest common divisor of two numbers a and b:

Type Parameters:

Scalar: type of operands, must be a GCD domain

Methods of ExtGCD:
g()

The greatest common divisor, gcd(a,b)

Returns:
Scalar
k1()

The factor of a: a=g*k1

Returns:
Scalar
k2()

The factor of b: b=g*k2

Returns:
Scalar
p()

The co-factor of a: g=a*p+b*q

Returns:
Scalar
q()

The co-factor of b: g=a*p+b*q

Returns:
Scalar

Max

tropical addition: max

Methods of Max:
apply

UNDOCUMENTED

orientation

UNDOCUMENTED


Min

tropical addition: min

Methods of Min:
apply

UNDOCUMENTED

orientation

UNDOCUMENTED


TropicalNumber<Addition, Scalar>
Type Parameters:

Addition

Scalar: default: Rational

Methods of TropicalNumber:
orientation()

The orientation of the associated addition, i.e. +1 if the corresponding 0 is +inf -1 if the corresponding 0 is -inf

Returns:
Int
zero()

The zero element of the tropical semiring of this element.

Returns:
Scalar

Artificial

These types are auxiliary artifacts helping to build other classes, primarily representing template parameters or enumeration constants. They should not be used alone as property types or function arguments. In the most cases they won't even have user-accessible constructors.


CachedObjectPointer<>
Type Parameters:

Container

One-dimensional collection of objects, aka container in STL It can be accessed like a perl array. Sequential iteration via foreach() is always supported; random access might be supported depending on the underlying C++ object.


Directed

Type tag for a directed Graph.


DirectedMulti

Type tag for a directed multigraph.


EdgeIterator

EdgeList

Iterator<Element>

An iterator over a sequence of objects. The objects may be stored in a container or be generated on the fly.

Type Parameters:

Element


LocalFloatEpsilon

NonSymmetric

Labels a Matrix or an IncidenceMatrix as non-symmetric.


Serialized<X>
Type Parameters:

X


Symmetric

Labels a Matrix or an IncidenceMatrix as symmetric.


Undirected

Type tag for an undirected Graph.


UndirectedMulti

Type tag for an undirected multigraph.


Basic Types

This category contains all basic types, in particular those that wrap C++, GMP or perl types such as Int, Integer, Rational, Long, Float, Array, String, …


AccurateFloat

A wrapper for AccurateFloat.


Array<Element>

An array with elements of type Element. Corresponds to the C++ type Array.

Type Parameters:

Element

Methods of Array:
size()

Returns the size.

Returns:
Int

Bool

Corresponds to the C++ type bool.


Float

Corresponds to the C++ type double.

Methods of Float:
inf

produce an infinitely large positive value

minus_inf

produce an infinitely large negative value


Int

Corresponds to the C++ type int.


Integer

An integer of arbitrary size.

Methods of Integer:
inf

produce an infinitely large positive value

minus_inf

produce an infinitely large negative value


List<Element>

Corresponds to the C++ type std::list.

Type Parameters:

Element


Long

Corresponds to the C++ type long. This type is primarily needed for automatic generated function wrappers, because perl integral constants are always kept as a long.

derived from:
Int

Pair<First, Second>

Corresponds to the C++ type std::pair.

Type Parameters:

First

Second


QuadraticExtension<Field>

Realizes quadratic extensions of fields. You can construct the value a+b\(\sqrt r\) via QuadraticExtension(a, b, r) (where a, b, r are of type Field).

Type Parameters:

Field: default: Rational


Rational

A class for rational numbers. You can easily create a Rational like that: $x = 1/2;

Methods of Rational:
inf

Produce an infinitely large positive value.

minus_inf

Produce an infinitely large negative value.


String

Corresponds to the C++ type std::string.


Text

Plain text without any imposed structure.


Database

Here you can find the functions to access the polymake database.


DBCursor

A database cursor. Initialize it with a database name, a collection name and a query. You can then iterate over the objects matching the query with next. It lazily fetches more objects from the database server. (Note that you have to create a new cursor if you want to start from the beginning.)


MongoClient

A handler for the polyDB database internally controlling the connection to the MongoDB database


Graph Types

This contains all property types that are related to graphs.


EdgeHashMap<Dir, Element>

Sparse mapping of edges to data items.

Type Parameters:

Element: data associated with edges

derived from:
Methods of EdgeHashMap:
edge(Int from, Int to)

Access the data associated with an edge between two given nodes. The new data element is created on demand.

Parameters:

Int from: source node

Int to: target node

erase(Int from, Int to)

Delete the data associated with an edge between two given nodes.

Parameters:

Int from: source node

Int to: target node

find(Int from, Int to)

Access the data associated with an edge between two given nodes.

Parameters:

Int from: source node

Int to: target node

Returns:

EdgeMap<Dir, Element>

Dense mapping of edges to data items.

Type Parameters:

Dir: kind of the host graph, Undirected, Directed, UndirectedMulti, or DirectedMulti

Element: data associated with edges

derived from:
Methods of EdgeMap:
edge(Int from, Int to)

Access the data associated with an edge between two given nodes.

Parameters:

Int from: source node

Int to: target node


Graph<Dir>
Type Parameters:
Methods of Graph:
add_edge(Int tail_node, Int head_node)

In a multigraph, creates a new edge connecting two given nodes. In a normal graph, creates a new edge only if the nodes were not connected yet. Returns the index of the (new) edge.

Parameters:

Int tail_node

Int head_node

Returns:
Int
add_node()

Add a new node without incident edes.

Returns:
Int
adjacent_nodes(Int node)

Returns the set of indices of nodes adjacent to node.

Parameters:

Int node

Returns:
Set
all_edges(Int tail_node, Int head_node)

Returns an iterator visiting all (parallel) edges connecting two given nodes.

Parameters:

Int tail_node

Int head_node

Returns:
contract_edge(Int node1, Int node2)

Contract the edge(s) between node1 and node2. Reconnects all edges from node2 to node1, deleting the edge(s) between them and, finally, deleting node2.

Parameters:

Int node1

Int node2

degree(Int node)

Returns the number of edges incident to node.

Parameters:

Int node

Returns:
Int
delete_all_edges(Int tail_node, Int head_node)

Deletes all edges in a multigraph connecting two given nodes.

Parameters:

Int tail_node

Int head_node

delete_edge(Int tail_node, Int head_node)

Deletes the edge connecting two given nodes, if there was one. In a multigraph, deletes one arbitrary edge from the parallel bundle.

Parameters:

Int tail_node

Int head_node

delete_edge(Iterator iterator)

Delete the edge in a multigraph pointed to by the given iterator

Parameters:

Iterator iterator: as returned by all_edges.

delete_node(Int node)

Deletes all edges incident to the given node and marks it as invalid. The numeration of other nodes stays unchanged.

Parameters:

Int node

dim()

Returns the maximal node index + 1. If the graph does not have gaps caused by node deletion, the result is equivalent to nodes().

Returns:
Int
edge(Int tail_node, Int head_node)

Returns the index of the edge connecting two given nodes. The edge is created if was not there. In a multigraph, an arbitrary edge from the parallel bundle will be picked.

Parameters:

Int tail_node

Int head_node

Returns:
Int
edge_exists(Int tail_node, Int head_node)

Checks whether two given nodes are connected by (at least) one edge.

Parameters:

Int tail_node

Int head_node

Returns:
edges()

Get the total number of edges.

Returns:
Int
has_gaps()

Returns true if some nodes have been deleted since the last squeeze operation.

Returns:
in_adjacent_nodes(Int node)

Returns the set of indices of the nodes that have an edge heading to node.

Parameters:

Int node

Returns:
Set
in_degree(Int node)

Returns the number of edges heading to node.

Parameters:

Int node

Returns:
Int
in_edges(Int node)

Returns a sequence of edges heading to (in Directed case) or incident to (in Undirected case) node.

Parameters:

Int node

Returns:
invalid_node(Int node)

Returns true if the given node index is either out of valid range or points to a formerly deleted node.

Parameters:

Int node

Returns:
node_exists(Int node)

Check whether the node with given index exists.

Parameters:

Int node

Returns:
node_out_of_range(Int node)

Returns true if the given node index is out of valid range.

Parameters:

Int node

Returns:
nodes()

Get the total number of nodes.

Returns:
Int
out_adjacent_nodes(Int node)

Returns the set of indices of the nodes with an edge arriving from node.

Parameters:

Int node

Returns:
Set
out_degree(Int node)

Returns the number of edges leaving node.

Parameters:

Int node

Returns:
Int
out_edges(Int node)

Returns a sequence of edges leaving (in Directed case) or incident to (in Undirected case) node.

Parameters:

Int node

Returns:
permute_inv_nodes

permute the nodes param perm inverse permutation of node indexes

permute_nodes

permute the nodes param perm permutation of node indexes

squeeze

Renumbers the valid nodes as to eliminate all gaps left after deleting.

squeeze_isolated

Deletes all nodes of degree 0, then renumbers the remaining nodes without gaps.


GraphMap<Dir, Element>

The common abstract base class for all kinds of associative containers that can be attached to a Graph.

Type Parameters:

Dir: kind of the host graph: Undirected, Directed, UndirectedMulti, or DirectedMulti

Element: data associated with nodes or edges


NodeHashMap<Dir, Element>

Sparse mapping of nodes to data items.

Type Parameters:

Element: data associated with nodes

derived from:

NodeMap<Dir, Element>

Dense mapping of nodes to data items.

Type Parameters:

Dir: kind of the host graph, Undirected, Directed, UndirectedMulti, or DirectedMulti

Element: data associated with nodes

derived from:

Linear Algebra

These types are needed as return types of algebraic computations.


HermiteNormalForm<Scalar>

Complete result of the Hermite normal form computation of the input matrix M.

Type Parameters:

Scalar: matrix element type

Methods of HermiteNormalForm:
companion()

unimodular matrix R such that M*R = H

Returns:
SparseMatrix<Scalar>
hnf()

the Hermite normal form

Returns:
Matrix<Scalar>
rank()

rank of M

Returns:
Int

SingularValueDecomposition

Complete result of the singular value decomposition of a matrix M, such that left_companion * sigma * transpose(right_companion) = M Contains the following fields:

Methods of SingularValueDecomposition:
left_companion()

matrix of left singular vectors

Returns:
right_companion()

matrix of right singular vectors

Returns:
sigma()

the diagonalized matrix

Returns:

SmithNormalForm<Scalar>

Complete result of the Smith normal form computation of the input matrix M.

Type Parameters:

Scalar: matrix element type

Methods of SmithNormalForm:
form()

the Smith normal form

Returns:
SparseMatrix<Scalar>
left_companion()

unimodular matrix L such that M = L*S*R

Returns:
SparseMatrix<Scalar>
rank()

rank of M

Returns:
Int
right_companion()

unimodular matrix R such that M = L*S*R

Returns:
SparseMatrix<Scalar>
torsion()

absolute values of the entries greater than 1 of the diagonal together with their multiplicity

Returns:
List<Pair<Scalar,Int>>

Set Types

In this category you find all property types related to sets, such as Set, Map, HashMap, IncidenceMatrix, …


ApproximateSet<Element>

A specialization of Sets containing elements of type Element, but where equality is enforced only up to a global epsilon.

Type Parameters:

Element: default: Float

derived from:
Set
Example:

You can for example create a new ApproximateSet with two elements by:

 > $s = new ApproximateSet(1.1, 1.2, 1.200000001);


Bitset

Container class for dense sets of integers. A special class optimized for representation of a constrained range of non-negative integer numbers.

derived from:
Set<Int>

FacetList

A FacetList is a collection of sets of integral numbers from a closed contiguous range [0..n-1]. The contained sets usually encode facets of a simplicial complex, with set elements corresponding to vertices of a complex, therefore the name. From the structural perspective, FacetList is interchangeable with IncidenceMatrix, but they significantly differ in supported operations and their performance. IncidenceMatrix offers fast random access to elements, while FacetList is optimized for finding, inserting, and deleting facets fulfilling certain conditions like all subsets or supersets of a given vertex set. On perl side, FacetList behaves like a sequence of common without random access to facets. Facets are visited in chronological order. Each facet has a unique integral ID generated at the moment of insertion. The IDs can be obtained via call to index() of iterators created by find() methods.

Methods of FacetList:
erase(Set f)

Remove a facet.

Parameters:

Set f: facet to remove

Returns:
eraseSubsets(Set s)

Remove all subsets of a given set

Parameters:

Set s: filter for removal

Returns:
Int
eraseSupersets(Set s)

Remove all supersets of a given set

Parameters:

Set s: filter for removal

Returns:
Int
find(Set f)

Look up a facet.

Parameters:

Set f: facet to find

Returns:
findSubsets(Set s)

Find all subsets of a given set.

Parameters:

Set s

Returns:
findSupersets(Set s)

Find all supersets of a given set.

Parameters:

Set s

Returns:
insert(Set f)

Add a new facet. It may be a proper subset or a proper superset of existing facets. It must not be empty or coincide with any existing facet.

Parameters:

Set f: facet to add.

insertMax(Set f)

Add a new facet if and only if there are no facets including it. If this holds, remove all facets that are included in the new one.

Parameters:

Set f: facet to add

Returns:
insertMin(Set f)

Add a new facet if and only if there are no facets included in it. If this holds, remove all facets including the new facet.

Parameters:

Set f: facet to add

Returns:
n_vertices()

The number of vertices

Returns:
Int
size()

The number of facets in the list.

Returns:
Int

HashMap<Key, Value>

An unordered map based on a hash table. Its interface is similar to that of Map, but the order of elements is not stable across polymake sessions and does not correlate with key values. Accessing and inserting a value by its key works in constant time O(1). On the perl side HashMaps are treated like hashrefs. You can work with a HashMap like you work with a Map (keeping in mind differences in performance and memory demand).

Type Parameters:

Key: type of the key values

Value: type of the mapped value

Example:

You can create a new HashMap mapping Ints to Strings by

 > $myhashmap = new HashMap<Int, String>([1, "Monday"], [2, "Tuesday"]);
Methods of HashMap:
size()

Size of the map

Returns:
Int


HashSet<Element>

An unordered set of elements based on a hash table. Can be traversed as a normal container, but the order of elements is not stable across polymake sessions, even if the set is restored from the same data file every time.

Type Parameters:

Element

Methods of HashSet:
size()

The cardinality of the set.

Returns:
Int

IncidenceMatrix<Sym>

A 0/1 incidence matrix.

Type Parameters:

Sym: one of Symmetric or NonSymmetric, default: NonSymmetric

Methods of IncidenceMatrix:
col(Int i)

Returns the i-th column.

Parameters:

Int i

Returns:
cols()

Returns the number of columns.

Returns:
Int
elem(Int r, Int c)

Returns an element of the matrix as a boolean value. The return value is an `lvalue', that is, it can be assigned to, flipped, etc. if the matrix object is mutable.

Parameters:

Int r: the row index

Int c: the column index

Returns:
minor(Set r, Set c)

Returns a minor of the matrix containing the rows in r and the columns in c. You can pass All if you want all rows or columns and ~ for the complement of a set.

Parameters:

Set r: the rows

Set c: the columns

Returns:
Example:

For example,

 > print polytope::cube(2)->VERTICES_IN_FACETS->minor(All, ~[0]);
     {1}
     {0 2}
     {0}
     {1 2}
 

will give you the minor of a matrix containing all rows and all but the 0-th column.

row(Int i)

Returns the i-th row.

Parameters:

Int i

Returns:
rows()

Returns the number of rows.

Returns:
Int
squeeze

Removes empty rows and columns. The remaining rows and columns are renumbered without gaps.

squeeze_cols

Removes empty columns. The remaining columns are renumbered without gaps.

squeeze_rows

Removes empty rows. The remaining rows are renumbered without gaps.


Map<Key, Value>

Maps are sorted associative containers that contain unique key/value pairs. Maps are sorted by their keys. Accessing or inserting a value needs logarithmic time O(log n), where n is the size of the map.

Type Parameters:

Key: type of the key values

Value: type of the mapped value

Example:

You can create a new Map mapping Ints to Strings by

 > $mymap = new Map<Int, String>([1, "Monday"], [2, "Tuesday"]);

On the perl side Maps are treated like hashrefs. You can add a new key/value pair by

 > $mymap->{3} = "Wednesday";

(If the key is already contained in the Map, the corresponding value is replaced by the new one.) or ask for the value of a key by

 > print $mymap->{1};
 Monday


PowerSet<Element>

A Set whose elements are of type Set<Element>.

Type Parameters:

Element: default: Int

derived from:
Set

Set<Element>

A type for ordered sets containing elements of type Element.

Type Parameters:

Element: default: Int

Example:

You can for example create a new Set by:

 > $s1 = new Set(2, 3, 5, 7);
 > $s2 = new Set(4, 5);

You can perform set theoretic operations: union

 > print $s1 + $s2;
 {2 3 4 5 7}

intersection

 > print $s1 * $s2;
 {5}

difference

 > print $s1 - $s2;
 {2 3 7}

symmetric difference

 > print $s1 ^ $s2;
 {2 3 4 7}
Methods of Set:
back()

The last element of the set, that is, the largest element

Returns:
Int
collect(Element e)

Add to the set, report true if existed formerly.

Parameters:

Element e: element to insert into the set

Returns:
contains(Element e)

Check if e is contained in the set.

Parameters:

Element e: element check for

Returns:
front()

The first element of the set, that is, the smallest element

Returns:
Int
size()

The cardinality of the set.

Returns:
Int


Visualization

These property_types are for visualization.


Color

This is a pseudo-type for documentation purposes only. A function expecting an argument or option of type Color can digest an object of type RGB or HSV as well as a string with an RGB value in hex notation “#RRGGBB” or a symbolic color name.


Flexible

This is a pseudo-type for documentation purposes only. Many options of visualization functions modifying the appearance of some set of graphical elements like points, edges, facets, etc. accept a wide range of possible values, allowing for different grades of flexibility (and complexity):

  • SCALAR the same attribute value is applied to all elements
  • ARRAY each element gets its individual attribute value
  • HASH elements found in the hash get their individual attribute values, for the rest the appropriate default applies
  • SUB a piece of code computing the attribute value for the given element

Unless specified explicitly in the detailed option description, the indices, keys, or subroutine arguments used for retrieval of the attribute values are just the zero-based ordinal numbers of the elements.


HSV

A color described as a Hue-Saturation-Value triple. Is convertible to and from an RGB representation.


RGB

A color described as a Red-Green-Blue triple. Can be constructed from a list of three integral values from the range 0..255, or a hex triplet with a leading # symbol, or a list of three floating-point values from the range 0..1, or a symbolic name from the X11 color names.