Added docstrings for range parameter

Author: m.lohmann

odl/solvers/functional/default_functionals.py

@@ -15,7 +15,7 @@
 from odl.solvers.functional.functional import (Functional,
                                                FunctionalQuadraticPerturb)
 from odl.space import ProductSpace
-from odl.set import RealNumbers#, ComplexNumbers
+from odl.set import RealNumbers
 from odl.operator import (Operator, ConstantOperator, ZeroOperator,
                           ScalingOperator, DiagonalOperator, PointwiseNorm)
 from odl.solvers.nonsmooth.proximal_operators import (
@@ -69,10 +69,13 @@ def __init__(self, domain, exponent, range=None):
             Domain of the functional.
         exponent : float
             Exponent for the norm (``p``).
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `RealNumbers`.
         """
         if range is None and getattr(domain, 'is_complex', False):
             range = RealNumbers()
-        
+
         super(LpNorm, self).__init__(
             domain=domain, linear=False, grad_lipschitz=np.nan, range=range)
         self.exponent = float(exponent)
@@ -227,6 +230,9 @@ def __init__(self, vfspace, exponent=None, range=None):
             0 and 1 are currently not supported due to numerical
             instability. Infinity gives the supremum norm.
             Default: ``vfspace.exponent``, usually 2.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `vfspace.field`.
 
         Examples
         --------
@@ -356,6 +362,9 @@ def __init__(self, vfspace, exponent=None, range=None):
             0 and 1 are currently not supported due to numerical
             instability. Infinity gives the supremum norm.
             Default: ``vfspace.exponent``, usually 2.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `vfspace.field`.
 
         Examples
         --------
@@ -466,6 +475,9 @@ def __init__(self, domain, exponent, range=None):
             Domain of the functional.
         exponent : int or infinity
             Specifies wich norm to use.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field`.
         """
         super(IndicatorLpUnitBall, self).__init__(domain=domain, linear=False,
                                                   range=range)
@@ -512,7 +524,6 @@ def convex_conj(self):
         [BC2011] Bauschke, H H, and Combettes, P L. *Convex analysis and
         monotone operator theory in Hilbert spaces*. Springer, 2011.
         """
-        # HELP: I guess it needs `range`, too
         if self.exponent == np.inf:
             return L1Norm(self.domain, range=self.range_)
         elif self.exponent == 2:
@@ -582,6 +593,9 @@ def __init__(self, domain, range=None):
         ----------
         domain : `DiscreteLp` or `TensorSpace`
             Domain of the functional.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `RealNumbers`.
         """
         super(L1Norm, self).__init__(domain=domain, exponent=1, range=range)
 
@@ -620,6 +634,9 @@ def __init__(self, domain, range=None):
         ----------
         domain : `DiscreteLp` or `TensorSpace`
             Domain of the functional.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `RealNumbers`.
         """
         super(L2Norm, self).__init__(domain=domain, exponent=2, range=range)
 
@@ -666,6 +683,9 @@ def __init__(self, domain, range=None):
         ----------
         domain : `DiscreteLp` or `TensorSpace`
             Domain of the functional.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `RealNumbers`.
         """
         super(L2NormSquared, self).__init__(
             domain=domain, linear=False, grad_lipschitz=2, range=range)
@@ -723,6 +743,9 @@ def __init__(self, domain, constant, range=None):
             Domain of the functional.
         constant : element in ``domain.field``
             The constant value of the functional
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field`.
         """
         super(ConstantFunctional, self).__init__(
             domain=domain, linear=(constant == 0), grad_lipschitz=0,
@@ -781,9 +804,12 @@ def __init__(self, domain, range=None):
         ----------
         domain : `LinearSpace`
             Domain of the functional.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field`.
         """
         super(ZeroFunctional, self).__init__(domain=domain, constant=0,
-              range=range)
+                                             range=range)
 
     def __repr__(self):
         """Return ``repr(self)``."""
@@ -874,6 +900,9 @@ def __init__(self, domain, lower=None, upper=None, range=None):
         upper : ``domain.field`` element or ``domain`` `element-like`, optional
             The upper bound.
             Default: ``None``, interpreted as +infinity
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field`.
 
         Examples
         --------
@@ -929,6 +958,9 @@ def __init__(self, domain, range=None):
         ----------
         domain : `LinearSpace`
             Domain of the functional.
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field`.
 
         Examples
         --------
@@ -963,6 +995,9 @@ def __init__(self, domain, constant=0, range=None):
             Domain of the functional.
         constant : element in ``domain.field``, optional
             The constant value of the functional
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field`.
 
         Examples
         --------
@@ -1107,7 +1142,6 @@ def __init__(self, domain, prior=None):
         >>> func(x)
         3.0
         """
-        # HELP: range is domain.field, correct?
         super(KullbackLeibler, self).__init__(
             domain=domain, linear=False, grad_lipschitz=np.nan)
 
@@ -1955,7 +1989,9 @@ def __init__(self, domain, outer_exp=1, singular_vector_exp=2, range=None):
             Exponent for the outer norm.
         singular_vector_exp : {1, 2, inf}, optional
             Exponent for the norm for the singular vectors.
-
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `RealNumbers`.
         Examples
         --------
         Simple example, nuclear norm of matrix valued function with all ones
@@ -1974,7 +2010,8 @@ def __init__(self, domain, outer_exp=1, singular_vector_exp=2, range=None):
                             '`ProductSpace`s')
         if (not domain.is_power_space or not domain[0].is_power_space):
             raise TypeError('`domain` must be of the form `TensorSpace^(nxm)`')
