Commit d1e3ac86 authored by Philipp Arras's avatar Philipp Arras

Work on code.rst

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