Database interface for Sage

Setup

• Copy folder discretezoo into the working folder.
• data/example.s6 contains first eight CVT graphs in sparse6 format.
• Upon import, the graphs are stored in a SQLite file .discretezoo/discretezoo.db in the home directory.
• A database is available which contains:
  • all connected cubic vertex-transitive graphs with at most 1280 vertices (from the census by P. Potočnik, P. Spiga and G. Verret),
  • all connected cubic arc-transitive graphs with at most 2048 vertices (from the extended Foster census by M. Conder), and
  • all vertex-transitive graphs with at most 31 vertices (from the census by G. Royle)

import discretezoo
discretezoo.entities.cvt.import_cvt("data/example.s6") # to import the sample data
discretezoo.DEFAULT_DB.importDB("/path/to/discretezoo.db") # to import the downloaded database

• It is possible to import only selected functions and objects.

from discretezoo.entities.cvt import CVTGraph # import only the CVTGraph constructor.
G = CVTGraph(10, 3)

User functions

The discretezoo package contains all DiscreteZOO-related functionality.

Constructors

• discretezoo.entities.vt.VTGraph() accepts parameters n and k and returns the graph of order n and index k in the G. Royle's census.
• discretezoo.entities.cvt.CVTGraph() accepts parameters n and k and returns the graph of order n and index k in the CVT census. Alternatively, it accepts a parameter n and a named parameter symcubic_index and returns the graph of order n and index symcubic_index in the extended Foster census.
• discretezoo.entities.spx.SPXGraph() accepts parameters r and s and returns the graph SPX(2, r, s) (currently, only the graphs appearing in the CVT census are available).

Additionally, a generic graph constructor discretezoo.entities.zoograph.ZooGraph() is also available. Besides the parameters mentioned above, each of these constructors also accepts:

• a Sage GenericGraph object (providing a graph whose type is one of the above classes will retain the fields and methods particular to that class),
• a "unique id" (a SHA-256 hash of the sparse6 string of a canonical labelling of the graph),
• a database row ID (this is not guaranteed to be constant over distinct copies of the database).

Querying

For each data class there is an object info in the same module which provides the following functions (as of 3ae245b):

• count(groupby = [], ...) - Returns the number of objects in the database matching the criteria. If a property name (or a list or set of them) is given for the groupby argument, counting is done for each value of the specified properties.

• all(orderby = [], limit = None, offset = None, ...) - Returns a generator returning all objects in the database matching the criteria, sorted by the values of the properties specified in the orderby argument with an optional offset. Sorting order for each property can be specified by passing a tuple of the form (prop, bool) as an element of orderby, where prop is the name of the property and bool is a boolean value specifying the sort order (True for ascending, False for descending).

• one(orderby = [], offset = None, ...) - Returns the first object matching the specified criteria. orderby and offset work as above.

• props(orderby = [], limit = None, offset = None, ...) - Returns a generator returning data on all objects in the database matching the criteria as a dictionary. orderby, limit and offset work as above.

The criteria can be specified either as a key = value parameter, or as an expression of type discretezoo.query.Expression. These can be constructed from one such expression using usual arithmetic operators and comparisons with other expressions or raw values (where strings are taken to be column names, and numbers are taken for their value). discretezoo.C and discretezoo.V are provided as aliases of discretezoo.query.Column and discretezoo.query.Value.

Examples

from discretezoo.entities.cvt import CVTGraph

G = CVTGraph(10, 3) # Petersen graph
# This returns a CVTGraph object with cached properties returned from the database
G.is_isomorphic(graphs.PetersenGraph()) # True
G.girth() # Returns the girth of G from the database.
G.is_cayley() # Returns whether G is a Cayley graph

from discretezoo.entities.cvt import info # The object providing query methods
from discretezoo.entities.cvt.fields import * # The fields relevant for CVT graphs
from discretezoo.db.query import * # Additional objects useful for querying

info.count() # The number of CVT graphs in the database
info.count(diameter == 5) # The number of CVT graphs with diameter 5
info.count(diameter == 5, girth == 7) # The number of CVT graphs with diameter 5 and girth 7
info.count(diameter == 5, groupby = girth) # The number of CVT graphs with diameter 5 broken down by girth
info.count(groupby = [girth, diameter]) # The number of CVT graphs for each (girth, diameter) pair
info.count(order < 500) # The number of CVT graphs of order less than 500
info.count(V(500) > order) # Same as above - note that an Expression must appear on the left side of a comparison!
info.count(girth + diameter == 10) # The number of CVT graphs whose girth and diameter sum to 10
info.count((girth == 8) | (diameter == 10)) # The number of CVT graphs with girth 8 or diameter 10 - note that | has high precedence, so parentheses must be used
info.count((girth == 8) | ((diameter == 10) & (order < 100))) # In nested expressions, & should be used for conjunction

gen = info.all(girth == 5, orderby = order) # CVT graphs with girth 5 ordered by their order
G1 = next(gen) # CVT(10, 3) = Petersen graph
G2 = next(gen) # CVT(20, 6) = Dodecahedron
G3 = next(gen) # CVT(30, 10)
F1, F2 = info.all(girth + diameter == order) # both CVT graphs with the order equal to the sum of girth and diameter

# The list of all CVT graphs of diameter 6, sorted first by descending girth and then by ascending order
L = list(info.all(diameter == 6, orderby = [Desc(girth), Asc(order)]))

H1 = info.one(order = 288, orderby = Desc(girth)) # A CVT graph of order 288 with largest girth
H2 = info.one(order = 288, orderby = Desc(girth), offset = 1) # A second such graph
H3 = info.one(girth >= 6, diameter == 4) # A graph with girth at least 6 and diameter 4

L = list(info.props(~is_cayley, girth == 13)) # the data on non-Cayley CVT graphs with girth 13
H = CVTGraph(L[0]) # constructing a graph from the data

from discretezoo import info # discretezoo.info is an alias for discretezoo.entities.zoograph.info
info.count() # The number of all graphs in the database