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
Returns:

\(\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
Returns:

\(\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)
Returns:

\(\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.
Returns:

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)\).
Returns:

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)\).
Returns:

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.
Returns:

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”.
Returns:

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).
Returns:

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\):

\[\begin{equation} \mathbf A^{-1} \mathbf R, \end{equation}\]

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

\[\begin{equation} \mathbf L \mathbf A^{-1} \mathbf R, \end{equation}\]

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
Returns:

\(\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

\[\begin{equation} \mathbf A^{-1/2} \mathbf R, \end{equation}\]

If lhs is supplied, computes

\[\begin{equation} \mathbf L \mathbf A^{-1/2} \mathbf R, \end{equation}\]

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
Returns:

\(\mathbf A^{-1/2} \mathbf R\) or \(\mathbf L \mathbf A^{-1/2} \mathbf R\).