ENH/STY/MAINT/DOC: See full list below.

This commit contains updates in:
- functional_basic_example
- functional_basic_example_solver
- default_functionals
- functional
- default_functional_test
- functional_test

functional_basic_example:
- minor updates in comments.

functional_basic_example_solver:
- minor updates in comments.
- add example with forward-backward pd solver.
- update error in operator norm when chambolle-pock.

default_functionals:
- doc updates in many of the classes and methods.
- inner class L1ConjuagteFunctional -> real class IndicatorLinftyUnitBall.
- inner class L2ConjugateFunctional -> real class IndicatorL2UnitBall.
- remove class L2SquareConjugateFunctional, since this is just a scalar
multiplied with the L2Square functional.
- renamed ConstantFunctionalConvexConjuaget to ConjugateToConstantFunctional.
- add property to ConjugateToConstantFunctional that returns the constant.

functional:
- doc updates in some places.
- remove storing scalars and functionals when classes inherites from
OperatorComp, OperatorLeftScalarMult, etc. since these are stored in parent
classes.
- remove inner class LeftScalarMultGradient. Not needed, as the same can
be achieved in a simpler way.
- removed inner class RightScalarMultGradient. Not needed, as the same can
be achieved in a simpler way.
- input checks on TranslatedFunctional.
- add properties to access things as scaling and translation in
TranslatedFunctional, ConvexConjugateFuncScaling, etc.

default_functionals_test:
- add a TODO.

functional_test:
- style update.

Author: aringh

examples/solvers/functional_basic_example.py

@@ -15,7 +15,7 @@
 # You should have received a copy of the GNU General Public License
 # along with ODL.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Basic examples on how to write a fucntional.
+"""Basic example on how to write a functional.
 
 When defining a new functional, there are a few standard methods and properties
 that can be implemeted. These are:
@@ -32,8 +32,8 @@
     operator ``x --> <x, grad_f(y)>``. Note that this has a default
     implemetation that uses the gradient in order to achieve this.
 
-Below follows an example of implementing the functional ``||x||_2^2 + <x,y>,
-for some parameter y.``
+Below follows an example of implementing the functional ``||x||_2^2 + <x,y>``,
+for some parameter ``y.``
 """
 
 # Imports for common Python 2/3 codebase
@@ -64,7 +64,7 @@ def __init__(self, domain, y):
         self._y = y
 
     # Now we define a propert which returns y, so that the user can see which
-    # translation is used in a particular instance of the class.
+    # value is used in a particular instance of the class.
     @property
     def y(self):
         return self._y
@@ -80,24 +80,20 @@ def gradient(self):
         # defined anywhere and just returned here, but in this example we will
         # also define it here.
 
-        # In order for the initialization of the operator to know which
-        # functional it comes from.
-        this_functional = self
-
         class MyGradientOperator(odl.Operator):
 
             # Define an __init__ method for this operator
             def __init__(self, functional):
-                super().__init__(domain=this_functional.domain,
-                                 range=this_functional.domain)
+                super().__init__(domain=functional.domain,
+                                 range=functional.domain)
 
                 self._functional = functional
 
             # Define a _call method for this operator
             def _call(self, x):
                 return 2.0 * x + self._functional.y
 
-        return MyGradientOperator(functional=this_functional)
+        return MyGradientOperator(functional=self)
 
     # Next we define the convex conjugate functional
     @property
@@ -108,7 +104,7 @@ def conjugate_functional(self):
 
 # Here is the conjugate functional
 class MyFunctionalConjugate(odl.solvers.Functional):
