nifty.cl.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 nifty.cl.field.Field) – 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\).

__init__(h, res_samples)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#
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 (nifty.cl.field.Field) – Data field with events (1) or non-events (0).

__init__(d)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric.

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 CategoricalEnergy(d, axis=0)[source]#

Bases: LikelihoodEnergyOperator

This operator is used to calculate the negative log-likelihood energy for a categorical distribution when the observed data is one-hot encoded. It measures the discrepancy between an input probability distribution (x) and the observed one-hot encoded data (d).

The energy is computed as the negative dot product between the logarithm of the input probabilities and the one-hot encoded data:

\[E = - \sum_{i} d_i \log (x_i)\]

The input x is expected to represent probabilities and is assumed to be normalized such that it sums to 1 along the category axis.

Parameters:

  • d (Field) – One-hot encoded categorical data. Must contain only 0 and 1, and must sum to 1 along the specified axis.

  • axis (int) – The axis along which categories are defined (default: 0). Probabilities must sum to 1 along this axis.

__init__(d, axis=0)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric.

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(data=None, inverse_covariance=None, domain=None, sampling_dtype=None)[source]#

Bases: LikelihoodEnergyOperator

Computes a negative-log Gaussian.

Represents up to constants in \(d\):

\[E(f) = - \log G(f-d, D) = 0.5 (f-d)^\dagger D^{-1} (f-d),\]

an information energy for a Gaussian distribution with data d and covariance D.

Parameters:

  • data (nifty.cl.field.Field or None) – Observed data of the Gaussian likelihood. If inverse_covariance is None, the dtype of data is used for sampling. 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 data or covariance if specified

  • sampling_dtype (dtype or dict of dtype) – Type used for sampling from the inverse covariance if inverse_covariance and data is None. Otherwise, this parameter does not have an effect. Default: None.

Note

At least one of the arguments has to be provided.

__init__(data=None, inverse_covariance=None, domain=None, sampling_dtype=None)[source]#
__repr__()[source]#

Return repr(self).

apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric.

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 nifty.cl.field.Field \(s\) is known to have the covariance \(S_k\).

Parameters:
__init__(beta, alpha=-0.5)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric.

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(data_residual, sqrt_data_metric_at)[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.

__init__(data_residual, sqrt_data_metric_at)[source]#
property data_domain#
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().

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric.

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.

property name#
normalized_residual(x)[source]#
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 (nifty.cl.field.Field) – Data field with counts. Needs to have integer dtype and all field values need to be non-negative.

__init__(d)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric.

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

__init__(endo)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

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.

__init__(domain)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

class StandardHamiltonian(lh, ic_samp=None, prior_sampling_dtype=None)[source]#

Bases: EnergyOperator

Computes an information Hamiltonian in its standard form, i.e. with the prior being a real-valued 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_sampling_dtype (dtype of dict of dtypes) – The dtype with which the prior shall draw its samples. Typically this is float but it can also be, e.g., complex. Default is None.

See also

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

__init__(lh, ic_samp=None, prior_sampling_dtype=None)[source]#
__repr__()[source]#

Return repr(self).

apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

property iteration_controller#
property likelihood_energy#
property prior_energy#
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 nifty.cl.field.Field) – Degree of freedom parameter for the student t distribution

__init__(domain, theta)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#

The coordinate transformation that maps into a coordinate system in which the metric of a likelihood is the Euclidean metric.

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 (str) – Residual key of the Gaussian.

  • inverse_covariance_key (str) – 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.

__init__(domain, residual_key, inverse_covariance_key, sampling_dtype, use_full_fisher=True)[source]#
apply(x)[source]#

Applies the operator to a Field, MultiField or Linearization.

Parameters:

x (nifty.cl.field.Field, nifty.cl.multi_field.MultiField,) – or nifty.cl.linearization.Linearization Input on which the operator shall act. Needs to be defined on domain. If x`is a :class:`nifty.cl.linearization.Linearization, apply returns a new nifty.cl.linearization.Linearization contining the result of the operator application as well as its Jacobian, evaluated at x.

get_transformation()[source]#

Note

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

On this page
Show Source