add docstrings for getExtendedStoichiometryMatrix function

sys-bio · Dec 21, 2018 · e4bd80f · e4bd80f
1 parent df5535a
commit e4bd80f
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 6 deletions.
diff --git a/wrappers/Python/doc/stoichiometric.rst b/wrappers/Python/doc/stoichiometric.rst
@@ -44,6 +44,36 @@ The link matrix :math:`\mathbf{L}` has the form
 where :math:`\mathbf{I}_{r}` is the :math:`r \times r` identity matrix and :math:`\mathbf{L}_0` is a :math:`(m-r) \times r`
 matrix.
 
+Full vs. Extended Stoichiometry Matrix
+--------------------------------------
+
+The "full" stoichiometric matrix includes any conserved quantities (as opposed to the reduced stoichiometric matrix,
+which does not). The *extended* stoichiometric matrix is equal to the full stoichiometric matrix plus additional
+rows representing boundary species and sources / sinks. For example, consider the following reaction system:
+
+::
+
+    reaction1:  => C
+    reaction2: C =>
+    reaction3: C =>
+    reaction4: MI => M
+    reaction5: M => MI
+    reaction6: XI => X
+    reaction7: X => XI
+
+The extended stoichiometry matrix for this system is:
+
+     >>>  rr.getExtendedStoichiometryMatrix()
+                          reaction1, reaction2, reaction3, reaction4, reaction5, reaction6, reaction7
+      C                [[         1,        -1,        -1,         0,         0,         0,         0],
+      M                 [         0,         0,         0,         1,        -1,         0,         0],
+      X                 [         0,         0,         0,         0,         0,         1,        -1],
+      MI                [         0,         0,         0,        -1,         1,         0,         0],
+      XI                [         0,         0,         0,         0,         0,        -1,         1],
+      reaction1_source  [        -1,         0,         0,         0,         0,         0,         0],
+      reaction2_sink    [         0,         1,         0,         0,         0,         0,         0],
+      reaction3_sink    [         0,         0,         1,         0,         0,         0,         0]]
+
 Methods
 -------
 
@@ -57,11 +87,9 @@ The following methods are related to the analysis of the stoichiometric matrix.
    RoadRunner.getConservationMatrix
    RoadRunner.getL0Matrix
    RoadRunner.getFullStoichiometryMatrix
+   RoadRunner.getExtendedStoichiometryMatrix
    RoadRunner.getReducedStoichiometryMatrix
    ExecutableModel.getNumConservedMoieties
    ExecutableModel.getConservedMoietyIds
    ExecutableModel.getConservedMoietyValues
    ExecutableModel.setConservedMoietyValues
-
-
-
diff --git a/wrappers/Python/roadrunner/rr_docstrings.i b/wrappers/Python/roadrunner/rr_docstrings.i
@@ -1245,6 +1245,17 @@ it was converted via conservation conversion.
 
 
 
+%feature("docstring") rr::RoadRunner::getExtendedStoichiometryMatrix "
+RoadRunner.getExtendedStoichiometryMatrix()
+
+
+Returns the full stoichiometric matrix plus additional rows for boundary
+species and source/sink nodes. Use this if you want to apply detailed
+balance to the network as a whole.
+";
+
+
+
 %feature("docstring") rr::RoadRunner::getReducedStoichiometryMatrix "
 RoadRunner.getReducedStoichiometryMatrix()
 
@@ -2421,6 +2432,3 @@ Get the converted document contents.
 :returns: The contents of the converted document, or empty string
           if there is no source document.
 ";
-
-
-