-    """Hand calculations give that this funtional has the analytic expression
+    """Calculations give that this funtional has the analytic expression
     f^*(x) = ||x||^2/2 - ||x-y||^2/4 + ||y||^2/2 - <x,y>.
     """
     def __init__(self, domain, y):
@@ -164,7 +160,7 @@ def _call(self, x):
 my_deriv = my_func.derivative(x)
 
 if my_deriv(p) == my_gradient(x).inner(p):
-    print('The default implementation of the gradient works as intended.')
+    print('The default implementation of the derivative works as intended.')
 else:
     print('There is a bug in the implementation of the derivative')
 

examples/solvers/functional_basic_example_solver.py

@@ -15,14 +15,15 @@
 # You should have received a copy of the GNU General Public License
 # along with ODL.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Basic examples on how to use the fucntional class together with solvers.
+"""Basic example on how to use the functional class together with solvers.
 
 This file shows an example of how to set up and solve an optimization problem
 using the default functionals. The problem we will solve is to minimize
 1/2 * ||x - g||_2^2 + lam*||x||_1, for some vector g and some constant lam,
 subject to that all components in x are greater than or equal to 0. The
 theoretical optimal solution to this problem is x = (g - lam)_+, where ( )+
-denotes the positive part of (i.e., (z)_+ = z if z >= 0, 0 otherwise).
+denotes the positive part of the element, i.e., (z_i)_+ = z_i if z_i >= 0, and
+0 otherwise.
 """
 
 import numpy as np
@@ -46,9 +47,37 @@
 l2_func = 1.0 / 2.0 * odl.solvers.L2NormSquare(space)
 trans_l2_func = l2_func.translate(g)
 
-# The problem will be solved using the Chambolle-Pock algorithm. Here we create
-# the necessary proximal factories of the conjugate functionals (see the
-# Chambolle-Pock algorithm and examples on this for more information).
+# The problem will be solved using the forward-backward primal-dual algorithm.
+# In this setting we let f = nonnegativity contraint, g = l1-norm, and h =
+# the squared l2-norm. Here we create necessary proximal and gradient operators
+# from the functionals.
+prox_f = odl.solvers.proximal_nonnegativity(space)
+prox_cc_g = lam_l1_func.conjugate_functional.proximal
+L = odl.IdentityOperator(space)
+grad_h = trans_l2_func.gradient
+
+# Some solver parameters
+niter = 50
+tau = 0.5
+sigma = 0.5
+
+# Starting point, and also updated inplace in the solver
+x_fbpd = space.zero()
+
+# Optional: pass callback objects to solver
+callback = (odl.solvers.CallbackPrintIteration())
+
+# Run the algorithm
+odl.solvers.forward_backward_pd(x=x_fbpd, prox_f=prox_f, prox_cc_g=[prox_cc_g],
+                                L=[L], grad_h=grad_h, tau=tau, sigma=[sigma],
+                                niter=niter, callback=callback)
+
+print(x_fbpd.asarray())
+
+
+# The problem can also be solved using, e.g., the Chambolle-Pock algorithm.
+# Here we create the necessary proximal factories of the conjugate functionals
+# (see the Chambolle-Pock algorithm and examples on this for more information).
 prox_cc_l2 = trans_l2_func.conjugate_functional.proximal
 prox_cc_l1 = lam_l1_func.conjugate_functional.proximal
 
@@ -62,23 +91,24 @@
 # Create the proximal operator for the constraint
 proximal_primal = odl.solvers.proximal_nonnegativity(op.domain)
 
-# The operator norm is 1, since only identity operators are used
-op_norm = 1
+# The operator norm is sqrt(2), since only identity operators are used
+op_norm = np.sqrt(2)
 
 # Some solver parameters
-niter = 100  # Number of iterations
+niter = 50  # Number of iterations
 tau = 1.0 / op_norm  # Step size for the primal variable
 sigma = 1.0 / op_norm  # Step size for the dual variable
 
 # Optional: pass callback objects to solver
 callback = (odl.solvers.CallbackPrintIteration())
 
 # Starting point, and also updated inplace in the solver
-x = op.domain.zero()
+x_cp = op.domain.zero()
 
 # Run the algorithm
-odl.solvers.chambolle_pock_solver(
-    op, x, tau=tau, sigma=sigma, proximal_primal=proximal_primal,
-    proximal_dual=proximal_dual, niter=niter, callback=callback)
+odl.solvers.chambolle_pock_solver(op=op, x=x_cp, tau=tau, sigma=sigma,
+                                  proximal_primal=proximal_primal,
+                                  proximal_dual=proximal_dual, niter=niter,
+                                  callback=callback)
 
-print(x.asarray())
+print(x_cp.asarray())