Skip to content

Commit 547488d

Browse files
anujthakjames-d-mitchell
anujthak
authored and
james-d-mitchell
committed
Improve the documentation of the Digraph encoding formats
1 parent f82c9f1 commit 547488d

2 files changed

Lines changed: 95 additions & 60 deletions

File tree

‎doc/io.xml‎

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,88 @@
88
#############################################################################
99
##
1010

11+
12+
<#GAPDoc Label="EncodingFormats">
13+
<Subsection Label="EncodingFormats">
14+
<Heading>Encoding Formats</Heading>
15+
<List>
16+
<Mark> Graph6 </Mark>
17+
<Item>
18+
<E> Graph6 </E> is a graph data format for storing undirected graphs
19+
with no multiple edges nor loops of size up to <M> 2^{36} - 1 </M> in
20+
printable characters. Graphs that do not fit the above criteria cannot be
21+
guaranteed to be accurately encoded as Graph6. The format consists of two parts. The first part
22+
uses one to eight bytes to store the number of vertices. And the second
23+
part is the upper half of the adjacency matrix converted into ASCII
24+
characters. For a more detailed description see <URL Text='Graph6'>
25+
http://cs.anu.edu.au/~bdm/data/formats.txt</URL>.
26+
</Item>
27+
28+
<Mark> Sparse6 </Mark>
29+
<Item>
30+
<E> Sparse6 </E> is a graph data format for storing undirected graphs
31+
with possibly multiple edges or loops. The maximal number of vertices
32+
allowed is <M> 2^{36} - 1 </M>. The format consists of two parts. The
33+
first part uses one to eight bytes to store the number of vertices.
34+
And the second part only stores information about the edges.
35+
Therefore, the <E> Sparse6 </E> format return a more compact encoding
36+
then <E> Graph6 </E> for sparse graph, i.e. graphs where the number
37+
of edges is much less than the number of vertices squared. Sparse6 can
38+
faithfully encode any symmetric digraph. For a more
39+
detailed description see <URL Text='Sparse6'>
40+
http://cs.anu.edu.au/~bdm/data/formats.txt</URL>.
41+
</Item>
42+
43+
<Mark> Digraph6 </Mark>
44+
<Item>
45+
<E>Digraph6</E> is a new format based on <E> Graph6 </E>, but designed
46+
for digraphs. The entire adjacency matrix is stored, and
47+
therefore there is support for directed edges and single-vertex loops.
48+
However, multiple edges are not supported.
49+
</Item>
50+
51+
<Mark> DiSparse6 </Mark>
52+
<Item>
53+
<E>DiSparse6</E> is a new format based on <E> Sparse6 </E>, but
54+
designed for digraphs. In this format the list of edges is
55+
partitioned into increasing and decreasing edges, depending whether the
56+
edge has its source bigger than the range. Then both sets of edges are
57+
written separately in <E> Sparse6 </E> format with a separation symbol
58+
in between. Any digraph can be properly encoded with a DiSparse6 representation.
59+
</Item>
60+
<Mark> dreadnaut </Mark>
61+
<Item>
62+
<E>dreadnaut</E> is a graph data format designed for directed and undirected graphs.
63+
The format supports loops but multiple edges are ignored. The format consists of an
64+
initial section that defines the graph's structural properties, such as the number of
65+
vertices, the starting value for vertices, and whether the graph is directed. This is followed
66+
by a list of edges. For more information and examples of the format see
67+
<URL Text="nauty and Traces User's Guide">http://pallini.di.uniroma1.it/Guide.html</URL>.
68+
</Item>
69+
<Mark> DIMACS </Mark>
70+
<Item>
71+
<E>DIMACS</E> is a graph data format that can be used for symmetric digraphs.
72+
For a more detailed description, see <Ref Oper="WriteDIMACSDigraph"/>
73+
</Item>
74+
</List>
75+
76+
NOTE: These functions do not signal an error if <A>digraph</A> has features that
77+
the chosen format does not support. In that case the encoding may not be equal
78+
to <A>digraph</A>. For example, <C>Digraph6String</C>
79+
silently drops multiple edges, since Digraph6 stores only the adjacency
80+
matrix:
81+
<Log><![CDATA[
82+
gap> gr := Digraph([[2, 2], []]);
83+
<immutable multidigraph with 2 vertices, 2 edges>
84+
gap> Digraph6String(gr);
85+
"+AG"
86+
gap> DigraphFromDigraph6String(last) = gr;
87+
false
88+
]]></Log>
89+
90+
</Subsection>
91+
<#/GAPDoc>
92+
1193
<#GAPDoc Label="IteratorFromDigraphFile">
1294
<ManSection>
1395
<Func Name="IteratorFromDigraphFile" Arg="filename [, decoder]"/>
@@ -233,6 +315,10 @@ gap> DigraphFromGraph6String(IsMutableDigraph, "IheA@GUAo");
233315
be mutable or immutable.
234316
If no first argument is provided, then an immutable
235317
digraph is returned by default.
318+
319+
Note that some Digraphs will not be accurately recovered if they were
320+
encoded in an invalid format; see <Ref Subsect="EncodingFormats" Style="Number"/> for
321+
full limitations. <P/>
236322
<Example><![CDATA[
237323
gap> DigraphFromGraph6String("?");
238324
<immutable empty digraph with 0 vertices>
@@ -496,13 +582,18 @@ gap> ReadDigraphs(filename);
496582
<Oper Name="DiSparse6String" Arg="digraph"/>
497583
<Returns>A string.</Returns>
498584
<Description>
499-
These four functions return a highly compressed string fully describing the
585+
These four functions return a highly compressed string describing the
500586
digraph <A>digraph</A>. <P/>
501587

502588
Graph6 and Digraph6 are formats best used on small, dense graphs, if
503589
applicable. For larger, sparse graphs use <E>Sparse6</E> and
504590
<E>Disparse6</E> (this latter also preserves multiple edges). <P/>
505591

592+
A detailed description of the formats: Graph6, Digraph6,
593+
Sparse6, and DiSparse6, the kinds of digraphs that each format can encode,
594+
and their comparative strengths and weaknesses, is given in
595+
<Ref Subsect="EncodingFormats" Style="Number"/>. <P/>
596+
506597
See <Ref Func="WriteDigraphs"/>.
507598
<Example><![CDATA[
508599
gap> gr := Digraph([[2, 3], [1], [1]]);

‎doc/z-chap9.xml‎

Lines changed: 3 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -11,65 +11,9 @@
1111

1212
<Section><Heading>Reading and writing digraphs to a file</Heading>
1313
This section describes different ways to store and read graphs
14-
from a file in the &Digraphs; package.
15-
<List>
16-
<Mark> Graph6 </Mark>
17-
<Item>
18-
<E> Graph6 </E> is a graph data format for storing undirected graphs
19-
with no multiple edges nor loops of size up to <M> 2^{36} - 1 </M> in
20-
printable characters. The format consists of two parts. The first part
21-
uses one to eight bytes to store the number of vertices. And the second
22-
part is the upper half of the adjacency matrix converted into ASCII
23-
characters. For a more detail description see <URL Text='Graph6'>
24-
http://cs.anu.edu.au/~bdm/data/formats.txt</URL>.
25-
</Item>
26-
27-
<Mark> Sparse6 </Mark>
28-
<Item>
29-
<E> Sparse6 </E> is a graph data format for storing undirected graphs
30-
with possibly multiple edges or loops. The maximal number of vertices
31-
allowed is <M> 2^{36} - 1 </M>. The format consists of two parts. The
32-
first part uses one to eight bytes to store the number of vertices.
33-
And the second part only stores information about the edges.
34-
Therefore, the <E> Sparse6 </E> format return a more compact encoding
35-
then <E> Graph6 </E> for sparse graph, i.e. graphs where the number
36-
of edges is much less than the number of vertices squared. For a more
37-
detail description see <URL Text='Sparse6'>
38-
http://cs.anu.edu.au/~bdm/data/formats.txt</URL>.
39-
</Item>
40-
41-
<Mark> Digraph6 </Mark>
42-
<Item>
43-
<E>Digraph6</E> is a new format based on <E> Graph6 </E>, but designed
44-
for digraphs. The entire adjacency matrix is stored, and
45-
therefore there is support for directed edges and single-vertex loops.
46-
However, multiple edges are not supported.
47-
</Item>
48-
49-
<Mark> DiSparse6 </Mark>
50-
<Item>
51-
<E>DiSparse6</E> is a new format based on <E> Sparse6 </E>, but
52-
designed for digraphs. In this format the list of edges is
53-
partitioned into increasing and decreasing edges, depending whether the
54-
edge has its source bigger than the range. Then both sets of edges are
55-
written separately in <E> Sparse6 </E> format with a separation symbol
56-
in between.
57-
</Item>
58-
<Mark> dreadnaut </Mark>
59-
<Item>
60-
<E>dreadnaut</E> is a graph data format designed for directed and undirected graphs.
61-
The format supports loops but multiple edges are ignored. The format consists of an
62-
initial section that defines the graph's structural properties, such as the number of
63-
vertices, the starting value for vertices, and whether the graph is directed. This is followed
64-
by a list of edges. For more information and examples of the format see
65-
<URL Text="nauty and Traces User's Guide">http://pallini.di.uniroma1.it/Guide.html</URL>.
66-
</Item>
67-
<Mark> DIMACS </Mark>
68-
<Item>
69-
<E>DIMACS</E> is a graph data format that can be used for symmetric digraphs.
70-
For a more detailed description, see <Ref Oper="WriteDIMACSDigraph"/>
71-
</Item>
72-
</List>
14+
from a file in the &Digraphs; package as well as their limitations.
15+
16+
<#Include Label="EncodingFormats">
7317
<#Include Label="String">
7418
<#Include Label="DigraphFromGraph6String">
7519
<#Include Label="Graph6String">

0 commit comments

Comments
 (0)