Merge branch 'doc_fixes_mr' into 'NIFTy_5'

Doc fixes mr

Closes #1

See merge request ift/nifty-dev!182

docs/source/code.rst

@@ -264,13 +264,13 @@ This functionality is provided by NIFTy's
 :class:`~inversion_enabler.InversionEnabler` class, which is itself a linear
 operator.
 
-.. currentmodule:: nifty5.operators.linear_operator
+.. currentmodule:: nifty5.operators.operator
 
 Direct multiplication and adjoint inverse multiplication transform a field
-defined on the operator's :attr:`~LinearOperator.domain` to one defined on the
-operator's :attr:`~LinearOperator.target`, whereas adjoint multiplication and
-inverse multiplication transform from :attr:`~LinearOperator.target` to
-:attr:`~LinearOperator.domain`.
+defined on the operator's :attr:`~Operator.domain` to one defined on the
+operator's :attr:`~Operator.target`, whereas adjoint multiplication and inverse
+multiplication transform from :attr:`~Operator.target` to
+:attr:`~Operator.domain`.
 
 .. currentmodule:: nifty5.operators
 
@@ -379,7 +379,7 @@ Minimization algorithms
 
 All minimization algorithms in NIFTy inherit from the abstract
 :class:`~minimizer.Minimizer` class, which presents a minimalistic interface
-consisting only of a :meth:`~minimizer.Minimizer.__call__()` method taking an
+consisting only of a :meth:`~minimizer.Minimizer.__call__` method taking an
 :class:`~energy.Energy` object and optionally a preconditioning operator, and
 returning the energy at the discovered minimum and a status code.
 
@@ -399,17 +399,16 @@ Many minimizers for nonlinear problems can be characterized as
 This family of algorithms is encapsulated in NIFTy's
 :class:`~descent_minimizers.DescentMinimizer` class, which currently has three
 concrete implementations: :class:`~descent_minimizers.SteepestDescent`,
-:class:`~descent_minimizers.RelaxedNewton`,
 :class:`~descent_minimizers.NewtonCG`, :class:`~descent_minimizers.L_BFGS` and
 :class:`~descent_minimizers.VL_BFGS`. Of these algorithms, only
-:class:`~descent_minimizers.RelaxedNewton` requires the energy object to provide
+:class:`~descent_minimizers.NewtonCG` requires the energy object to provide
 a :attr:`~energy.Energy.metric` property, the others only need energy values and
 gradients.
 
 The flexibility of NIFTy's design allows using externally provided minimizers.
 With only small effort, adapters for two SciPy minimizers were written; they are
 available under the names :class:`~scipy_minimizer.ScipyCG` and
-:class:`L_BFGS_B`.
+:class:`~scipy_minimizer.L_BFGS_B`.
 
 
 Application to operator inversion
@@ -432,4 +431,4 @@ performs a minimization of a
 :class:`~minimization.quadratic_energy.QuadraticEnergy` by means of the
 :class:`~minimization.conjugate_gradient.ConjugateGradient` algorithm. An
 example is provided in
-:func:`~ļibrary.wiener_filter_curvature.WienerFilterCurvature`.
+:func:`~library.wiener_filter_curvature.WienerFilterCurvature`.

docs/source/conf.py

@@ -13,6 +13,7 @@ napoleon_use_ivar = True
 napoleon_use_admonition_for_notes = True
 napoleon_use_admonition_for_examples = True
 napoleon_use_admonition_for_references = True
+napoleon_include_special_with_doc = True
 
 project = u'NIFTy5'
 copyright = u'2013-2019, Max-Planck-Society'

docs/source/ift.rst

@@ -9,9 +9,9 @@ Theoretical Background
 
 IFT is fully Bayesian. How else could infinitely many field degrees of freedom be constrained by finite data?
 
