From 1e53cf45da8cfb64db71b590ea6bcdfd04750927 Mon Sep 17 00:00:00 2001 From: William Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Wed, 30 Sep 2026 15:33:59 +0100 Subject: [PATCH] Fix issue #861, removing duplication of digraph encoding --- doc/io.xml | 390 +++++++++++++++-------------------------------------- 1 file changed, 105 insertions(+), 285 deletions(-) diff --git a/doc/io.xml b/doc/io.xml index c1caf5156..24768ddaf 100644 --- a/doc/io.xml +++ b/doc/io.xml @@ -13,19 +13,19 @@ Encoding Formats - Graph6 + Graph6 (.g6) 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. + 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 (.s6) Sparse6 is a graph data format for storing undirected graphs with possibly multiple edges or loops. The maximal number of vertices @@ -40,7 +40,7 @@ http://cs.anu.edu.au/~bdm/data/formats.txt. - Digraph6 + Digraph6 (.d6) Digraph6 is a new format based on Graph6 , but designed for digraphs. The entire adjacency matrix is stored, and @@ -48,36 +48,62 @@ However, multiple edges are not supported. - DiSparse6 + DiSparse6 (.ds6) 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. + in between. Any digraph can be properly encoded with a DiSparse6 + representation. - dreadnaut + + dreadnaut (.dre) + + 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) - 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 is a graph data format that can be used for symmetric digraphs. + For a more detailed description, see . - DIMACS + + pickled (.p or .pickle) - DIMACS is a graph data format that can be used for symmetric digraphs. - For a more detailed description, see + Digraphs are pickled using the &IO; package. This is particularly good when + the is non-trivial. + + plain text (.txt) + + This is a human-readable format which stores graphs as pairs of vertices + describing edges in a graph. By convention, the vertices making up one + edge are separated by a single space, and pairs of vertices are + separated by two spaces. By default, vertices also start at 0, not 1. For + example, Digraph([[1, 3], [4], [], [4]]) becomes + 0 0  0 2  1 3  3 3. + provides more control over the choice of + delimiter, and the vertex index offset. +

+ Note that the number of vertices of a digraph is not stored, and so vertices + which are not connected to any edge may be lost. + + - 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: + 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], []]); @@ -98,7 +124,7 @@ false If filename is a string representing the name of a file containing encoded digraphs, then IteratorFromDigraphFile returns an iterator for which the value of is the - next digraph encoded in the file. + next digraph encoded in the file; see .

If the optional argument decoder is specified and is a function @@ -108,9 +134,8 @@ false The purpose of this function is to easily allow looping over digraphs encoded in a file when loading all of the encoded digraphs would require - too much memory.

- - To see what file types are available, see . + too much memory. +

filename := Concatenation(DIGRAPHS_Dir(), "/tst/out/man.d6.gz");; @@ -136,15 +161,13 @@ gap> for x in iter do od; DigraphFile returns an &IO; package file object for that file.

- If the optional argument coder is specified - and is a function which either encodes a digraph as a string, or decodes a - string into a digraph, then this function will be used when reading or - writing to the returned file object. If the optional argument coder - is not specified, then the encoding of the digraphs in the returned file - object must be specified in the the file extension. The file extension must - be one of: .g6, .s6, .d6, .ds6, .txt, - .p, or .pickle; more details of these file formats is given - below.

+ If the optional argument coder is specified and is a function which + either encodes a digraph as a string, or decodes a string into a digraph, + then this function will be used when reading or writing to the returned + file object. If the optional argument coder is not specified, then + the encoding will be deduced from the file extension; see + EncodingFormats (). +

If the optional argument mode is specified, then it must be one of: "w" (for write), "a" (for append), or "r" (for read). @@ -156,74 +179,13 @@ gap> for x in iter do od;

The file object returned by DigraphFile can be given as the first - argument for either of the functions or . The purpose of this is to reduce the overhead of - recreating the file object inside the functions - or when, for example, reading or writing many - digraphs in a loop. + argument for either of the functions or + . The purpose of this is to reduce the overhead + of recreating the file object inside the functions + or when, for + example, reading or writing many digraphs in a loop.

