Commit f630300b authored by Pumpe, Daniel (dpumpe)'s avatar Pumpe, Daniel (dpumpe)
Browse files

Docstrings for DiagonalOperator

parent 17484a4e
......@@ -28,6 +28,61 @@ 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.
Parameters
----------
domain : NIFTy.Space
The Space on which the operator acts
diagonal : {scalar, list, array, NIFTy.Field, d2o-object}
The diagonal entries of the operator.
bare : boolean
Indicates whether the diagonal entries are 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.
Attributes
----------
distribution_strategy : string
Defines the diagonal is distributed among the nodes.
Raises
------
Notes
-----
The ambiguity of bare or non-bare diagonal entries is based on the choice
of a matrix representation of the operator in question. The naive choice
of absorbing the volume weights into the matrix leads to a matrix-vector
calculus with the non-bare entries which seems intuitive, though.
The choice of keeping matrix entries and volume weights separate
deals with the bare entries that allow for correct interpretation
of the matrix entries; e.g., as variance in case of an covariance operator.
Examples
--------
>>> x_space = RGSpace(5)
>>> D = DiagonalOperator(x_space, diagonal=2.)
>>> f = Field(x_space, val=1.)
>>> res = D.times(f)
>>> res.val
<distributed_data_object>
array([ 2., 2., 2., 2., 2.])
See Also
--------
EndomorphicOperator
"""
# ---Overwritten properties and methods---
def __init__(self, domain=(), implemented=True,
......@@ -64,6 +119,23 @@ class DiagonalOperator(EndomorphicOperator):
operation=lambda z: z.adjoint().__rdiv__)
def diagonal(self, bare=False, copy=True):
""" Returns the diagonal of the operator.
Parameters
----------
bare : boolean
Whether the returned Field values should be bare or not.
copy : boolean
Whether the returned Field should be copied or not.
Returns
-------
out : NIFTy.Field
the diagonal of the Operator
See Also
--------
"""
if bare:
diagonal = self._diagonal.weight(power=-1)
elif copy:
......@@ -73,25 +145,118 @@ class DiagonalOperator(EndomorphicOperator):
return diagonal
def inverse_diagonal(self, bare=False):
""" Returns the inverse-diagonal of the operator.
Parameters
----------
bare : boolean
Whether the returned Field values should be bare or not.
Returns
-------
out : NIFTy.Field
the inverse-diagonal of the Operator
See Also
--------
"""
return 1/self.diagonal(bare=bare, copy=False)
def trace(self, bare=False):
""" Returns the trace the operator.
Parameters
----------
bare : boolean
Whether the returned Field values should be bare or not.
Returns
-------
out : scalar
the trace of the Operator
See Also
--------
"""
return self.diagonal(bare=bare, copy=False).sum()
def inverse_trace(self, bare=False):
""" Returns the inverse-trace of the operator.
Parameters
----------
bare : boolean
Whether the returned Field values should be bare or not.
Returns
-------
out : scalar
the inverse-trace of the Operator
See Also
--------
"""
return self.inverse_diagonal(bare=bare, copy=False).sum()
def trace_log(self):
""" Returns the trave-log of the operator.
Parameters
----------
Returns
-------
out : scalar
the trace-log of the Operator
See Also
--------
"""
log_diagonal = self.diagonal(copy=False).apply_scalar_function(np.log)
return log_diagonal.sum()
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---
......@@ -138,6 +303,26 @@ class DiagonalOperator(EndomorphicOperator):
return distribution_strategy
def set_diagonal(self, diagonal, bare=False, copy=True):
""" Sets the diagonal of the Operator.
Parameters
----------
diagonal : {scalar, list, array, NIFTy.Field, d2o-object}
The diagonal entries of the operator.
bare : boolean
Indicates whether the diagonal entries are bare or not
(default: False)
copy : boolean
Internal copy of the diagonal (default: True)
Returns
-------
See Also
--------
"""
# use the casting functionality from Field to process `diagonal`
f = Field(domain=self.domain,
val=diagonal,
......
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