Merge branch 'mr_docs' into 'NIFTy_5'

attempt to document probe_diagonal()

See merge request ift/nifty-dev!184

nifty5/operators/energy_operators.py

@@ -318,7 +318,7 @@ class Hamiltonian(EnergyOperator):
 
 
 class AveragedEnergy(EnergyOperator):
-    """Computes Kullbach-Leibler (KL) divergence or Gibbs free energies.
+    """Computes Kullback-Leibler (KL) divergence or Gibbs free energies.
 
     A sample-averaged energy, e.g. an Hamiltonian, approximates the relevant
     part of a KL to be used in Variational Bayes inference if the samples are

nifty5/probing.py

@@ -107,8 +107,27 @@ def probe_with_posterior_samples(op, post_op, nprobes):
 
 
 def probe_diagonal(op, nprobes, random_type="pm1"):
-    '''
-    FIXME
+    '''Probes the diagonal of an endomorphic operator.
+
+    The operator is called on a user-specified number of randomly generated
+    input vectors :math:`v_i`, producing :math:`r_i`. The estimated diagonal
+    is the mean of :math:`r_i^\dagger v_i`.
+
+    Parameters
+    ----------
+    op: EndomorphicOperator
+        The operator to be probed.
+    nprobes: int
+        The number of probes to be used.
+    random_type: str
+        The kind of random number distribution to be used for the probing.
+        The default value `pm1` causes the probing vector to be randomly
+        filled with values of +1 and -1.
+
+    Returns
+    -------
+    Field
+        The estimated diagonal.
     '''
     sc = StatCalculator()
     for i in range(nprobes):