warp.eig3#

warp.eig3( A: Matrix[Float, Literal[3], Literal[3]], ) → tuple[Matrix[Float, Literal[3], Literal[3]], Vector[Float, Literal[3]]]#

Kernel: true
Python: true
Differentiable: true

Compute the eigendecomposition of a symmetric 3x3 matrix.

Do not rely on a particular ordering of the eigenvalues, signs of the eigenvectors, or a specific eigenvector basis when eigenvalues repeat.

Autodiff supports smooth losses that depend only on the eigenvalues d and are unchanged by reordering its components. Examples include the sum of the eigenvalues and their sum of squares. These losses can be differentiated even when eigenvalues repeat.

Repeated eigenvalues make the corresponding eigenvectors non-unique. Losses that require a particular eigenvector may therefore have no well-defined gradient. Losses that select an individual eigenvalue may also be nondifferentiable when eigenvalues repeat.

Currently, gradients through the eigenvector matrix Q may be unreliable when eigenvalues are close or repeated. Check gradients for the inputs and precision you use before relying on eigenvector-dependent losses.

The current implementation uses a fixed number of Jacobi iterations. Check reconstruction and orthogonality when accuracy is critical.

Parameters:: A – Symmetric matrix to decompose.
Returns:: A tuple (Q, d) such that A = Q * wp.diag(d) * wp.transpose(Q) up to numerical error. The columns of Q form a right-handed orthonormal eigenvector basis, paired with the corresponding eigenvalues in d.

Example

Decompose a symmetric matrix and reconstruct it from its eigenpairs:

@wp.kernel
def decompose_symmetric_matrices(
    matrices: wp.array[wp.mat33],
    eigenvectors: wp.array[wp.mat33],
    eigenvalues: wp.array[wp.vec3],
):
    i = wp.tid()
    Q, d = wp.eig3(matrices[i])
    eigenvectors[i] = Q
    eigenvalues[i] = d

matrices = wp.array(
    [wp.mat33(4.0, 1.0, 2.0, 1.0, 3.0, 1.0, 2.0, 1.0, 5.0)],
    dtype=wp.mat33,
)
eigenvectors = wp.empty(1, dtype=wp.mat33)
eigenvalues = wp.empty(1, dtype=wp.vec3)

wp.launch(
    decompose_symmetric_matrices,
    dim=1,
    inputs=[matrices],
    outputs=[eigenvectors, eigenvalues],
)

Q = eigenvectors.numpy()[0]
d = eigenvalues.numpy()[0]
print(np.round(Q @ np.diag(d) @ Q.T, 3))

[[4. 1. 2.]
 [1. 3. 1.]
 [2. 1. 5.]]

warp.eig3( A: Matrix[Float, Literal[3], Literal[3]], Q: Matrix[Float, Literal[3], Literal[3]], d: Vector[Float, Literal[3]], ) → None

Kernel: true
Python: false
Differentiable: true

Compute the eigendecomposition of a symmetric 3x3 matrix and store the eigenpairs in caller-provided output arguments.

See the return-value overload for the factorization convention, numerical behavior, and autodiff guidance.

Parameters:

A – Symmetric matrix to decompose.
Q – Output matrix whose columns are eigenvectors.
d – Output vector of the corresponding eigenvalues.

Example

Store the eigenpairs of A in Q and d:

@wp.kernel
def compute_eig3(A: wp.mat33):
    Q = wp.mat33()
    d = wp.vec3()

    wp.eig3(A, Q, d)