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

.. py:module:: pytomography.priors.relative_difference


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

Classes
~~~~~~~

.. autoapisummary::

   pytomography.priors.relative_difference.DiffAndSumSmoothnessPrior
   pytomography.priors.relative_difference.RelativeDifferencePrior




.. py:class:: DiffAndSumSmoothnessPrior(beta, phi, device = None, **kwargs)

   Bases: :py:obj:`pytomography.priors.prior.Prior`

   Implementation of priors where gradients depend on difference and the sum of neighbouring voxels: :math:`\frac{\partial V}{\partial f_r}=\beta\sum_{r,s}w_{r,s}\phi(f_r-f_s, f_r+f_s)` where :math:`V` is from the log-posterior probability :math:`\ln L (\tilde{f}, f) - \beta V(f)`.

   :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 device: Pytorch device used for computation. Defaults to 'cpu'.
   :type device: str, optional

   .. py:method:: get_kernel(sign = 1)

      Obtains the kernel used to get :math:`\frac{\partial V}{\partial f_r}` (this is an array with the same dimensions as the object space image)

      :param sign: Kernel computes image :math:`f_r + \text{sign} \cdot f_k` for all 26 nearest neighbours :math:`k` (i.e. a 3D image is returned with 26 channels). Defaults to 1.
      :type sign: float

      :returns: Kernel used for convolution (number of output channels equal to number of :math:`s`), and array of weights :math:`w_s` used in expression for gradient.
      :rtype: (torch.nn.Conv3d, torch.tensor)


   .. py:method:: set_kernel(object_meta)

      Sets the kernel using  `get_kernel` and the corresponding object metadata.

      :param object_meta: Metadata for object space.
      :type object_meta: ObjectMeta


   .. py:method:: forward()

      Computes the prior on ``self.object``

      :returns: Tensor of shape [batch_size, Lx, Ly, Lz] representing :math:`\frac{\partial V}{\partial f_r}`
      :rtype: torch.tensor



.. 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



