\ :py:mod:`clipppy.commands.fit`
================================

.. py:module:: clipppy.commands.fit


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

.. py:class:: Fit(**kwargs)



   Fit using ELBO maximisation.

   .. py:attribute:: avgwindow
      :annotation: :int = 100

      Number of most recents steps to use for calculating various
      averaged quantities (average rate, mean loss...).

   .. py:attribute:: callback
      :annotation: :Callable[[int, float, Mapping[str, Any]], Any]

      Callback to be executed after each step.

      Signature should be ``callback(i, loss, locals)``, where ``i`` is the
      current step index, ``loss`` is the current loss, and ``locals`` is a
      dictionary of the local variables in the fitting function. Depending on
      the python implementation, modifying its values might influence the
      fitting. Returning any ``True`` value interrupts the fitting.

   .. py:attribute:: conv_th
      :annotation: :float

      Convergence threshold. Should be positive or ``-float('inf')`` to turn
      off convergence-based termination.

      See `converged`.

   .. py:attribute:: loss_args
      :annotation: :Mapping

      Arguments for the ``loss_cls`` constructor.

      Pass the special value `Command.no_call` to avoid instantiating
      ``load_cls`` and use it directly.

   .. py:attribute:: loss_cls
      :annotation: :Union[Type[pyro.infer.ELBO], Callable[Ellipsis, torch.Tensor]]

      The loss class to instantiate.

   .. py:attribute:: lr
      :annotation: :float = 0.001

      Learning rate (passed to the optimizer).

   .. py:attribute:: min_steps
      :annotation: :int = 1

      Run at least ``min_steps`` steps.

   .. py:attribute:: n_steps
      :annotation: :int = 1000

      Run at most ``n_steps`` steps.

   .. py:attribute:: n_write
      :annotation: :int

      Save the guide each ``n_write`` steps.

   .. py:attribute:: optimizer_args
      :annotation: :Optional[Mapping]

      The (keyword!) arguments to pass to ``optimizer_cls``.

      Will be updated with the standalone ``lr`` passed, unless it is ``noop``.

      Pass the special value `Command.no_call` to avoid instantiating
      ``optimizer_cls`` and use it directly.

   .. py:attribute:: optimizer_cls
      :annotation: :Union[Type[pyro.optim.PyroOptim], Callable[[Mapping], pyro.optim.PyroOptim]]

      The class of `PyroOptim <pyro.optim.optim.PyroOptim>` to
      instantiate (or a function that acts like it).

   .. py:method:: converged(self, slope: float, windowed_losses: Iterable[float] = None)

      Indicate whether the fit is considered converged.

      This implementation returns `True` if the averaged slope ``slope``,
      defined as the fitted slope of losses over the last `avgwindow`
      iterations, divided by the learning rate, is shallower than `conv_th`,
      which should be given as positive. If the ``slope`` is positive, this
      will always be true, so turning this check off requires setting
      ``conv_th = -float('inf')``.

      This method can be overridden in subclasses to provide more
      sophisticated checks.



   .. py:method:: forward(self, model: clipppy.utils.typing._Model, guide: clipppy.utils.typing._Guide, *args, **kwargs)


   .. py:method:: lossfunc(self) -> Union[pyro.infer.ELBO, Callable[Ellipsis, torch.Tensor]]
      :property:

      Construct a loss as ``loss_cls(**loss_args)`` or simply return
      `loss_cls` if `loss_args` is `Command.no_call`.


   .. py:method:: optimizer(self) -> pyro.optim.PyroOptim
      :property:

      Construct an optimizer as ``optimizer_cls(optimizer_args)`` or simply
      return `optimizer_cls` if `optimizer_args` is `Command.no_call`.