Work on code.rst

docs/source/code.rst

@@ -89,16 +89,17 @@ NIFTy comes with several concrete subclasses of :class:`StructuredDomain`:
 
 .. currentmodule:: nifty5.domains
 
-- :class:`rg_space.RGSpace` represents a regular Cartesian grid with an arbitrary
+- :class:`~rg_space.RGSpace` represents a regular Cartesian grid with an arbitrary
   number of dimensions, which is supposed to be periodic in each dimension.
-- :class:`hp_space.HPSpace` and :class:`gl_space.GLSpace` describe pixelisations of the
-  2-sphere; their counterpart in harmonic space is :class:`lm_space.LMSpace`, which
+- :class:`~hp_space.HPSpace` and :class:`~gl_space.GLSpace` describe pixelisations of the
+  2-sphere; their counterpart in harmonic space is :class:`~lm_space.LMSpace`, which
   contains spherical harmonic coefficients.
-- :class:`power_space.PowerSpace` is used to describe one-dimensional power spectra.
+- :class:`~power_space.PowerSpace` is used to describe one-dimensional power spectra.
 
-Among these, :class:`rg_space.RGSpace` can be harmonic or not (depending on constructor arguments), :class:`gl_space.GLSpace`, :class:`hp_space.HPSpace`, and :class:`power_space.PowerSpace` are
-pure position domains (i.e. nonharmonic), and :class:`lm_space.LMSpace` is always
-harmonic.
+Among these, :class:`~rg_space.RGSpace` can be harmonic or not (depending on
+constructor arguments), :class:`~gl_space.GLSpace`, :class:`~hp_space.HPSpace`,
+and :class:`~power_space.PowerSpace` are pure position domains (i.e.
+nonharmonic), and :class:`~lm_space.LMSpace` is always harmonic.
 
 
 Combinations of domains
@@ -110,27 +111,31 @@ field on a product of elementary domains instead of a single one.
 More sophisticated operators also require a set of several such fields.
 Some examples are:
 
-- sky emission depending on location and energy. This could be represented by
-  a product of an :class:`HPSpace` (for location) with an :class:`RGSpace`
-  (for energy).
+- sky emission depending on location and energy. This could be represented by a
+  product of an :class:`~hp_space.HPSpace` (for location) with an
+  :class:`~rg_space.RGSpace` (for energy).
 - a polarized field, which could be modeled as a product of any structured
   domain (representing location) with a four-element
-  :class:`UnstructuredDomain` holding Stokes I, Q, U and V components.
+  :class:`~unstructured_domain.UnstructuredDomain` holding Stokes I, Q, U and V components.
 - a model for the sky emission, which holds both the current realization
   (on a harmonic domain) and a few inferred model parameters (e.g. on an
   unstructured grid).
 
-Consequently, NIFTy defines a class called :class:`DomainTuple` holding
-a sequence of :class:`Domain` objects, which is used to specify full field
-domains. In principle, a :class:`DomainTuple` can even be empty, which implies
-that the field living on it is a scalar.
+.. currentmodule:: nifty5
 
-A :class:`DomainTuple` supports iteration and indexing, and also provides the
-properties :attr:`~DomainTuple.shape`, :attr:`~DomainTuple.size` in analogy to
-the elementary :class:`Domain`.
+Consequently, NIFTy defines a class called :class:`~domain_tuple.DomainTuple`
+holding a sequence of :class:`~domains.domain.Domain` objects, which is used to
+specify full field domains. In principle, a :class:`~domain_tuple.DomainTuple`
+can even be empty, which implies that the field living on it is a scalar.
 
-An aggregation of several :class:`DomainTuple` s, each member identified by a
-name, is described by the :class:`MultiDomain` class.
+A :class:`~domain_tuple.DomainTuple` supports iteration and indexing, and also
+provides the properties :attr:`~domain_tuple.DomainTuple.shape`,
+:attr:`~domain_tuple.DomainTuple.size` in analogy to the elementary
+:class:`~domains.domain.Domain`.
+
+An aggregation of several :class:`~domain_tuple.DomainTuple` s, each member
+identified by a name, is described by the :class:`~multi_domain.MultiDomain`
+class.
 
 Fields
 ======
@@ -138,9 +143,9 @@ Fields
 Fields on a single DomainTuple
 ------------------------------
 
-A :class:`Field` object consists of the following components:
+A :class:`~field.Field` object consists of the following components:
 
-- a domain in form of a :class:`DomainTuple` object
+- a domain in form of a :class:`~domain_tuple.DomainTuple` object
 - a data type (e.g. numpy.float64)
 - an array containing the actual values
 
@@ -168,52 +173,57 @@ result.
 Fields defined on a MultiDomain
 -------------------------------
 
-The :class:`MultiField` class can be seen as a dictionary of individual
-:class:`Field` s, each identified by a name, which is defined on a
-:class:`MultiDomain`.
+The :class:`~multi_field.MultiField` class can be seen as a dictionary of
+individual :class:`~field.Field` s, each identified by a name, which is defined
+on a :class:`~multi_domain.MultiDomain`.
 
 
 Operators
 =========
 
