Introduction to polyDB

The polyDB extension provides access to the polymake polytope database.

If you encounter any errors or problems concerning polyDB, please don't hesitate to contact me.

Getting polyDB

See here for download and installation instructions and here for the latest development version (on GitHub).

The polymake database

The database is hosted on the polymake server (on polymake.org). The objects are arranged in collections which reside in so-called databases. See here for a list of available databases and collections.

From the polymake shell the function db_info prints information about available databases and collections.

polytope > db_info();
DATABASE: LatticePolytopes
This database contains various classes of lattice polytopes.

Collection: SmoothReflexive
All smooth reflexive lattice polytopes in dimensions up to 8 up to lattice equivalence. The lists were computed with the algorithm of Mikkel Oebro (see [[http://arxiv.org/abs/0704.0049|arxiv: 0704.0049]]) and are taken from the [[http://polymake.org/polytopes/paffenholz/www/fano.html|website of Andreas Paffenholz]].

In dimensions up to 7 the database contains the properties:
H_STAR_VECTOR, REFLEXIVE, CONE_DIM, date, _id, LATTICE_CODEGREE, N_INTERIOR_LATTICE_POINTS, SMOOTH, N_LATTICE_POINTS, FACET_WIDTHS, VERTICES, FACETS, CENTROID, N_VERTICES, contributor, LATTICE_DEGREE, LATTICE_VOLUME, EHRHART_POLYNOMIAL_COEFF, N_BOUNDARY_LATTICE_POINTS, ESSENTIALLY_GENERIC, VERY_AMPLE, F_VECTOR, GORENSTEIN, FEASIBLE, LINEALITY_SPACE, AFFINE_HULL.

In dimension 8 it only contains the minimal set:
LINEALITY_SPACE, CONE_DIM, date, _id, VERTICES, FEASIBLE, N_VERTICES, contributor.

__________________

DATABASE: Tropical
This database contains tropical objects.

Collection: TOM
All known non-realisable tropical oriented matroids with parameters n=6, d=3 or n=d=4. They were computed using polymake with the tropmat extension and Topcom. You need the extension [[http://solros.de/polymake/tropmat|tropmat]] for this.

__________________

Note that is only lists those databases that for which you have read access. But specifying the appropriate options you can also restrict the output to a subset of the databases and collections.

It is also possible to host your own database on your server. This is, however, not yet documented.

Basic database access

In this tutorial we are going to use the collection SmoothReflexive in the database LatticePolytopes, which contains all smooth reflexive lattice polytopes in dimensions up to 8.

The extension provides three functions for basic read access: poly_db, poly_db_one and poly_db_count. The function poly_db returns an Array of polymake objects matching the query criteria, the function poly_db_one returns just one matching object and poly_db_count returns the number of such objects in the database.

poly_db

Note that you should not use this function if you expect a large number of objects to match your search criteria. (Check this with poly_db_count.) In this case create a DatabaseCursor instead.

Assume we want to have all smooth reflexive lattice polytopes in dimension 3. The function poly_db expects a query, which is a hash mapping properties to values, and as options (a.o.) a database and a collection name. The right property to ask for is CONE_DIM, which is DIM+1. The following code returns an Array<LatticePolytope> of all 3-dimensional polytopes in the specified collection.

polytope > $a = poly_db({"CONE_DIM" => 4}, db=>"LatticePolytopes", collection=>"SmoothReflexive");

Note that (depending on server capacity and network speed) this may take a while. Sometimes it might even result in a time out. In this case just try again (and feel free to contact us if the problem persists).

Now we can browse through the elements of $a and inspect their properties, e.g.:

polytope > print $a->[0]->SMOOTH;
1
polytope > print $a->[0]->REFLEXIVE;
1
polytope > print $a->[0]->VERTICES;
1 1 1 0
1 1 0 0
1 0 1 -1
1 1 -2 1
1 1 1 1
1 0 1 1
1 0 -3 1
1 -4 1 -3
polytope > print $a->size;
18

If you only want a limited number of objects, you can use the limit option:

polytope > $a=poly_db({'CONE_DIM' => 8}, db=>"LatticePolytopes", collection=>"SmoothReflexive", limit => 10);

polytope > print $a->size;
10

In addition the “normal” polymake properties, database objects have three additional properties: Every object in a collection has a unique _id. Moreover, the date the object was added to the database and a contributor, who provided the data (in the smooth reflexive case the polytopes were taken from the website of Andreas Paffenholz), are recorded:

polytope > print $a->[1]->_id;
F.3D.0001
polytope > print $a->[1]->date;
2013-08-14
polytope > print $a->[1]->contributor;
Andreas Paffenholz

Custom variables

If you are going to access the same collection all the time, you can set the custom variables $db_name and $collection_name:

$db_name = "LatticePolytopes";
$collection_name = "SmoothReflexive";

These variables are used as default for the database and collection name if you omit the options of poly_db, poly_db_one and poly_db_count, e.g.:

$a = poly_db({"CONE_DIM"=>5, "N_VERTICES"=>15});

If you do

set_custom $db_name = "LatticePolytopes";
set_custom $collection_name = "SmoothReflexive";

these settings will be saved in your preference file and still be available after restarting polymake.

In the code examples below it is assumed that $db_name and $collection_name are set as above.

poly_db_one

You can use the poly_db_one function if you are only looking for one arbitrary example matching certain query criteria, e.g.:

polytope > $p = poly_db_one({"CONE_DIM"=>4, "N_VERTICES"=>10});

polytope > print $p->_id;
F.3D.0002
polytope > print $p->DIM;
3
polytope > print $p->N_VERTICES;
10  

Note that you might get a different polytope (with another _id) if you repeat the above code.

You can also use this function to extract a polytope with a certain _id:

polytope > $p = poly_db_one({"_id"=>"F.4D.0123"});

poly_db_count

The function poly_db_count returns the number of objects matching your query criteria, e.g.:

polytope > print poly_db_count({"CONE_DIM"=>4});
18
polytope > print poly_db_count({"CONE_DIM"=>5});
124
polytope > print poly_db_count({"CONE_DIM"=>6});
866
polytope > print poly_db_count({"CONE_DIM"=>7});
7622
polytope > print poly_db_count({"CONE_DIM"=>8});
72256
polytope > print poly_db_count({"CONE_DIM"=>9});
749892

In fact, these numbers match those on the website.

poly_db_ids

There is another function poly_db_ids that is very similar to poly_db but only returns an array of IDs, e.g.:

polytope > print poly_db_ids({'CONE_DIM' => 8}, db=>"LatticePolytopes", collection=>"SmoothReflexive", limit => 10);
F.7D.009999 F.7D.000000 F.7D.000001 F.7D.000002 F.7D.000003 F.7D.000004 F.7D.000005 F.7D.000006 F.7D.000007 F.7D.000008

Advanced queries

Instead of specifying the exact value of a property we might be interested in specifying ranges for numerical properties.

The following queries the polytopes with (strictly) less than 100 vertices:

polytope > print poly_db_count({"N_VERTICES" => { '$lt' => 100 }});
107917

You can also query those with less than 100 but (strictly) more than 50 vertices:

polytope > print poly_db_count({"N_VERTICES" => { '$lt' => 100, '$gt' => 50 }});
97595

The operators $lte (for less than or equal) and $gte (for greater than or equal) are also supported.

You can also use regular expressions to search for strings. Since there are not so many string-valued properties around, let's try with the _id. The following is another way to count 4-dimensional polytopes (those with _id beginning with F.4D).

polytope > print poly_db_count({"_id" => qr/F.4D/});
124

We could also count those objects added in August 2013:

polytope > print poly_db_count({"date" => qr/2013-08-/});
80886  

Using a DatabaseCursor

If you expect your query to match a large number of objects (which you can find out using poly_db_count on your query), you should construct a DatabaseCursor instead of using the function poly_db. You initialize this with a DATABASE, a COLLECTION and a QUERY. (If you don't specify DATABASE and COLLECTION it will try to use the custom variables to determine them.)

$c = new DatabaseCursor(DATABASE=>"LatticePolytopes", COLLECTION=>"SmoothReflexive", QUERY=>{"CONE_DIM"=>5});

It has a property COUNT that knows the number of objects matching the QUERY:

polytope > print $c->COUNT;
124

Moreover, it possesses two user_methods next and has_next, that you can use to iterate over the objects.

polytope > while ($c->has_next) { print $c->next->N_VERTICES." "; }
11 8 17 13 15 18 15 16 12 12 15 16 16 12 16 16 16 13 12 12 9 21 17 17 23 30 13 17 15 18 16 15 12 17 21 21 18 24 18 17 16 13 13 12 15 12 9 20 24 20 16 16 20 20 24 20 24 20 20 16 20 24 20 21 20 24 24 20 20 16 16 16 16 12 25 30 36 20 24 20 16 16 16 20 16 12 17 16 16 16 16 20 16 12 15 18 15 20 24 18 15 15 16 11 11 12 12 12 13 16 16 12 12 12 8 8 12 9 16 12 8 8 9 5

While iterating over the objects, it lazily fetches more objects from the database server. Note though that you have to create a new cursor if you want to start from the beginning.

Sorting, etc.

If you want the objects to be retrieved in a certain order, the property SORT_BY allows to specify a sorting order. E.g. assume you want to sort ascending by _id

polytope > $c = new DatabaseCursor(QUERY=>{'CONE_DIM'=>5}, SORT_BY=>{'_id'=>1});

polytope > for ($i=1; $i<=10; ++$i) { print $c->next->_id." "; }
F.4D.0000 F.4D.0001 F.4D.0002 F.4D.0003 F.4D.0004 F.4D.0005 F.4D.0006 F.4D.0007 F.4D.0008 F.4D.0009

… or descending by number of vertices:

polytope > $c = new DatabaseCursor(QUERY=>{'CONE_DIM'=>5}, SORT_BY=>{'N_VERTICES'=>-1});

polytope > while($c->has_next){print $c->next->N_VERTICES." ";}
36 30 30 25 24 24 24 24 24 24 24 24 24 23 21 21 21 21 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 18 18 18 18 18 18 17 17 17 17 17 17 17 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 16 15 15 15 15 15 15 15 15 15 15 13 13 13 13 13 13 12 12 12 12 12 12 12 12 12 12 12 12 12 12 12 12 12 12 12 11 11 11 9 9 9 9 8 8 8 8 8 5

(Use 1 for ascending and -1 for descending.)

If you want to skip the first few objects, you can do so by specifying SKIP:

polytope > $c = new DatabaseCursor(QUERY=>{'CONE_DIM'=>5}, SORT_BY=>{'_id'=>1}, SKIP=>100);

polytope > for ($i=1; $i<=10; ++$i) { print $c->next->_id." "; }
F.4D.0100 F.4D.0101 F.4D.0102 F.4D.0103 F.4D.0104 F.4D.0105 F.4D.0106 F.4D.0107 F.4D.0108 F.4D.0109
tutorial/poly_db_tutorial.txt · Last modified: 2014/03/27 14:16 by joswig
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki