# gpytorch.functions¶

## Functions¶

gpytorch.add_diagonal(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], diag: torch.Tensor) → linear_operator.operators._linear_operator.LinearOperator[source]

Adds an element to the diagonal of the matrix $$\mathbf A$$.

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). diag – Diagonal to add $$\mathbf A + \text{diag}(\mathbf d)$$, where $$\mathbf A$$ is the linear operator and $$\mathbf d$$ is the diagonal component
gpytorch.add_jitter(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], jitter_val: float = 0.001) → Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor][source]

Adds jitter (i.e., a small diagonal component) to the matrix this LinearOperator represents. This is equivalent to calling add_diagonal() with a scalar tensor.

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). jitter_val – The diagonal component to add $$\mathbf A + \alpha (\mathbf I)$$, where $$\mathbf A$$ is the linear operator and $$\alpha$$ is jitter_val.
gpytorch.dsmm(sparse_mat: Union[torch.sparse.HalfTensor, torch.sparse.FloatTensor, torch.sparse.DoubleTensor], dense_mat: torch.Tensor) → torch.Tensor[source]

Performs the (batch) matrix multiplication $$\mathbf{SD}$$ where $$\mathbf S$$ is a sparse matrix and $$\mathbf D$$ is a dense matrix.

Parameters: sparse_mat – Sparse matrix $$\mathbf S$$ (… x M x N) dense_mat – Dense matrix $$\mathbf D$$ (… x N x O) $$\mathbf S \mathbf D$$ (… x M x N)
gpytorch.diagonalization(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], method: Optional[str] = None) → Tuple[torch.Tensor, torch.Tensor][source]

Returns a (usually partial) diagonalization of a symmetric positive definite matrix (or batch of matrices). $$\mathbf A$$. Options are either “lanczos” or “symeig”. “lanczos” runs Lanczos while “symeig” runs LinearOperator.symeig.

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). method – Specify the method to use (“lanczos” or “symeig”). The method will be determined based on size if not specified. eigenvalues and eigenvectors representing the diagonalization.
gpytorch.inv_quad(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], inv_quad_rhs: torch.Tensor, reduce_inv_quad: bool = True) → torch.Tensor[source]

Computes an inverse quadratic form (w.r.t self) with several right hand sides, i.e:

$\text{tr}\left( \mathbf R^\top \mathbf A^{-1} \mathbf R \right),$

where $$\mathbf A$$ is a positive definite matrix (or batch of matrices) and $$\mathbf R$$ represents the right hand sides (inv_quad_rhs).

If reduce_inv_quad is set to false (and inv_quad_rhs is supplied), the function instead computes

$\text{diag}\left( \mathbf R^\top \mathbf A^{-1} \mathbf R \right).$
Parameters: input – $$\mathbf A$$ - the positive definite matrix (… X N X N) inv_quad_rhs – $$\mathbf R$$ - the right hand sides of the inverse quadratic term (… x N x M) reduce_inv_quad – Whether to compute $$\text{tr}\left( \mathbf R^\top \mathbf A^{-1} \mathbf R \right)$$ or $$\text{diag}\left( \mathbf R^\top \mathbf A^{-1} \mathbf R \right)$$. The inverse quadratic term. If reduce_inv_quad=True, the inverse quadratic term is of shape (…). Otherwise, it is (… x M).
gpytorch.inv_quad_logdet(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], inv_quad_rhs: Optional[torch.Tensor] = None, logdet: bool = False, reduce_inv_quad: bool = True) → Tuple[torch.Tensor, torch.Tensor][source]

Calls both inv_quad_logdet() and logdet() on a positive definite matrix (or batch) $$\mathbf A$$. However, calling this method is far more efficient and stable than calling each method independently.

Parameters: input – $$\mathbf A$$ - the positive definite matrix (… X N X N) inv_quad_rhs – $$\mathbf R$$ - the right hand sides of the inverse quadratic term (… x N x M) logdet – Whether or not to compute the logdet term $$\log \vert \mathbf A \vert$$. reduce_inv_quad – Whether to compute $$\text{tr}\left( \mathbf R^\top \mathbf A^{-1} \mathbf R \right)$$ or $$\text{diag}\left( \mathbf R^\top \mathbf A^{-1} \mathbf R \right)$$. The inverse quadratic term (or None), and the logdet term (or None). If reduce_inv_quad=True, the inverse quadratic term is of shape (…). Otherwise, it is (… x M).
gpytorch.pivoted_cholesky(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], rank: int, error_tol: Optional[float] = None, return_pivots: bool = False) → Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]][source]

Performs a partial pivoted Cholesky factorization of a positive definite matrix (or batch of matrices). $$\mathbf L \mathbf L^\top = \mathbf A$$. The partial pivoted Cholesky factor $$\mathbf L \in \mathbb R^{N \times \text{rank}}$$ forms a low rank approximation to the LinearOperator.

The pivots are selected greedily, correspoading to the maximum diagonal element in the residual after each Cholesky iteration. See Harbrecht et al., 2012.

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). rank – The size of the partial pivoted Cholesky factor. error_tol – Defines an optional stopping criterion. If the residual of the factorization is less than error_tol, then the factorization will exit early. This will result in a $$\leq \text{ rank}$$ factor. return_pivots – Whether or not to return the pivots alongside the partial pivoted Cholesky factor. The … x N x rank factor (and optionally the … x N pivots if return_pivots is True).
gpytorch.root_decomposition(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], method: Optional[str] = None) → linear_operator.operators._linear_operator.LinearOperator[source]

Returns a (usually low-rank) root decomposition linear operator of the positive definite matrix (or batch of matrices) $$\mathbf A$$. This can be used for sampling from a Gaussian distribution, or for obtaining a low-rank version of a matrix.

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). method – Which method to use to perform the root decomposition. Choices are: “cholesky”, “lanczos”, “symeig”, “pivoted_cholesky”, or “svd”. A tensor $$\mathbf R$$ such that $$\mathbf R \mathbf R^\top \approx \mathbf A$$.
gpytorch.root_inv_decomposition(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], initial_vectors: Optional[torch.Tensor] = None, test_vectors: Optional[torch.Tensor] = None, method: Optional[str] = None) → linear_operator.operators._linear_operator.LinearOperator[source]

Returns a (usually low-rank) inverse root decomposition linear operator of the PSD LinearOperator $$\mathbf A$$. This can be used for sampling from a Gaussian distribution, or for obtaining a low-rank version of a matrix.

The root_inv_decomposition is performed using a partial Lanczos tridiagonalization.

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). initial_vectors – Vectors used to initialize the Lanczos decomposition. The best initialization vector (determined by test_vectors) will be chosen. test_vectors – Vectors used to test the accuracy of the decomposition. method – Root decomposition method to use (symeig, diagonalization, lanczos, or cholesky). A tensor $$\mathbf R$$ such that $$\mathbf R \mathbf R^\top \approx \mathbf A^{-1}$$.
gpytorch.solve(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], rhs: torch.Tensor, lhs: Optional[torch.Tensor] = None) → torch.Tensor[source]

Given a positive definite matrix (or batch of matrices) $$\mathbf A$$, computes a linear solve with right hand side $$\mathbf R$$:

$$$\mathbf A^{-1} \mathbf R,$$$

where $$\mathbf R$$ is right_tensor and $$\mathbf A$$ is the LinearOperator.

Note

Unlike torch.linalg.solve(), this function can take an optional left_tensor attribute. If this is supplied gpytorch.solve() computes

$$$\mathbf L \mathbf A^{-1} \mathbf R,$$$

where $$\mathbf L$$ is left_tensor. Supplying this can reduce the number of solver calls required in the backward pass.

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). rhs – $$\mathbf R$$ - the right hand side lhs – $$\mathbf L$$ - the left hand side $$\mathbf A^{-1} \mathbf R$$ or $$\mathbf L \mathbf A^{-1} \mathbf R$$.
gpytorch.sqrt_inv_matmul(input: Union[linear_operator.operators._linear_operator.LinearOperator, torch.Tensor], rhs: torch.Tensor, lhs: Optional[torch.Tensor] = None) → torch.Tensor[source]

Given a positive definite matrix (or batch of matrices) $$\mathbf A$$ and a right hand size $$\mathbf R$$, computes

$$$\mathbf A^{-1/2} \mathbf R,$$$

If lhs is supplied, computes

$$$\mathbf L \mathbf A^{-1/2} \mathbf R,$$$

where $$\mathbf L$$ is lhs. (Supplying lhs can reduce the number of solver calls required in the backward pass.)

Parameters: input – The matrix (or batch of matrices) $$\mathbf A$$ (… x N x N). rhs – $$\mathbf R$$ - the right hand side lhs – $$\mathbf L$$ - the left hand side $$\mathbf A^{-1/2} \mathbf R$$ or $$\mathbf L \mathbf A^{-1/2} \mathbf R$$.