nitorch_fastmath.qr

eig_sym

eig_sym(a, compute_u=False, upper=True, inplace=False, check_finite=True, max_iter=1024, tol=1e-32)

Compute the eigendecomposition of a Hermitian square matrix.

Note

We use the explicit QR algorithm, which is probably less stable than the implicit QR algorithm used in Lapack.

Note

Eigenvalues are not sorted

To sort eigenvalues and eigenvectors according to some criterion:

s, u = eig_sym(x, compute_u=True)
_, i = crit(s).sort()
s = s.gather(-1, i)    # permute eigenvalues
i = i.unsqueeze(-2).expand(y.shape)
u = u.gather(-1, i)    # permute eigenvectors

If the criterion is the value of the eigenvalues, it simplifies:

s, u = eig_sym(x, compute_u=True)
s, i = s.sort()
i = i.unsqueeze(-2).expand(y.shape)
u = u.gather(-1, i)    # permute eigenvectors

Parameters:

Name	Type	Description	Default
`a`	`(..., m, m) tensor`	Input hermitian matrix or field of matrices	required
`compute_u`	`bool`	Compute the eigenvectors. If False, only return `s`.	`False`
`upper`	`bool`	Whether to use the upper or lower triangular component.	`True`
`inplace`	`bool`	If `True`, overwrite `a`.	`False`
`check_finite`	`bool`	If `True`, checks that the input matrix does not contain any non finite value. Disabling this may speed up the algorithm.	`True`
`max_iter`	`int`	Maximum number of iterations.	`1024`
`tol`	`float`	Tolerance for early stopping. Default: machine precision for `a.dtype`.	`1e-32`

Returns:

Name	Type	Description
`s`	`(..., m) tensor`	Eigenvalues.
`u`	`(..., m, m) tensor`, optional	Corresponding eigenvectors.

rq_hessenberg

rq_hessenberg(h, u=None, inplace=False, check_finite=True)

Compute the QR decomposition of a Hessenberg matrix and R` @ Q.

Note

This is slower than torch.qr when the batch size is small, even though torch.qr does not know that h has a Hessenberg form. It's just hard to beat lapack. With larger batch size, both algorithms are on par.

Parameters:

Name	Type	Description	Default
`h`	`(..., n, n) tensor`	Hessenberg matrix, with shape `(..., n, n)`. All elements should be zeros below the first lower diagonal.	required
`u`	`(..., n) tensor`	Vectors to transform with. With shape `(..., n)`.	`None`
`inplace`	`bool`	Process inplace.	`False`
`check_finite`	`bool`	Check that all input values are finite.	`True`

Returns:

Name	Type	Description
`rq`	`tensor`	Reverse product of the QR decomposition: `rq = r @ q`.

qr_hessenberg

qr_hessenberg(h, inplace=False, check_finite=True)

QR decomposition for Hessenberg matrices.

Note

This is slower than torch.qr when the batch size is small, even though torch.qr does not know that h has a Hessenberg form. It's just hard to beat lapack. With larger batch size, both algorithms are on par.

Parameters:

Name	Type	Description	Default
`h`	`(..., n, n) tensor`	Hessenberg matrix, with shape `(..., n, n)`. All elements should be zeros below the first lower diagonal.	required
`inplace`	`bool`	Process inplace.	`False`
`check_finite`	`bool`	Check that all input values are finite.	`True`

Returns:

Name	Type	Description
`q`	`tensor`
`r`	`tensor`

hessenberg

hessenberg(a, inplace=False, check_finite=True, compute_u=False)

Return an Hessenberg form of the matrix (or matrices) a.

Parameters:

Name	Type	Description	Default
`a`	`(..., n, n) tensor`	Input matrix, with shape `(..., n, n)`. Can be complex.	required
`inplace`	`bool`	Overwrite `a`.	`False`
`check_finite`	`bool`	Check that all values in `a` ar finite.	`True`
`compute_u`	`bool`	Compute and return the transformation matrix `u`.	`False`

Returns:

Name	Type	Description
`h`	`(..., n, n) tensor`	Hessenberg form of `a`, with shape `(..., n, n)`.
`u`	`list[tensor]`, optional	Set of Householder reflectors.

References

Hessenberg matrix, Wikipedia

hessenberg_sym

hessenberg_sym(a, upper=True, fill=True, inplace=False, check_finite=True, compute_u=False)

Return a tridiagonal form of the hermitian matrix (or matrices) a.

Note

The Hessenberg form of a Hermitian matrix is tridiagonal.

Parameters:

Name	Type	Description	Default
`a`	`(..., n, n) tensor`	Input hermitian matrix, with shape (..., n, n)`. Can be complex.	required
`upper`	`bool`	Whether to use the upper or lower triangular part of the matrix.	`True`
`fill`	`bool`	Fill the other half of the output matrix by conjugate symmetry.	`False`
`inplace`	`bool`	Overwrite `a`.	`False`
`check_finite`	`bool`	Check that all values in `a` ar finite.	`True`
`compute_u`	`bool`	Compute and return the transformation matrix `u`.	`False`

Returns:

Name	Type	Description
`h`	`(..., n, n) tensor`	Hessenberg (tridiagonal) form of `a`, with shape `(..., n, n)`.
`u`	`list[tensor]`, optional	Set of Householder reflectors.

References

Hessenberg matrix, Wikipedia

householder

householder(x, basis=0, inplace=False, check_finite=True, return_alpha=False)

