[Serializable]
[DataContract]
[Quality(QualityBand.Mature)]
public class VectorGaussian : IDistribution<Vector>, IDistribution, ICloneable, HasPoint<Vector>, CanGetLogProb<Vector>, SettableTo<VectorGaussian>, SettableToProduct<VectorGaussian>, SettableToProduct<VectorGaussian, VectorGaussian>, Diffable, SettableToUniform, SettableToRatio<VectorGaussian>, SettableToRatio<VectorGaussian, VectorGaussian>, SettableToPower<VectorGaussian>, SettableToWeightedSum<VectorGaussian>, Sampleable<Vector>, CanSamplePrep<VectorGaussian, Vector>, CanGetLogProbPrep<VectorGaussian, Vector>, CanGetMean<DenseVector>, CanGetVariance<PositiveDefiniteMatrix>, CanGetMeanAndVariance<Vector, PositiveDefiniteMatrix>, CanSetMeanAndVariance<Vector, PositiveDefiniteMatrix>, CanGetLogAverageOf<VectorGaussian>, CanGetLogAverageOfPower<VectorGaussian>, CanGetAverageLog<VectorGaussian>, CanGetLogNormalizer, CanGetMode<DenseVector>

Remarks

The distribution is parameterized by MeanTimesPrecision and Precision. Precision is the inverse of the variance, so a Gaussian with mean m and variance v is represented as Precision = inv(v), MeanTimesPrecision = inv(v)*m.

Some special cases: If the precision is zero, then the distribution is uniform. If the precision is infinite along the diagonal, then the distribution is a point mass. The Point property gives the location of the point mass. If precision[i,i] is infinite, then the distribution is a point mass along dimension i. Point[i] gives the mean. The rest of the row and column of precision must be zero.

The formula for the distribution is: N(x;m,v) = |2*pi*v|^(-d/2) * exp(-0.5 (x-m)' inv(v) (x-m)). When v=0, this reduces to delta(x-m). When v=infinity, the density is redefined to be 1. When inv(v) is singular, the density is redefined to be exp(-0.5 x' inv(v) x + x' inv(v) m), i.e. we drop the terms |2*pi*v|^(-d/2) * exp(-0.5 m' inv(v) m).

Constructors

VectorGaussian()

Constructs a new VectorGaussian

Declaration

protected VectorGaussian()

VectorGaussian(VectorGaussian)

Sets this VectorGaussian to the value of another

Declaration

public VectorGaussian(VectorGaussian that)

Parameters

Type	Name	Description
VectorGaussian	that

VectorGaussian(Vector, PositiveDefiniteMatrix)

Creates a Gaussian with given mean and variance.

Declaration

