Commit ba6dc97b authored by Martin Reinecke's avatar Martin Reinecke
Browse files

some documentation work

parent 012feede
...@@ -99,6 +99,7 @@ Combinations of domains ...@@ -99,6 +99,7 @@ Combinations of domains
The fundamental classes described above are often sufficient to specify the The fundamental classes described above are often sufficient to specify the
domain of a field. In some cases, however, it will be necessary to have the domain of a field. In some cases, however, it will be necessary to have the
field live on a product of elementary domains instead of a single one. field live on a product of elementary domains instead of a single one.
More sophisticated models 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
...@@ -107,6 +108,9 @@ Some examples are: ...@@ -107,6 +108,9 @@ Some examples are:
- a polarised field, which could be modeled as a product of any structured - a polarised 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:`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 Consequently, NIFTy defines a class called :class:`DomainTuple` holding
a sequence of :class:`Domain` objects, which is used to specify full field a sequence of :class:`Domain` objects, which is used to specify full field
...@@ -117,10 +121,15 @@ A :class:`DomainTuple` supports iteration and indexing, and also provides the ...@@ -117,10 +121,15 @@ A :class:`DomainTuple` supports iteration and indexing, and also provides the
properties :attr:`~DomainTuple.shape`, :attr:`~DomainTuple.size` in analogy to properties :attr:`~DomainTuple.shape`, :attr:`~DomainTuple.size` in analogy to
the elementary :class:`Domain`. the elementary :class:`Domain`.
An aggregation of several :class:`DomainTuple`s, each member identified by a
name, is described by the :class:`MultiDomain` class.
Fields Fields
====== ======
Fields on a single DomainTuple
------------------------------
A :class:`Field` object consists of the following components: A :class:`Field` object consists of the following components:
- a domain in form of a :class:`DomainTuple` object - a domain in form of a :class:`DomainTuple` object
...@@ -148,14 +157,44 @@ that are not covered by the provided standard operations, its data content must ...@@ -148,14 +157,44 @@ that are not covered by the provided standard operations, its data content must
be extracted first, then changed, and a new field has to be created from the be extracted first, then changed, and a new field has to be created from the
result. result.
Fields living on a MultiDomain
------------------------------
The :class:`MultiField` class can be seen as a dictionary of individual
:class:`Field`s, each identified by a name, which lives on an associated
:class:`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 `domain` which returns
a `Domaintuple` or `MultiDomain` object specifying the structure of the
`Field`s or `MultiField`s it expects as input, another property `target`
describing its output, and finally an overloaded `apply` method, which can
take
- a `Field`/`MultiField`object, in which case it returns the transformed
`Field`/`MultiField`
- a `Linearization` object, in which case it returns the transformed
`Linearization`
This is the interface that all objects derived from `Operator` must implement.
In addition, `Operator` objects can be added/subtracted, multiplied, chained
(via the `__call__` method) and support pointwise application of functions like
`exp()`, `log()`, `sqrt()`, `conjugate()` etc.
Linear Operators Linear Operators
================ ================
A linear operator (represented by NIFTy5's abstract :class:`LinearOperator` A linear operator (represented by NIFTy5's abstract :class:`LinearOperator`
class) can be interpreted as an (implicitly defined) matrix. class) is derived from `Operator` and can be interpreted as an
It can be applied to :class:`Field` instances, resulting in other :class:`Field` (implicitly defined) matrix. Since its operation is linear, it can provide some
instances that potentially live on other domains. additional functionality which is not available for the more generic `Operator`
class.
Operator basics Operator basics
...@@ -163,13 +202,13 @@ Operator basics ...@@ -163,13 +202,13 @@ Operator basics
There are four basic ways of applying an operator :math:`A` to a field :math:`f`: There are four basic ways of applying an operator :math:`A` to a field :math:`f`:
- direct multiplication: :math:`A\cdot f` - direct application: :math:`A\cdot f`
- adjoint multiplication: :math:`A^\dagger \cdot f` - adjoint application: :math:`A^\dagger \cdot f`
- inverse multiplication: :math:`A^{-1}\cdot f` - inverse application: :math:`A^{-1}\cdot f`
- adjoint inverse multiplication: :math:`(A^\dagger)^{-1}\cdot f` - adjoint inverse application: :math:`(A^\dagger)^{-1}\cdot f`
(For linear operators, inverse adjoint multiplication and adjoint inverse (Because of the linearity, inverse adjoint and adjoint inverse application
multiplication are equivalent.) are equivalent.)
These different actions of an operator ``Op`` on a field ``f`` can be invoked These different actions of an operator ``Op`` on a field ``f`` can be invoked
in various ways: in various ways:
...@@ -190,9 +229,6 @@ enhanced by this approach to support the complete set. This functionality is ...@@ -190,9 +229,6 @@ enhanced by this approach to support the complete set. This functionality is
provided by NIFTy's :class:`InversionEnabler` class, which is itself a linear provided by NIFTy's :class:`InversionEnabler` class, which is itself a linear
operator. operator.
There are two :class:`DomainTuple` objects associated with a
:class:`LinearOperator`: a :attr:`~LinearOperator.domain` and a
:attr:`~LinearOperator.target`.
Direct multiplication and adjoint inverse multiplication transform a field Direct multiplication and adjoint inverse multiplication transform a field
living on the operator's :attr:`~LinearOperator.domain` to one living on the operator's :attr:`~LinearOperator.target`, whereas adjoint multiplication living on the operator's :attr:`~LinearOperator.domain` to one living on the operator's :attr:`~LinearOperator.target`, whereas adjoint multiplication
and inverse multiplication transform from :attr:`~LinearOperator.target` to :attr:`~LinearOperator.domain`. and inverse multiplication transform from :attr:`~LinearOperator.target` to :attr:`~LinearOperator.domain`.
...@@ -221,7 +257,7 @@ operators. ...@@ -221,7 +257,7 @@ 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:`LinearOperator`
and ``f1`` and ``f2`` are of type :class:`Field`, writing:: and ``f1`` and ``f2`` are of type :class:`Field`, writing::
X = A*B.inverse*A.adjoint + C X = A(B.inverse(A.adjoint)) + C
f2 = X(f1) f2 = X(f1)
will perform the operation suggested intuitively by the notation, checking will perform the operation suggested intuitively by the notation, checking
......
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