diff --git a/doc/io.xml b/doc/io.xml index 6064ebd67..d0e08f80b 100644 --- a/doc/io.xml +++ b/doc/io.xml @@ -8,6 +8,88 @@ ############################################################################# ## + +<#GAPDoc Label="EncodingFormats"> + + Encoding Formats + + Graph6 + + Graph6 is a graph data format for storing undirected graphs + with no multiple edges nor loops of size up to 2^{36} - 1 in + printable characters. Graphs that do not fit the above criteria cannot be + guaranteed to be accurately encoded as Graph6. The format consists of two parts. The first part + uses one to eight bytes to store the number of vertices. And the second + part is the upper half of the adjacency matrix converted into ASCII + characters. For a more detailed description see + http://cs.anu.edu.au/~bdm/data/formats.txt. + + + Sparse6 + + Sparse6 is a graph data format for storing undirected graphs + with possibly multiple edges or loops. The maximal number of vertices + allowed is 2^{36} - 1 . The format consists of two parts. The + first part uses one to eight bytes to store the number of vertices. + And the second part only stores information about the edges. + Therefore, the Sparse6 format return a more compact encoding + then Graph6 for sparse graph, i.e. graphs where the number + of edges is much less than the number of vertices squared. Sparse6 can + faithfully encode any symmetric digraph. For a more + detailed description see + http://cs.anu.edu.au/~bdm/data/formats.txt. + + + Digraph6 + + Digraph6 is a new format based on Graph6 , but designed + for digraphs. The entire adjacency matrix is stored, and + therefore there is support for directed edges and single-vertex loops. + However, multiple edges are not supported. + + + DiSparse6 + + DiSparse6 is a new format based on Sparse6 , but + designed for digraphs. In this format the list of edges is + partitioned into increasing and decreasing edges, depending whether the + edge has its source bigger than the range. Then both sets of edges are + written separately in Sparse6 format with a separation symbol + in between. Any digraph can be properly encoded with a DiSparse6 representation. + + dreadnaut + + dreadnaut is a graph data format designed for directed and undirected graphs. + The format supports loops but multiple edges are ignored. The format consists of an + initial section that defines the graph's structural properties, such as the number of + vertices, the starting value for vertices, and whether the graph is directed. This is followed + by a list of edges. For more information and examples of the format see + http://pallini.di.uniroma1.it/Guide.html. + + DIMACS + + DIMACS is a graph data format that can be used for symmetric digraphs. + For a more detailed description, see + + + + NOTE: These functions do not signal an error if digraph has features that + the chosen format does not support. In that case the encoding may not be equal + to digraph. For example, Digraph6String + silently drops multiple edges, since Digraph6 stores only the adjacency + matrix: + gr := Digraph([[2, 2], []]); + +gap> Digraph6String(gr); +"+AG" +gap> DigraphFromDigraph6String(last) = gr; +false +]]> + + +<#/GAPDoc> + <#GAPDoc Label="IteratorFromDigraphFile"> @@ -233,6 +315,10 @@ gap> DigraphFromGraph6String(IsMutableDigraph, "IheA@GUAo"); be mutable or immutable. If no first argument is provided, then an immutable digraph is returned by default. + + Note that some Digraphs will not be accurately recovered if they were + encoded in an invalid format; see for + full limitations.

DigraphFromGraph6String("?"); @@ -496,13 +582,18 @@ gap> ReadDigraphs(filename); A string. - These four functions return a highly compressed string fully describing the + These four functions return a highly compressed string describing the digraph digraph.

Graph6 and Digraph6 are formats best used on small, dense graphs, if applicable. For larger, sparse graphs use Sparse6 and Disparse6 (this latter also preserves multiple edges).

+ A detailed description of the formats: Graph6, Digraph6, + Sparse6, and DiSparse6, the kinds of digraphs that each format can encode, + and their comparative strengths and weaknesses, is given in + .

+ See . gr := Digraph([[2, 3], [1], [1]]); diff --git a/doc/z-chap9.xml b/doc/z-chap9.xml index 42adee63f..a3599c40a 100644 --- a/doc/z-chap9.xml +++ b/doc/z-chap9.xml @@ -11,65 +11,9 @@

Reading and writing digraphs to a file This section describes different ways to store and read graphs - from a file in the &Digraphs; package. - - Graph6 - - Graph6 is a graph data format for storing undirected graphs - with no multiple edges nor loops of size up to 2^{36} - 1 in - printable characters. The format consists of two parts. The first part - uses one to eight bytes to store the number of vertices. And the second - part is the upper half of the adjacency matrix converted into ASCII - characters. For a more detail description see - http://cs.anu.edu.au/~bdm/data/formats.txt. - - - Sparse6 - - Sparse6 is a graph data format for storing undirected graphs - with possibly multiple edges or loops. The maximal number of vertices - allowed is 2^{36} - 1 . The format consists of two parts. The - first part uses one to eight bytes to store the number of vertices. - And the second part only stores information about the edges. - Therefore, the Sparse6 format return a more compact encoding - then Graph6 for sparse graph, i.e. graphs where the number - of edges is much less than the number of vertices squared. For a more - detail description see - http://cs.anu.edu.au/~bdm/data/formats.txt. - - - Digraph6 - - Digraph6 is a new format based on Graph6 , but designed - for digraphs. The entire adjacency matrix is stored, and - therefore there is support for directed edges and single-vertex loops. - However, multiple edges are not supported. - - - DiSparse6 - - DiSparse6 is a new format based on Sparse6 , but - designed for digraphs. In this format the list of edges is - partitioned into increasing and decreasing edges, depending whether the - edge has its source bigger than the range. Then both sets of edges are - written separately in Sparse6 format with a separation symbol - in between. - - dreadnaut - - dreadnaut is a graph data format designed for directed and undirected graphs. - The format supports loops but multiple edges are ignored. The format consists of an - initial section that defines the graph's structural properties, such as the number of - vertices, the starting value for vertices, and whether the graph is directed. This is followed - by a list of edges. For more information and examples of the format see - http://pallini.di.uniroma1.it/Guide.html. - - DIMACS - - DIMACS is a graph data format that can be used for symmetric digraphs. - For a more detailed description, see - - + from a file in the &Digraphs; package as well as their limitations. + + <#Include Label="EncodingFormats"> <#Include Label="String"> <#Include Label="DigraphFromGraph6String"> <#Include Label="Graph6String">