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

start documenting

parent dd23c622
......@@ -20,6 +20,25 @@ from ..minimization.energy import Energy
class EnergyAdapter(Energy):
"""Helper class which provides the traditional Nifty Energy interface to
Nifty operators with a scalar target domain.
Parameters
-----------
position: Field or MultiField living on the operator's input domain.
The position where the minimization process is started
op: Operator with a scalar target domain
The expression computing the energy from the input data
constants: list of strings (default: [])
The component names of the operator's input domain which are assumed
to be constant during the minimization process.
If the operator's input domain is not a MultiField, this must be empty.
want_metric: bool (default: False)
if True, the class will provide a `metric` property. This should only
be enabled if it is required, because it will most likely consume
additional resources.
"""
def __init__(self, position, op, constants=[], want_metric=False):
super(EnergyAdapter, self).__init__(position)
self._op = op
......
......@@ -143,7 +143,24 @@ class GradientNormController(IterationController):
class GradInfNormController(IterationController):
def __init__(self, tol=None, convergence_level=1, iteration_limit=None,
"""An iteration controller checking (mainly) the L_infinity gradient norm.
Parameters
----------
tol : float
If the L_infinity norm of the energy gradient is below this value, the
convergence counter will be increased in this iteration.
convergence_level : int, default=1
The number which the convergence counter must reach before the
iteration is considered to be converged
iteration_limit : int, optional
The maximum number of iterations that will be carried out.
name : str, optional
if supplied, this string and some diagnostic information will be
printed after every iteration
"""
def __init__(self, tol, convergence_level=1, iteration_limit=None,
name=None):
self._tol = tol
self._convergence_level = convergence_level
......@@ -185,6 +202,25 @@ class GradInfNormController(IterationController):
class DeltaEnergyController(IterationController):
"""An iteration controller checking (mainly) the energy change from one
iteration to the next.
Parameters
----------
tol_rel_deltaE : float
If the difference between the last and current energies divided by
the current energy is below this value, the convergence counter will
be increased in this iteration.
convergence_level : int, default=1
The number which the convergence counter must reach before the
iteration is considered to be converged
iteration_limit : int, optional
The maximum number of iterations that will be carried out.
name : str, optional
if supplied, this string and some diagnostic information will be
printed after every iteration
"""
def __init__(self, tol_rel_deltaE, convergence_level=1,
iteration_limit=None, name=None):
self._tol_rel_deltaE = tol_rel_deltaE
......
......@@ -25,6 +25,13 @@ from .linear_operator import LinearOperator
class VdotOperator(LinearOperator):
"""Operator computing the scalar product of its input with a given Field.
Parameters
----------
field : Field/MultiField
The field used to build the scalar product with the operator input
"""
def __init__(self, field):
self._field = field
self._domain = field.domain
......@@ -39,6 +46,7 @@ class VdotOperator(LinearOperator):
class ConjugationOperator(EndomorphicOperator):
"""Operator computing the complex conjugate of its input."""
def __init__(self, domain):
self._domain = DomainTuple.make(domain)
self._capability = self._all_ops
......@@ -49,6 +57,7 @@ class ConjugationOperator(EndomorphicOperator):
class Realizer(EndomorphicOperator):
"""Operator returning the real component of its input."""
def __init__(self, domain):
self._domain = DomainTuple.make(domain)
self._capability = self.TIMES | self.ADJOINT_TIMES
......
......@@ -19,10 +19,25 @@ from .field import Field
class StatCalculator(object):
"""Helper class to compute mean and variance of a set of inputs.
Notes
-----
- the memory usage of this object is constant, i.e. it does not increase
with the number of samples added
- FIXME describe the kind of variance used (divided by n-1)
"""
def __init__(self):
self._count = 0
def add(self, value):
"""Adds a sample.
Parameters
----------
value: any type that supports multiplication by a scalar and
element-wise addition/subtraction/multiplication.
"""
self._count += 1
if self._count == 1:
self._mean = 1.*value
......@@ -35,12 +50,18 @@ class StatCalculator(object):
@property
def mean(self):
"""
value type : the mean of all samples added so far.
"""
if self._count == 0:
raise RuntimeError
return 1.*self._mean
@property
def var(self):
"""
value type : the variance of all samples added so far.
"""
if self._count < 2:
raise RuntimeError
return self._M2 * (1./(self._count-1))
......
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