Improved documentation w.r.t. submatrix file format.

doc/balanced.md

@@ -9,7 +9,7 @@ The command
 
     cmr-balanced IN-MAT [OPTION...]
 
-determines whether the matrix given in file `IN-MAT` is balanced.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is balanced.
 
 **Options:**
   - `-i FORMAT`    Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -20,8 +20,8 @@ determines whether the matrix given in file `IN-MAT` is balanced.
   - `--time-limit LIMIT` Allow at most LIMIT seconds for the computation.
   - `--algorithm ALGO`   Algorithm to use, among `enumerate` and `graph`; default: choose best.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `NON-SUB` is `-` then the submatrix is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `NON-SUB` is `-` then the [submatrix](\ref file-formats-submatrix) is written to stdout.
 
 ## Algorithm ##
 

doc/camion.md

@@ -16,15 +16,15 @@ The command
 
     cmr-camion IN-MAT [OPTION]...
 
-determines whether the matrix given in file `IN-MAT` is Camion-signed.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is Camion-signed.
 
 **Options:**
   - `-i FORMAT`   Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
   - `-N NON-SUB`  Write a minimal non-Camion submatrix to file `NON-SUB`; default: skip computation.
   - `-s`          Print statistics about the computation to stderr.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `NON-SUB` is `-` then the submatrix is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `NON-SUB` is `-` then the [submatrix](\ref file-formats-submatrix)  is written to stdout.
 
 ### Algorithm ###
 

doc/ctu.md

@@ -14,7 +14,7 @@ The command
 
     cmr-ctu IN-MAT [OPTION]...
 
-determines whether the matrix given in file `IN-MAT` is complement totally unimodular.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is complement totally unimodular.
 
 **Options**:
   - `-i FORMAT`   Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -23,8 +23,8 @@ determines whether the matrix given in file `IN-MAT` is complement totally unimo
   - `-N OUT-MAT`  Write a complemented matrix that is non-totally-unimodular to file `OUT-MAT`; default: skip computation.
   - `-s`          Print statistics about the computation to stderr.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `OUT-OPS` or `OUT-MAT` is `-` then the list of operations (resp. the matrix) is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `OUT-OPS` or `OUT-MAT` is `-` then the list of operations (resp. the [matrix](\ref file-formats-matrix)) is written to stdout.
 
 ### C Interface ###
 

doc/equimodular.md

@@ -16,7 +16,7 @@ The special cases with \f$ k = 1 \f$ are called **unimodular** and **strongly un
 
 ## Usage ##
 
-The executable `cmr-equimodular` determines whether a given matrix \f$ M \f$ with determinant gcd \f$ k \f$.
+The executable `cmr-equimodular` determines whether a given [matrix](\ref file-formats-matrix) \f$ M \f$ with determinant gcd \f$ k \f$.
 
     ./cmr-equimodular [OPTION]... FILE
 

doc/file-formats.md

@@ -1,6 +1,6 @@
 # File Formats # {#file-formats}
 
-## Matrix File Formats ##
+## Matrix File Formats ## {#file-formats-matrix}
 
 There are two accepted file formats for matrices.
 
@@ -29,6 +29,20 @@ The matrix \f$ A = \begin{pmatrix} 1 & -1 & 0 \\ 0 & 1 & 1 \end{pmatrix} \f$ is
     2 2 1
     2 3 1
 
+## Submatrices ## {#file-formats-submatrix}
+
+Several algorithms produce a submatrix of a matrix \f$ A \in \mathbb{Z}^{m \times n} \f$ as output.
+The corresponding format consists of three lines with whitespace-delimited integers.
+The first has the four entries \f$ m \f$, \f$ n \f$, \f$ r \f$, \f$ c \f$ for an \f$ r \f$-by-\f$ c \f$ submatrix of \f$ A \f$.
+The second line consists of \f$ r \f$ entries indicating the row subset (indexing starts at 1) and the third line consists of \f$ c \f$ entries indicating the column subset.
+The submatrix obtained from \f$ A = \begin{pmatrix} 1 & -1 & 0 \\ 0 & 1 & 1 \end{pmatrix} \f$ by removing the first column is represented as follows:
+
+    2 3 2 2
+    1 2
+    2 3
+
+In order to extract the actual submatrix, please use the [cmr-matrix](\ref utilities) command.
+
 ## Graph File Formats ##
 
 Currently, graphs can only be specified by means of edge lists.

doc/graphic.md

@@ -20,7 +20,7 @@ The command
 
     cmr-graphic IN-MAT [OPTION]...
 
