# LostTech.TensorFlow : API Documentation

Type MultivariateNormalDiagPlusLowRank

Namespace tensorflow.contrib.distributions

Interfaces IMultivariateNormalDiagPlusLowRank

The multivariate normal distribution on `R^k`.

The Multivariate Normal distribution is defined over `R^k` and parameterized by a (batch of) length-`k` `loc` vector (aka "mu") and a (batch of) `k x k` `scale` matrix; `covariance = scale @ scale.T` where `@` denotes matrix-multiplication.

#### Mathematical Details

The probability density function (pdf) is,

```none pdf(x; loc, scale) = exp(-0.5 ||y||**2) / Z, y = inv(scale) @ (x - loc), Z = (2 pi)**(0.5 k) |det(scale)|, ```

where:

* `loc` is a vector in `R^k`, * `scale` is a linear operator in `R^{k x k}`, `cov = scale @ scale.T`, * `Z` denotes the normalization constant, and, * `||y||**2` denotes the squared Euclidean norm of `y`.

A (non-batch) `scale` matrix is:

```none scale = diag(scale_diag + scale_identity_multiplier ones(k)) + scale_perturb_factor @ diag(scale_perturb_diag) @ scale_perturb_factor.T ```

where:

* `scale_diag.shape = [k]`, * `scale_identity_multiplier.shape = []`, * `scale_perturb_factor.shape = [k, r]`, typically `k >> r`, and, * `scale_perturb_diag.shape = [r]`.

If both `scale_diag` and `scale_identity_multiplier` are `None`, then `scale` is the Identity matrix.

The MultivariateNormal distribution is a member of the [location-scale family](https://en.wikipedia.org/wiki/Location-scale_family), i.e., it can be constructed as,

```none X ~ MultivariateNormal(loc=0, scale=1) # Identity scale, zero shift. Y = scale @ X + loc ```

#### Examples
Show Example
```import tensorflow_probability as tfp
tfd = tfp.distributions  # Initialize a single 3-variate Gaussian with covariance `cov = S @ S.T`,
# `S = diag(d) + U @ diag(m) @ U.T`. The perturbation, `U @ diag(m) @ U.T`, is
# a rank-2 update.
mu = [-0.5., 0, 0.5]   # shape: [3]
d = [1.5, 0.5, 2]      # shape: [3]
U = [[1., 2],
[-1, 1],
[2, -0.5]]        # shape: [3, 2]
m = [4., 5]            # shape: [2]
mvn = tfd.MultivariateNormalDiagPlusLowRank(
loc=mu
scale_diag=d
scale_perturb_factor=U,
scale_perturb_diag=m)  # Evaluate this on an observation in `R^3`, returning a scalar.
mvn.prob([-1, 0, 1]).eval()  # shape: []  # Initialize a 2-batch of 3-variate Gaussians; `S = diag(d) + U @ U.T`.
mu = [[1.,  2,  3],
[11, 22, 33]]      # shape: [b, k] = [2, 3]
U = [[[1., 2],
[3,  4],
[5,  6]],
[[0.5, 0.75],
[1,0, 0.25],
[1.5, 1.25]]]      # shape: [b, k, r] = [2, 3, 2]
m = [[0.1, 0.2],
[0.4, 0.5]]         # shape: [b, r] = [2, 2]  mvn = tfd.MultivariateNormalDiagPlusLowRank(
loc=mu,
scale_perturb_factor=U,
scale_perturb_diag=m)  mvn.covariance().eval()   # shape: [2, 3, 3]
# ==> [[[  15.63   31.57    48.51]
#       [  31.57   69.31   105.05]
#       [  48.51  105.05   162.59]]
#
#      [[   2.59    1.41    3.35]
#       [   1.41    2.71    3.34]
#       [   3.35    3.34    8.35]]]  # Compute the pdf of two `R^3` observations (one from each batch);
# return a length-2 vector.
x = [[-0.9, 0, 0.1],
[-10, 0, 9]]     # shape: [2, 3]
mvn.prob(x).eval()    # shape: [2] ```