External Representations of Block Designs

The “ext_rep” module is an API to the abstract tree represented by an XML document containing the External Representation of a list of block designs. The module also provides the related I/O operations for reading/writing ext-rep files or data. The parsing is based on expat.

This is a modified form of the module ext_rep.py (version 0.8) written by Peter Dobcsanyi [Do2009] peter@designtheory.org.

Todo

The XML data from the designtheory.org database contains a wealth of information about things like automorphism groups, transitivity, cycle type representatives, etc, but none of this data is made available through the current implementation.

Functions

class sage.combinat.designs.ext_rep.XTree(node)[source]

Bases: object

A lazy class to wrap a rooted tree representing an XML document. The tree’s nodes are tuples of the structure:

(name, {dictionary of attributes}, [list of children])

Methods and services of an XTree object t:

  • t.attribute – attribute named

  • t.child – first child named

  • t[i] – \(i\)-th child

  • for child in t: – iterate over t’s children

  • len(t) – number of t’s children

If child is not an empty subtree, return the subtree as an XTree object. If child is an empty subtree, return _name of the subtree. Otherwise return the child itself.

The lazy tree idea originated from a utility class of the pyRXP 0.9 package by Robin Becker at ReportLab.

class sage.combinat.designs.ext_rep.XTreeProcessor[source]

Bases: object

An incremental event-driven parser for ext-rep documents. The processing stages:

  • <list_of_designs ...> opening element. call-back: list_of_designs_proc

  • <list_definition> subtree. call-back: list_definition_proc

  • <info> subtree. call-back: info_proc

  • iterating over <designs> processing each <block_design> separately. call-back: block_design_proc

  • finishing with closing </designs> and </list_of_designs>.

parse(xml_source)[source]

The main parsing function. Given an XML source (either a file handle or a string), parse the entire XML source.

EXAMPLES:

sage: from sage.combinat.designs import ext_rep
sage: file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
sage: proc = ext_rep.XTreeProcessor()
sage: proc.save_designs = True
sage: f = ext_rep.open_extrep_file(file_loc)
sage: proc.parse(f)
sage: f.close()
sage: os.remove(file_loc)
sage: proc.list_of_designs[0]
(2, [[0, 1], [0, 1]])

>>> from sage.all import *
>>> from sage.combinat.designs import ext_rep
>>> file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
>>> proc = ext_rep.XTreeProcessor()
>>> proc.save_designs = True
>>> f = ext_rep.open_extrep_file(file_loc)
>>> proc.parse(f)
>>> f.close()
>>> os.remove(file_loc)
>>> proc.list_of_designs[Integer(0)]
(2, [[0, 1], [0, 1]])
sage.combinat.designs.ext_rep.check_dtrs_protocols(input_name, input_pv)[source]

Check that the XML data is in a valid format. We can currently handle version 2.0. For more information see http://designtheory.org/library/extrep/

EXAMPLES:

sage: from sage.combinat.designs import ext_rep
sage: ext_rep.check_dtrs_protocols('source', '2.0')
sage: ext_rep.check_dtrs_protocols('source', '3.0')
Traceback (most recent call last):
...
RuntimeError: Incompatible dtrs_protocols: program: 2.0 source: 3.0

>>> from sage.all import *
>>> from sage.combinat.designs import ext_rep
>>> ext_rep.check_dtrs_protocols('source', '2.0')
>>> ext_rep.check_dtrs_protocols('source', '3.0')
Traceback (most recent call last):
...
RuntimeError: Incompatible dtrs_protocols: program: 2.0 source: 3.0
sage.combinat.designs.ext_rep.designs_from_XML(fname)[source]

Return a list of designs contained in an XML file fname. The list contains tuples of the form (v, bs) where v is the number of points of the design and bs is the list of blocks.

EXAMPLES:

sage: from sage.combinat.designs import ext_rep
sage: file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
sage: ext_rep.designs_from_XML(file_loc)[0]
(2, [[0, 1], [0, 1]])
sage: os.remove(file_loc)

sage: from sage.combinat.designs import ext_rep
sage: from sage.combinat.designs.block_design import BlockDesign
sage: file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
sage: v, blocks = ext_rep.designs_from_XML(file_loc)[0]
sage: d = BlockDesign(v, blocks)
sage: d.blocks()
[[0, 1], [0, 1]]
sage: d.is_t_design(t=2)
True
sage: d.is_t_design(return_parameters=True)
(True, (2, 2, 2, 2))

>>> from sage.all import *
>>> from sage.combinat.designs import ext_rep
>>> file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
>>> ext_rep.designs_from_XML(file_loc)[Integer(0)]
(2, [[0, 1], [0, 1]])
>>> os.remove(file_loc)