Compute the Householder reflector of a (batch of) vector(s).

Note

Householder reflectors are matrices of the form $\mathbf{P} = \mathbf{I} - 2\mathbf{u}\mathbf{u}^\ast$, where $\mathbf{u}$ is a Householder vector. Reflectors are typically used to project a (complex) vector onto a Euclidean basis: $\mathbf{P} \times \mathbf{x} = r \lVert\mathbf{x}\rVert \mathbf{e}_i$, with $r = -\exp(i*\operatorname{angle}(x_i))$. This function returns a Householder vector tailored to a specific (complex) vector.

Parameters:

Name	Type	Description	Default
`x`	`(..., n) tensor`	Input vector, with shape `(..., n)` where `...` is any number of leading batch dimensions.	required
`basis`	`int`	Index of the Euclidean basis.	`1`
`inplace`	`bool`	If True, overwrite `x`.	`False`
`check_finite`	`bool`	If True, checks that the input matrix does not contain any non finite value. Disabling this may speed up the algorithm.	`True`
`return_alpha`	`bool`	Return alpha, the 'projection' of x on the Euclidean basis: $-\lVert \mathbf{x} \rVert \times \exp(i*\operatorname{angle}(x_i))$, where $i$ is the index of the Euclidean basis.	`False`

Returns:

Name	Type	Description
`u`	`(..., n) tensor`	Householder vector, with shape `(..., n)`.
`a`	`(...) tensor`, optional	Projection on the Euclidean basis, with shape `(...)`.

householder_apply

householder_apply(a, u, k=None, side='both', inverse=False, inplace=False, check_finite=True)

Apply a series of Householder reflectors to a matrix.

Parameters:

Name	Type	Description	Default
`a`	`(..., n, n) tensor`	$N \times N$ matrix, with shape `(..., n, n)` where `...` is any number of leading batch dimensions.	required
`u`	`tensor or list[tensor]`	A list of Householder reflectors $\left\{\mathbf{u}_k\right\}_{k=1}^K$. Each reflector forms the Householder matrix $\mathbf{P}_k = \mathbf{I} - 2 \mathbf{u}_k \mathbf{u}_k^H$.	required
`k`	`int or list[int]`	The index corresponding to each reflector.	`None`
`side`	`{'left', 'right', 'both'}`	Side to apply to.	`'both'`
`inverse`	`bool`	Apply the inverse transform	`False`
`inplace`	`bool`	Apply transformation inplace.	`False`
`check_finite`	`bool`	Check that the input does not have any nonfinite values	`True`

Returns:

Name	Type	Description
`h`	`(..., n, n) tensor`	The transformed matrix: $\mathbf{H} = \mathbf{U} \times \mathbf{A} \times \mathbf{U}^H$ with $\mathbf{U} = \mathbf{P}_{k-2} \times ... \times \mathbf{P}_1$.

givens

givens(x, y)

Compute a Givens rotation matrix.

Note

A Givens rotation is a rotation in a plane that aligns a specific vector (in this plane) with the first axis of the plane: $$ \mathbf{G} \times \mathbf{x} = \left(\lVert\mathbf{x}\rVert, \mathbf{0} \right)^\mathrm{T}. $$

Parameters:

Name	Type	Description	Default
`x`	`tensor`	First vector component	required
`y`	`tensor`	Second vector component	required

Returns:

Name	Type	Description
`c`	`tensor`	Cosine of the Givens rotation: `c = x / norm([x, y])`
`s`	`tensor`	Sine of the Givens rotation: `s = -y / norm([x, y])`

References

Givens rotation, Wikipedia

givens_apply

givens_apply(a, c, s, i=0, j=None, side='both', inplace=False, check_finite=True)

Apply a Givens rotation to a matrix

Parameters:

Name	Type	Description	Default
`a`	`(..., n, n) tensor`	Input matrix	required
`c`	`tensor`	Cosine of the Givens rotation	required
`s`	`tensor`	Sine of the Givens rotation	required
`i`	`int`	Index in `a` of the first component of the 2D vector to rotate	`0`
`j`	`int`	Index in `a` of the second component of the 2D vector to rotate	`i+1`
`side`	`{'left', 'right', 'both'}`	Whether to apply the rotation on the left or on the right.	`'both'`
`inplace`	`bool`	Apply the rotation in-place.	`False`
`check_finite`	`bool`	Check for non-finite values	`True`

Returns:

Name	Type	Description
`a`	`(..., n, n) tensor`	Rotated matrix

References

Givens rotation, Wikipedia

Name	Type	Description	Default
`a`	`(..., n, n) tensor`	\(N \times N\) matrix, with shape `(..., n, n)` where `...` is any number of leading batch dimensions.	required
`u`	`tensor or list[tensor]`	A list of Householder reflectors \(\left\{\mathbf{u}_k\right\}_{k=1}^K\). Each reflector forms the Householder matrix \(\mathbf{P}_k = \mathbf{I} - 2 \mathbf{u}_k \mathbf{u}_k^H\).	required
`k`	`int or list[int]`	The index corresponding to each reflector.	`None`
`side`	`{'left', 'right', 'both'}`	Side to apply to.	`'both'`
`inverse`	`bool`	Apply the inverse transform	`False`
`inplace`	`bool`	Apply transformation inplace.	`False`
`check_finite`	`bool`	Check that the input does not have any nonfinite values	`True`