class_docstr: 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.
  
  The scale matrix for this particular Normal is a (typically low rank)
  perturbation of a diagonal matrix.
  Compare to `MultivariateNormalDiagPlusLowRankCovariance` which perturbs the
  *covariance* rather than scale.
  
  ```none
  C = S S.T
    = (D + U E U.T)(D + U E U.T)
    = D**2 + D U E U.T + U E U.T D + (U E U.T)(U E U.T)
  ```
  
  where
  
  * `C` is the `NxN` covariance matrix,
  * `S` is the `NxN` scale matrix,
  * `D` is the `NxN` diagonal part of the scale matrix,
  * `U` is the `NxK` low-rank update part of the scale matrix,
  * `E` is the `KxK` diagonal inside the low-rank update, and
  * `M.T` is matrix transpose.
  
  A covariance matrix in this form is not typically itself easily expressible as
  a diagonal plus low-rank.
  
  #### 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_perturb_factor @ diag(scale_perturb_diag) @ scale_perturb_factor.T
  ```
  
  where:
  
  * `scale_diag.shape = [k]`,
  * `scale_perturb_factor.shape = [k, r]`, typically `k >> r`, and,
  * `scale_perturb_diag.shape = [r]`.
  
  Additional leading dimensions (if any) will index batches.
  
  If `scale_diag` is `None`, then it defaults to 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
  
  ```python
  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])  # 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()   # 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)    # shape: [2]
  ```
class_docstr_tok: ["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",".","The","scale","matrix","for","this","particular","Normal","is","a","(","typically","low","rank",")","perturbation","of","a","diagonal","matrix",".","Compare","to","`","MultivariateNormalDiagPlusLowRankCovariance","`","which","perturbs","the","*","covariance","*","rather","than","scale",".","``","`","none","C","=","S","S.T","=","(","D","+","U","E","U.T",")","(","D","+","U","E","U.T",")","=","D","*","*","2","+","D","U","E","U.T","+","U","E","U.T","D","+","(","U","E","U.T",")","(","U","E","U.T",")","``","`","where","*","`","C","`","is","the","`","NxN","`","covariance","matrix",",","*","`","S","`","is","the","`","NxN","`","scale","matrix",",","*","`","D","`","is","the","`","NxN","`","diagonal","part","of","the","scale","matrix",",","*","`","U","`","is","the","`","NxK","`","low-rank","update","part","of","the","scale","matrix",",","*","`","E","`","is","the","`","KxK","`","diagonal","inside","the","low-rank","update",",","and","*","`","M.T","`","is","matrix","transpose",".","A","covariance","matrix","in","this","form","is","not","typically","itself","easily","expressible","as","a","diagonal","plus","low-rank",".","#","#","#","#","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_perturb_factor","@","diag","(","scale_perturb_diag",")","@","scale_perturb_factor.T","``","`","where",":","*","`","scale_diag.shape","=","[","k","]","`",",","*","`","scale_perturb_factor.shape","=","[","k",",","r","]","`",",","typically","`","k",">",">","r","`",",","and",",","*","`","scale_perturb_diag.shape","=","[","r","]","`",".","Additional","leading","dimensions","(","if","any",")","will","index","batches",".","If","`","scale_diag","`","is","`","None","`",",","then","it","defaults","to","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","``","`","python","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","]",")","#","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","(",")","#","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",")","#","shape",":","[","2","]","``","`"]
code: def _parameter_properties(cls, dtype, num_classes=None):
      return dict(
          loc=parameter_properties.ParameterProperties(event_ndims=1),
          scale_diag=parameter_properties.ParameterProperties(
              event_ndims=1,
              default_constraining_bijector_fn=(
                  lambda: softplus_bijector.Softplus(
                      low=dtype_util.eps(dtype)
                  )
              ),
          ),
          scale_perturb_factor=parameter_properties.ParameterProperties(
              event_ndims=2,
              shape_fn=parameter_properties.SHAPE_FN_NOT_IMPLEMENTED,
              is_preferred=False,
          ),
          scale_perturb_diag=parameter_properties.ParameterProperties(
              event_ndims=1,
              is_preferred=False,
              default_constraining_bijector_fn=(
                  lambda: softplus_bijector.Softplus(
                      low=dtype_util.eps(dtype)
                  )
              ),
          ),
      )
  
file_path: probability/tensorflow_probability/python/distributions/mvn_diag_plus_low_rank.py
imports: import tensorflow.compat.v2
  from tensorflow_probability.python.bijectors import softplus
  from tensorflow_probability.python.distributions import mvn_linear_operator
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.internal import parameter_properties
  from tensorflow_probability.python.internal import prefer_static
  from tensorflow_probability.python.internal import tensor_util
label_desc: Use image node_id 2 for calling the MultivariateNormalDiagPlusLowRank obj's underlying member method code with example usage: obj._parameter_properties(cls, dtype, num_classes) and returns: dict