Introduction to polyDB

The polyDB extension provides access to the polyDB database. It comes bundled with polymake, so there is no need to install extra software.

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

Note that the interface to the database has been rewritten and this tutorial already uses the version to be released with the next snapshot.

The polymake database

The database is hosted on the polymake server (at db.polymake.org, where you also find a web interface). 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 this command only lists those databases for which you have read access. By 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 two functions for basic read access: db_query and db_count. The function db_query returns an Array of polymake objects matching the query criteria, the function and db_count returns the number of such objects in the database.

db_query

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

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

polytope > $a = db_query({"DIM" => 3}, 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=db_query({'DIM' => 7}, db=>"LatticePolytopes", collection=>"SmoothReflexive", limit => 10);

polytope > print $a->size;
10

In addition the “normal” polymake properties, database objects have two additional properties:

  • Every object in a collection has a unique _id.
  • Every object has a metadata section that can contain
    • the contributor
    • the creation date
    • the name of the application in polymake
    • the version of polyDB the object was inserted with
    • the collection it is contained in
    • the database of the collection
    • the type of the object (currently only object is allowed, matrices etc cannot be stored in the db yet)

You can access the metadata with the db_print_metadata function

polytope > print $a->[1]->_id;
F.3D.0001
polytope > db_print_metadata_data($a->[1]);
collection: SmoothReflexive
contributor: Andreas Paffenholz
creation_date: 2016-08-30
database: LatticePolytopes
id: F.7D.000001
tag: object
version: 3.0

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:

$PolyDB::default::db_name = "LatticePolytopes";
$PolyDB::default::collection_name = "SmoothReflexive";

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

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

If you do

set_custom $PolyDB::default::db_name = "LatticePolytopes";
set_custom $PolyDB::default::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 $PolyDB::default::db_name and $PolyDB::default::collection_name are set as above.

only request a representative of a collection

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

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

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 = db_query({"_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 db_count({"DIM"=>3});
18
polytope > print db_count({"DIM"=>4});
124
polytope > print db_count({"DIM"=>5});
866
polytope > print db_count({"DIM"=>6});
7622
polytope > print db_count({"DIM"=>7});
72256
polytope > print db_count({"DIM"=>8});
749892

In fact, these numbers match those on the website.

db_ids

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

polytope > print 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 db_count({"N_VERTICES" => { '$lt' => 100 }});
107917

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

polytope > print 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 db_count({"_id" => qr/F.4D/});
124

We could also count those objects added in August 2013:

polytope > print 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 db_count on your query), you should construct a database cursor instead of using the function db_query.

$c = db_cursor({"DIM"=>4}, db=>"LatticePolytopes", collection=>"SmoothReflexive");
 

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 = db_cursor({"DIM"=>4}, db=>"LatticePolytopes", collection=>"SmoothReflexive", sort_by=>{'_id'=>1});

polytope > for ($i=1; $i<=10; ++$i) { print $c->next->name." "; }
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 = db_cursor({"DIM"=>4}, db=>"LatticePolytopes", collection=>"SmoothReflexive", 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 = db_cursor({"DIM"=>4}, db=>"LatticePolytopes", collection=>"SmoothReflexive", sort_by=>{'_id'=>1}, skip=>100);

polytope > for ($i=1; $i<=10; ++$i) { print $c->next->name." "; }
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: 2017/08/09 09:34 by paffenholz
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