:py:mod:`cobra.sampling.achr`
=============================

.. py:module:: cobra.sampling.achr

.. autoapi-nested-parse::

   Provide the ACHR sampler class.



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

Classes
~~~~~~~

.. autoapisummary::

   cobra.sampling.achr.ACHRSampler




.. py:class:: ACHRSampler(model: cobra.Model, thinning: int = 100, nproj: Optional[int] = None, seed: Optional[int] = None, **kwargs)


   Bases: :py:obj:`cobra.sampling.hr_sampler.HRSampler`

   Artificial Centering Hit-and-Run sampler.

   A sampler with low memory footprint and good convergence.

   :param model: The cobra model from which to generate samples.
   :type model: cobra.Model
   :param thinning: The thinning factor of the generated sampling chain. A thinning of
                    10 means samples are returned every 10 steps (default 100).
   :type thinning: int, optional
   :param nproj: How often to reproject the sampling point into the feasibility
                 space. Avoids numerical issues at the cost of lower sampling. If
                 you observe many equality constraint violations with
                 `sampler.validate` you should lower this number (default None).
   :type nproj: int > 0, optional
   :param seed: Sets the random number seed. Initialized to the current time stamp
                if None (default None).
   :type seed: int > 0, optional

   .. attribute:: n_samples

      The total number of samples that have been generated by this
      sampler instance.

      :type: int

   .. attribute:: problem

      A NamedTuple whose attributes define the entire sampling problem in
      matrix form.

      :type: typing.NamedTuple

   .. attribute:: warmup

      A numpy matrix with as many columns as reactions in the model and
      more than 3 rows containing a warmup sample in each row. None if no
      warmup points have been generated yet.

      :type: numpy.matrix

   .. attribute:: retries

      The overall of sampling retries the sampler has observed. Larger
      values indicate numerical instabilities.

      :type: int

   .. attribute:: fwd_idx

      A numpy array having one entry for each reaction in the model,
      containing the index of the respective forward variable.

      :type: numpy.array

   .. attribute:: rev_idx

      A numpy array having one entry for each reaction in the model,
      containing the index of the respective reverse variable.

      :type: numpy.array

   .. attribute:: prev

      The current/last flux sample generated.

      :type: numpy.array

   .. attribute:: center

      The center of the sampling space as estimated by the mean of all
      previously generated samples.

      :type: numpy.array

   .. rubric:: Notes

   ACHR generates samples by choosing new directions from the sampling
   space's center and the warmup points. The implementation used here is
   the same as in the MATLAB COBRA Toolbox [2]_ and uses only the initial
   warmup points to generate new directions and not any other previous
   iterations. This usually gives better mixing, since the startup points
   are chosen to span the space in a wide manner. This also makes the
   generated sampling chain quasi-Markovian since the center converges
   rapidly.

   Memory usage is roughly in the order of (2 * number of reactions) ^ 2
   due to the required nullspace matrices and warmup points. So, large
   models easily take up a few GBs of RAM.

   .. rubric:: References

   .. [1] Direction Choice for Accelerated Convergence in Hit-and-Run Sampling
      David E. Kaufman, Robert L. Smith
      Operations Research 199846:1 , 84-95
      https://doi.org/10.1287/opre.46.1.84

   .. [2] https://github.com/opencobra/cobratoolbox

   .. py:method:: __single_iteration() -> None

      Run a single iteration of the sampling.


   .. py:method:: sample(n: int, fluxes: bool = True) -> pandas.DataFrame

      Generate a set of samples.

      This is the basic sampling function for all hit-and-run samplers.

      :param n: The number of samples that are generated at once.
      :type n: int
      :param fluxes: Whether to return fluxes or the internal solver variables. If
                     set to False, will return a variable for each forward and
                     backward flux as well as all additional variables you might
                     have defined in the model (default True).
      :type fluxes: bool, optional

      :returns: Returns a pandas DataFrame with `n` rows, each containing a
                flux sample.
      :rtype: pandas.DataFrame

      .. rubric:: Notes

      Performance of this function linearly depends on the number
      of reactions in your model and the thinning factor.