:py:mod:`cobra.util.array`
==========================

.. py:module:: cobra.util.array

.. autoapi-nested-parse::

   Helper functions for array operations and sampling.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   cobra.util.array.create_stoichiometric_matrix
   cobra.util.array.nullspace
   cobra.util.array.constraint_matrices



.. py:function:: create_stoichiometric_matrix(model: cobra.Model, array_type: str = 'dense', dtype: Optional[numpy.dtype] = None) -> Union[numpy.ndarray, scipy.sparse.dok_matrix, scipy.sparse.lil_matrix, pandas.DataFrame]

   Return a stoichiometric array representation of the given model.

   The the columns represent the reactions and rows represent
   metabolites. S[i,j] therefore contains the quantity of metabolite `i`
   produced (negative for consumed) by reaction `j`.

   :param model: The cobra model to construct the matrix for.
   :type model: cobra.Model
   :param array_type: The type of array to construct. "dense" will return a standard
                      numpy.ndarray. "dok", or "lil" will construct a sparse array using
                      scipy of the corresponding type. "DataFrame" will give a
                      pandas.DataFrame with metabolite as indices and reaction as
                      columns.
   :type array_type: {"dense", "dok", "lil", "DataFrame"}
   :param dtype: The desired numpy data type for the array (default numpy.float64).
   :type dtype: numpy.dtype, optional

   :returns: The stoichiometric matrix for the given model.
   :rtype: matrix of class `dtype`

   :raises ValueError: If sparse matrix is used and scipy is not installed.
   :raises .. deprecated:: 0.18.1: "DataFrame" option for `array_type` will be replaced with
       "frame" in future versions.


.. py:function:: nullspace(A: numpy.ndarray, atol: float = 1e-13, rtol: float = 0.0) -> numpy.ndarray

   Compute an approximate basis for the nullspace of A.

   The algorithm used by this function is based on the Singular Value
   Decomposition (SVD) of `A`.

   :param A: `A` should be at most 2-D. 1-D array with length k will be treated
             as a 2-D with shape (1, k).
   :type A: numpy.ndarray
   :param atol: The absolute tolerance for a zero singular value. Singular values
                smaller than `atol` are considered to be zero (default 1e-13).
   :type atol: float, optional
   :param rtol: The relative tolerance. Singular values less than `rtol * smax` are
                considered to be zero, where `smax` is the largest singular value
                (default 0.0).
   :type rtol: float, optional

   :returns: If `A` is an array with shape (m, k), then `ns` will be an array
             with shape (k, n), where `n` is the estimated dimension of the
             nullspace of `A`.  The columns of `ns` are a basis for the
             nullspace; each element in numpy.dot(A, ns) will be approximately
             zero.
   :rtype: numpy.ndarray

   .. rubric:: Notes

   This is taken from the numpy cookbook.

   If both `atol` and `rtol` are positive, the combined tolerance is the
   maximum of the two; that is:

   .. math:: \mathtt{tol} = \max(\mathtt{atol}, \mathtt{rtol} * \mathtt{smax})

   Singular values smaller than `tol` are considered to be zero.


.. py:function:: constraint_matrices(model: cobra.Model, array_type: str = 'dense', zero_tol: float = 1e-06) -> NamedTuple

   Create a matrix representation of the problem.

   This is used for alternative solution approaches that do not use
   "optlang". The function will construct the equality matrix,
   inequality matrix and bounds for the complete problem.

   :param model: The model from which to obtain the LP problem.
   :type model: cobra.Model
   :param array_type: The type of array to construct. "dense" will return a standard
                      numpy.ndarray. "dok", or "lil" will construct a sparse array using
                      scipy of the corresponding type. "DataFrame" will give a
                      pandas.DataFrame with metabolite as indices and reaction as
                      columns.
   :type array_type: {"dense", "dok", "lil", "DataFrame"}
   :param zero_tol: The zero tolerance used to judge whether two bounds are the same
                    (default 1e-6).
   :type zero_tol: float, optional

   :returns: A named tuple consisting of 6 matrices and 2 vectors:
             - "equalities" is a matrix `S` such that `S * vars = b`. It
               includes a row for each constraint and one column for each
               variable.
             - "b" is the right side of the equality equation such that
               `S * vars = b`.
             - "inequalities" is a matrix M such that `lb <= M * vars <= ub`.
               It contains a row for each inequality and as many columns as
               variables.
             - "bounds" is a compound matrix [lb ub] containing the lower and
               upper bounds for the inequality constraints in M.
             - "variable_fixed" is a boolean vector indicating whether the
               variable at that index is fixed (`lower bound == upper_bound`)
               and is thus bounded by an equality constraint.
             - "variable_bounds" is a compound matrix `[lb ub]` containing the
               lower and upper bounds for all variables.
   :rtype: NamedTuple

   .. rubric:: Notes

   To accomodate non-zero equalities, the problem will add the variable
   "const_one" which is a variable that equals one.

   .. deprecated:: 0.18.1
             "DataFrame" option for `array_type` will be replaced with
             "frame" in future versions.