-All transformations between different NIFTy fields are expressed  (explicitly
-or implicitly) in the form of :class:`Operator` objects. The interface of this
-class is very minimalistic: it has a property called :class:`domain` which returns
-a :class:`DomainTuple` or :class:`MultiDomain` object specifying the structure of the
-:class:`Field` s or :class:`MultiField` s it expects as input, another property :class:`target`
-describing its output, and finally an overloaded `apply` method, which can
-take
-
-- a :class:`Field`/:class:`MultiField` object, in which case it returns the transformed
-  :class:`Field`/:class:`MultiField`
-- a :class:`Linearization` object, in which case it returns the transformed
-  :class:`Linearization`
-
-This is the interface that all objects derived from :class:`Operator` must implement.
-In addition, :class:`Operator` objects can be added/subtracted, multiplied, chained
-(via the :class:`__call__` method and the `@` operator) and support pointwise
-application of functions like
-:class:`exp()`, :class:`log()`, :class:`sqrt()`, :class:`conjugate()` etc.
+All transformations between different NIFTy fields are expressed in the form of
+:class:`~operators.operator.Operator` objects. The interface of this class is
+rather minimalistic: it has a property called
+:attr:`~operators.operator.Operator.domain` which returns a
+:class:`~domain_tuple.DomainTuple` or :class:`~multi_domain.MultiDomain` object
+specifying the structure of the :class:`~field.Field` or
+:class:`~multi_field.MultiField` it expects as input, another property
+:attr:`~operators.operator.Operator.target` describing its output, and finally
+an overloaded :attr:`~operators.operator.Operator.apply` method, which can take:
+
+- a :class:`~field.Field`/:class:`~multi_field.MultiField` object, in which case
+  it returns the transformed :class:`~field.Field`/:class:`~multi_field.MultiField`.
+- a :class:`~linearization.Linearization` object, in which case it returns the
+  transformed :class:`~linearization.Linearization`.
+
+This is the interface that all objects derived from
+:class:`~operators.operator.Operator` must implement. In addition,
+:class:`~operators.operator.Operator` objects can be added/subtracted,
+multiplied, chained (via the :attr:`__call__` method
+or the `@` operator) and support point-wise application of functions like
+:class:`exp()`, :class:`log()`, :class:`sqrt()`, :class:`conjugate()`.
 
 
 Advanced operators
 ------------------
 
-NIFTy provides a library of more sophisticated operators which are used for more
+NIFTy provides a library of commonly employed operators which can be used for
 specific inference problems. Currently these are:
 
 - :class:`AmplitudeOperator`, which returns a smooth power spectrum.
-- :class:`InverseGammaOperator`, which models point sources which follow a inverse gamma distribution.
-- :class:`CorrelatedField`, which models a diffuse log-normal field. It takes an amplitude operator to specify the correlation structure of the field.
+- :class:`InverseGammaOperator`, which models point sources which are
+  distributed according to a inverse-gamma distribution.
+- :class:`CorrelatedField`, which models a diffuse log-normal field. It takes an
+  amplitude operator to specify the correlation structure of the field.
 
 
 Linear Operators
 ================
 
-A linear operator (represented by NIFTy5's abstract :class:`LinearOperator`
+A linear operator (represented by NIFTy5's abstract :class:`operators.linear_operator.LinearOperator`
 class) is derived from `Operator` and can be interpreted as an
 (implicitly defined) matrix. Since its operation is linear, it can provide some
-additional functionality which is not available for the more generic :class:`Operator`
+additional functionality which is not available for the more generic :class:`operators.operator.Operator`
 class.
 
 
@@ -274,8 +284,8 @@ Syntactic sugar
 
 Nifty5 allows simple and intuitive construction of altered and combined
 operators.
-As an example, if ``A``, ``B`` and ``C`` are of type :class:`LinearOperator`
-and ``f1`` and ``f2`` are of type :class:`Field`, writing::
+As an example, if ``A``, ``B`` and ``C`` are of type :class:`operators.linear_operator.LinearOperator`
+and ``f1`` and ``f2`` are of type :class:`~field.Field`, writing::
 
     X = A(B.inverse(A.adjoint)) + C
     f2 = X(f1)
@@ -292,11 +302,11 @@ were the original operator's adjoint or inverse, respectively.
 Operators
 =========
 
-Operator classes (represented by NIFTy5's abstract :class:`Operator` class) are used to construct
+Operator classes (represented by NIFTy5's abstract :class:`operators.operator.Operator` class) are used to construct
 the equations of a specific inference problem.
-Most operators 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.
+Most operators are defined via a position, which is a :class:`~multi_field.MultiField` object,
+their value at this position, which is again a :class:`~multi_field.MultiField` object and a Jacobian derivative,
+which is a :class:`operators.linear_operator.LinearOperator` and is needed for the minimization procedure.
 
 Using the existing basic operator classes one can construct more complicated operators, as
 NIFTy allows for easy and self-consinstent combination via point-wise multiplication,
@@ -328,7 +338,7 @@ Basic operator classes provided by NIFTy are
 - :class:`Constant` contains a constant value and has a zero valued Jacobian.
   Like other operators, 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:`LinearModel` applies a :class:`operators.linear_operator.LinearOperator` on the model.
 - :class:`LocalModel` applies a non-linearity locally on the model.
 	value and Jacobian are combined into corresponding :class:`MultiFields` and operators.