- The currently supported file formats, and associated filename extensions, - are: - - graph6 (.g6) - - A standard and widely-used format for undirected graphs, with no support - for loops or multiple edges. Only symmetric graphs are allowed -- each - edge is combined with its converse edge to produce a single undirected - edge. This format is best used for "dense" graphs -- those with many - edges per vertex. - - sparse6 (.s6) - - Unlike graph6, sparse6 has support for loops and multiple edges. - However, its use is still limited to symmetric graphs. This format is - better-suited to "sparse" graphs -- those with few edges per vertex. - - digraph6 (.d6) - - This format is based on graph6, but stores direction information - - therefore is not limited to symmetric graphs. Loops are allowed, but - multiple edges are not. Best compression with "dense" graphs. - - disparse6 (.ds6) - - Any type of digraph can be encoded in disparse6: directions, loops, and - multiple edges are all allowed. Similar to sparse6, this has the best - compression rate with "sparse" graphs. - - plain text (.txt) - - This is a human-readable format which stores graphs in the form - 0 7 0 8 1 7 2 8 3 8 4 8 5 8 6 8 i.e. pairs of vertices - describing edges in a graph. More specifically, the vertices making up - one edge must be separated by a single space, and pairs of vertices must - be separated by two spaces.

- - See for a more flexible way to store - digraphs in a plain text file.

- - - pickled (.p or .pickle) - - Digraphs are pickled using the &IO; package. This is particularly good - when the is non-trivial. - - dreadnaut (.dre) - - A graph 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) - - A graph format that can be used for symmetric digraphs. For a more detailed description, see - - - filename := Concatenation(DIGRAPHS_Dir(), "/tst/out/man.d6.gz");; gap> file := DigraphFile(filename, "w");; @@ -309,16 +271,15 @@ gap> DigraphFromGraph6String(IsMutableDigraph, "IheA@GUAo"); the opposite direction is also present.

Each of these functions takes an optional first argument filt, - which should be either - or , - and which specifies whether the output digraph shall - be mutable or immutable. - If no first argument is provided, then an immutable - digraph is returned by default. + which should be either or + , and which specifies whether the output + digraph shall 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.

+ encoded in an invalid format; see + EncodingFormats () + for full limitations.

DigraphFromGraph6String("?"); @@ -348,97 +309,24 @@ gap> DigraphFromDiSparse6String(".CaWBGA?b"); If filename is a string containing the name of a file containing encoded digraphs or an &IO; file object created using , then ReadDigraphs returns the digraphs - encoded in the file as a list. Note that if filename is a - compressed file, which has been compressed appropriately to give a filename - extension of .gz, .bz2, or .xz, then - ReadDigraphs can read filename without it first needing to be - decompressed. + Func="DigraphFile"/>, then ReadDigraphs returns the digraphs + encoded in the file as a list.

- If the optional argument decoder is specified - and is a function which decodes a string into a digraph, - then ReadDigraphs will use decoder to decode the digraphs - contained in filename.

+ If filename ends in one of: .gz, .bz2, or .xz, + then the file is decompressed appropriately. If the optional argument + decoder is specified and is a function which decodes a string into a + digraph, then ReadDigraphs will use decoder to decode the + digraphs contained in filename. If the optional argument + decoder is not specified, then ReadDigraphs will deduce which + decoder to use based the file extension; see + EncodingFormats (). +

If the optional argument n is specified, then ReadDigraphs returns the nth digraph encoded in the file filename.

- If the optional argument decoder is not specified, then - ReadDigraphs will deduce which decoder to use based on the filename - extension of filename (after removing the compression-related - filename extensions .gz, .bz2, and .xz). For example, - if the filename extension is .g6, then ReadDigraphs will use - the graph6 decoder . -

- - The currently supported file formats, and associated filename extensions, - are: - - graph6 (.g6) - - A standard and widely-used format for undirected graphs, with no support - for loops or multiple edges. Only symmetric graphs are allowed -- each - edge is combined with its converse edge to produce a single undirected - edge. This format is best used for "dense" graphs -- those with many - edges per vertex. - - sparse6 (.s6) - - Unlike graph6, sparse6 has support for loops and multiple edges. - However, its use is still limited to symmetric graphs. This format is - better-suited to "sparse" graphs -- those with few edges per vertex. - - digraph6 (.d6) - - This format is based on graph6, but stores direction information - - therefore is not limited to symmetric graphs. Loops are allowed, but - multiple edges are not. Best compression with "dense" graphs. - - disparse6 (.ds6) - - Any type of digraph can be encoded in disparse6: directions, loops, and - multiple edges are all allowed. Similar to sparse6, this has the best - compression rate with "sparse" graphs. - - plain text (.txt) - - This is a human-readable format which stores graphs in the form - 0 7 0 8 1 7 2 8 3 8 4 8 5 8 6 8 i.e. pairs of vertices - describing edges in a graph. More specifically, the vertices making up - one edge must be separated by a single space, and pairs of vertices must - be separated by two spaces.

