Refactored Seymour decomposition parameters.

doc/matroids.md

@@ -3,7 +3,7 @@
 The matroid **represented** by a matrix \f$ M \in \mathbb{F}^{m \times n} \f$ has \f$ m + n \f$ elements that correspond to the columns of \f$ [ \mathbb{I} \mid M ] \f$.
 A subset of these columns is independent if and only if it is linearly independent over the field \f$ \mathbb{F} \f$.
 
-## Decomposition of matroids {#matroid_decomposition}
+## Decomposition of matroids {#seymour_decomposition}
 
 In CMR, the matroid represented by a matrix can be decomposed, which is essential for testing for [total unimodularity](\ref tu) and [regularity](\ref regular).
 The internal representation is a decomposition tree whose nodes are references to \ref CMR_MATROID_DEC.

include/cmr/matroid.h

@@ -89,8 +89,10 @@ CMR_ERROR CMRchrmatTernaryPivots(
 
 typedef enum
 {
- CMR_MINOR_TYPE_DETERMINANT = -1,
+ CMR_MINOR_TYPE_DETERMINANT = -2,
  /**< A submatrix \f$ M \f$ with \f$ |\det(M)| = 2 \f$. */
+ CMR_MINOR_TYPE_ENTRY = -1,
+ /**< A submatrix \f$ M \f$ of size 1-by-1 exhibiting a bad entry. */
  CMR_MINOR_TYPE_CUSTOM = 0,
  /**< A custom minor. */
  CMR_MINOR_TYPE_U24 = 1,

include/cmr/regular.h

@@ -22,85 +22,9 @@ extern "C" {
 #include <cmr/graphic.h>
 #include <cmr/network.h>
 
-typedef enum
-{
- CMR_DEC_CONSTRUCT_NONE = 0,
- CMR_DEC_CONSTRUCT_LEAVES = 1,
- CMR_DEC_CONSTRUCT_ALL = 2,
-} CMR_DEC_CONSTRUCT;
-
-/**
- * \brief Flags that control termination of the regular matroid decomposition algorithm.
- *
- * \see The desired types can be set by modifying \ref CMR_REGULAR_PARAMS.treeFlags.
- */
-
-typedef enum
-{
- CMR_REGULAR_TREE_FLAGS_RECURSE = 1,
- /**< Do not process child nodes. */
- CMR_REGULAR_TREE_FLAGS_STOP_IRREGULAR = 2,
- /**< Stop if a (grand-)child is irregular. */
- CMR_REGULAR_TREE_FLAGS_STOP_NONGRAPHIC = 4,
- /**< Stop if a (grand-)child is non-graphic. */
- CMR_REGULAR_TREE_FLAGS_STOP_NONCOGRAPHIC = 8,
- /**< Stop if a (grand-)child is non-cographic. */
- CMR_REGULAR_TREE_FLAGS_STOP_NONGRAPHIC_NONCOGRAPHIC = 16,
- /**< Stop if a (grand-)child is non-graphic **and** non-cographic. */
-
- CMR_REGULAR_TREE_FLAGS_DEFAULT = CMR_REGULAR_TREE_FLAGS_RECURSE | CMR_REGULAR_TREE_FLAGS_STOP_IRREGULAR
-
-} CMR_REGULAR_TREE_FLAGS;
-
 typedef struct
 {
- bool directGraphicness;
- /**< \brief Whether to use fast graphicness routines; default: \c true */
- bool seriesParallel;
- /**< \brief Whether to allow series-parallel operations in the decomposition tree; default: \c true */
- bool planarityCheck;
- /**< \brief Whether minors identified as graphic should still be checked for cographicness; default: \c false. */
-
- int treeFlags;
- /**< \brief Flags controlling the decomposition algorithm. See \ref */
-
- /**< \brief Whether to compute a complete decomposition tree (even if already non-regular; default: \c false. */
- bool threeSumPivotChildren;
- /**< \brief Whether pivots for 3-sums shall be applied such that the matrix contains both child matrices as
- ** submatrices, if possible. */
- int threeSumStrategy;
- /**< \brief Whether to perform pivots to change the rank distribution, and how to construct the children.
- **
- ** The value is a bit-wise or of three decisions. The first decision is that of the **rank distribution**:
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_NO_PIVOTS to not change the rank distribution (default), or
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_DISTRIBUTED_RANKS to enforce distributed ranks (1 + 1), or
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_CONCENTRATED_RANK to enforce concentrated ranks (2 + 0).
- **
- ** The second decision determines the layout of the **first child** matrix:
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_FIRST_WIDE for a wide first child (default) in case of distributed ranks,
- ** or
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_FIRST_TALL for a tall first child in that case.
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_FIRST_MIXED for a mixed first child (default) in case of concentrated
- ** ranks, or
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_FIRST_ALLREPR for a first child with all representing rows in that case.
- **
- ** Similarly, the third decision determines the layout of the **second child** matrix:
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_SECOND_WIDE for a wide second child (default) in case of distributed ranks,
- ** or
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_SECOND_TALL for a tall second child in that case.
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_SECOND_MIXED for a mixed second child (default) in case of concentrated
- ** ranks, or
- ** - \ref CMR_MATROID_DEC_THREESUM_FLAG_SECOND_ALLREPR for a first second with all representing rows in that case.
- **
- ** \see \ref matroid_decomposition for a description of these layouts.
- **
- ** A decomposition as described by Seymour can be selected via \ref CMR_MATROID_DEC_THREESUM_FLAG_SEYMOUR.
- ** A decomposition as used by Truemper can be selected via \ref CMR_MATROID_DEC_THREESUM_FLAG_TRUEMPER.
- ** The default is to not carry out any pivots and choose Seymour's or Truemper's definition depending on the rank
- ** distribution. */
-
- CMR_DEC_CONSTRUCT graphs;
- /**< \brief Which (co)graphs to construct; default: \ref CMR_DEC_CONSTRUCT_NONE. */
+ CMR_SEYMOUR_PARAMS seymour;
 } CMR_REGULAR_PARAMS;
 
 /**
@@ -120,19 +44,7 @@ CMR_ERROR CMRregularParamsInit(
 
 typedef struct
 {
- uint32_t totalCount; /**< Total number of invocations. */
- double totalTime; /**< Total time of all invocations. */
- CMR_SP_STATISTICS seriesParallel; /**< Statistics for series-parallel algorithm. */
- CMR_GRAPHIC_STATISTICS graphic; /**< Statistics for direct (co)graphic checks. */
- CMR_NETWORK_STATISTICS network; /**< Statistics for direct (co)network checks. */
- CMR_CAMION_STATISTICS camion; /**< Statistics for Camion signing. */
- uint32_t sequenceExtensionCount; /**< Number of extensions of sequences of nested minors. */
- double sequenceExtensionTime; /**< Time of extensions of sequences of nested minors. */
- uint32_t sequenceGraphicCount; /**< Number (co)graphicness tests applied to sequence of nested minors. */
- double sequenceGraphicTime; /**< Time of (co)graphicness tests applied to sequence of nested minors. */
- uint32_t enumerationCount; /**< Number of calls to enumeration algorithm for candidate 3-separations. */
- double enumerationTime; /**< Time of enumeration of candidate 3-separations. */
- uint32_t enumerationCandidatesCount; /**< Number of enumerated candidates for 3-separations. */
+ CMR_SEYMOUR_STATS seymour; /**< Statistics for Seymour decomposition computations. */
 } CMR_REGULAR_STATS;
 
 
@@ -172,7 +84,7 @@ CMR_ERROR CMRregularTest(
  CMR* cmr, /**< \ref CMR environment. */
  CMR_CHRMAT* matrix, /**< Input matrix. */
  bool *pisRegular, /**< Pointer for storing whether \p matrix is regular. */
-  CMR_SEYMOUR_NODE** pdec,  /**< Pointer for storing the decomposition tree (may be \c NULL). */
+ CMR_SEYMOUR_NODE** proot, /**< Pointer for storing the Seymour decomposition tree (may be \c NULL). */
  CMR_MINOR** pminor, /**< Pointer for storing an \f$ F_7 \f$ or \f$ F_7^\star \f$ minor. */
  CMR_REGULAR_PARAMS* params, /**< Parameters for the computation (may be \c NULL for defaults). */
  CMR_REGULAR_STATS* stats, /**< Statistics for the computation (may be \c NULL). */
@@ -189,7 +101,7 @@ CMR_ERROR CMRregularTest(
 CMR_EXPORT
 CMR_ERROR CMRregularCompleteDecomposition(
  CMR* cmr, /**< \ref CMR environment. */
-  CMR_SEYMOUR_NODE* dec,  /**< Pointer to the decomposition node that is the root of the new subtree. */
+ CMR_SEYMOUR_NODE* dec, /**< Pointer to the decomposition node that is the root of the new subtree. */
  CMR_REGULAR_PARAMS* params, /**< Parameters for the computation (may be \c NULL). */
  CMR_REGULAR_STATS* stats, /**< Statistics for the computation (may be \c NULL). */
  double timeLimit /**< Time limit to impose. */
@@ -205,7 +117,7 @@ CMR_EXPORT
 CMR_ERROR CMRregularRefineDecomposition(
  CMR* cmr, /**< \ref CMR environment. */
  size_t numNodes, /**< Number of nodes to refine. */
-  CMR_SEYMOUR_NODE** nodes,  /**< Array of decomposition nodes to refine. */
+ CMR_SEYMOUR_NODE** nodes, /**< Array of decomposition nodes to refine. */
  CMR_REGULAR_PARAMS* params, /**< Parameters for the computation (may be \c NULL). */
  CMR_REGULAR_STATS* stats, /**< Statistics for the computation (may be \c NULL). */
  double timeLimit /**< Time limit to impose. */