:py:mod:`pytomography.priors`
=============================

.. py:module:: pytomography.priors

.. autoapi-nested-parse::

   Under the modification :math:`L(\tilde{f}, f) \to L(\tilde{f}, f)e^{-\beta V(f)}`, the log-liklihood becomes :math:`\ln L(\tilde{f},f) - \beta V(f)`. Typically, the prior has a form :math:`V(f) = \sum_{r,s} w_{r,s} \phi(f_r,f_s)`. In this expression, :math:`r` represents a voxel in the object, :math:`s` represents a neighbouring voxel to voxel :math:`r`, and :math:`w_{r,s}` is a weight that adjusts for the Euclidean distance between the voxels (set to unity for neighbouring voxels). For all priors implemented here, the neighbouring voxels considered are those surrounding a given voxel, so :math:`\sum_s` is a sum over 26 points.



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   prior/index.rst
   relative_difference/index.rst
   smoothness/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   pytomography.priors.QuadraticPrior
   pytomography.priors.LogCoshPrior
   pytomography.priors.RelativeDifferencePrior
   pytomography.priors.Prior




.. py:class:: QuadraticPrior(beta, delta = 1, device = None)

   Bases: :py:obj:`SmoothnessPrior`

   Subclass of `SmoothnessPrior` where :math:`\phi(x)=x` corresponds to a quadratic prior :math:`V(f)=\frac{1}{4}\sum_{r,s} w_{r,s} \left(\frac{f_r-f_s}{\delta}\right)^2`

   :param beta: Used to scale the weight of the prior
   :type beta: float
   :param delta: Parameter :math:`\delta` in equation above. Defaults to 1.
   :type delta: int, optional
   :param device: Pytorch device used for computation. Defaults to 'cpu'.
   :type device: str, optional


.. py:class:: LogCoshPrior(beta, delta = 1, device = None)

   Bases: :py:obj:`SmoothnessPrior`

   Subclass of `SmoothnessPrior` where :math:`\phi(x)=\tanh(x)` corresponds to the logcosh prior :math:`V(f)=\sum_{r,s} w_{r,s} \log\cosh\left(\frac{f_r-f_s}{\delta}\right)`

   :param beta: Used to scale the weight of the prior
   :type beta: float
   :param delta: Parameter :math:`\delta` in equation above. Defaults to 1.
   :type delta: int, optional
   :param device: Pytorch device used for computation. Defaults to 'cpu'.
   :type device: str, optional


.. py:class:: RelativeDifferencePrior(beta = 1, gamma = 1, device = None)

   Bases: :py:obj:`DiffAndSumSmoothnessPrior`

   Subclass of `SmoothnessPrior` where :math:`\phi(f_r-f_s,f_r+f_s) = \frac{4(f_r-f_s)(f_r+f_s)}{((f_r+f_s)+\gamma|f_r-f_s|)^2}` corresponds to the Relative Difference Prior :math:`V(f) = \sum_{r,s} w_{r,s} \frac{(f_r-f_s)^2}{(f_r+f_s)+\gamma|f_r-f_s|}`

   :param beta: Used to scale the weight of the prior
   :type beta: float
   :param phi: Function $\phi$ used in formula above
   :type phi: function
   :param gamma: Parameter $\gamma$ in equation above. Defaults to 1.
   :type gamma: float, optional
   :param device: Pytorch device used for computation. Defaults to 'cpu'.
   :type device: str, optional

   .. py:method:: gradient(sum, diff, gamma, eps = 1e-11)

      Gradient function.

      :param sum: tensor of size [batch_size,Lx,Ly,Lz] representing :math:`f_r+f_s`
      :type sum: torch.Tensor
      :param diff: tensor of size [batch_size,Lx,Ly,Lz] representing :math:`f_r-f_s`
      :type diff: torch.Tensor
      :param gamma: hyperparameter :math:`\gamma`
      :type gamma: torch.Tensor
      :param eps: Used to prevent division by 0. Defaults to 1e-11.
      :type eps: float, optional

      :returns: Returns :math:`\frac{(f_r-f_s)^2}{(f_r+f_s)+\gamma|f_r-f_s|}` for a given :math:`r` and :math:`s`.
      :rtype: torch.Tensor



.. py:class:: Prior(beta, device = None)

   Bases: :py:obj:`torch.nn.Module`

   Abstract class for implementation of prior :math:`V(f)` where :math:`V` is from the log-posterior probability :math:`\ln L(\tilde{f}, f) - \beta V(f)`. Any function inheriting from this class should implement a ``foward`` method that computes the tensor :math:`\frac{\partial V}{\partial f_r}` where :math:`f` is an object tensor.

   :param beta: Used to scale the weight of the prior
   :type beta: float
   :param device: Pytorch device used for computation. Defaults to 'cpu'.
   :type device: float

   .. py:method:: set_object_meta(object_meta)

      Sets object metadata parameters.

      :param object_meta: Object metadata describing the system.
      :type object_meta: ObjectMeta


   .. py:method:: set_beta_scale(factor)

      Sets :math:`\beta`

      :param factor: Value of :math:`\beta`
      :type factor: float


   .. py:method:: set_object(object)

      Sets the object :math:`f_r` used to compute :math:`\frac{\partial V}{\partial f_r}`

      :param object: Tensor of size [batch_size, Lx, Ly, Lz] representing :math:`f_r`.
      :type object: torch.tensor


   .. py:method:: set_device(device)

      Sets the pytorch computation device

      :param device: sets device.
      :type device: str


   .. py:method:: forward()
      :abstractmethod:

      Abstract method to compute prior based on the ``self.object`` attribute.




