Commit 86891afb authored by Martin Reinecke's avatar Martin Reinecke
Browse files

first round of fixes

parent 4a44d1e8
......@@ -27,17 +27,16 @@ from .simple_linear_operators import VdotOperator
class EnergyOperator(Operator):
""" Basis class EnergyOperator, an abstract class from which
""" An abstract class from which
other specific EnergyOperator subclasses are derived.
An EnergyOperator has a scalar domain as target domain.
It turns a field into a scalar and a linearization into a linearization.
It is intended as an objective function for field inference.
Typical usage in IFT:
as an information Hamiltonian ( = negative log probability)
or as a Gibbs free energy ( = averaged Hamiltonian),
- as an information Hamiltonian (i.e. a negative log probability)
- or as a Gibbs free energy (i.e. an averaged Hamiltonian),
aka Kullbach-Leibler divergence.
"""
_target = DomainTuple.scalar_domain()
......@@ -73,12 +72,12 @@ class QuadraticFormOperator(EnergyOperator):
op : EndomorphicOperator
kernel of quadratic form
Usage
Notes
-----
E = QuadraticFormOperator(op) represents a field energy that is a
`E = QuadraticFormOperator(op)` represents a field energy that is a
quadratic form in a field f with kernel op:
E(f) = 0.5 f^dagger op f
:math:`E(f) = 0.5 f^\dagger op f`
"""
def __init__(self, op):
from .endomorphic_operator import EndomorphicOperator
......@@ -102,23 +101,20 @@ class GaussianEnergy(EnergyOperator):
Attributes
----------
mean = mean (field) of the Gaussian,
default = 0
covariance = field covariance of the Gaussian,
default = identity operator
domain = domain of field,
default = domain of mean or covariance if specified
One of the attributes has to be specified at instanciation of a GaussianEnergy
to inform about the domain, otherwise an exception is rasied.
Usage
mean : Field
mean of the Gaussian, (default 0)
covariance : LinearOperator
covariance of the Gaussian (default = identity operator)
domain : Domainoid
operator domain, inferred from mean or covariance if specified
Notes
-----
E = GaussianEnergy(mean = m, covariance = D) represents (up to constants)
E(f) = - log G(f-m, D) = 0.5 (f-m)^dagger D^-1 (f-m)
- At least one of the arguments has to be provided.
- `E = GaussianEnergy(mean=m, covariance=D)` represents (up to constants)
:math:`E(f) = - \log G(f-m, D) = 0.5 (f-m)^\dagger D^{-1} (f-m)`,
an information energy for a Gaussian distribution with mean m and covariance D.
"""
def __init__(self, mean=None, covariance=None, domain=None):
self._domain = None
......@@ -164,13 +160,13 @@ class PoissonianEnergy(EnergyOperator):
d : Field
data field with counts
Usage
Notes
-----
E = GaussianEnergy(d) represents (up to an f-independent term log(d!))
E(f) = -log Poisson(d|f) = sum(f) - d^dagger log(f),
E(f) = -\log Poisson(d|f) = sum(f) - d^\dagger \log(f),
where f is a field in data space (d.domain) with the expectation values for
where f is a Field in data space with the expectation values for
the counts.
"""
def __init__(self, d):
......@@ -217,11 +213,11 @@ class BernoulliEnergy(EnergyOperator):
d : Field
data field with events (=1) or non-events (=0)
Usage
Notes
-----
E = BernoulliEnergy(d) represents
E(f) = -log Bernoulli(d|f) = -d^dagger log(f) - (1-d)^dagger log(1-f),
:math:`E(f) = -\log \mbox{Bernoulli}(d|f) = -d^\dagger \log f - (1-d)^\dagger \log(1-f)`,
where f is a field in data space (d.domain) with the expected frequencies of
events.
......@@ -255,17 +251,15 @@ class Hamiltonian(EnergyOperator):
(= Hessian without terms that generate negative eigenvalues)
default = None
Usage
Notes
-----
H = Hamiltonian(E_lh) represents
H(f) = 0.5 f^dagger f + E_lh(f)
:math:`H(f) = 0.5 f^\dagger f + E_{lh}(f)`
an information Hamiltonian for a field f with a white Gaussian prior
(unit covariance) and the likelihood energy E_lh.
(unit covariance) and the likelihood energy :math:`E_{lh}`.
Tip
---
Other field priors can be represented via transformations of a white
Gaussian field into a field with the desired prior probability structure.
......@@ -332,8 +326,8 @@ class SampledKullbachLeiblerDivergence(EnergyOperator):
set of residual sample points to be added to mean field
for approximate estimation of the KL
Usage:
------
Notes
-----
KL = SampledKullbachLeiblerDivergence(H, samples) represents
KL(m) = sum_i H(m+v_i) / N,
......@@ -341,8 +335,6 @@ class SampledKullbachLeiblerDivergence(EnergyOperator):
where v_i are the residual samples, N is their number, and m is the mean field
around which the samples are drawn.
Tip:
----
Having symmetrized residual samples, with both, v_i and -v_i being present,
ensures that the distribution mean is exactly represented. This reduces sampling
noise and helps the numerics of the KL minimization process in the variational
......
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