>>> from sage.combinat.designs import ext_rep
>>> from sage.combinat.designs.block_design import BlockDesign
>>> file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
>>> v, blocks = ext_rep.designs_from_XML(file_loc)[Integer(0)]
>>> d = BlockDesign(v, blocks)
>>> d.blocks()
[[0, 1], [0, 1]]
>>> d.is_t_design(t=Integer(2))
True
>>> d.is_t_design(return_parameters=True)
(True, (2, 2, 2, 2))
sage.combinat.designs.ext_rep.designs_from_XML_url(url)[source]

Return a list of designs contained in an XML file named by a URL. The list contains tuples of the form (v, bs) where v is the number of points of the design and bs is the list of blocks.

EXAMPLES:

sage: from sage.combinat.designs import ext_rep
sage: file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
sage: ext_rep.designs_from_XML_url("file://" + file_loc)[0]
(2, [[0, 1], [0, 1]])
sage: os.remove(file_loc)

sage: from sage.combinat.designs import ext_rep
sage: ext_rep.designs_from_XML_url("http://designtheory.org/database/v-b-k/v3-b6-k2.icgsa.txt.bz2") # optional - internet
[(3, [[0, 1], [0, 1], [0, 1], [0, 1], [0, 1], [0, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 1], [0, 2], [0, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 1], [0, 2], [1, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 2], [0, 2], [0, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 2], [0, 2], [1, 2]]),
 (3, [[0, 1], [0, 1], [0, 2], [0, 2], [1, 2], [1, 2]])]

>>> from sage.all import *
>>> from sage.combinat.designs import ext_rep
>>> file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
>>> ext_rep.designs_from_XML_url("file://" + file_loc)[Integer(0)]
(2, [[0, 1], [0, 1]])
>>> os.remove(file_loc)

>>> from sage.combinat.designs import ext_rep
>>> ext_rep.designs_from_XML_url("http://designtheory.org/database/v-b-k/v3-b6-k2.icgsa.txt.bz2") # optional - internet
[(3, [[0, 1], [0, 1], [0, 1], [0, 1], [0, 1], [0, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 1], [0, 2], [0, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 1], [0, 2], [1, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 2], [0, 2], [0, 2]]),
 (3, [[0, 1], [0, 1], [0, 1], [0, 2], [0, 2], [1, 2]]),
 (3, [[0, 1], [0, 1], [0, 2], [0, 2], [1, 2], [1, 2]])]
sage.combinat.designs.ext_rep.dump_to_tmpfile(s)[source]

Utility function to dump a string to a temporary file.

EXAMPLES:

sage: from sage.combinat.designs import ext_rep
sage: file_loc = ext_rep.dump_to_tmpfile("boo")
sage: os.remove(file_loc)

>>> from sage.all import *
>>> from sage.combinat.designs import ext_rep
>>> file_loc = ext_rep.dump_to_tmpfile("boo")
>>> os.remove(file_loc)
sage.combinat.designs.ext_rep.open_extrep_file(fname)[source]

Try to guess the compression type from extension and open the extrep file.

EXAMPLES:

sage: from sage.combinat.designs import ext_rep
sage: file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
sage: proc = ext_rep.XTreeProcessor()
sage: f = ext_rep.open_extrep_file(file_loc)
sage: proc.parse(f)
sage: f.close()
sage: os.remove(file_loc)

>>> from sage.all import *
>>> from sage.combinat.designs import ext_rep
>>> file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
>>> proc = ext_rep.XTreeProcessor()
>>> f = ext_rep.open_extrep_file(file_loc)
>>> proc.parse(f)
>>> f.close()
>>> os.remove(file_loc)
sage.combinat.designs.ext_rep.open_extrep_url(url)[source]

Try to guess the compression type from extension and open the extrep file pointed to by the url. This function (unlike open_extrep_file) returns the uncompressed text contained in the file.

EXAMPLES:

sage: from sage.combinat.designs import ext_rep
sage: file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
sage: proc = ext_rep.XTreeProcessor()
sage: s = ext_rep.open_extrep_url("file://" + file_loc)
sage: proc.parse(s)
sage: os.remove(file_loc)

sage: from sage.combinat.designs import ext_rep
sage: s = ext_rep.designs_from_XML_url("http://designtheory.org/database/v-b-k/v3-b6-k2.icgsa.txt.bz2") # optional - internet

>>> from sage.all import *
>>> from sage.combinat.designs import ext_rep
>>> file_loc = ext_rep.dump_to_tmpfile(ext_rep.v2_b2_k2_icgsa)
>>> proc = ext_rep.XTreeProcessor()
>>> s = ext_rep.open_extrep_url("file://" + file_loc)
>>> proc.parse(s)
>>> os.remove(file_loc)

>>> from sage.combinat.designs import ext_rep
>>> s = ext_rep.designs_from_XML_url("http://designtheory.org/database/v-b-k/v3-b6-k2.icgsa.txt.bz2") # optional - internet