Merge branch 'NIFTy_5' into energy_cleanup

docs/source/code.rst

@@ -13,8 +13,10 @@ recognized from a large distance, ignoring all technical details.
 
 From such a perspective,
 
-- IFT problems largely consist of *minimization* problems involving a large
-  number of equations.
+- IFT problems largely consist of the combination of several high dimensional
+  *minimization* problems.
+- Within NIFTy, *models* are used to define the characteristic equations and
+  properties of the problems.
 - The equations are built mostly from the application of *linear operators*,
   but there may also be nonlinear functions involved.
 - The unknowns in the equations represent either continuous physical *fields*,
@@ -232,6 +234,62 @@ The properties :attr:`~LinearOperator.adjoint` and
 were the original operator's adjoint or inverse, respectively.
 
 
+Models
+======
+
+Model classes (represented by NIFTy5's abstract :class:`Model` class) are used to construct
+the equations of a specific inference problem.
+Most models are defined via a position, which is a :class:`MultiField` object,
+their value at this position, which is again a :class:`MultiField` object and a Jacobian derivative,
+which is a :class:`LinearOperator` and is needed for the minimization procedure.
+
+Using the existing basic model classes one can construct more complicated models, as
+NIFTy allows for easy and self-consinstent combination via point-wise multiplication,
+addition and subtraction. The model resulting from these operations then automatically
+contains the correct Jacobians, positions and values.
+Notably, :class:`Constant` and :class:`Variable` allow for an easy way to turn
+inference of specific quantities on and off.
+
+The basic model classes also allow for more complex operations on models such as
+the application of :class:`LinearOperators` or local non-linearities.
+As an example one may consider the following combination of ``x``, which is a model of type
+:class:`Variable` and ``y``, which is a model of type :class:`Constant`::
+
+	z = x*x + y
+
+``z`` will then be a model with the following properties::
+
+	z.value = x.value*x.value + y.value
+	z.position = Union(x.position, y.position)
+	z.jacobian = 2*makeOp(x.value)
+
+
+Basic models
+------------
+
+Basic model classes provided by NIFTy are
+
+- :class:`Constant` contains a constant value and has a zero valued Jacobian.
+  Like other models, it has a position, but its value does not depend on it.
+- :class:`Variable` returns the position as its value, its derivative is one.
+- :class:`LinearModel` applies a :class:`LinearOperator` on the model.
+- :class:`LocalModel` applies a non-linearity locally on the model.
+- :class:`MultiModel` combines various models into one. In this case the position,
+	value and Jacobian are combined into corresponding :class:`MultiFields` and operators.
+
+
+Advanced models
+---------------
+
+NIFTy also provides a library of more sophisticated models which are used for more
+specific inference problems. Currently these are:
+
+- :class:`AmplitudeModel`, which returns a smooth power spectrum.
+- :class:`PointModel`, which models point sources which follow a inverse gamma distribution.
+- :class:`SmoothSkyModel`, which models a diffuse lognormal field. It takes an amplitude model
+	to specify the correlation structure of the field.
+
+
 .. _minimization:
 
 

nifty5/dobj.py

@@ -26,7 +26,7 @@ except ImportError:
     from .data_objects.numpy_do import *
 
 __all__ = ["ntask", "rank", "master", "local_shape", "data_object", "full",
-           "empty", "zeros", "ones", "empty_like", "vdot", "abs", "exp",
+           "empty", "zeros", "ones", "empty_like", "vdot", "exp",
            "log", "tanh", "sqrt", "from_object", "from_random",
            "local_data", "ibegin", "ibegin_from_shape", "np_allreduce_sum",
            "distaxis", "from_local_data", "from_global_data", "to_global_data",

nifty5/field.py

@@ -24,8 +24,6 @@ from .domain_tuple import DomainTuple
 from functools import reduce
 from . import dobj
 
-__all__ = ["Field", "sqrt", "exp", "log", "conjugate"]
-
 
 class Field(object):
     """ The discrete representation of a continuous field over multiple spaces.

nifty5/operators/sampling_enabler.py

@@ -24,16 +24,17 @@ from .endomorphic_operator import EndomorphicOperator
 
 
 class SamplingEnabler(EndomorphicOperator):
-    """Class which augments the capability of another operator object via
-    numerical inversion.
+    """Class which acts as the operator object (likelihood + prior)
+    and enables sampling from its inverse even if the operator object
+    itself does not support it.
+
 
     Parameters
     ----------
-    op : :class:`EndomorphicOperator`
-        The operator to be enhanced.
-        The InversionEnabler object will support the same operation modes as
-        `op`, and additionally the inverse set. The newly-added modes will
-        be computed by iterative inversion.
+    likelihood : :class:`EndomorphicOperator`
+        Curvature of the likelihood
+    prior : :class:`EndomorphicOperator`
+        Inverse curvature of the prior
     iteration_controller : :class:`IterationController`
         The iteration controller to use for the iterative numerical inversion
         done by a :class:`ConjugateGradient` object.