-There is a full toolbox of methods that can be used, like the classical approximation (= Maximum a posteriori = MAP), effective action (= Variational Bayes = VI), Feynman diagrams, renormalitation, and more. IFT reproduces many known well working algorithms. This should be reassuring. And, there were certainly previous works in a similar spirit. Anyhow, in many cases IFT provides novel rigorous ways to extract information from data. NIFTy comes with reimplemented MAP and VI estimators. It also provides a Hamiltonian Monte Carlo sampler for Fields (HMCF).
+There is a full toolbox of methods that can be used, like the classical approximation (= Maximum a posteriori = MAP), effective action (= Variational Bayes = VI), Feynman diagrams, renormalization, and more. IFT reproduces many known well working algorithms. This should be reassuring. Also, there were certainly previous works in a similar spirit. Anyhow, in many cases IFT provides novel rigorous ways to extract information from data. NIFTy comes with reimplemented MAP and VI estimators. It also provides a Hamiltonian Monte Carlo sampler for Fields (HMCF). (*FIXME* does it?)
 
-.. tip:: *In-a-nutshell introductions to information field theory* can be found in [2]_, [3]_, [4]_, and [5]_, with the latter probably being the most didactically.
+.. tip:: *In-a-nutshell introductions to information field theory* can be found in [2]_, [3]_, [4]_, and [5]_, with the latter probably being the most didactical.
 
 .. [1] T.A. Enßlin et al. (2009), "Information field theory for cosmological perturbation reconstruction and nonlinear signal analysis", PhysRevD.80.105005, 09/2009; `[arXiv:0806.3474] <http://www.arxiv.org/abs/0806.3474>`_
 
@@ -84,7 +84,7 @@ The above line of argumentation analogously applies to the discretization of ope
     A(x \in \Omega_p, y \in \Omega_q) \quad\mapsto\quad A_{pq} \quad=\quad \frac{\iint_{\Omega_p \Omega_q} \mathrm{d}x \, \mathrm{d}y \; A(x,y)}{\iint_{\Omega_p \Omega_q} \mathrm{d}x \, \mathrm{d}y} \quad=\quad \big< \big< A(x,y) \big>_{\Omega_p} \big>_{\Omega_q}
     .
 
-The proper discretization of spaces, fields, and operators, as well as the normalization of position integrals, is essential for the conservation of the continuum limit. Their consistent implementation in NIFTY allows a pixelization independent coding of algorithms.
+The proper discretization of spaces, fields, and operators, as well as the normalization of position integrals, is essential for the conservation of the continuum limit. Their consistent implementation in NIFTy allows a pixelization independent coding of algorithms.
 
 Free Theory & Implicit Operators
 --------------------------------
@@ -101,7 +101,7 @@ and the measurement equation is linear in both signal and noise,
 
     d= R\, s + n,
 
-with :math:`{R}` the measurement response, which maps the continous signal field into the discrete data space.
+with :math:`{R}` being the measurement response, which maps the continous signal field into the discrete data space.
 
 This is called a free theory, as the information Hamiltonian
 
@@ -137,7 +137,7 @@ the posterior covariance operator, and
 
 the information source. The operation in :math:`{m = D\,R^\dagger N^{-1} d}` is also called the generalized Wiener filter.
 
-NIFTy permits to define the involved operators :math:`{R}`, :math:`{R^\dagger}`, :math:`{S}`, and :math:`{N}` implicitely, as routines that can be applied to vectors, but which do not require the explicit storage of the matrix elements of the operators.
+NIFTy permits to define the involved operators :math:`{R}`, :math:`{R^\dagger}`, :math:`{S}`, and :math:`{N}` implicitly, as routines that can be applied to vectors, but which do not require the explicit storage of the matrix elements of the operators.
 
 Some of these operators are diagonal in harmonic (Fourier) basis, and therefore only require the specification of a (power) spectrum and :math:`{S= F\,\widehat{P_s} F^\dagger}`. Here :math:`{F = \mathrm{HarmonicTransformOperator}}`, :math:`{\widehat{P_s} = \mathrm{DiagonalOperator}(P_s)}`, and :math:`{P_s(k)}` is the power spectrum of the process that generated :math:`{s}` as a function of the (absolute value of the) harmonic (Fourier) space koordinate :math:`{k}`. For those, NIFTy can easily also provide inverse operators, as :math:`{S^{-1}= F\,\widehat{\frac{1}{P_s}} F^\dagger}` in case :math:`{F}` is unitary, :math:`{F^\dagger=F^{-1}}`.
 
