jexplore.sampling.mh
====================

.. py:module:: jexplore.sampling.mh

.. autoapi-nested-parse::

   This module contains the definitions of classes and types
   for running a Metropolis-Hastings  markov sampler.



Classes
-------

.. autoapisummary::

   jexplore.sampling.mh.StateMH
   jexplore.sampling.mh.SamplingMH
   jexplore.sampling.mh.EpochMH


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

.. py:class:: StateMH

   Bases: :py:obj:`jexplore.sampling.state.State`


   This class provides the definition of a markovc chain state for a
   Metropolis-Hastings markov sampler. With respect to the parent
   :py:attr:`jexplore.sampling.state.State` class, it simply adds
   log likelihood and log prior values to the state attributes (operations
   on these parameters are handled by the parent class methods).

   :param p: status point (nchains, dim)
   :param ll: log likelihood values for each chain point (nchains, 1).
   :param lp: log prior values for each chain point (nchains, 1).


   .. py:attribute:: ll
      :type:  jax.Array

      log likelihood values


   .. py:attribute:: lp
      :type:  jax.Array

      log prior values.


.. py:class:: SamplingMH[Tspace: jexplore.sampling.space.Space](nwalker, temps, loglik, logprior, dim = None, space = None, inpars = None)

   Bases: :py:obj:`jexplore.sampling.base.Sampling`\ [\ :py:obj:`Tspace`\ ]


   Markov sampling defining parameters for Metropolis-Hastings
   sampling.
   With respect to the parent :py:attr:`jexplore.sampling.base.Sampling`
   class the definition of the sampling includes the following parameters

   :param nwalker: number of walkers per temperature.
   :param temps: temperature ladder
   :param loglik: log likelihood function
   :param logprior: log prior function

   The `nchain` parameter is computed from `nwalker` and `temps`.


   .. py:attribute:: nwalker
      :type:  int

      number of walkers


   .. py:attribute:: temps
      :type:  jax.Array

      temperature ladder


   .. py:attribute:: loglik
      :type:  jexplore.sampling.state.ArrayFn

      log likelihood function


   .. py:attribute:: logprior
      :type:  jexplore.sampling.state.ArrayFn

      log prior function


   .. py:attribute:: inpars
      :type:  list[str]

      list of input parameters of loglik and logprior


   .. py:method:: to_backend()

      Save the attributes of the object in
      backend format.



   .. py:method:: get_sampler(steps=None, backend=None)

      Return a sampler with default steps and backend.

      :param steps: list of `Step`-like instances. If None, use strech
                    and tswap (if more than 1 temp).
      :param backend: a `Backend` instance. If None, use the default one.

      :return: a `JaxSampler` instance.



   .. py:method:: get_epoch(p)

      Return an `Epoch` object from starting sample, to be use by MH
      sampler as initial epoch.

      :params p: samples array of shape nwalker x ntemp, dim
      :return: a `EpochMH` instance



.. py:class:: EpochMH[Tstate: StateMH, Tsampling: SamplingMH](epoch, force_covs = False)

   Bases: :py:obj:`jexplore.sampling.epoch.Epoch`\ [\ :py:obj:`Tstate`\ , :py:obj:`Tsampling`\ ]


   Epoch definition class for Metropolis-Hastings.

   With respect to the parent :py:attr:`jexplore.sampling.epoch.Epoch` class,
   this class define :py:attr:`jexplore.sampling.mh.StateMH` as default state
   class and overrides the `complete` method to also compute the log likelihood
   and log prior of the epoch points.

   :param epoch: `Epoch` object from which the new instance can be derived by
                 computing the covariance and getting the last sample. Alternatively
                 this can be a dictionnary with the definition of the epoch samples.

   :param force_covs: if true forces the recomputing of the covariance matrices.


   .. py:attribute:: statecls
      :type:  type[Tstate] | type[StateMH]

      State class


   .. py:method:: complete(sampling, compute = None)

      Complete the definition and the parameters of the epoch.

      :param sampling: sampling parameters.
      :param compute: dictionnary defining how to compute the missing parameters.
                      The keys are the names of the parameters to be computed. Values
                      are `(func, inpars)`  tuples, where `func` is a callable for the
                      computation of the corresponding parameter and `inpars` is the
                      list of the names if the input parameters.

      With respect to :py:attr:`jexplore.sampling.epoch.Epoch.complete`, this
      implementation of the `complete` method provides a base for the `compute`
      parameter with the instructions to compute log likelihood and log prior
      epoch samples attributes.

      :return: this object after update.