nifty7.operators.energy_operators module#

class AveragedEnergy(h, res_samples)[source]#

Bases: EnergyOperator

Averages an energy over samples.

Parameters:
  • h (Hamiltonian) – The energy to be averaged.

  • res_samples (iterable of Fields) – Set of residual sample points to be added to mean field for approximate estimation of the KL.

Notes

  • Having symmetrized residual samples, with both v_i and -v_i being present, ensures that the distribution mean is exactly represented.

  • AveragedEnergy(h) approximates \left< H(f) \right>_{G(f-m,D)} if the residuals f-m are drawn from a Gaussian distribution with covariance D.

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric. It is None, except for instances of LikelihoodEnergyOperator or (nested) sums thereof.

Returns:

  • np.dtype, or dict of np.dtype (The dtype(s) of the target space of the)

  • transformation.

  • Operator (The transformation that maps from domain into the)

  • Euclidean target space.

Note

This Euclidean target space is the disjoint union of the Euclidean target spaces of all summands. Therefore, the keys of MultiDomains are prefixed with an index and DomainTuples are converted to MultiDomains with the index as the key.

class BernoulliEnergy(d)[source]#

Bases: LikelihoodEnergyOperator

Computes likelihood energy of expected event frequency constrained by event data.

E(f) = -\log \text{Bernoulli}(d|f)
     = -d^\dagger \log f  - (1-d)^\dagger \log(1-f),

where f is a field defined on d.domain with the expected frequencies of events.

Parameters:

d (Field) – Data field with events (1) or non-events (0).

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric. It is None, except for instances of LikelihoodEnergyOperator or (nested) sums thereof.

Returns:

  • np.dtype, or dict of np.dtype (The dtype(s) of the target space of the)

  • transformation.

  • Operator (The transformation that maps from domain into the)

  • Euclidean target space.

Note

This Euclidean target space is the disjoint union of the Euclidean target spaces of all summands. Therefore, the keys of MultiDomains are prefixed with an index and DomainTuples are converted to MultiDomains with the index as the key.

class EnergyOperator[source]#

Bases: Operator

Operator which has a scalar domain as target domain.

It is intended as an objective function for field inference. It can implement a positive definite, symmetric form (called metric) that is used as curvature for second-order minimizations.

Examples

  • Information Hamiltonian, i.e. negative-log-probabilities.

  • Gibbs free energy, i.e. an averaged Hamiltonian, aka Kullback-Leibler divergence.

class GaussianEnergy(mean=None, inverse_covariance=None, domain=None, sampling_dtype=None)[source]#

Bases: LikelihoodEnergyOperator

Computes a negative-log Gaussian.

Represents up to constants in m:

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.

Parameters:
  • mean (Field) – Mean of the Gaussian. Default is 0.

  • inverse_covariance (LinearOperator) – Inverse covariance of the Gaussian. Default is the identity operator.

  • domain (Domain, DomainTuple, tuple of Domain or MultiDomain) – Operator domain. By default it is inferred from mean or covariance if specified

  • sampling_dtype (type) – Here one can specify whether the distribution is a complex Gaussian or not. Note that for a complex Gaussian the inverse_covariance is .. math :: (<ff^dagger>)^{-1}_P(f)/2, where the additional factor of 2 is necessary because the domain of s has double as many dimensions as in the real case.

Note

At least one of the arguments has to be provided.

__repr__()[source]#

Return repr(self).

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric. It is None, except for instances of LikelihoodEnergyOperator or (nested) sums thereof.

Returns:

  • np.dtype, or dict of np.dtype (The dtype(s) of the target space of the)

  • transformation.

  • Operator (The transformation that maps from domain into the)

  • Euclidean target space.

Note

This Euclidean target space is the disjoint union of the Euclidean target spaces of all summands. Therefore, the keys of MultiDomains are prefixed with an index and DomainTuples are converted to MultiDomains with the index as the key.

class InverseGammaEnergy(beta, alpha=-0.5)[source]#

Bases: LikelihoodEnergyOperator

Computes the negative log-likelihood of the inverse gamma distribution.

It negative log-pdf(x) is given by

\sum_i (\alpha_i+1)*\ln(x_i) + \beta_i/x_i

This is the likelihood for the variance x=S_k given data \beta = 0.5 |s_k|^2 where the Field s is known to have the covariance S_k.

Parameters:
  • beta (Field) – beta parameter of the inverse gamma distribution

  • alpha (Scalar, Field, optional) – alpha parameter of the inverse gamma distribution

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric. It is None, except for instances of LikelihoodEnergyOperator or (nested) sums thereof.

Returns:

  • np.dtype, or dict of np.dtype (The dtype(s) of the target space of the)

  • transformation.

  • Operator (The transformation that maps from domain into the)

  • Euclidean target space.

Note

This Euclidean target space is the disjoint union of the Euclidean target spaces of all summands. Therefore, the keys of MultiDomains are prefixed with an index and DomainTuples are converted to MultiDomains with the index as the key.

class LikelihoodEnergyOperator[source]#

Bases: EnergyOperator

Represent a negative log-likelihood.

The input to the Operator are the parameters of the negative log-likelihood. Unlike a general EnergyOperator, the metric of a LikelihoodEnergyOperator is the Fisher information metric of the likelihood.

get_metric_at(x)[source]#

