Commit 6861afd1 authored by Theo Steininger's avatar Theo Steininger
Browse files

Docstring refactoring.

parent 7bb482cf
Pipeline #12385 passed with stages
in 11 minutes and 59 seconds
......@@ -20,45 +20,47 @@ from nifty.operators.linear_operator import LinearOperator
class ComposedOperator(LinearOperator):
""" NIFTY class for composed operators.
"""NIFTY class for composed operators.
The NIFTY composed operator class inherits multiple Operators of various kinds acting on
a Field living over a product space.
The NIFTY composed operator class combines multiple linear operators.
Parameters
----------
Operators : tuple(NIFTy.LinearOperators)
Contains the list of LinearOperators.
operators : tuple of NIFTy Operators
The tuple of LinearOperators.
Attributes
----------
domain : NIFTy.space
domain : tuple of DomainObjects, i.e. Spaces and FieldTypes
The NIFTy.space in which the operator is defined.
target : NIFTy.space
target : tuple of DomainObjects, i.e. Spaces and FieldTypes
The NIFTy.space in which the outcome of the operator lives
Raises
------
TypeError
Raised if
* the elements of the operator list is not an instance of the
LinearOperator-baseclass
* an element of the operator list is not an instance of the
LinearOperator-baseclass.
Notes
-----
Very usefull in case one has to transform a NIFTy.Field living over the product space. (see example below)
Very usefull in case one has to transform a Field living over a product
space (see example below).
Examples
--------
Minimal example of transforming a Field living on two domains into its harmonic space.
Minimal example of transforming a Field living on two domains into its
harmonic space.
>>> x1 = RGSpace(5)
>>> x2 = RGSpace(10)
>>> k1 = RGRGTransformation.get_codomain(x1)
>>> k2 = RGRGTransformation.get_codomain(x2)
>>> FFT1 = FFTOperator(domain=x1, target=k1, domain_dtype=np.float64, target_dtype=np.complex128)
>>> FFT2 = FFTOperator(domain=x2, target=k2, domain_dtype=np.float64, target_dtype=np.complex128)
>>> FFT1 = FFTOperator(domain=x1, target=k1,
domain_dtype=np.float64, target_dtype=np.complex128)
>>> FFT2 = FFTOperator(domain=x2, target=k2,
domain_dtype=np.float64, target_dtype=np.complex128)
>>> FFT = ComposedOperator((FFT1, FFT2)
>>> f = Field.from_random('normal', domain=(x1,x2))
>>> FFT.times(f)
......
......@@ -28,32 +28,34 @@ from nifty.operators.endomorphic_operator import EndomorphicOperator
class DiagonalOperator(EndomorphicOperator):
""" NIFTY class for diagonal operators.
The NIFTY DiagonalOperator class is a subclass derived from the
EndomorphicOperator. It multiplies an input field pixel-wise with its
diagonal.
"""NIFTY class for diagonal operators.
The NIFTY DiagonalOperator class is a subclass derived from the
EndomorphicOperator.
Parameters
----------
domain : NIFTy.Space
The Space on which the operator acts
diagonal : {scalar, list, array, NIFTy.Field, d2o-object}
domain : tuple of DomainObjects, i.e. Spaces and FieldTypes
The domain on which the Operator's input Field lives.
diagonal : {scalar, list, array, Field, d2o-object}
The diagonal entries of the operator.
bare : boolean
Indicates whether the diagonal entries are bare or not
(default: False)
Indicates whether the input for the diagonal is bare or not
(default: False).
copy : boolean
Internal copy of the diagonal (default: True)
distribution_strategy : string
setting the prober distribution_strategy of the
diagonal (default : None). In case diagonal is d2o-object or Field,
their distribution_strategy is reused.
their distribution_strategy is used as a fallback.
Attributes
----------
distribution_strategy : string
Defines the diagonal is distributed among the nodes.
Defines the distribution_strategy of the distributed_data_object
in which the diagonal entries are stored in.
Raises
------
......@@ -71,12 +73,12 @@ class DiagonalOperator(EndomorphicOperator):
Examples
--------
>>> x_space = RGSpace(5)
>>> D = DiagonalOperator(x_space, diagonal=2.)
>>> f = Field(x_space, val=1.)
>>> D = DiagonalOperator(x_space, diagonal=[1., 3., 2., 4., 6.])
>>> f = Field(x_space, val=2.)
>>> res = D.times(f)
>>> res.val
<distributed_data_object>
array([ 2., 2., 2., 2., 2.])
array([ 2., 6., 4., 8., 12.])
See Also
--------
......@@ -119,7 +121,7 @@ class DiagonalOperator(EndomorphicOperator):
operation=lambda z: z.adjoint().__rdiv__)
def diagonal(self, bare=False, copy=True):
""" Returns the diagonal of the operator.
""" Returns the diagonal of the Operator.
Parameters
----------
......@@ -130,11 +132,9 @@ class DiagonalOperator(EndomorphicOperator):
Returns
-------
out : NIFTy.Field
the diagonal of the Operator
out : Field
The diagonal of the Operator.
See Also
--------
"""
if bare:
diagonal = self._diagonal.weight(power=-1)
......@@ -154,11 +154,9 @@ class DiagonalOperator(EndomorphicOperator):
Returns
-------
out : NIFTy.Field
the inverse-diagonal of the Operator
out : Field
The inverse of the diagonal of the Operator.
See Also
--------
"""
return 1./self.diagonal(bare=bare, copy=False)
......@@ -173,10 +171,8 @@ class DiagonalOperator(EndomorphicOperator):
Returns
-------
out : scalar
the trace of the Operator
The trace of the Operator.
See Also
--------
"""
return self.diagonal(bare=bare, copy=False).sum()
......@@ -191,25 +187,19 @@ class DiagonalOperator(EndomorphicOperator):
Returns
-------
out : scalar
the inverse-trace of the Operator
The inverse of the trace of the Operator.
See Also
--------
"""
return self.inverse_diagonal(bare=bare).sum()
def trace_log(self):
""" Returns the trave-log of the operator.
Parameters
----------
Returns
-------
out : scalar
the trace-log of the Operator
the trace of the logarithm of the Operator.
See Also
--------
"""
log_diagonal = nifty_log(self.diagonal(copy=False))
return log_diagonal.sum()
......@@ -217,46 +207,37 @@ class DiagonalOperator(EndomorphicOperator):
def determinant(self):
""" Returns the determinant of the operator.
Parameters
----------
Returns
-------
out : scalar
the determinant of the Operator
See Also
--------
"""
return self.diagonal(copy=False).val.prod()
def inverse_determinant(self):
""" Returns the inverse-determinant of the operator.
Parameters
----------
Returns
-------
out : scalar
the inverse-determinant of the Operator
See Also
--------
"""
return 1/self.determinant()
def log_determinant(self):
""" Returns the log-eterminant of the operator.
Parameters
----------
Returns
-------
out : scalar
the log-determinant of the Operator
See Also
--------
"""
return np.log(self.determinant())
# ---Mandatory properties and methods---
......@@ -285,18 +266,14 @@ class DiagonalOperator(EndomorphicOperator):
"""
distribution_strategy : string
Defines the way how the diagonal operator is distributed
among the nodes.
Popoular ones are:
'fftw'
'all'
'local'
'slicing'
'not'
'hdf5'
among the nodes. Available distribution_strategies are:
'fftw', 'equal' and 'not'.
Notes :
https://arxiv.org/abs/1606.05385
"""
return self._distribution_strategy
def _parse_distribution_strategy(self, distribution_strategy, val):
......@@ -318,22 +295,16 @@ class DiagonalOperator(EndomorphicOperator):
Parameters
----------
diagonal : {scalar, list, array, NIFTy.Field, d2o-object}
diagonal : {scalar, list, array, Field, d2o-object}
The diagonal entries of the operator.
bare : boolean
Indicates whether the diagonal entries are bare or not
(default: False)
Indicates whether the input for the diagonal is bare or not
(default: False).
copy : boolean
Internal copy of the diagonal (default: True)
Specifies if a copy of the input shall be made (default: True).
Returns
-------
See Also
--------
"""
# use the casting functionality from Field to process `diagonal`
f = Field(domain=self.domain,
val=diagonal,
......
......@@ -22,22 +22,23 @@ from nifty.operators.linear_operator import LinearOperator
class EndomorphicOperator(LinearOperator):
""" NIFTY class for endomorphic operators.
"""NIFTY class for endomorphic operators.
The NIFTY EndomorphicOperator class is a class derived from the
LinearOperator. Domain and target are the same in any EndomorphicOperator.
Prominent other specific operator subclasses, in NIFTy are
(e.g. DiagonalOperator, SmoothingOperator,
PropagatorOperator, ProjectionOperator).
LinearOperator. By definition, domain and target are the same in
EndomorphicOperator.
Parameters
----------
#TODO: Copy Parameters from LinearOperator
Attributes
----------
target : NIFTy.space
The NIFTy.space in which the outcome of the operator lives.
As the Operator is endomorphic this is the same as its domain.
domain : tuple of DomainObjects, i.e. Spaces and FieldTypes
The domain on which the Operator's input Field lives.
target : tuple of DomainObjects, i.e. Spaces and FieldTypes
The domain in which the outcome of the operator lives. As the Operator
is endomorphic this is the same as its domain.
self_adjoint : boolean
Indicates whether the operator is self_adjoint or not.
......@@ -61,33 +62,9 @@ class EndomorphicOperator(LinearOperator):
"""
# ---Overwritten properties and methods---
def inverse_times(self, x, spaces=None):
""" Applies the inverse-Operator to a given Field.
Operator and Field have to live over the same domain.
Parameters
----------
x : NIFTY.Field
the input Field on which the operator acts on
spaces : integer (default: None)
defines on which space of the given Field the Operator acts
**kwargs
Additional keyword arguments get passed to the used copy_empty
routine.
Returns
-------
out : NIFTy.Field
the processed Field living on the domain space
See Also
--------
"""
if self.self_adjoint and self.unitary:
return self.times(x, spaces)
else:
......@@ -96,29 +73,6 @@ class EndomorphicOperator(LinearOperator):
spaces=spaces)
def adjoint_times(self, x, spaces=None):
""" Applies the adjoint-Operator to a given Field.
Operator and Field have to live over the same domain.
Parameters
----------
x : NIFTY.Field
applies the Operator to the given Field
spaces : integer (default: None)
defines on which space of the given Field the Operator acts
**kwargs
Additional keyword arguments get passed to the used copy_empty
routine.
Returns
-------
out : NIFTy.Field
the processed Field living on the domain space
See Also
--------
"""
if self.self_adjoint:
return self.times(x, spaces)
else:
......@@ -127,29 +81,6 @@ class EndomorphicOperator(LinearOperator):
spaces=spaces)
def adjoint_inverse_times(self, x, spaces=None):
""" Applies the adjoint-inverse-Operator to a given Field.
Operator and Field have to live over the same domain.
Parameters
----------
x : NIFTY.Field
applies the Operator to the given Field
spaces : integer (default: None)
defines on which space of the given Field the Operator acts
**kwargs
Additional keyword arguments get passed to the used copy_empty
routine.
Returns
-------
out : NIFTy.Field
the processed Field living on the domain space
See Also
--------
"""
if self.self_adjoint:
return self.inverse_times(x, spaces)
else:
......@@ -158,29 +89,6 @@ class EndomorphicOperator(LinearOperator):
spaces=spaces)
def inverse_adjoint_times(self, x, spaces=None):
""" Applies the inverse-adjoint-Operator to a given Field.
Operator and Field have to live over the same domain.
Parameters
----------
x : NIFTY.Field
applies the Operator to the given Field
spaces : integer (default: None)
defines on which space of the given Field the Operator acts
**kwargs
Additional keyword arguments get passed to the used copy_empty
routine.
Returns
-------
out : NIFTy.Field
the processed Field living on the domain space
See Also
--------
"""
if self.self_adjoint:
return self.inverse_times(x, spaces)
else:
......@@ -198,14 +106,7 @@ class EndomorphicOperator(LinearOperator):
@abc.abstractproperty
def self_adjoint(self):
""" States whether the Operator is self_adjoint or not.
"""
self_adjoint : boolean
States whether the Operator is self_adjoint or not
Every operator which inherits from the abstract EndomorphicOperator
class must have this attribute.
Notes :
is an abstractbaseclass.abstractproperty
(https://docs.python.org/2/library/abc.html)
"""
raise NotImplementedError
......@@ -22,23 +22,23 @@ from nifty.field import Field
class InvertibleOperatorMixin(object):
""" Mixin class to invert implicit defined operators.
"""NIFTY to invert implicit defined operators.
To invert the application of a given implicitly defined operator on a field,
this class gives the necessary functionality. Inheriting functionality from
this class provides you with the inverse to the given implicitly definied
application of the operator on a field. (e.g. .inverse_times vs. .times
and .adjoint_times vs. .adjoint_inverse_times)
To invert the application of a given implicitly defined operator on a
field, this class gives the necessary functionality. Inheriting
functionality from this class provides the derived class with the inverse
to the given implicitly definied application of the operator on a field.
(e.g. .inverse_times vs. .times and
.adjoint_times vs. .adjoint_inverse_times)
Parameters
----------
inverter : Minimization object
Defines the object how to minimize the functional
inverter : Inverter
An instance of an Inverter class.
(default: ConjugateGradient)
preconditioner : LinearOperator
Preconditions the minimizaion problem
(further details see any good text book about conjugate gradient)
Attributes
----------
......@@ -51,13 +51,11 @@ class InvertibleOperatorMixin(object):
Examples
--------
most promiment see PropagatorOperator class
The PropagatorOperator inherits from InvertibleOperatorMixin.
See Also
--------
EndomorphicOperator, ProjectionOperator,
DiagonalOperator, SmoothingOperator, ResponseOperator,
PropagatorOperator, ComposedOperator
PropagatorOperator
"""
......
......@@ -25,27 +25,28 @@ import nifty.nifty_utilities as utilities
class LinearOperator(Loggable, object):
"""NIFTY base class for linear operators.
The base NIFTY operator class is an abstract class from which
other specific operator subclasses, including those preimplemented
in NIFTY (e.g. the EndomorphicOperator, ProjectionOperator,
DiagonalOperator, SmoothingOperator, ResponseOperator,
PropagatorOperator, ComposedOperator) must be derived.
PropagatorOperator, ComposedOperator) are derived.
Parameters
----------
default_spaces : tuple of ints *optional*
Defines on which space(s) of a given field the Operator acts by
default (default: None)
Attributes
----------
domain : NIFTy.space
The NIFTy.space in which the operator is defined.
target : NIFTy.space
The NIFTy.space in which the outcome of the operator lives
domain : tuple of DomainObjects, i.e. Spaces and FieldTypes
The domain on which the Operator's input Field lives.
target : tuple of DomainObjects, i.e. Spaces and FieldTypes
The domain in which the Operators result lives.
unitary : boolean
Indicates whether the operator is unitary or not
Indicates whether the Operator is unitary or not.
Raises
------
......@@ -57,13 +58,9 @@ class LinearOperator(Loggable, object):
Notes
-----
All Operators wihtin NIFTy are linear and must therefore be a subclasses of the
LinearOperator. A LinearOperator must have the attributes domain, target
and unitary to be properly defined.
Examples
--------
All Operators wihtin NIFTy are linear and must therefore be a subclasses of
the LinearOperator. A LinearOperator must have the attributes domain,
target and unitary to be properly defined.
See Also
--------
......@@ -84,29 +81,25 @@ class LinearOperator(Loggable, object):
@abc.abstractproperty
def domain(self):
"""
domain : NIFTy.space
The NIFTy.space in which the operator is defined.
Every operator which inherits from the abstract LinearOperator
domain : tuple of DomainObjects, i.e. Spaces and FieldTypes
The domain on which the Operator's input Field lives.
Every Operator which inherits from the abstract LinearOperator
base class must have this attribute.
Notes :
is an abstractbaseclass.abstractproperty
(https://docs.python.org/2/library/abc.html)
"""
raise NotImplementedError
@abc.abstractproperty
def target(self):
"""
target : NIFTy.space
The NIFTy.space on which the processed (output) Field lives.
Every operator which inherits from the abstract LinearOperator
target : tuple of DomainObjects, i.e. Spaces and FieldTypes
The domain on which the Operator's output Field lives.
Every Operator which inherits from the abstract LinearOperator
base class must have this attribute.
Notes :
is an abstractbaseclass.abstractproperty
(https://docs.python.org/2/library/abc.html)
"""
raise NotImplementedError
@abc.abstractproperty
......@@ -117,11 +110,8 @@ class LinearOperator(Loggable, object):
Every Operator which inherits from the abstract LinearOperator
base class must have this attribute.
Notes :
is an abstractbaseclass.abstractproperty
(https://docs.python.org/2/library/abc.html)
"""
raise NotImplementedError
@property
......@@ -135,134 +125,110 @@ class LinearOperator(Loggable, object):
def __call__(self, *args, **kwargs):
return self.times(*args, **kwargs)