Merge branch 'operator_documentation' into 'NIFTy_5'

Operator documentation

See merge request ift/nifty-dev!86

demos/getting_started_3.py

@@ -100,7 +100,7 @@ if __name__ == '__main__':
                    for _ in range(N_samples)]
 
         KL = ift.SampledKullbachLeiblerDivergence(H, samples)
-        KL = ift.EnergyAdapter(position, KL, ic_cg)
+        KL = ift.EnergyAdapter(position, KL, ic_cg, constants=["xi"])
         KL, convergence = minimizer(KL)
         position = KL.position
 

nifty5/operators/central_zero_padder.py

+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Copyright(C) 2013-2018 Max-Planck-Society
+#
+# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik
+# and financially supported by the Studienstiftung des deutschen Volkes.
+
 from __future__ import absolute_import, division, print_function
 
 import numpy as np
@@ -15,11 +33,29 @@ from .. import dobj
 # MR FIXME: for even axis lengths, we probably should split the value at the
 #           highest frequency.
 class CentralZeroPadder(LinearOperator):
+    """Operator that enlarges a fields domain by adding zeros from the middle.
+
+    Parameters
+    ---------
+
+    domain: Domain, tuple of Domains or DomainTuple
+            The domain of the data that is input by "times" and output by
+            "adjoint_times"
+    new_shape: tuple
+               Shape of the target domain.
+    space: int, optional
+           The index of the subdomain on which the operator should act
+           If None, it is set to 0 if `domain` contains exactly one space.
+           `domain[space]` must be an RGSpace.
+
+    """
+
     def __init__(self, domain, new_shape, space=0):
         self._domain = DomainTuple.make(domain)
         self._space = utilities.infer_space(self._domain, space)
         dom = self._domain[self._space]
 
+        # verify domains
         if not isinstance(dom, RGSpace):
             raise TypeError("RGSpace required")
         if dom.harmonic:
@@ -29,12 +65,15 @@ class CentralZeroPadder(LinearOperator):
         if any([a < b for a, b in zip(new_shape, dom.shape)]):
             raise ValueError("New shape must be larger than old shape")
 
+        # make target space
         tgt = RGSpace(new_shape, dom.distances)
         self._target = list(self._domain)
         self._target[self._space] = tgt
         self._target = DomainTuple.make(self._target)
+
         self._capability = self.TIMES | self.ADJOINT_TIMES
 
+        # define the axes along which the input field is sliced
         slicer = []
         axes = self._target.axes[self._space]
         for i in range(len(self._domain.shape)):
@@ -65,10 +104,14 @@ class CentralZeroPadder(LinearOperator):
         x = dobj.local_data(x)
 
         if mode == self.TIMES:
+            # slice along each axis and copy the data to an
+            # array of zeros which has the shape of the target domain
             y = np.zeros(dobj.local_shape(shp_out, curax), dtype=x.dtype)
             for i in self.slicer:
                 y[i] = x[i]
         else:
+            # slice along each axis and copy the data to an array of zeros
+            # which has the shape of the input domain to remove excess zeros
             y = np.empty(dobj.local_shape(shp_out, curax), dtype=x.dtype)
             for i in self.slicer:
                 y[i] = x[i]

nifty5/operators/exp_transform.py

@@ -31,6 +31,24 @@ from ..utilities import infer_space, special_add_at
 
 
 class ExpTransform(LinearOperator):
+    """
+    Transforms log-space to target.
+
+    This operator creates a log-space subject to the degrees of freedom and
+    and its target-domain.
+    Then transforms between this log-space and its target, which lives in
+    normal units.
+
+    E.g: A field in log-log-space can be transformed into log-norm-space,
+         that is the y-axis stays logarithmic, but the x-axis is transfromed.
+
+    Parameters
+    ----------
+    target : domain, tuple of domains or DomainTuple
+        The full output domain
+    dof : int
+        The degrees of freedom of the log-domain, i.e. the number of bins.
+    """
     def __init__(self, target, dof, space=0):
         self._target = DomainTuple.make(target)
         self._capability = self.TIMES | self.ADJOINT_TIMES

nifty5/operators/slope_operator.py

@@ -29,6 +29,23 @@ from .linear_operator import LinearOperator
 
 
 class SlopeOperator(LinearOperator):
+    """
+    Creates a slope on target.
+
+    This operator creates a field on a LogRGSpace, which is created
+    according to a slope of given entries, (mean, y-intercept).
+    The slope mean is the powerlaw of the field in normal-space.
+
+    Parameters
+    ----------
+    domain : domain or DomainTuple, shape=(2,)
+        It has to be and UnstructuredDomain.
+        The domain of the slope mean and the y-intercept mean.
+    target : domain or DomainTuple
+        The output domain has to a LogRGSpace
+    sigmas : np.array, shape=(2,)
+        The slope variance and the y-intercept variance.
+    """
     def __init__(self, domain, target, sigmas):
         if not isinstance(target, LogRGSpace):
             raise TypeError