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`:
.. 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.
......
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