WIP: fix functional docs

Author: kohr-h

odl/solvers/functional/default_functionals.py

@@ -45,7 +45,6 @@
 #TODO:
 # - Add some documentation to `proximal`, `gradient` and `convex_conj`
 #   (use See Also when applicable, otherwise a full doc)
-# - Unify citations
 
 
 class LpNorm(Functional):
@@ -1222,7 +1221,7 @@ def convex_conj(self):
 
     @property
     def proximal(self):
-        """Return the proximal factory of the functional.
+        """A proximal factory for this functional.
 
         This is the zero operator.
         """
@@ -1256,37 +1255,44 @@ def __repr__(self):
                            allow_mixed_seps=False)
 
 
-#TODO: continue here
-
 class KullbackLeibler(Functional):
 
     r"""The Kullback-Leibler divergence functional.
 
     Notes
     -----
-    The functional :math:`F` with prior :math:`g>=0` is given by:
+    The Kullback-Leibler divergence with prior :math:`g>=0` is defined as
 
     .. math::
-        F(x)
-        =
+        \text{KL}(x)
+        &=
         \begin{cases}
-            \sum_{i} \left( x_i - g_i + g_i \log \left( \frac{g_i}{x_i}
-            \right) \right) & \text{if } x_i > 0 \forall i
+            \sum_{i} \left( x_i - g_i + g_i \ln \left( \frac{g_i}{x_i}
+            \right) \right) & \text{if } x_i > 0 \text{ for all } i,
             \\
-            +\infty & \text{else.}
+            +\infty & \text{otherwise.}
         \end{cases}
+        \quad (\mathbb{R}^n\text{-like space}) \\[2ex]
+        \text{KL}(x)
+        &=
+        \begin{cases}
+            \int \left(
+                x(t) - g(t) + g(t) \ln\left(\frac{g(t)}{x(t)}\right)
+            \right)\, \mathrm{d}t  & \text{if } x(t) > 0 \text{ for all } t,
+            \\
+            +\infty & \text{otherwise.}
+        \end{cases}
+        \quad (L^p-\text{like space})
 
-    Note that we use the common definition 0 log(0) := 0.
-    KL based objectives are common in MLEM optimization problems and are often
+    Note that we use the common convention :math:`0 \ln 0 := 0`.
+    KL-based objectives are common in MLEM optimization problems and are often
     used as data-matching term when data noise governed by a multivariate
     Poisson probability distribution is significant.
 
-    The functional is related to the Kullback-Leibler cross entropy functional
-    `KullbackLeiblerCrossEntropy`. The KL cross entropy is the one
-    diescribed in `this Wikipedia article
-    <https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence>`_, and
-    the functional :math:`F` is obtained by switching place of the prior and
-    the varialbe in the KL cross entropy functional.
+    This functional is related to the `KullbackLeiblerCrossEntropy`
+    described in `this Wikipedia article
+    <https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence>`_,
+    in that they have flipped roles of variable :math:`x` and prior :math:`g`.
 
     For a theoretical exposition, see `[Csiszar1991]
     <http://www.jstor.org/stable/2241918>`_.
@@ -1340,23 +1346,23 @@ def prior(self):
     def _call(self, x):
         """Return ``self(x)``.
 
-        If any components of ``x`` is non-positive, the value is positive
+        If any component of ``x`` is non-positive, the value is positive
         infinity.
         """
         # Lazy import to improve `import odl` time
         import scipy.special
 
         if self.prior is None:
-            tmp = ((x - 1 - np.log(x)).inner(self.domain.one()))
+            integral = (x - 1 - np.log(x)).inner(self.domain.one())
         else:
-            tmp = ((x - self.prior +
-                    scipy.special.xlogy(self.prior, self.prior / x))
-                   .inner(self.domain.one()))
-        if np.isnan(tmp):
+            integrand = (x - self.prior +
+                         scipy.special.xlogy(self.prior, self.prior / x))
+            integral = integrand.inner(self.domain.one())
+        if np.isnan(integral):
             # In this case, some element was less than or equal to zero
             return np.inf
         else:
-            return tmp
+            return integral
 
     @property
     def gradient(self):
@@ -1365,7 +1371,7 @@ def gradient(self):
         For a prior :math:`g` is given by
 
         .. math::
-            \nabla F(x) = 1 - \frac{g}{x}.
+            \nabla \text{KL}(x) = 1 - \frac{g}{x}.
 
         The gradient is not defined if any component of :math:`x` is
         non-positive.
@@ -1392,7 +1398,7 @@ def _call(self, x):
 
     @property
     def proximal(self):
-        """Return the `proximal factory` of the functional.
+        """A `proximal factory` for this functional.
 
         See Also
         --------
