diff --git a/docs/source/code.rst b/docs/source/code.rst index d01d01e18026f99e059d494fac6528639fc5a0d6..aaba97077d8237b139993d248cd92e0023b4a6a5 100644 --- a/docs/source/code.rst +++ b/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.