-determines whether the matrix given in file `IN-MAT` is (co)graphic.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is (co)graphic.
 
 **Options**:
   - `-i FORMAT`    Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -31,8 +31,8 @@ determines whether the matrix given in file `IN-MAT` is (co)graphic.
   - `-N NON-SUB`   Write a minimal non-(co)graphic submatrix to file `NON-SUB`; default: skip computation.
   - `-s`           Print statistics about the computation to stderr.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `OUT-GRAPH`, `OUT-TREE`, `OUT-DOT` or `NON-SUB` is `-` then the graph (resp. the tree, dot file or non-(co)graphic submatrix) is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `OUT-GRAPH`, `OUT-TREE`, `OUT-DOT` or `NON-SUB` is `-` then the graph (resp. the tree, dot file or non-(co)graphic [submatrix](\ref file-formats-submatrix)) is written to stdout.
 
 ### Algorithm ###
 
@@ -55,7 +55,7 @@ The command
 
     cmr-graphic -c IN-GRAPH OUT-MAT [OPTION]...
 
-computes a (co)graphic matrix corresponding to the graph from file `IN-GRAPH` and writes it to `OUT-MAT`.
+computes a (co)graphic [matrix](\ref file-formats-matrix) corresponding to the graph from file `IN-GRAPH` and writes it to `OUT-MAT`.
 
 **Options**:
   - `-o FORMAT`    Format of file `OUT-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -64,7 +64,7 @@ computes a (co)graphic matrix corresponding to the graph from file `IN-GRAPH` an
   - `-s`           Print statistics about the computation to stderr.
 
 If `IN-GRAPH` or `IN-TREE` is `-` then the graph (resp. tree) is read from stdin.
-If `OUT-MAT` is `-` then the matrix is written to stdout.
+If `OUT-MAT` is `-` then the [matrix](\ref file-formats-matrix) is written to stdout.
 
 ### C Interface ###
 

doc/k_ary.md

@@ -13,7 +13,7 @@ The command
 
     cmr-k-ary IN-MAT [OPTION...]
 
-determines whether the matrix given in file `IN-MAT` is integer (resp. binary or ternary).
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is integer (resp. binary or ternary).
 
 **Options**:
   - `-i FORMAT`  Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -22,7 +22,7 @@ determines whether the matrix given in file `IN-MAT` is integer (resp. binary or
   - `-I`         Test whether the matrix is integer.
   - `-e EPSILON` Allows rounding of numbers up to tolerance `EPSILON`; default: \f$ 10^{-9} \f$.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
 
 
 ## Finding Large Binary or Ternary Submatrices ##
@@ -31,16 +31,16 @@ The command
 
     cmr-k-ary IN-MAT -R OUT-SUB [OPTION...]
 
-finds a large binary (resp. ternary) submatrix of the matrix given in file `IN-MAT`.
+finds a large binary (resp. ternary) [submatrix](\ref file-formats-matrix) of the [matrix](\ref file-formats-matrix) given in file `IN-MAT`.
 
 **Options:**
   - `-i FORMAT`  Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
   - `-b`         Find a large binary submatrix, i.e., one with only entries in \f$ \{0,+1\} \f$.
   - `-t`         Find a large ternary submatrix, i.e., one with only entries in \f$ \{-1,0,+1\} \f$.
   - `-e EPSILON` Allows rounding of numbers up to tolerance `EPSILON`; default: \f$ 10^{-9} \f$.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `OUT-SUB` is `-` then the submatrix is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `OUT-SUB` is `-` then the [submatrix](\ref file-formats-submatrix) is written to stdout.
 
 ## Algorithm ##
 

doc/network.md

@@ -20,7 +20,7 @@ The command
 
     cmr-network IN-MAT [OPTION]...
 
-determines whether the matrix given in file `IN-MAT` is (co)network.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is (co)network.
 
 **Options**:
   - `-i FORMAT`    Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -31,8 +31,8 @@ determines whether the matrix given in file `IN-MAT` is (co)network.
   - `-N NON-SUB`   Write a minimal non-network submatrix to file `NON-SUB`; default: skip computation.
   - `-s`           Print statistics about the computation to stderr.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `OUT-GRAPH`, `OUT-TREE`, `OUT-DOT` or `NON-SUB` is `-` then the graph (resp. the tree, dot file or non-(co)network submatrix) is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `OUT-GRAPH`, `OUT-TREE`, `OUT-DOT` or `NON-SUB` is `-` then the graph (resp. the tree, dot file or non-(co)network [submatrix](\ref file-formats-submatrix)) is written to stdout.
 
 ### Algorithm ###
 
@@ -54,7 +54,7 @@ The command
 
     cmr-network -c IN-GRAPH OUT-MAT [OPTION]...
 
-computes a (co)network matrix corresponding to the digraph from file `IN-GRAPH` and writes it to `OUT-MAT`.
+computes a (co)network [matrix](\ref file-formats-matrix) corresponding to the digraph from file `IN-GRAPH` and writes it to `OUT-MAT`.
 
 **Options**:
   - `-o FORMAT`    Format of file `OUT-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -63,7 +63,7 @@ computes a (co)network matrix corresponding to the digraph from file `IN-GRAPH`
   - `-s`           Print statistics about the computation to stderr.
 
 If `IN-GRAPH` or `IN-TREE` is `-` then the digraph (resp. directed tree) is read from stdin.
