Add examples to OneSumNode in seymour_decomposition.pyx, add methods block_matrix_form, summand_matrices (sagemath#8)

* wip onesum

* wip onesum2

* wip onesum test

* onesum node example

* fixed names of .summand_matrices() and .block_matrix_form,
....: and added examples to ._children()

* style fixes

---------

Co-authored-by: J S <[email protected]>
Co-authored-by: J S <[email protected]>

Author: 3 people

src/sage/matrix/seymour_decomposition.pyx

@@ -157,6 +157,35 @@ cdef class DecompositionNode(SageObject):
 
     @cached_method
     def _children(self):
+        r"""
+        Returns tuple of summands, () in the case of graphic or leaf nodes.
+        EXAMPLES::
+
+            sage: from sage.matrix.matrix_cmr_sparse import Matrix_cmr_chr_sparse
+            sage: M = Matrix_cmr_chr_sparse.one_sum([[1, 0], [-1, 1]],
+            ....: [[1, 1], [-1, 0]], [[1, 0], [0,1]]); M
+            [ 1  0| 0  0| 0  0]
+            [-1  1| 0  0| 0  0]
+            [-----+-----+-----]
+            [ 0  0| 1  1| 0  0]
+            [ 0  0|-1  0| 0  0]
+            [-----+-----+-----]
+            [ 0  0| 0  0| 1  0]
+            [ 0  0| 0  0| 0  1]
+            sage: result, certificate = M3.is_totally_unimodular(certificate=True); certificate
+            OneSumNode with 4 children
+            sage: certificate._children()
+            (GraphicNode, GraphicNode, GraphicNode, GraphicNode)
+
+            sage: M2 = Matrix_cmr_chr_sparse(MatrixSpace(ZZ, 2, 2, sparse=True),
+            ...:  [[1, 1], [-1, 0]]); M2
+            [ 1  1]
+            [-1  0]
+            sage: result, certificate = M.is_totally_unimodular(certificate=True); certificate
+            GraphicNode
+            certificate._children()
+            ()
+        """
         return tuple(create_DecompositionNode(CMRdecChild(self._dec, index),
                                               self._root or self)
                      for index in range(CMRdecNumChildren(self._dec)))
@@ -194,14 +223,65 @@ cdef class SumNode(DecompositionNode):
 
     summands = DecompositionNode._children
 
+    def summand_matrices(self):
+        return tuple(s.matrix() for s in self._children())
+
 
 cdef class OneSumNode(SumNode):
 
-    pass
+    def block_matrix_form(self):
+        r"""
+        EXAMPLES::
+
+            sage: from sage.matrix.matrix_cmr_sparse import Matrix_cmr_chr_sparse
+            sage: M = Matrix_cmr_chr_sparse.one_sum([[1, 0], [-1, 1]], [[1, 1], [-1, 0]])
+            sage: result, certificate = M.is_totally_unimodular(certificate=True); certificate
+            OneSumNode with 2 children
+            sage: certificate.summand_matrices()
+            (
+            [ 1  0]  [ 1  1]
+            [-1  1], [-1  0]
+            )
+            sage: certificate.block_matrix_form()
+            [ 1  0| 0  0]
+            [-1  1| 0  0]
+            [-----+-----]
+            [ 0  0| 1  1]
+            [ 0  0|-1  0]
+
+            sage: M3 = Matrix_cmr_chr_sparse.one_sum([[1, 0], [-1, 1]], [[1, 1], [-1, 0]], [[1, 0], [0,1]]
+            ....: [[1, 1], [-1, 0]], [[1, 0], [0,1]]); M3
+            [ 1  0| 0  0| 0  0]
+            [-1  1| 0  0| 0  0]
+            [-----+-----+-----]
+            [ 0  0| 1  1| 0  0]
+            [ 0  0|-1  0| 0  0]
+            [-----+-----+-----]
+            [ 0  0| 0  0| 1  0]
+            [ 0  0| 0  0| 0  1]
+            sage: result, certificate = M3.is_totally_unimodular(certificate=True); certificate
+            OneSumNode with 4 children
+            sage: certificate.summand_matrices()
+            (
+            [ 1  0]  [ 1  1]
+            [-1  1], [-1  0], [1], [1]
+            )
+            sage: certificate.block_matrix_form()
+            [ 1  0| 0  0| 0| 0]
+            [-1  1| 0  0| 0| 0]
+            [-----+-----+--+--]
+            [ 0  0| 1  1| 0| 0]
+            [ 0  0|-1  0| 0| 0]
+            [-----+-----+--+--]
+            [ 0  0| 0  0| 1| 0]
+            [-----+-----+--+--]
+            [ 0  0| 0  0| 0| 1]
+        """
+        return Matrix_cmr_chr_sparse.one_sum(*self.summand_matrices())
 
 
 cdef class TwoSumNode(SumNode):
-
+    
     pass