public VectorGaussian(Vector mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
Vector	mean	Mean
PositiveDefiniteMatrix	variance	Variance

Remarks

The mean and variance objects are copied into the Gaussian and not referenced afterwards.

VectorGaussian(Double, Double)

Creates a 1D VectorGaussian with given mean and variance.

Declaration

public VectorGaussian(double mean, double variance)

Parameters

Type	Name	Description
Double	mean	Mean
Double	variance	Variance

VectorGaussian(Int32)

Creates a uniform VectorGaussian of a given dimension

Declaration

public VectorGaussian(int dimension)

Parameters

Type	Name	Description
Int32	dimension	The dimension

Properties

Dimension

The dimension of the VectorGaussian domain

Declaration

[IgnoreDataMember]
public int Dimension { get; }

Property Value

Type	Description
Int32

IsPointMass

Asks whether the instance is a point mass

Declaration

[IgnoreDataMember]
public bool IsPointMass { get; }

Property Value

Type	Description
Boolean

MeanTimesPrecision

Gets/Sets Mean times precision

Declaration

public Vector MeanTimesPrecision { get; set; }

Property Value

Type	Description
Vector

Point

Sets/gets the instance as a point mass

Declaration

[IgnoreDataMember]
public Vector Point { get; set; }

Property Value

Type	Description
Vector

Precision

Gets/sets precision value

Declaration

public PositiveDefiniteMatrix Precision { get; set; }

Property Value

Type	Description
PositiveDefiniteMatrix

Methods

Clone()

Clones this VectorGaussian.

Declaration

public object Clone()

Returns

Type	Description
Object	An object which is a clone of the current instance. This must be cast if you want to assign the result to a VectorGaussian type

Copy(VectorGaussian)

Creates a copy of a given VectorGaussian

Declaration

public static VectorGaussian Copy(VectorGaussian that)

Parameters

Type	Name	Description
VectorGaussian	that

Returns

Type	Description
VectorGaussian

Equals(Object)

Override of the Equals method

Declaration

public override bool Equals(object thatd)

Parameters

Type	Name	Description
Object	thatd	The instance to compare to

Returns

Type	Description
Boolean	True if the two distributions are the same in value, false otherwise

Overrides

Object.Equals(Object)

FromCursors(Vector, PositiveDefiniteMatrix)

Creates a Gaussian from Cursor objects.

Declaration

public static VectorGaussian FromCursors(Vector meanTimesPrecision, PositiveDefiniteMatrix precision)

Parameters

Type	Name	Description
Vector	meanTimesPrecision	Mean times precision
PositiveDefiniteMatrix	precision	Precision

Returns

Type	Description
VectorGaussian

Remarks

The cursors will use their existing source array. The Gaussian will reference the given cursors.

FromDerivatives(Vector, Vector, PositiveDefiniteMatrix, Boolean)

Construct a Gaussian distribution whose pdf has the given derivatives at a point.

Declaration

public static VectorGaussian FromDerivatives(Vector x, Vector dlogp, PositiveDefiniteMatrix negativeHessian, bool forceProper)

Parameters

Type	Name	Description
Vector	x
Vector	dlogp	The gradient
PositiveDefiniteMatrix	negativeHessian	The negative Hessian matrix
Boolean	forceProper	If true and both derivatives cannot be matched, match only the first.

Returns

Type	Description
VectorGaussian

FromMeanAndPrecision(Vector, PositiveDefiniteMatrix)

Create a VectorGaussian with given mean and precision matrix.

Declaration

public static VectorGaussian FromMeanAndPrecision(Vector mean, PositiveDefiniteMatrix precision)

Parameters

Type	Name	Description
Vector	mean	Mean
PositiveDefiniteMatrix	precision	Precision

Returns

Type	Description
VectorGaussian	A new VectorGaussian object.

FromMeanAndPrecision(Double, Double)

Creates a 1D VectorGaussian with given mean and precision.

Declaration

public static VectorGaussian FromMeanAndPrecision(double mean, double precision)

Parameters

Type	Name	Description
Double	mean	Mean
Double	precision	Precision

Returns

Type	Description
VectorGaussian	A new VectorGaussian object.

FromMeanAndVariance(Vector, PositiveDefiniteMatrix)

Create a Gaussian with given mean and variance.

Declaration

public static VectorGaussian FromMeanAndVariance(Vector mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
Vector	mean	Mean
PositiveDefiniteMatrix	variance	Variance

Returns

Type	Description
VectorGaussian	A new Gaussian instance.

Remarks

The mean and variance objects are copied into the Gaussian and not referenced afterwards.

FromMeanAndVariance(Double, Double)

Creates a 1D VectorGaussian with given mean and variance.

Declaration

public static VectorGaussian FromMeanAndVariance(double mean, double variance)

Parameters

Type	Name	Description
Double	mean	Mean
Double	variance	Variance

Returns

Type	Description
VectorGaussian	A new VectorGaussian object.

FromNatural(Vector, PositiveDefiniteMatrix)

Create a new VectorGaussian from its natural parameters (Mean times precision, and precision)

Declaration

[Construction(new string[]{"MeanTimesPrecision", "Precision"})]
public static VectorGaussian FromNatural(Vector meanTimesPrecision, PositiveDefiniteMatrix precision)

Parameters

Type	Name	Description
Vector	meanTimesPrecision	Mean times precision
PositiveDefiniteMatrix	precision	Precision matrix

Returns

Type	Description
VectorGaussian	A new VectorGaussian object.

GetAverageLog(VectorGaussian)

The expected logarithm of that distribution under this distribution.

Declaration

public double GetAverageLog(VectorGaussian that)

Parameters

Type	Name	Description
VectorGaussian	that	The distribution to take the logarithm of.

Returns

Type	Description
Double	`sum_x this.Evaluate(x)*Math.Log(that.Evaluate(x))`

Remarks

This is also known as the cross entropy.

GetHashCode()

Override of GetHashCode method

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	The hash code for this instance

Overrides

Object.GetHashCode()

GetLogAverageOf(VectorGaussian)

Log-integral of the product of this VectorGaussian with that VectorGaussian

Declaration

public double GetLogAverageOf(VectorGaussian that)

Parameters

Type	Name	Description
VectorGaussian	that	That VectorGaussian

Returns

Type	Description
Double	The log inner product

GetLogAverageOfPower(VectorGaussian, Double)

Get the integral of this distribution times another distribution raised to a power.

Declaration

public double GetLogAverageOfPower(VectorGaussian that, double power)

Parameters

Type	Name	Description
VectorGaussian	that
Double	power

Returns

Type	Description
Double

GetLogNormalizer()

Gets the normalizer for the VectorGaussian density function

Declaration

public double GetLogNormalizer()

Returns

Type	Description
Double

GetLogProb(Vector)

Evaluates the log of the multivariate Gaussian density.

Declaration

public double GetLogProb(Vector x)

Parameters

Type	Name	Description
Vector	x	Point to evaluate the density at.

Returns

Type	Description
Double	log p(x)

GetLogProb(Vector, LowerTriangularMatrix, Vector)

Evaluates the log of the multivariate Gaussian density.

Declaration

public double GetLogProb(Vector x, LowerTriangularMatrix L, Vector iLb)

Parameters

Type	Name	Description
Vector	x	Point to evaluate the density at.
LowerTriangularMatrix	L	Work matrix - same size as Precision
Vector	iLb	Work vector - same size as x

Returns

Type	Description
Double	log p(x)

GetLogProb(Vector, Vector, PositiveDefiniteMatrix)

Evaluate the log of multivariate Gaussian density with specified mean vector and covariance matrix

Declaration

public static double GetLogProb(Vector x, Vector mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
Vector	x	Where to evaluate the density function
Vector	mean	The mean vector
PositiveDefiniteMatrix	variance	A non-singular covariance matrix.

Returns

Type	Description
Double

GetLogProb(Vector, Vector, PositiveDefiniteMatrix, LowerTriangularMatrix, Vector)

Evaluates the log of the multivariate Gaussian density.

Declaration

public static double GetLogProb(Vector x, Vector meanTimesPrecision, PositiveDefiniteMatrix precision, LowerTriangularMatrix L, Vector iLb)

Parameters

Type	Name	Description
Vector	x	Point to evaluate the density at.
Vector	meanTimesPrecision	Precision matrix times the mean vector.
PositiveDefiniteMatrix	precision	A non-singular precision matrix (inverse of covariance matrix).
LowerTriangularMatrix	L	Same size as precision.
Vector	iLb	Same size as x.

Returns

Type	Description
Double	log p(x)

GetLogProbPrep()

Returns an Evaluator delegate which has a pre-allocated workspace for efficient evaluation calculation. If you are generating many evaluations, call this method to get an Evaluator, then use the Evaluator delegate to calculate the evaluations

Declaration

public Evaluator<VectorGaussian, Vector> GetLogProbPrep()

Returns

Type	Description
Evaluator<VectorGaussian, Vector>	Evaluator delegate

GetMarginal(Int32)

The marginal distribution of one dimension.

Declaration

public Gaussian GetMarginal(int dim)

Parameters

Type	Name	Description
Int32	dim

Returns

Type	Description
Gaussian

GetMarginal(Int32, VectorGaussian)

The marginal distribution of a subvector.

Declaration

public VectorGaussian GetMarginal(int firstDim, VectorGaussian result)

Parameters

Type	Name	Description
Int32	firstDim	The first dimension of the subvector
VectorGaussian	result	A VectorGaussian receiving the result, whose Dimension specifies the length of the subvector.

Returns

Type	Description
VectorGaussian	`result`

GetMean()

Gets the mean of the distribution.

Declaration

public DenseVector GetMean()

Returns

Type	Description
DenseVector	A new Vector.

GetMean(Vector)

Gets the mean of the distribution

Declaration

public Vector GetMean(Vector result)

Parameters

Type	Name	Description
Vector	result	Where to place the mean value

Returns

Type	Description
Vector	mean

GetMean(Vector, PositiveDefiniteMatrix)

Get the mean of the distribution

Declaration

public Vector GetMean(Vector result, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
Vector	result	Where to place the mean vector
PositiveDefiniteMatrix	variance	The pre-computed inverse of this.Precision

Returns

Type	Description
Vector

GetMeanAndPrecision(Vector, PositiveDefiniteMatrix)

Gets the mean vector and precision matrix of the distribution

Declaration

public void GetMeanAndPrecision(Vector mean, PositiveDefiniteMatrix precision)

Parameters

Type	Name	Description
Vector	mean	Modified to contain the mean. Must already be the correct size.
PositiveDefiniteMatrix	precision	Modified to contain the precision matrix. Must already be the correct size.

GetMeanAndVariance(Vector, PositiveDefiniteMatrix)

Gets the mean and variance of the distribution.

Declaration

public void GetMeanAndVariance(Vector mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
Vector	mean	Modified to contain the mean. Must already be the correct size.
PositiveDefiniteMatrix	variance	Modified to contain the covariance matrix. Must already be the correct size.

Remarks

Because the Gaussian stored its parameters in exponential form, it is more efficient to compute the mean and variance at the same time rather than separately.

GetMode()

The most likely value

Declaration

public DenseVector GetMode()

Returns

Type	Description
DenseVector	A new Vector.

GetVariance()

Gets the variance-covariance matrix of the distribution.

Declaration

public PositiveDefiniteMatrix GetVariance()

Returns

Type	Description
PositiveDefiniteMatrix	A new PositiveDefiniteMatrix.

GetVariance(PositiveDefiniteMatrix)

Gets the variance-covariance matrix of the distribution.

Declaration

public PositiveDefiniteMatrix GetVariance(PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	variance	Where to place the variance-covariance

Returns

Type	Description
PositiveDefiniteMatrix	variance

IsProper()

Asks whether this VectorGaussian instance is proper or not. A VectorGaussian distribution is proper only if its precision matrix is positive definite.

Declaration

public bool IsProper()

Returns

Type	Description
Boolean	True if proper, false otherwise

IsUniform()

Asks whether this instance is uniform

Declaration

public bool IsUniform()

Returns

Type	Description
Boolean	True if uniform, false otherwise

MaxDiff(Object)

The maximum difference between the parameters of this VectorGaussian and that VectorGaussian

Declaration

public double MaxDiff(object thatd)

Parameters

Type	Name	Description
Object	thatd	That VectorGaussian

Returns

Type	Description
Double	The maximum difference

PointMass(Vector)

Creates a VectorGaussian point mass at the specified location

Declaration

[Construction(new string[]{"Point"}, UseWhen = "IsPointMass")]
public static VectorGaussian PointMass(Vector mean)

Parameters

Type	Name	Description
Vector	mean	Where to position the point mass

Returns

Type	Description
VectorGaussian	A new point mass VectorGaussian

PointMass(Double)

Creates a VectorGaussian point mass where the location is a vector of identical values

Declaration

public static VectorGaussian PointMass(double mean)

Parameters

Type	Name	Description
Double	mean	The value for the mean vector

Returns

Type	Description
VectorGaussian	A new point mass VectorGaussian

Sample()

Sample from this VectorGaussian distribution

Declaration

public Vector Sample()

Returns

Type	Description
Vector	The sample value

Sample(Vector)

Samples from this VectorGaussian distribution

Declaration

public Vector Sample(Vector result)

Parameters

Type	Name	Description
Vector	result	Where to put the result

Returns

Type	Description
Vector	The sample value

Sample(Vector, LowerTriangularMatrix)

Samples from this VectorGaussian distribution

Declaration

public Vector Sample(Vector result, LowerTriangularMatrix precL)

Parameters

Type	Name	Description
Vector	result	Where to put the result
LowerTriangularMatrix	precL	A DxD workspace

Returns

Type	Description
Vector	The sample value

Sample(Vector, PositiveDefiniteMatrix)

Samples from a VectorGaussian distribution with the specified mean and precision

Declaration

public static Vector Sample(Vector mean, PositiveDefiniteMatrix precision)

Parameters

Type	Name	Description
Vector	mean
PositiveDefiniteMatrix	precision

Returns

Type	Description
Vector	The sample value

SampleFromMeanAndVariance(Vector, PositiveDefiniteMatrix)

Samples from a VectorGaussian distribution with the specified mean and variance

Declaration

[ParameterNames(new string[]{"sample", "mean", "variance"})]
public static Vector SampleFromMeanAndVariance(Vector mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
Vector	mean
PositiveDefiniteMatrix	variance

Returns

Type	Description
Vector	The sample value

SamplePrep()

Returns a sampler delegate which has a pre-allocated workspace for efficient sample calculation. If you are generating many samples, call this method to get a sampler, then use the sampler delegate to generate samples.

Declaration

public Sampler<VectorGaussian, Vector> SamplePrep()

Returns

Type	Description
Sampler<VectorGaussian, Vector>	Sampler delegate

SetMeanAndPrecision(Vector, PositiveDefiniteMatrix)

Sets the mean and precision of the distribution.

Declaration

public void SetMeanAndPrecision(Vector mean, PositiveDefiniteMatrix precision)

Parameters

Type	Name	Description
Vector	mean	The mean vector
PositiveDefiniteMatrix	precision	The precision matrix

SetMeanAndVariance(Vector, PositiveDefiniteMatrix)

Sets the mean and variance of the distribution.

Declaration

public void SetMeanAndVariance(Vector mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
Vector	mean	The mean vector. Cannot be the same object as `this.MeanTimesPrecision`.
PositiveDefiniteMatrix	variance	The covariance matrix. Can be the same object as `this.Precision`.

SetNatural(Vector, PositiveDefiniteMatrix)

Sets the natural parameters of the distribution (mean times precision, and precision)

Declaration

public void SetNatural(Vector meanTimesPrecision, PositiveDefiniteMatrix precision)

Parameters

Type	Name	Description
Vector	meanTimesPrecision	Mean times precision
PositiveDefiniteMatrix	precision	The precision matrix

SetTo(VectorGaussian)

Sets this VectorGaussian instance to have the parameter values of that VectorGaussian instance

Declaration

public void SetTo(VectorGaussian that)

Parameters

Type	Name	Description
VectorGaussian	that	That VectorGaussian

SetToPointMass()

Sets this instance to a point mass. The location of the point mass is the existing mean vector

Declaration

protected void SetToPointMass()

SetToPower(VectorGaussian, Double)

Sets the parameters to represent the power of a source VectorGaussian to some exponent.

Declaration

public void SetToPower(VectorGaussian dist, double exponent)

Parameters

Type	Name	Description
VectorGaussian	dist	The source VectorGaussian
Double	exponent	The exponent

SetToProduct(VectorGaussian, VectorGaussian)

Sets the parameters to represent the product of two VectorGaussians.

Declaration

public void SetToProduct(VectorGaussian g1, VectorGaussian g2)

Parameters

Type	Name	Description
VectorGaussian	g1	The first VectorGaussian. May refer to `this`.
VectorGaussian	g2	The second VectorGaussian. May refer to `this`.

Remarks

The result may not be proper. No error is thrown in this case.

SetToRatio(VectorGaussian, VectorGaussian, Boolean)

Sets the parameters to represent the product of two VectorGaussians.

Declaration

public void SetToRatio(VectorGaussian numerator, VectorGaussian denominator, bool forceProper = false)

Parameters

Type	Name	Description
VectorGaussian	numerator	The numerator VectorGaussian. Can be the same object as `this`.
VectorGaussian	denominator	The denominator VectorGaussian
Boolean	forceProper	If true, the precision of the result is made non-negative definite, under the constraint that result*denominator has the same mean as numerator

SetToSum(Double, VectorGaussian, Double, VectorGaussian)

Sets the mean and covariance to match a VectorGaussian mixture.

Declaration

public void SetToSum(double weight1, VectorGaussian dist1, double weight2, VectorGaussian dist2)

Parameters

Type	Name	Description
Double	weight1	First weight
VectorGaussian	dist1	First VectorGaussian
Double	weight2	Second weight
VectorGaussian	dist2	Second VectorGaussian

SetToUniform()

Sets this VectorGaussian instance to be a uniform distribution

Declaration

public void SetToUniform()

ToString()

ToString override

Declaration

public override string ToString()

Returns

Type	Description
String	String representation of the instance

Overrides

Object.ToString()

Uniform(Int32)

Creates a uniform VectorGaussian of a given dimension

Declaration

[Construction(new string[]{"Dimension"}, UseWhen = "IsUniform")]
public static VectorGaussian Uniform(int dimension)

Parameters

Type	Name	Description
Int32	dimension	The dimension

Returns

Type	Description
VectorGaussian

WeightedSum<T>(T, Int32, Double, T, Double, T)

Creates a distribution of the specified type which matchs the mean and variance/covariance of a VectorGaussian mixture. The distribution type must implement CanGetMeanAndVariance<MeanType, VarType> and CanSetMeanAndVariance<MeanType, VarType>

Declaration

public static T WeightedSum<T>(T result, int dimension, double weight1, T dist1, double weight2, T dist2)
    where T : CanGetMeanAndVariance<Vector, PositiveDefiniteMatrix>, CanSetMeanAndVariance<Vector, PositiveDefiniteMatrix>, SettableTo<T>, SettableToUniform

Parameters

Type	Name	Description
T	result	Resulting distribution
Int32	dimension	The dimension of the domain
Double	weight1	The first weight
T	dist1	The first distribution
Double	weight2	The second weight
T	dist2	The second distribution

Returns

Type	Description
T

Type Parameters

Name	Description
T	Distribution type for the mixture

Operators

Division(VectorGaussian, VectorGaussian)

Creates a new VectorGaussian which the ratio of two other VectorGaussians

Declaration

public static VectorGaussian operator /(VectorGaussian numerator, VectorGaussian denominator)

Parameters

Type	Name	Description
VectorGaussian	numerator	numerator VectorGaussian
VectorGaussian	denominator	denominator VectorGaussian

Returns

Type	Description
VectorGaussian	Result

ExclusiveOr(VectorGaussian, Double)

Raises a distribution to a power.

Declaration

public static VectorGaussian operator ^(VectorGaussian dist, double exponent)

Parameters

Type	Name	Description
VectorGaussian	dist	The distribution.
Double	exponent	The power to raise to.

Returns

Type	Description
VectorGaussian	`dist` raised to power `exponent`.

Multiply(VectorGaussian, VectorGaussian)

Creates a new VectorGaussian which the product of two other VectorGaussians

Declaration

public static VectorGaussian operator *(VectorGaussian a, VectorGaussian b)

Parameters

Type	Name	Description
VectorGaussian	a	First VectorGaussian
VectorGaussian	b	Second VectorGaussian

Returns

Type	Description
VectorGaussian	Result

Implements

IDistribution<T>

IDistribution

System.ICloneable

HasPoint<T>

CanGetLogProb<T>

SettableTo<T>

SettableToProduct<T>

SettableToProduct<T, U>

Diffable

SettableToUniform

SettableToRatio<T>

SettableToRatio<T, U>

SettableToPower<T>

SettableToWeightedSum<T>

Sampleable<T>

CanSamplePrep<DistributionType, T>

CanGetLogProbPrep<DistributionType, T>

CanGetMean<MeanType>

CanGetVariance<VarType>

CanGetMeanAndVariance<MeanType, VarType>

CanSetMeanAndVariance<MeanType, VarType>

CanGetLogAverageOf<T>

CanGetLogAverageOfPower<T>

CanGetAverageLog<T>

CanGetLogNormalizer

CanGetMode<ModeType>