Commit 3cf07f85 authored by Sebastian Hutschenreuter's avatar Sebastian Hutschenreuter
Browse files

Reviewed docs on operators, library, sugar. Fixed bug in makeOp due to the...

Reviewed docs on operators, library, sugar. Fixed bug in makeOp due to the recent BlochdiagonalOperator interface change
parent 3996cb92
...@@ -25,7 +25,7 @@ from .domain_tuple import DomainTuple ...@@ -25,7 +25,7 @@ from .domain_tuple import DomainTuple
class Field(object): class Field(object):
"""The discrete representation of a continuous field over multiple spaces. """The discrete representation of a continuous field over multiple spaces.
Stores data arrays and carries all the needed metainformation (i.e. the Stores data arrays and carries all the needed meta-information (i.e. the
domain) for operators to be able to operate on them. domain) for operators to be able to operate on them.
Parameters Parameters
......
...@@ -41,7 +41,7 @@ def make_adjust_variances(a, ...@@ -41,7 +41,7 @@ def make_adjust_variances(a,
Operator which gives the amplitude when evaluated at a position Operator which gives the amplitude when evaluated at a position
xi : Operator xi : Operator
Operator which gives the excitation when evaluated at a position Operator which gives the excitation when evaluated at a position
postion : Field, MultiField position : Field, MultiField
Position of the whole problem Position of the whole problem
samples : Field, MultiField samples : Field, MultiField
Residual samples of the whole problem Residual samples of the whole problem
......
...@@ -25,15 +25,15 @@ from ..operators.simple_linear_operators import ducktape ...@@ -25,15 +25,15 @@ from ..operators.simple_linear_operators import ducktape
def CorrelatedField(target, amplitude_operator, name='xi'): def CorrelatedField(target, amplitude_operator, name='xi'):
'''Constructs an operator which turns a white Gaussian excitation field """Constructs an operator which turns a white Gaussian excitation field
into a correlated field. into a correlated field.
This function returns an operator which implements: This function returns an operator which implements:
ht @ (vol * A * xi), ht @ (vol * A * xi),
where `ht` is a harmonic transform operator, `A` is the sqare root of the where `ht` is a harmonic transform operator, `A` is the square root of the
prior covariance an `xi` is the excitation field. prior covariance and `xi` is the excitation field.
Parameters Parameters
---------- ----------
...@@ -41,12 +41,12 @@ def CorrelatedField(target, amplitude_operator, name='xi'): ...@@ -41,12 +41,12 @@ def CorrelatedField(target, amplitude_operator, name='xi'):
Target of the operator. Must contain exactly one space. Target of the operator. Must contain exactly one space.
amplitude_operator: Operator amplitude_operator: Operator
name : string name : string
:class:`MultiField` key for xi-field. :class:`MultiField` key for the xi-field.
Returns Returns
------- -------
Correlated field : Operator Correlated field : Operator
''' """
tgt = DomainTuple.make(target) tgt = DomainTuple.make(target)
if len(tgt) > 1: if len(tgt) > 1:
raise ValueError raise ValueError
...@@ -60,7 +60,7 @@ def CorrelatedField(target, amplitude_operator, name='xi'): ...@@ -60,7 +60,7 @@ def CorrelatedField(target, amplitude_operator, name='xi'):
def MfCorrelatedField(target, amplitudes, name='xi'): def MfCorrelatedField(target, amplitudes, name='xi'):
'''Constructs an operator which turns white Gaussian excitation fields """Constructs an operator which turns white Gaussian excitation fields
into a correlated field defined on a DomainTuple with two entries and two into a correlated field defined on a DomainTuple with two entries and two
separate correlation structures. separate correlation structures.
...@@ -79,7 +79,7 @@ def MfCorrelatedField(target, amplitudes, name='xi'): ...@@ -79,7 +79,7 @@ def MfCorrelatedField(target, amplitudes, name='xi'):
Returns Returns
------- -------
Correlated field : Operator Correlated field : Operator
''' """
tgt = DomainTuple.make(target) tgt = DomainTuple.make(target)
if len(tgt) != 2: if len(tgt) != 2:
raise ValueError raise ValueError
......
...@@ -144,7 +144,7 @@ def dynamic_operator(*, ...@@ -144,7 +144,7 @@ def dynamic_operator(*,
key, key,
causal=True, causal=True,
minimum_phase=False): minimum_phase=False):
'''Constructs an operator encoding the Green's function of a linear """Constructs an operator encoding the Green's function of a linear
homogeneous dynamic system. homogeneous dynamic system.
When evaluated, this operator returns the Green's function representation When evaluated, this operator returns the Green's function representation
...@@ -189,7 +189,7 @@ def dynamic_operator(*, ...@@ -189,7 +189,7 @@ def dynamic_operator(*,
Notes Notes
----- -----
The first axis of the domain is interpreted the time axis. The first axis of the domain is interpreted the time axis.
''' """
dct = { dct = {
'target': target, 'target': target,
'harmonic_padding': harmonic_padding, 'harmonic_padding': harmonic_padding,
......
...@@ -31,11 +31,11 @@ class InverseGammaOperator(Operator): ...@@ -31,11 +31,11 @@ class InverseGammaOperator(Operator):
The pdf of the inverse gamma distribution is defined as follows: The pdf of the inverse gamma distribution is defined as follows:
.. math :: .. math ::
\\frac{\\beta^\\alpha}{\\Gamma(\\alpha)}x^{-\\alpha -1}\\exp \\left(-\\frac{\\beta }{x}\\right) \\frac{q^\\alpha}{\\Gamma(\\alpha)}x^{-\\alpha -1}\\exp \\left(-\\frac{q}{x}\\right)
That means that for large x the pdf falls off like x^(-alpha -1). That means that for large x the pdf falls off like :math:`x^(-\\alpha -1)`.
The mean of the pdf is at q / (alpha - 1) if alpha > 1. The mean of the pdf is at :math:`q / (\\alpha - 1)` if :math:`\\alpha > 1`.
The mode is q / (alpha + 1). The mode is :math:`q / (\\alpha + 1)`.
This transformation is implemented as a linear interpolation which maps a This transformation is implemented as a linear interpolation which maps a
Gaussian onto a inverse gamma distribution. Gaussian onto a inverse gamma distribution.
......
...@@ -104,7 +104,7 @@ def apply_erf(wgt, dist, lo, mid, hi, sig, erf): ...@@ -104,7 +104,7 @@ def apply_erf(wgt, dist, lo, mid, hi, sig, erf):
class LOSResponse(LinearOperator): class LOSResponse(LinearOperator):
"""Line-of-sight response operator """Line-of-sight response operator
This operator transforms from a single RGSpace to an unstructured domain This operator transforms from a single RGSpace to an UnstructuredDomain
with as many entries as there were lines of sight passed to the with as many entries as there were lines of sight passed to the
constructor. Adjoint application is also provided. constructor. Adjoint application is also provided.
......
...@@ -33,7 +33,7 @@ def _ceps_kernel(k, a, k0): ...@@ -33,7 +33,7 @@ def _ceps_kernel(k, a, k0):
def CepstrumOperator(target, a, k0): def CepstrumOperator(target, a, k0):
'''Turns a white Gaussian random field into a smooth field on a LogRGSpace. """Turns a white Gaussian random field into a smooth field on a LogRGSpace.
Composed out of three operators: Composed out of three operators:
...@@ -69,10 +69,10 @@ def CepstrumOperator(target, a, k0): ...@@ -69,10 +69,10 @@ def CepstrumOperator(target, a, k0):
regularization of the inverse laplace operator to be finite at zero. regularization of the inverse laplace operator to be finite at zero.
Larger values for the cutoff results in a weaker constraining prior. Larger values for the cutoff results in a weaker constraining prior.
k0 : float, list of float k0 : float, list of float
Strength of smothness prior in quefrency space (positive only) along Strength of smoothness prior in quefrency space (positive only) along
each axis. If float then the strength is the same along each axis. each axis. If float then the strength is the same along each axis.
Larger values result in a weaker constraining prior. Larger values result in a weaker constraining prior.
''' """
a = float(a) a = float(a)
target = DomainTuple.make(target) target = DomainTuple.make(target)
if a <= 0: if a <= 0:
......
...@@ -25,7 +25,8 @@ from .domain_tuple import DomainTuple ...@@ -25,7 +25,8 @@ from .domain_tuple import DomainTuple
class MultiField(object): class MultiField(object):
def __init__(self, domain, val): def __init__(self, domain, val):
""" """The discrete representation of a continuous field over a sum space.
Parameters Parameters
---------- ----------
domain: MultiDomain domain: MultiDomain
......
...@@ -24,9 +24,10 @@ class BlockDiagonalOperator(EndomorphicOperator): ...@@ -24,9 +24,10 @@ class BlockDiagonalOperator(EndomorphicOperator):
""" """
Parameters Parameters
---------- ----------
domain : :class:`MultiDomain`
Domain and target of the operator.
operators : dict operators : dict
Dictionary with operators domain names as keys and LinearOperators as Dictionary with subdomain names as keys and :class:`LinearOperators` as items.
items.
""" """
def __init__(self, domain, operators): def __init__(self, domain, operators):
if not isinstance(domain, MultiDomain): if not isinstance(domain, MultiDomain):
......
...@@ -23,7 +23,12 @@ from .simple_linear_operators import NullOperator ...@@ -23,7 +23,12 @@ from .simple_linear_operators import NullOperator
class ChainOperator(LinearOperator): class ChainOperator(LinearOperator):
"""Class representing chains of operators.""" """Class representing chains of operators.
Notes
-----
This operator has to be called using the :attr:`make` method.
"""
def __init__(self, ops, _callingfrommake=False): def __init__(self, ops, _callingfrommake=False):
if not _callingfrommake: if not _callingfrommake:
......
...@@ -24,10 +24,10 @@ from .linear_operator import LinearOperator ...@@ -24,10 +24,10 @@ from .linear_operator import LinearOperator
class ContractionOperator(LinearOperator): class ContractionOperator(LinearOperator):
"""A linear operator which sums up fields into the direction of subspaces. """A :class:`LinearOperator` which sums up fields into the direction of subspaces.
This ContractionOperator sums up a field with is defined on a DomainTuple This Operator sums up a field with is defined on a :class:`DomainTuple`
to a DomainTuple which contains the former as a subset. to a :class:`DomainTuple` which contains the former as a subset.
Parameters Parameters
---------- ----------
......
...@@ -24,10 +24,10 @@ from .endomorphic_operator import EndomorphicOperator ...@@ -24,10 +24,10 @@ from .endomorphic_operator import EndomorphicOperator
class DiagonalOperator(EndomorphicOperator): class DiagonalOperator(EndomorphicOperator):
"""Represents a linear operator which is diagonal. """Represents a :class:`LinearOperator` which is diagonal.
The NIFTy DiagonalOperator class is a subclass derived from the The NIFTy DiagonalOperator class is a subclass derived from the
EndomorphicOperator. It multiplies an input field pixel-wise with its :class:`EndomorphicOperator`. It multiplies an input field pixel-wise with its
diagonal. diagonal.
Parameters Parameters
......
...@@ -23,7 +23,7 @@ from .linear_operator import LinearOperator ...@@ -23,7 +23,7 @@ from .linear_operator import LinearOperator
class DomainTupleFieldInserter(LinearOperator): class DomainTupleFieldInserter(LinearOperator):
'''Writes the content of a field into one slice of a DomainTuple. """Writes the content of a :class:`Field` into one slice of a :class:`DomainTuple`.
Parameters Parameters
---------- ----------
...@@ -33,7 +33,7 @@ class DomainTupleFieldInserter(LinearOperator): ...@@ -33,7 +33,7 @@ class DomainTupleFieldInserter(LinearOperator):
Index at which new_space shall be added to domain. Index at which new_space shall be added to domain.
position : tuple position : tuple
Slice in new_space in which the input field shall be written into. Slice in new_space in which the input field shall be written into.
''' """
def __init__(self, domain, new_space, index, position): def __init__(self, domain, new_space, index, position):
self._domain = DomainTuple.make(domain) self._domain = DomainTuple.make(domain)
tgt = list(self.domain) tgt = list(self.domain)
......
...@@ -21,7 +21,7 @@ from .linear_operator import LinearOperator ...@@ -21,7 +21,7 @@ from .linear_operator import LinearOperator
class EndomorphicOperator(LinearOperator): class EndomorphicOperator(LinearOperator):
"""Represents a linear operator which is endomorphic, i.e. one which """Represents a :class:`LinearOperator` which is endomorphic, i.e. one which
has identical domain and target. has identical domain and target.
""" """
@property @property
......
...@@ -49,7 +49,7 @@ class SquaredNormOperator(EnergyOperator): ...@@ -49,7 +49,7 @@ class SquaredNormOperator(EnergyOperator):
Parameters Parameters
---------- ----------
domain : Domain, DomainTuple or tuple of Domain domain : Domain, DomainTuple or tuple of Domain
Target domain of the operator in which the L2-norm shall be computed. Domain of the operator in which the L2-norm shall be computed.
""" """
def __init__(self, domain): def __init__(self, domain):
...@@ -66,7 +66,7 @@ class SquaredNormOperator(EnergyOperator): ...@@ -66,7 +66,7 @@ class SquaredNormOperator(EnergyOperator):
class QuadraticFormOperator(EnergyOperator): class QuadraticFormOperator(EnergyOperator):
"""Computes the L2-norm of a Field or MultiField with respect to a """Computes the L2-norm of a Field or MultiField with respect to a
specific metric `endo`. specific kernel given by `endo`.
.. math :: .. math ::
E(f) = \\frac12 f^\\dagger \\text{endo}(f) E(f) = \\frac12 f^\\dagger \\text{endo}(f)
...@@ -74,7 +74,7 @@ class QuadraticFormOperator(EnergyOperator): ...@@ -74,7 +74,7 @@ class QuadraticFormOperator(EnergyOperator):
Parameters Parameters
---------- ----------
endo : EndomorphicOperator endo : EndomorphicOperator
Kernel of quadratic form. Kernel of the quadratic form
""" """
def __init__(self, endo): def __init__(self, endo):
...@@ -283,7 +283,7 @@ class Hamiltonian(EnergyOperator): ...@@ -283,7 +283,7 @@ class Hamiltonian(EnergyOperator):
lh : EnergyOperator lh : EnergyOperator
The likelihood energy. The likelihood energy.
ic_samp : IterationController ic_samp : IterationController
Tells an internal :class:`SamplingEnabler` which convergence criterium Tells an internal :class:`SamplingEnabler` which convergence criterion
to use to draw Gaussian samples. to use to draw Gaussian samples.
......
...@@ -31,13 +31,13 @@ class ExpTransform(LinearOperator): ...@@ -31,13 +31,13 @@ class ExpTransform(LinearOperator):
This operator creates a log-space subject to the degrees of freedom and This operator creates a log-space subject to the degrees of freedom and
and its target-domain. and its target-domain.
Then transforms between this log-space and its target, which is defined in Then it transforms between this log-space and its target, which is defined in
normal units. normal units.
FIXME Write something on t_0 of domain space FIXME Write something on t_0 of domain space
E.g: A field in log-log-space can be transformed into log-norm-space, E.g: A field in log-log-space can be transformed into log-norm-space,
that is the y-axis stays logarithmic, but the x-axis is transfromed. that is the y-axis stays logarithmic, but the x-axis is transformed.
Parameters Parameters
---------- ----------
......
...@@ -143,7 +143,7 @@ class HartleyOperator(LinearOperator): ...@@ -143,7 +143,7 @@ class HartleyOperator(LinearOperator):
(https://en.wikipedia.org/wiki/Discrete_Hartley_transform). (https://en.wikipedia.org/wiki/Discrete_Hartley_transform).
For complex input fields, the operator will transform the real and For complex input fields, the operator will transform the real and
imaginary parts separately and use the results as real and imaginary parts imaginary parts separately and use the results as real and imaginary parts
of the result field, respectivey. of the result field, respectively.
In many contexts the Hartley transform is a perfect substitute for the In many contexts the Hartley transform is a perfect substitute for the
Fourier transform, but in some situations (e.g. convolution with a general, Fourier transform, but in some situations (e.g. convolution with a general,
non-symmetric kernel, the full FFT must be used instead. non-symmetric kernel, the full FFT must be used instead.
...@@ -386,7 +386,7 @@ class HarmonicTransformOperator(LinearOperator): ...@@ -386,7 +386,7 @@ class HarmonicTransformOperator(LinearOperator):
def HarmonicSmoothingOperator(domain, sigma, space=None): def HarmonicSmoothingOperator(domain, sigma, space=None):
"""Returns an operator that carries out a smoothing with a Gaussian kernel """Returns an operator that carries out a smoothing with a Gaussian kernel
of width `sigma` on the part of `domain` given by `space` of width `sigma` on the part of `domain` given by `space`.
Parameters Parameters
---------- ----------
...@@ -408,7 +408,7 @@ def HarmonicSmoothingOperator(domain, sigma, space=None): ...@@ -408,7 +408,7 @@ def HarmonicSmoothingOperator(domain, sigma, space=None):
sigma = float(sigma) sigma = float(sigma)
if sigma < 0.: if sigma < 0.:
raise ValueError("sigma must be nonnegative") raise ValueError("sigma must be non-negative")
if sigma == 0.: if sigma == 0.:
return ScalingOperator(1., domain) return ScalingOperator(1., domain)
......
...@@ -35,9 +35,8 @@ class LinearInterpolator(LinearOperator): ...@@ -35,9 +35,8 @@ class LinearInterpolator(LinearOperator):
Parameters Parameters
---------- ----------
domain : RGSpace domain : RGSpace
positions : numpy.ndarray sampling_points : numpy.ndarray, shape (dim, ndata)
Positions at which to interpolate Positions at which to interpolate.
Field with UnstructuredDomain, shape (dim, ndata)
Notes Notes
----- -----
......
...@@ -19,12 +19,13 @@ from .operator import Operator ...@@ -19,12 +19,13 @@ from .operator import Operator
class OffsetOperator(Operator): class OffsetOperator(Operator):
'''Shifts the input by a fixed field. """Shifts the input by a fixed field.
Parameters Parameters
---------- ----------
field : Field field : Field
The field by which the input is shifted.''' The field by which the input is shifted.
"""
def __init__(self, field): def __init__(self, field):
self._field = field self._field = field
self._domain = self._target = field.domain self._domain = self._target = field.domain
......
...@@ -110,14 +110,14 @@ class Operator(NiftyMetaBase()): ...@@ -110,14 +110,14 @@ class Operator(NiftyMetaBase()):
return _OpChain.make((_Clipper(self.target, min, max), self)) return _OpChain.make((_Clipper(self.target, min, max), self))
def apply(self, x): def apply(self, x):
'''Applies the operator to a Field or MultiField. """Applies the operator to a Field or MultiField.
Parameters Parameters
---------- ----------
x : Field or MultiField x : Field or MultiField
Input on which the operator shall act. Needs to be defined on Input on which the operator shall act. Needs to be defined on
:attr:`domain`. :attr:`domain`.
''' """
raise NotImplementedError raise NotImplementedError
def force(self, x): def force(self, x):
......
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