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 ...@@ -20,6 +20,25 @@ from ..minimization.energy import Energy
class EnergyAdapter(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): def __init__(self, position, op, constants=[], want_metric=False):
super(EnergyAdapter, self).__init__(position) super(EnergyAdapter, self).__init__(position)
self._op = op self._op = op
......
...@@ -143,7 +143,24 @@ class GradientNormController(IterationController): ...@@ -143,7 +143,24 @@ class GradientNormController(IterationController):
class GradInfNormController(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): name=None):
self._tol = tol self._tol = tol
self._convergence_level = convergence_level self._convergence_level = convergence_level
...@@ -185,6 +202,25 @@ class GradInfNormController(IterationController): ...@@ -185,6 +202,25 @@ class GradInfNormController(IterationController):
class DeltaEnergyController(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, def __init__(self, tol_rel_deltaE, convergence_level=1,
iteration_limit=None, name=None): iteration_limit=None, name=None):
self._tol_rel_deltaE = tol_rel_deltaE self._tol_rel_deltaE = tol_rel_deltaE
......
...@@ -25,6 +25,13 @@ from .linear_operator import LinearOperator ...@@ -25,6 +25,13 @@ from .linear_operator import LinearOperator
class VdotOperator(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): def __init__(self, field):
self._field = field self._field = field
self._domain = field.domain self._domain = field.domain
...@@ -39,6 +46,7 @@ class VdotOperator(LinearOperator): ...@@ -39,6 +46,7 @@ class VdotOperator(LinearOperator):
class ConjugationOperator(EndomorphicOperator): class ConjugationOperator(EndomorphicOperator):
"""Operator computing the complex conjugate of its input."""
def __init__(self, domain): def __init__(self, domain):
self._domain = DomainTuple.make(domain) self._domain = DomainTuple.make(domain)
self._capability = self._all_ops self._capability = self._all_ops
...@@ -49,6 +57,7 @@ class ConjugationOperator(EndomorphicOperator): ...@@ -49,6 +57,7 @@ class ConjugationOperator(EndomorphicOperator):
class Realizer(EndomorphicOperator): class Realizer(EndomorphicOperator):
"""Operator returning the real component of its input."""
def __init__(self, domain): def __init__(self, domain):
self._domain = DomainTuple.make(domain) self._domain = DomainTuple.make(domain)
self._capability = self.TIMES | self.ADJOINT_TIMES self._capability = self.TIMES | self.ADJOINT_TIMES
......
...@@ -19,10 +19,25 @@ from .field import Field ...@@ -19,10 +19,25 @@ from .field import Field
class StatCalculator(object): 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): def __init__(self):
self._count = 0 self._count = 0
def add(self, value): 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 self._count += 1
if self._count == 1: if self._count == 1:
self._mean = 1.*value self._mean = 1.*value
...@@ -35,12 +50,18 @@ class StatCalculator(object): ...@@ -35,12 +50,18 @@ class StatCalculator(object):
@property @property
def mean(self): def mean(self):
"""
value type : the mean of all samples added so far.
"""
if self._count == 0: if self._count == 0:
raise RuntimeError raise RuntimeError
return 1.*self._mean return 1.*self._mean
@property @property
def var(self): def var(self):
"""
value type : the variance of all samples added so far.
"""
if self._count < 2: if self._count < 2:
raise RuntimeError raise RuntimeError
return self._M2 * (1./(self._count-1)) 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