@@ -175,10 +175,10 @@ NIFTy takes advantage of this formulation in several ways:
 1) All prior degrees of freedom have unit covariance which improves the condition number of operators which need to be inverted.
 2) The amplitude operator can be regarded as part of the response, :math:`{R'=R\,A}`. In general, more sophisticated responses can be constructed out of the composition of simpler operators.
 3) The response can be non-linear, e.g. :math:`{R'(s)=R \exp(A\,\xi)}`, see demos/getting_started_2.py.
-4) The amplitude operator can be made dependent on unknowns as well, e.g. :math:`A=A(\tau)= F\, \widehat{e^\tau}` represents an amplitude operator with a positive definite, unknown spectrum defined in Fourier domain. The amplitude field :math:`{\tau}` would get its own amplitude operator, with a cepstrum (spectrum of a log spectrum) defined in quefrency space (harmonic space of a logarithmically binned harmonic space) to regularize its degrees of freedom by imposing some (user-defined level of) spectral smoothness.
-5) NIFTy can calculate the gradient of the information Hamiltonian and the Fischer information metric with respect to all unknown parameters, here :math:`{\xi}` and :math:`{\tau}`, by automatic differentiation. The gradients are used for MAP and HMCF estimates, and the Fischer matrix is required in addition to the gradient by Metric Gaussian Variational Inference (MGVI), which is available in NIFTy as well. MGVI is an implicit operator extension of Automatic Differentiation Variational Inference (ADVI).
+4) The amplitude operator can be made dependent on unknowns as well, e.g. :math:`A=A(\tau)= F\, \widehat{e^\tau}` represents an amplitude operator with a positive definite, unknown spectrum defined in the Fourier domain. The amplitude field :math:`{\tau}` would get its own amplitude operator, with a cepstrum (spectrum of a log spectrum) defined in quefrency space (harmonic space of a logarithmically binned harmonic space) to regularize its degrees of freedom by imposing some (user-defined degree of) spectral smoothness.
+5) NIFTy can calculate the gradient of the information Hamiltonian and the Fisher information metric with respect to all unknown parameters, here :math:`{\xi}` and :math:`{\tau}`, by automatic differentiation. The gradients are used for MAP and HMCF estimates, and the Fisher matrix is required in addition to the gradient by Metric Gaussian Variational Inference (MGVI), which is available in NIFTy as well. MGVI is an implicit operator extension of Automatic Differentiation Variational Inference (ADVI).
 
-The reconstruction of a non-Gaussian signal with unknown covarinance from a non-trivial (tomographic) response is demonstrated in demos/getting_started_3.py. Here, the uncertainty of the field and the power spectrum of its generating process are probed via posterior samples provided by the MGVI algorithm.
+The reconstruction of a non-Gaussian signal with unknown covariance from a non-trivial (tomographic) response is demonstrated in demos/getting_started_3.py. Here, the uncertainty of the field and the power spectrum of its generating process are probed via posterior samples provided by the MGVI algorithm.
 
 +----------------------------------------------------+
 | **Output of tomography demo getting_started_3.py** |

nifty5/minimization/minimizer.py

@@ -21,7 +21,6 @@ from ..utilities import NiftyMeta
 class Minimizer(metaclass=NiftyMeta):
     """A base class used by all minimizers."""
 
-    # MR FIXME: the docstring is partially ignored by Sphinx. Why?
     def __call__(self, energy, preconditioner=None):
         """Performs the minimization of the provided Energy functional.