start documenting

nifty5/minimization/energy_adapter.py

@@ -20,6 +20,25 @@ from ..minimization.energy import Energy
 
 
 class EnergyAdapter(Energy):
+    """Helper class which provides the traditional Nifty Energy interface to
+    Nifty operators with a scalar target domain.
+
+    Parameters
+    -----------
+    position: Field or MultiField living on the operator's input domain.
+        The position where the minimization process is started
+    op: Operator with a scalar target domain
+        The expression computing the energy from the input data
+    constants: list of strings (default: [])
+        The component names of the operator's input domain which are assumed
+        to be constant during the minimization process.
+        If the operator's input domain is not a MultiField, this must be empty.
+    want_metric: bool (default: False)
+        if True, the class will provide a `metric` property. This should only
+        be enabled if it is required, because it will most likely consume
+        additional resources.
+    """
+
     def __init__(self, position, op, constants=[], want_metric=False):
         super(EnergyAdapter, self).__init__(position)
         self._op = op

nifty5/minimization/iteration_controllers.py

@@ -143,7 +143,24 @@ class GradientNormController(IterationController):
 
 
 class GradInfNormController(IterationController):
-    def __init__(self, tol=None, convergence_level=1, iteration_limit=None,
+    """An iteration controller checking (mainly) the L_infinity gradient norm.
+
+    Parameters
+    ----------
+    tol : float
+        If the L_infinity norm of the energy gradient is below this value, the
+        convergence counter will be increased in this iteration.
+    convergence_level : int, default=1
+        The number which the convergence counter must reach before the
+        iteration is considered to be converged
+    iteration_limit : int, optional
+        The maximum number of iterations that will be carried out.
+    name : str, optional
+        if supplied, this string and some diagnostic information will be
+        printed after every iteration
+    """
+
+    def __init__(self, tol, convergence_level=1, iteration_limit=None,
                  name=None):
         self._tol = tol
         self._convergence_level = convergence_level
@@ -185,6 +202,25 @@ class GradInfNormController(IterationController):
 
 
 class DeltaEnergyController(IterationController):
+    """An iteration controller checking (mainly) the energy change from one
+    iteration to the next.
+
+    Parameters
+    ----------
+    tol_rel_deltaE : float
+        If the difference between the last and current energies divided by
+        the current energy is below this value, the convergence counter will
+        be increased in this iteration.
+    convergence_level : int, default=1
+        The number which the convergence counter must reach before the
+        iteration is considered to be converged
+    iteration_limit : int, optional
+        The maximum number of iterations that will be carried out.
+    name : str, optional
+        if supplied, this string and some diagnostic information will be
+        printed after every iteration
+    """
+
     def __init__(self, tol_rel_deltaE, convergence_level=1,
                  iteration_limit=None, name=None):
         self._tol_rel_deltaE = tol_rel_deltaE

nifty5/operators/simple_linear_operators.py

@@ -25,6 +25,13 @@ from .linear_operator import LinearOperator
 
 
 class VdotOperator(LinearOperator):
+    """Operator computing the scalar product of its input with a given Field.
+
+    Parameters
+    ----------
+    field : Field/MultiField
+        The field used to build the scalar product with the operator input
+    """
     def __init__(self, field):
         self._field = field
         self._domain = field.domain
@@ -39,6 +46,7 @@ class VdotOperator(LinearOperator):
 
 
 class ConjugationOperator(EndomorphicOperator):
+    """Operator computing the complex conjugate of its input."""
     def __init__(self, domain):
         self._domain = DomainTuple.make(domain)
         self._capability = self._all_ops
@@ -49,6 +57,7 @@ class ConjugationOperator(EndomorphicOperator):
 
 
 class Realizer(EndomorphicOperator):
+    """Operator returning the real component of its input."""
     def __init__(self, domain):
         self._domain = DomainTuple.make(domain)
         self._capability = self.TIMES | self.ADJOINT_TIMES

nifty5/probing.py

@@ -19,10 +19,25 @@ from .field import Field
 
 
 class StatCalculator(object):
+    """Helper class to compute mean and variance of a set of inputs.
+
+    Notes
+    -----
+    - the memory usage of this object is constant, i.e. it does not increase
+      with the number of samples added
+    - FIXME describe the kind of variance used (divided by n-1)
+    """
     def __init__(self):
         self._count = 0
 
     def add(self, value):
+        """Adds a sample.
+
+        Parameters
+        ----------
+        value: any type that supports multiplication by a scalar and
+               element-wise addition/subtraction/multiplication.
+        """
         self._count += 1
         if self._count == 1:
             self._mean = 1.*value
@@ -35,12 +50,18 @@ class StatCalculator(object):
 
     @property
     def mean(self):
+        """
+        value type : the mean of all samples added so far.
+        """
         if self._count == 0:
             raise RuntimeError
         return 1.*self._mean
 
     @property
     def var(self):
+        """
+        value type : the variance of all samples added so far.
+        """
         if self._count < 2:
             raise RuntimeError
         return self._M2 * (1./(self._count-1))