Compute the Fisher information metric for a LikelihoodEnergyOperator at x using the Jacobian of the coordinate transformation given by get_transformation().

class PoissonianEnergy(d)[source]#

Bases: LikelihoodEnergyOperator

Computes likelihood Hamiltonians of expected count field constrained by Poissonian count data.

Represents up to an f-independent term log(d!):

E(f) = -\log \text{Poisson}(d|f) = \sum f - d^\dagger \log(f),

where f is a Field in data space with the expectation values for the counts.

Parameters:

d (Field) – Data field with counts. Needs to have integer dtype and all field values need to be non-negative.

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric. It is None, except for instances of LikelihoodEnergyOperator or (nested) sums thereof.

Returns:

  • np.dtype, or dict of np.dtype (The dtype(s) of the target space of the)

  • transformation.

  • Operator (The transformation that maps from domain into the)

  • Euclidean target space.

Note

This Euclidean target space is the disjoint union of the Euclidean target spaces of all summands. Therefore, the keys of MultiDomains are prefixed with an index and DomainTuples are converted to MultiDomains with the index as the key.

class QuadraticFormOperator(endo)[source]#

Bases: EnergyOperator

Computes the L2-norm of a Field or MultiField with respect to a specific kernel given by endo.

E(f) = \frac12 f^\dagger \text{endo}(f)

Parameters:

endo (EndomorphicOperator) – Kernel of the quadratic form

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

class Squared2NormOperator(domain)[source]#

Bases: EnergyOperator

Computes the square of the L2-norm of the output of an operator.

Parameters:

domain (Domain, DomainTuple or tuple of Domain) – Domain of the operator in which the L2-norm shall be computed.

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

class StandardHamiltonian(lh, ic_samp=None, prior_dtype=<class 'numpy.float64'>)[source]#

Bases: EnergyOperator

Computes an information Hamiltonian in its standard form, i.e. with the prior being a Gaussian with unit covariance.

Let the likelihood energy be E_{lh}. Then this operator computes:

H(f) = 0.5 f^\dagger f + E_{lh}(f):

Other field priors can be represented via transformations of a white Gaussian field into a field with the desired prior probability structure.

By implementing prior information this way, the field prior is represented by a generative model, from which NIFTy can draw samples and infer a field using the Maximum a Posteriori (MAP) or the Variational Bayes (VB) method.

The metric of this operator can be used as covariance for drawing Gaussian samples.

Parameters:
  • lh (EnergyOperator) – The likelihood energy.

  • ic_samp (IterationController) – Tells an internal SamplingEnabler which convergence criterion to use to draw Gaussian samples.

  • prior_dtype (numpy.dtype or dict of numpy.dtype, optional) – Data type of prior used for sampling.

See also

Encoding prior knowledge in the structure of the likelihood, Jakob Knollmüller, Torsten A. Ensslin, https://arxiv.org/abs/1812.04403

__repr__()[source]#

Return repr(self).

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

class StudentTEnergy(domain, theta)[source]#

Bases: LikelihoodEnergyOperator

Computes likelihood energy corresponding to Student’s t-distribution.

E_\theta(f) = -\log \text{StudentT}_\theta(f)
             = \frac{\theta + 1}{2} \log(1 + \frac{f^2}{\theta}),

where f is a field defined on domain. Assumes that the data is float64 for sampling.

Parameters:
  • domain (Domain or DomainTuple) – Domain of the operator

  • theta (Scalar or Field) – Degree of freedom parameter for the student t distribution

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric. It is None, except for instances of LikelihoodEnergyOperator or (nested) sums thereof.

Returns:

  • np.dtype, or dict of np.dtype (The dtype(s) of the target space of the)

  • transformation.

  • Operator (The transformation that maps from domain into the)

  • Euclidean target space.

Note

This Euclidean target space is the disjoint union of the Euclidean target spaces of all summands. Therefore, the keys of MultiDomains are prefixed with an index and DomainTuples are converted to MultiDomains with the index as the key.

class VariableCovarianceGaussianEnergy(domain, residual_key, inverse_covariance_key, sampling_dtype, use_full_fisher=True)[source]#

Bases: LikelihoodEnergyOperator

Computes the negative log pdf of a Gaussian with unknown covariance.

The covariance is assumed to be diagonal.

E(s,D) = - \log G(s, C) = 0.5 (s)^\dagger C (s) - 0.5 tr log(C),

an information energy for a Gaussian distribution with residual s and inverse diagonal covariance C. The domain of this energy will be a MultiDomain with two keys, the target will be the scalar domain.

Parameters:
  • domain (Domain, DomainTuple, tuple of Domain) – domain of the residual and domain of the covariance diagonal.

  • residual_key (key) – Residual key of the Gaussian.

  • inverse_covariance_key (key) – Inverse covariance diagonal key of the Gaussian.

  • sampling_dtype (np.dtype) – Data type of the samples. Usually either ‘np.float*’ or ‘np.complex*’

  • use_full_fisher (boolean) – Determines if the proper Fisher information metric should be used as metric. If False, the same approximation as in get_transformation is used. Default is True.

apply(x)[source]#

Applies the operator to a Field or MultiField.

Parameters:

x (Field or MultiField) – Input on which the operator shall act. Needs to be defined on domain.

get_transformation()[source]#

Note

For VariableCovarianceGaussianEnergy, a global transformation to Euclidean space does not exist. A local approximation invoking the residual is used instead.