-If `OUT-MAT` is `-` then the matrix is written to stdout.
+If `OUT-MAT` is `-` then the [matrix](\ref file-formats-matrix) is written to stdout.
 
 ### C Interface ###
 

doc/regular.md

@@ -10,7 +10,7 @@ The command
 
     cmr-regular IN-MAT [OPTION...]
 
-determines whether the matrix given in file `IN-MAT` is regular.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is regular.
 
 **Options:**
   - `-i FORMAT`    Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -22,8 +22,8 @@ determines whether the matrix given in file `IN-MAT` is regular.
   - `--no-direct-graphic`  Check only 3-connected matrices for regularity.
   - `--no-series-parallel` Do not allow series-parallel operations in decomposition tree.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `OUT-DEC` or `NON-SUB` is `-` then the decomposition tree (resp. the submatrix) is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `OUT-DEC` or `NON-SUB` is `-` then the decomposition tree (resp. the [submatrix](\ref file-formats-submatrix)) is written to stdout.
 
 ## Algorithm ##
 

doc/series-parallel.md

@@ -33,7 +33,7 @@ The command
 
     cmr-series-parallel IN-MAT [OPTION...]
 
-determines whether the matrix given in file `IN-MAT` is series-parallel.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is series-parallel.
 If this is not the case, then a maximal number of SP-reductions is carried out, leading to the **reduced** matrix.
 Moreover, one can ask for one of the minimal non-series-parallel submatrices above.
 
@@ -45,8 +45,8 @@ Moreover, one can ask for one of the minimal non-series-parallel submatrices abo
   - `-b`              Test for being binary series-parallel; default: ternary.
   - `-s`              Print statistics about the computation to stderr.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `OUT-SP`, `OUT-REDUCED` or `NON-SUB` is `-` then the list of reductions (resp. the submatrix) is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `OUT-SP`, `OUT-REDUCED` or `NON-SUB` is `-` then the list of reductions (resp. the [submatrix](\ref file-formats-submatrix)) is written to stdout.
 
 ## Algorithm ##
 

doc/tu.md

@@ -11,7 +11,7 @@ The command
 
     cmr-tu IN-MAT [OPTION...]
 
-determines whether the matrix given in file `IN-MAT` is totally unimodular.
+determines whether the [matrix](\ref file-formats-matrix) given in file `IN-MAT` is totally unimodular.
 
 **Options:**
   - `-i FORMAT`  Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
@@ -25,8 +25,8 @@ determines whether the matrix given in file `IN-MAT` is totally unimodular.
   - `--no-series-parallel` Do not allow series-parallel operations in decomposition tree.
   - `--algo ALGO`          Use algorithm from {decomposition, submatrix, partition}; default: decomposition.
 
-If `IN-MAT` is `-` then the matrix is read from stdin.
-If `OUT-DEC` or `NON-SUB` is `-` then the decomposition tree (resp. the submatrix) is written to stdout.
+If `IN-MAT` is `-` then the [matrix](\ref file-formats-matrix) is read from stdin.
+If `OUT-DEC` or `NON-SUB` is `-` then the decomposition tree (resp. the [submatrix](\ref file-formats-submatrix)) is written to stdout.
 
 ## Algorithms ##
 

doc/utilities.md

@@ -13,12 +13,12 @@ The command
 
     cmr-matrix IN-MAT OUT-MAT [OPTION]...
 
-copies the matrix from file `IN-MAT` to file `OUT-MAT`, potentially applying certain operations.
+copies the [matrix](\ref file-formats-matrix) from file `IN-MAT` to file `OUT-MAT`, potentially applying certain operations.
 
 **Options:**
   - `-i FORMAT` Format of file `IN-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: dense.
   - `-o FORMAT` Format of file `OUT-MAT`, among `dense` for \ref dense-matrix and `sparse` for \ref sparse-matrix; default: same as format of `IN-MAT`.
-  - `-S IN-SUB` Consider the submatrix of `IN-MAT` specified in file `IN-SUB` instead of `IN-MAT` itself; can be combined with other operations.
+  - `-S IN-SUB` Consider the [submatrix](\ref file-formats-submatrix) of `IN-MAT` specified in file `IN-SUB` instead of `IN-MAT` itself; can be combined with other operations.
   - `-t`        Transpose the matrix; can be combined with other operations.
   - `-c`        Compute the support matrix instead of copying.
   - `-C`        Compute the signed support matrix instead of copying.

src/cmr/balanced.c

@@ -400,7 +400,7 @@ CMR_ERROR balancedTestGraph(
 
   assert(!"Not implemented");
 
-  return CMR_OKAY;
+  return CMR_ERROR_INVALID;
 }
 
 /**