- - See for a more flexible way to store - digraphs in a plain text file.

- - - - pickled (.p or .pickle) - - Digraphs are pickled using the &IO; package. This is particularly good - when the is non-trivial.

- - dreadnaut (.dre) - - A graph 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) - - A graph format that can be used for symmetric digraphs. For a more detailed description, see - - - ReadDigraphs( > Concatenation(DIGRAPHS_Dir(), "/data/graph5.g6.gz"), 10); @@ -473,84 +361,20 @@ gap> ReadDigraphs( If digraphs is a list of digraphs or a digraph and filename is a string or an &IO; file object created using , then WriteDigraphs writes the digraphs to the file represented by - filename. If the supplied filename ends in one of the extensions - .gz, .bz2, or .xz, then the file will be compressed - appropriately. Excluding these extensions, if the file ends with an - extension in the list below, the corresponding graph format will be used to - encode it. If such an extension is not included, an appropriate format - will be chosen intelligently, and an extension appended, to minimise file - size. + filename. +

+ If filename ends in one of: .gz, .bz2, or .xz, + then the file is compressed appropriately. If the file ends with an + extension in + EncodingFormats (), + the corresponding graph format will be used to encode it. If such an + extension is not included, an appropriate format will be chosen + intelligently, and an extension appended, to minimise file size.

- - For more verbose information on the progress of the function, set the info level of InfoDigraphs to 1 or higher, using SetInfoLevel.

- The currently supported file formats are: - - graph6 (.g6) - - A standard and widely-used format for undirected graphs, with no support - for loops or multiple edges. Only symmetric graphs are allowed -- each - edge is combined with its converse edge to produce a single undirected - edge. This format is best used for "dense" graphs -- those with many - edges per vertex. - - sparse6 (.s6) - - Unlike graph6, sparse6 has support for loops and multiple edges. - However, its use is still limited to symmetric graphs. This format is - better-suited to "sparse" graphs -- those with few edges per vertex. - - digraph6 (.d6) - - This format is based on graph6, but stores direction information - - therefore is not limited to symmetric graphs. Loops are allowed, but - multiple edges are not. Best compression with "dense" graphs. - - disparse6 (.ds6) - - Any type of digraph can be encoded in disparse6: directions, loops, and - multiple edges are all allowed. Similar to sparse6, this has the best - compression rate with "sparse" graphs. - - - plain text (.txt) - - This is a human-readable format which stores graphs in the form - 0 7 0 8 1 7 2 8 3 8 4 8 5 8 6 8 i.e. pairs of vertices - describing edges in a graph. More specifically, the vertices making up - one edge must be separated by a single space, and pairs of vertices must - be separated by two spaces.

- - See for a more flexible way to store - digraphs in a plain text file.

- - - pickled (.p or .pickle) - - Digraphs are pickled using the &IO; package. This is particularly good - when the is non-trivial. - - dreadnaut (.dre) - - A graph 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) - - A graph format that can be used for symmetric digraphs. For a more detailed description, see - - - grs := [];; gap> grs[1] := Digraph([]); @@ -592,7 +416,8 @@ gap> ReadDigraphs(filename); 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 - .

+ EncodingFormats (). +

See . dec(last); A string. PlainTextString takes a single digraph, and returns a string - describing the edges of that digraph. DigraphFromPlainTextString - takes such a string and returns the digraph which it describes. Each edge - is written as a pair of integers separated by a single space. The edges - themselves are separated by a double space. Vertex numbers are reduced by - 1 when they are encoded, so that vertices in the string are labelled - starting at 0.

- - Note that the number of vertices of a digraph is not stored, and so vertices - which are not connected to any edge may be lost.

- + describing the edges of that digraph. DigraphFromPlainTextString + takes such a string and returns the digraph which it describes. The + encoding method is described in + EncodingFormats (). - The operation DigraphFromPlainTextString - takes an optional first argument - or , which specifies whether the output digraph shall - be mutable or immutable. If no first argument is provided, then an immutable - digraph is returned by default. + The operation DigraphFromPlainTextString takes an optional first + argument or + , which specifies whether the output + digraph shall be mutable or immutable. If no first argument is provided, + then an immutable digraph is returned by default. +

gr := Digraph([[2, 3], [1], [1]]);