eig — Compute eigenvalue decompositions in MATLAB and RunMat.
eig(A) computes eigenvalues of square matrix A; eig(A,B) computes generalized eigenvalues for dense square matrix pencils. Additional outputs return right and left eigenvectors under MATLAB and RunMat multi-output semantics.
Syntax
d = eig(A)
d = eig(A, options...)
[V, D] = eig(A)
[V, D] = eig(A, options...)
[V, D, W] = eig(A)
[V, D, W] = eig(A, options...)All supported eig forms
d = eig(A)
d = eig(A, options...)
[V, D] = eig(A)
[V, D] = eig(A, options...)
[V, D, W] = eig(A)
[V, D, W] = eig(A, options...)
d = eig(A, B)
d = eig(A, B, options...)
[V, D] = eig(A, B)
[V, D] = eig(A, B, options...)
[V, D, W] = eig(A, B)
[V, D, W] = eig(A, B, options...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | NumericArray | Yes | — | Input square matrix. |
options | Any | Variadic | — | Optional selectors (`balance`, `nobalance`, `vector`, `matrix`). |
B | NumericArray | Yes | — | Second square matrix in the generalized problem A*V = B*V*D. |
Returns
| Name | Type | Description |
|---|---|---|
d | NumericArray | Eigenvalues as a column vector. |
V | NumericArray | Right eigenvectors. |
D | NumericArray | Diagonal matrix (or vector when `vector` option is used). |
W | NumericArray | Left eigenvectors. |
Returned values from eig depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:eig:InvalidArgument | Option arguments or requested output count are invalid. | eig currently supports at most three outputs |
RunMat:eig:InvalidInput | Input is unsupported or matrix shape is invalid. | eig: input matrix must be square |
RunMat:eig:Internal | Runtime cannot compute or materialize eig outputs. | eig: internal runtime failure |
How eig works
- Single output
d = eig(A)returns the eigenvalues as ann × 1column vector (values may be complex even whenAis real). - Two outputs
[V,D] = eig(A)return the eigenvectors (columns ofV) and the diagonal eigenvalue matrixD. - Three outputs
[V,D,W] = eig(A)additionally return the left eigenvectorsWsatisfyingW' * A = D * W'. - Generalized calls
d = eig(A,B),[V,D] = eig(A,B), and[V,D,W] = eig(A,B)solveA*V = B*V*Dfor square, same-size single or double matrices. Native BLAS/LAPACK builds useZGGEVand can return infinite eigenvalues for singular pencils; non-LAPACK builds support the nonsingularBcase. - The selector
'vector'may be supplied (eig(A,'vector'),eig(A,B,'vector'),[V,d] = eig(A,'vector')) to request the eigenvalues as a column vector even when two outputs are requested.'matrix'resets the second output to the diagonal-matrix form. - Logical and typed-integer coefficient matrices are a named RunMat-only extension. Strict modes reject them before provider access; RunMat mode promotes them to double only after every integer coefficient passes an exact binary64-representability check.
- Single host and gpuArray inputs retain single output storage. Complex inputs remain complex throughout the factorisation.
- Empty and scalar matrices follow MATLAB’s shape conventions (
eig([])returns[],eig(5)returns5). - When the BLAS/LAPACK feature is unavailable and
Bis singular, RunMat detects that the fallback path would need full QZ support and raises a clear error instead of returning a partial factorization. - Optional balancing keywords (
'balance','nobalance') are accepted. Balancing defaults to on; true balancing remains an explicit numerical-compatibility gap in the current implementation. - Explicit generalized
'chol'and'qz'selectors and MATLAB's limited real-symmetric sparse eig form remain explicit implementation gaps rather than advertised completed behavior.
Does RunMat run eig on the GPU?
The WGPU provider implements the reserved standard eig(A) hook by downloading the input, running the same CPU decomposition used by the host path, and immediately re-uploading the double-precision eigenvalues, eigenvectors, and diagonal matrix. When the spectrum is real, the outputs therefore remain on the GPU without any user intervention.
If the provider hook cannot serve a call, including generalized or complex problems and calls using 'nobalance' or 'vector', RunMat gathers through the input handle's owning provider, computes with the host implementation, and uploads eligible numeric outputs back through that same owner. Floating-point outputs therefore retain accelerator residency across these transparent fallbacks.
The fusion planner treats eig as an allocation boundary: its result handles are not fused into the decomposition itself, but eligible floating-point outputs remain available to subsequent accelerator work without an explicit gpuArray round trip.
Examples
Computing Eigenvalues of a 2x2 Matrix
A = [2 1; 0 3];
d = eig(A)Expected output:
d = [2; 3]Diagonalizing a Matrix with Two Outputs
A = [0 1; -2 -3];
[V,D] = eig(A);
recon = V * D / VRetrieving Left Eigenvectors with Three Outputs
A = [4 2; 1 3];
[V,D,W] = eig(A);
check = W' * A - D * W'Eigenvalues of a Complex-Valued Matrix
A = [1+2i, 2-1i; 0, -3i];
[V,D] = eig(A);
diag(D) % Complex eigenvaluesEigenvalues of a Diagonal Matrix
A = diag([10, -2, 7]);
d = eig(A)Handling Repeated Eigenvalues
A = [3 1 0; 0 3 0; 0 0 5];
d = eig(A)Using the 'nobalance' Option
A = [1e6 1; 0 1e-6];
d_balanced = eig(A);
d_nobalance = eig(A, 'nobalance')Returning Eigenvalues as a Vector with Two Outputs
A = [0 1; -2 -3];
[V,d] = eig(A, 'vector');
size(d) % 2 x 1 column vectorSolving a Generalized Eigenvalue Problem
A = [2 0; 0 9];
B = [1 0; 0 3];
d = eig(A, B)Expected output:
d = [2; 3]Generalized Eigenvectors
A = [4 1; 0 9];
B = [2 0; 0 3];
[V,D,W] = eig(A, B);
rightResidual = A*V - B*V*D;
leftResidual = W'*A - D*W'*BRunning eig on a gpuArray
G = gpuArray(randn(128));
d = eig(G); % Real spectra stay on the GPU when the provider implements eig
isa(d, 'gpuArray') % logical 1 when the provider kept the result on deviceHow RunMat validates eig
eig uses a dense complex Schur decomposition for standard problems. Generalized eig(A,B) uses LAPACK ZGGEV when the native BLAS/LAPACK feature is enabled, including singular pencils with infinite eigenvalues; otherwise it solves the equivalent standard problem B\A for nonsingular B and rejects singular fallback cases with a descriptive QZ-required error. CPU correctness is exercised by the in-module tests linked below; GPU residency is validated at the host-fallback boundary described above rather than via a separate GPU eigensolver.
- Implementation: crates/runmat-runtime/src/builtins/math/linalg/factor/eig.rs
- Parity test: eig unit tests
- Tolerance: CPU-only validated; no dedicated GPU eigensolver
See Correctness & Trust for the full methodology and coverage table.
Using eig with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how eig changes the result.
Run a small eig example, explain the result, then change one input and compare the output.
FAQ
What shapes does eig support?⌄
eig requires a square matrix. Scalars are treated as 1×1 matrices, and empty inputs return empty outputs. Non-square inputs raise an error, matching MATLAB.
Do I always get complex outputs?⌄
Eigenvalues and eigenvectors are returned as complex arrays when necessary. If all imaginary parts are numerically zero, RunMat returns real doubles for convenience, mirroring MATLAB behaviour.
How do I obtain the eigenvalues as a vector when requesting eigenvectors?⌄
Pass the 'vector' selector. For example, [V,d] = eig(A,'vector') returns a column vector d and the right eigenvectors in V. Use 'matrix' (or omit the selector) when you prefer the diagonal-matrix form.
What about the optional balancing keywords?⌄
'balance' (default) and 'nobalance' are accepted, but true balancing is not implemented yet. This is a documented numerical-compatibility gap.
Are generalized eigenvalue problems supported?⌄
Yes. In native BLAS/LAPACK builds, eig(A,B) uses LAPACK ZGGEV for dense generalized matrix pencils and can return infinite eigenvalues when the pencil is singular. In non-LAPACK builds, RunMat supports the nonsingular B case by solving the equivalent standard problem B\A and raises a descriptive QZ-required error for singular B.
How are left eigenvectors normalised?⌄
RunMat scales standard left eigenvectors so that W' * V = I. For generalized eig(A,B), it scales them so that W' * B * V = I. When a provider supplies the GPU implementation the same normalisation is expected.
Does eig participate in fusion or auto-offload?⌄
No. Eigenvalue decomposition executes eagerly and terminates fusion. Resident inputs remain available to the builtin for provider dispatch or an explicit owning-provider gather fallback.
How can I continue on the GPU after calling eig today?⌄
When the input provider implements the standard eig(A) hook, validated outputs remain resident. Generalized, complex, 'nobalance', and unsupported-provider paths gather through the input owner, compute on the host, and upload eligible numeric results back to that same owner.
What happens if the eigenvector matrix is singular?⌄
When the right eigenvectors form a singular matrix, RunMat falls back to computing left eigenvectors from the conjugate-transposed problem. If that fails, requesting the third output raises an error, matching MATLAB’s failure behaviour.
What equation does eig solve?⌄
For the standard form [V, D] = eig(A), the outputs satisfy A*V = V*D, where the columns of V are right eigenvectors and D is a diagonal matrix of eigenvalues. For the generalized form [V, D] = eig(A, B), the outputs satisfy A*V = B*V*D when B is nonsingular.
How do I get just the eigenvalues versus eigenvalues and eigenvectors?⌄
Call d = eig(A) with a single output to get a column vector of eigenvalues only. Use [V, D] = eig(A) to also get the eigenvectors, or [V, D, W] = eig(A) to additionally get the left eigenvectors in W.
Are the eigenvalues returned by eig sorted?⌄
No. Unlike svd, which returns singular values in descending order, eig returns eigenvalues in whatever order the underlying decomposition produces. Sort them yourself when you need ordering, for example [d, idx] = sort(diag(D)); D = diag(d); V = V(:, idx);.
When should I use eig versus eigs?⌄
Use eig for dense matrices when you want the full spectrum. The current RunMat eigs implementation selects a subset from the dense eig fallback; a true iterative Arnoldi/Lanczos provider path remains future work.
Related Linalg functions
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how eig is executed, line by line, in Rust.
- View the source for eig in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.