@@ -1401,12 +1407,17 @@ def proximal(self):
         odl.solvers.nonsmooth.proximal_operators.proximal_convex_conj :
             Proximal of the convex conjugate of a functional.
         """
-        return proximal_convex_conj(proximal_convex_conj_kl(space=self.domain,
-                                                            g=self.prior))
+        return proximal_convex_conj(
+            proximal_convex_conj_kl(space=self.domain, g=self.prior))
 
     @property
     def convex_conj(self):
-        """The convex conjugate functional of the KL-functional."""
+        """The convex conjugate of the KL functional.
+
+        See Also
+        --------
+        KullbackLeiblerConvexConj
+        """
         return KullbackLeiblerConvexConj(self.domain, self.prior)
 
     def __repr__(self):
@@ -1429,24 +1440,38 @@ def __repr__(self):
 
 class KullbackLeiblerConvexConj(Functional):
 
-    r"""The convex conjugate of Kullback-Leibler divergence functional.
+    r"""The convex conjugate of the Kullback-Leibler divergence functional.
 
     Notes
     -----
-    The functional :math:`F^*` with prior :math:`g > 0` is given by
+    The convex conjugate :math:`\text{KL}^*` of the KL divergence is given
+    by
+
+    The Kullback-Leibler divergence with prior :math:`g>=0` is defined as
 
     .. math::
-        F^*(x) =
+        \text{KL}(x)
+        &=
         \begin{cases}
-            \sum_{i} \left( -g_i \ln(1 - x_i) \right)
-            & \text{if } x_i < 1 \forall i
+            \sum_{i} \left( -g_i \ln(1 - x_i) \right) & \text{if }
+            x_i < 1 \text{ for all } i,
             \\
-            +\infty & \text{else}
+            +\infty & \text{otherwise.}
         \end{cases}
+        \quad (\mathbb{R}^n\text{-like space}) \\[2ex]
+        \text{KL}(x)
+        &=
+        \begin{cases}
+            \int \big(-g(t)\ln\left(1 - x(t)\big)
+            \right)\, \mathrm{d}t  & \text{if } x(t) < 1 \text{ for all } t,
+            \\
+            +\infty & \text{otherwise.}
+        \end{cases}
+        \quad (L^p-\text{like space})
 
     See Also
     --------
-    KullbackLeibler : convex conjugate functional
+    KullbackLeibler : convex conjugate
     """
 
     def __init__(self, space, prior=None):
@@ -1472,37 +1497,42 @@ def __init__(self, space, prior=None):
 
     @property
     def prior(self):
-        """The prior in convex conjugate Kullback-Leibler functional."""
+        """The prior in the convex conjugate of the KL functional."""
         return self.__prior
 
     # TODO(#440): use integration operator when available
     def _call(self, x):
         """Return ``self(x)``.
 
-        If any components of ``x`` is larger than or equal to 1, the value is
+        If any component of ``x`` is larger than or equal to 1, the value is
         positive infinity.
         """
         # Lazy import to improve `import odl` time
         import scipy.special
 
         if self.prior is None:
-            tmp = self.domain.element(
-                -1.0 * (np.log(1 - x))).inner(self.domain.one())
+            integral = (-1.0 * (np.log1p(-x))).inner(self.domain.one())
         else:
-            tmp = self.domain.element(-scipy.special.xlogy(
-                self.prior, 1 - x)).inner(self.domain.one())
-        if np.isnan(tmp):
+            integrand = -scipy.special.xlog1py(self.prior, -x)
+            integral = integrand.inner(self.domain.one())
+        if np.isnan(integral):
             # In this case, some element was larger than or equal to one
             return np.inf
         else:
-            return tmp
+            return integral
 
     @property
     def gradient(self):
-        """Gradient operator of the functional.
+        """Gradient operator of this functional.
 
-        The gradient is not defined in points where one or more components
-        are larger than or equal to one.
+        The gradient of the convex conjugate of the KL divergence is given
+        by
+
+        .. math::
+            \nabla \text{KL}^*(x) = \frac{g}{1 - x}.
+
+        The gradient is not defined in points where any component of :math:`x`
+        is (larger than or) equal to one.
         """
         functional = self
 
@@ -1530,7 +1560,7 @@ def _call(self, x):
 
     @property
     def proximal(self):
-        """Return the `proximal factory` of the functional.
+        """A `proximal factory` for this functional.
 
         See Also
         --------
@@ -1543,7 +1573,10 @@ def proximal(self):
 
     @property
     def convex_conj(self):
-        """The convex conjugate functional of the conjugate KL-functional."""
+        """The convex conjugate functional of the KL convex conjugate.
+
+        This is the original KL divergence.
+        """
         return KullbackLeibler(self.domain, self.prior)
 
     def __repr__(self):
@@ -1556,6 +1589,7 @@ def __repr__(self):
                            allow_mixed_seps=False)
 
 
+#TODO: continue here
 class KullbackLeiblerCrossEntropy(Functional):
 
     r"""The Kullback-Leibler Cross Entropy divergence functional.
@@ -1568,7 +1602,7 @@ class KullbackLeiblerCrossEntropy(Functional):
         F(x)
         =
         \begin{cases}
-            \sum_{i} \left( g_i - x_i + x_i \log \left( \frac{x_i}{g_i}
+            \sum_{i} \left( g_i - x_i + x_i \ln \left( \frac{x_i}{g_i}
             \right) \right)
             & \text{if } g_i > 0 \forall i
             \\
@@ -1638,7 +1672,7 @@ def prior(self):
     def _call(self, x):
         """Return ``self(x)``.
 
-        If any components of ``x`` is non-positive, the value is positive
+        If any component of ``x`` is non-positive, the value is positive
         infinity.
         """
         # Lazy import to improve `import odl` time
@@ -2204,7 +2238,7 @@ def __repr__(self):
 
 class NuclearNorm(Functional):
 
-    r"""Nuclear norm for matrix valued functions.
+    r"""Nuclear norm for matrix-valued functions.
 
     Notes
     -----
@@ -2294,8 +2328,7 @@ def _asvector(self, arr):
 
     def _call(self, x):
         """Return ``self(x)``."""
-
-        # Convert to array with most
+        # Convert to array with "outer" indices last
         arr = self._asarray(x)
         svd_diag = np.linalg.svd(arr, compute_uv=False)