sequince.steps.mutation.emcee
=============================

.. py:module:: sequince.steps.mutation.emcee


Attributes
----------

.. autoapisummary::

   sequince.steps.mutation.emcee.logger
   sequince.steps.mutation.emcee.EMCEE_MOVES


Classes
-------

.. autoapisummary::

   sequince.steps.mutation.emcee.EmceeMutation


Functions
---------

.. autoapisummary::

   sequince.steps.mutation.emcee.get_emcee_move
   sequince.steps.mutation.emcee.resolve_emcee_moves


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

.. py:data:: logger

.. py:data:: EMCEE_MOVES

.. py:function:: get_emcee_move(name, **kwargs)

   Construct a named emcee move.


.. py:function:: resolve_emcee_moves(spec)

   Resolve an emcee move object, named move, preset, or weighted schedule.


.. py:class:: EmceeMutation(log_prob_fn, *, n_steps = 1, move = None, run_kwargs = None, transform = None, transform_refit = 'always', store_chains = False, metrics = (), **kwargs)

   Bases: :py:obj:`sequince.steps.mutation.base.MutationStep`


   Run emcee ensemble MCMC moves to rejuvenate particles.

   Transforms requiring walker-specific auxiliary data are currently
   unsupported. emcee evaluates internally selected walker subsets, but its
   standard log-probability callback does not expose the original walker
   selection or context. Such auxiliary is rejected because Sequince cannot
   guarantee that the correct entry would be supplied to each walker.

   :param log_prob_fn: Function to compute the log-probability of a particle position, or a
                       `Target` instance.
   :param n_steps: Number of emcee steps to perform.
   :param move: An emcee Move instance, named move configuration, weighted move list,
                or preset to use for proposing new positions. If ``None`` (default),
                uses ``StretchMove``.
   :param run_kwargs: Additional keyword arguments to pass to the ``emcee.EnsembleSampler.run_mcmc``
                      method.
   :param transform: A `ParticleTransform` instance to apply to the particles before mutation.
   :param store_chains: Whether to store the entire mutation chain in the metadata. Default is
                        False.
   :param \*\*kwargs: Additional keyword arguments to pass to the ``emcee.EnsembleSampler``


   .. py:method:: apply(state, context, rng)


   .. py:method:: apply_with_mutation_state(state, context, rng, *, n_steps, mutation_state = None)

      Run transitions within a block without finalizing metrics.

      Pass ``mutation_state=None`` to initialize a new block; otherwise pass
      the state returned by the preceding call. The state holds individual
      metric states and cumulative acceptance bookkeeping. It must belong
      to the same metric configuration and mutation coordinate space.

      Returns ``(state, context, output, mutation_state)``. The output's
      metrics remain unset, including on the first and zero-step calls.
      Concrete mutations prepare existing metrics on entry, update state for each
      transition, and return it explicitly without calling metric.result().
      Runtime state must never be stored on the mutation object.

      Use ``apply`` or ``apply_with_n_steps`` for a complete standalone block.
      RepeatedMutationStep uses this method to continue across rounds and
      finalizes metrics once after the complete block.