-
+        if range is None:
+            range = RealNumbers()
         super(NuclearNorm, self).__init__(
             domain=domain, linear=False, grad_lipschitz=np.nan, range=range)
 
@@ -2166,7 +2203,9 @@ def __init__(self, domain, outer_exp=1, singular_vector_exp=2, range=None):
             Exponent for the outer norm.
         singular_vector_exp : {1, 2, inf}, optional
             Exponent for the norm for the singular vectors.
-
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field` or it that doesn't exist `RealNumbers`.
         Examples
         --------
         Simple example, nuclear norm of matrix valued function with all ones
@@ -2282,7 +2321,8 @@ def __init__(self, functional, sigma=1.0, range=RealNumbers()):
         sigma : positive float, optional
             The scalar ``sigma`` in the definition of the Moreau envelope.
             Larger values mean stronger smoothing.
-
+        range : `Field`, optional
+            Range of the functional. The default is `RealNumbers`.
         Examples
         --------
         Create smoothed l1 norm:
@@ -2354,6 +2394,8 @@ def __init__(self, domain, gamma, range=RealNumbers()):
             the functional is non-smooth and corresponds to the usual L1 norm.
             For ``gamma > 0``, it has a ``1/gamma``-Lipschitz gradient so that
             its convex conjugate is ``gamma``-strongly convex.
+        range : `Field`, optional
+            Range of the functional. The default is `RealNumbers`.
 
         Examples
         --------

odl/solvers/functional/functional.py

@@ -61,16 +61,21 @@ def __init__(self, domain, linear=False, grad_lipschitz=np.nan,
             If `True`, the functional is considered as linear.
         grad_lipschitz : float, optional
             The Lipschitz constant of the gradient. Default: ``nan``
+        range : `Field`, optional
+            Range of the functional. The default `None` will be treated as
+            `domain.field`.
         """
         # Cannot use `super(Functional, self)` here since that breaks
         # subclasses with multiple inheritance (at least those where both
         # parents implement `__init__`, e.g., in `ScalingFunctional`)
-        default_range = getattr(domain, 'field', None)
         if range is None:
+            default_range = getattr(domain, 'field', None)
             if default_range is None:
+                # HELP: I think this is not correct. How to do it properly?
                 raise TypeError('Could not infere range for `functional` {!r}'
-                                .format(self))
-            else: range = default_range
+                                ''.format(self))
+            else:
+                range = default_range
 
         Operator.__init__(self, domain=domain, range=range, linear=linear)
         self.__grad_lipschitz = float(grad_lipschitz)
@@ -696,8 +701,7 @@ def __init__(self, func, vector):
                             ''.format(func))
 
         OperatorRightVectorMult.__init__(self, operator=func, vector=vector)
-        # HELP: before it was Functional.__init__(self, domain=func.domain).
-        # But doesn't this loose the information on grad_lipschitz and linear?
+        # HELP: grad_lipschitz = func.grad_lipschitz * ||constant||_\infty ?
         Functional.__init__(self, domain=func.domain,
                             grad_lipschitz=func.grad_lipschitz,
                             linear=func.is_linear,
@@ -1325,7 +1329,7 @@ def __init__(self, func):
         if not isinstance(func, Functional):
             raise TypeError('`func` {} is not a `Functional` instance'
                             ''.format(func))
-        
+
         super(FunctionalDefaultConvexConjugate, self).__init__(
             domain=func.domain, linear=func.is_linear, range=func.range)
         self.__convex_conj = func