## Documentation ¶

### Overview ¶

Package distmat provides probability distributions over matrices.

### Constants ¶

This section is empty.

### Variables ¶

This section is empty.

### Functions ¶

This section is empty.

### Types ¶

#### type UniformPermutation ¶

```type UniformPermutation struct {
// contains filtered or unexported fields
}```

UniformPermutation is a uniform distribution over the n! permutation matrices of size n×n for a given n.

#### func NewUniformPermutation ¶

`func NewUniformPermutation(src rand.Source) *UniformPermutation`

NewUniformPermutation constructs a new permutation matrix generator using the given random source.

#### func (*UniformPermutation) PermTo ¶

`func (p *UniformPermutation) PermTo(dst *mat.Dense)`

PermTo sets the given matrix to be a random permutation matrix. It does not zero the destination's elements, so it is the responsibility of the caller to ensure it is correctly conditioned prior to the call.

PermTo panics if dst is not square.

#### type UnitVector ¶

```type UnitVector struct {
// contains filtered or unexported fields
}```

UnitVector is a uniform distribution over the surface of a sphere.

Example

ExampleUnitVector uses the UnitVector distribution to take a random walk in n-space. At the end it computes how far from the origin the walk finished.

```package main

import (
"fmt"

"golang.org/x/exp/rand"
"gonum.org/v1/gonum/mat"
"gonum.org/v1/gonum/stat/distmat"
)

func main() {
src := rand.NewSource(1)
rnd := rand.New(src)
dist := distmat.NewUnitVector(src)

// Draw a random dimension for the space to walk through.
nDim := 1 + rnd.Intn(100)
// Vectors to hold the current position and next step.
position := mat.NewVecDense(nDim, nil)
step := mat.NewVecDense(nDim, nil)

// Draw a random number of steps to take.
nSteps := 1 + rnd.Intn(100)
for i := 0; i < nSteps; i++ {
// Draw a random step and update the position.
dist.UnitVecTo(step)
}

// Finally compute distance from the origin.
distance := mat.Norm(position, 2)
fmt.Printf("took %d steps in %d-space, walked %1.1f in total", nSteps, nDim, distance)
}
```
```Output:

took 22 steps in 52-space, walked 5.3 in total
```

#### func NewUnitVector ¶

`func NewUnitVector(src rand.Source) *UnitVector`

NewUnitVector constructs a unit vector generator.

#### func (*UnitVector) UnitVecTo ¶

`func (u *UnitVector) UnitVecTo(dst *mat.VecDense)`

UnitVecTo sets dst to be a random unit-length vector.

This uses the algorithm of Mueller from: https://dl.acm.org/doi/10.1145/377939.377946 and summarized at: https://mathworld.wolfram.com/HyperspherePointPicking.html

UnitVecTo panics if dst has 0 length.

#### type Wishart ¶

```type Wishart struct {
// contains filtered or unexported fields
}```

Wishart is a distribution over d×d positive symmetric definite matrices. It is parametrized by a scalar degrees of freedom parameter ν and a d×d positive definite matrix V.

The Wishart PDF is given by

```p(X) = [|X|^((ν-d-1)/2) * exp(-tr(V^-1 * X)/2)] / [2^(ν*d/2) * |V|^(ν/2) * Γ_d(ν/2)]
```

where X is a d×d PSD matrix, ν > d-1, |·| denotes the determinant, tr is the trace and Γ_d is the multivariate gamma function.

#### func NewWishart ¶

`func NewWishart(v mat.Symmetric, nu float64, src rand.Source) (*Wishart, bool)`

NewWishart returns a new Wishart distribution with the given shape matrix and degrees of freedom parameter. NewWishart returns whether the creation was successful.

NewWishart panics if nu <= d - 1 where d is the order of v.

#### func (*Wishart) LogProbSym ¶

`func (w *Wishart) LogProbSym(x mat.Symmetric) float64`

LogProbSym returns the log of the probability of the input symmetric matrix.

LogProbSym returns -∞ if the input matrix is not positive definite (the Cholesky decomposition fails).

#### func (*Wishart) LogProbSymChol ¶

`func (w *Wishart) LogProbSymChol(cholX *mat.Cholesky) float64`

LogProbSymChol returns the log of the probability of the input symmetric matrix given its Cholesky decomposition.

#### func (*Wishart) MeanSymTo ¶

`func (w *Wishart) MeanSymTo(dst *mat.SymDense)`

MeanSymTo calculates the mean matrix of the distribution in and stores it in dst. If dst is empty, it is resized to be an d×d symmetric matrix where d is the order of the receiver. When dst is non-empty, MeanSymTo panics if dst is not d×d.

#### func (*Wishart) ProbSym ¶

`func (w *Wishart) ProbSym(x mat.Symmetric) float64`

ProbSym returns the probability of the symmetric matrix x. If x is not positive definite (the Cholesky decomposition fails), it has 0 probability.

#### func (*Wishart) RandCholTo ¶

`func (w *Wishart) RandCholTo(dst *mat.Cholesky)`

RandCholTo generates the Cholesky decomposition of a random matrix from the distribution. If dst is empty, it is resized to be an d×d symmetric matrix where d is the order of the receiver. When dst is non-empty, RandCholTo panics if dst is not d×d.

#### func (*Wishart) RandSymTo ¶

`func (w *Wishart) RandSymTo(dst *mat.SymDense)`

RandSymTo generates a random symmetric matrix from the distribution. If dst is empty, it is resized to be an d×d symmetric matrix where d is the order of the receiver. When dst is non-empty, RandSymTo panics if dst is not d×d.