eigs — Compute selected eigenvalues and eigenvectors with MATLAB-compatible dense-fallback signatures.
eigs(A) returns a subset of eigenvalues. MATLAB-compatible coefficient matrices A and B use class single or double; in runmat compatibility mode, supported integer and logical coefficient matrices are accepted as a RunMat extension. Inputs are materialized on the host, decomposed through the shared exact eig path, and reduced to the requested subset.
Syntax
d = eigs(A)
d = eigs(A, k)
d = eigs(A, k, sigma)
d = eigs(A, k, sigma, opts)
d = eigs(A, k, sigma, Name, Value)
d = eigs(A, B, ...)
[V, D] = eigs(...)
[V, D, flag] = eigs(...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | NumericArray | Yes | — | Square numeric, sparse, logical, complex, or gpuArray matrix. |
args | Any | Variadic | — | Optional B, k, sigma, opts, and name-value arguments. |
Returns
| Name | Type | Description |
|---|---|---|
d | NumericArray | Selected eigenvalues as a column vector. |
V | NumericArray | Selected right eigenvectors. |
D | NumericArray | Diagonal matrix of selected eigenvalues. |
flag | NumericScalar | Convergence flag; exact host fallback returns 0. |
Returned values from eigs depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:eigs:InvalidArgument | Inputs, options, or requested output count are invalid. | eigs: invalid argument |
RunMat:eigs:InvalidInput | The matrix input is unsupported or has invalid shape. | eigs: input matrix must be square |
RunMat:eigs:UnsupportedInput | Function-handle or provider-only eigs behavior is requested. | eigs: unsupported input form |
RunMat:eigs:Internal | Runtime cannot materialize selected eigen outputs. | eigs: internal runtime failure |
How eigs works
eigs(A)returns up to six eigenvalues with largest magnitude.eigs(A,k)clampsktosize(A,2)when larger than the matrix order.- Typed-integer
kis an exact documented structural control. Typed-integersigmaand typed-integerStartVectorare separately named RunMat-only extensions because the public data-type lists for those roles are single and double. - Admitted integer coefficient and sigma values must be exactly representable at the explicit binary64 dense-fallback boundary; integer k and CholeskyPermutation are parsed structurally.
eigs(A,k,sigma)supports numericsigmaand the documented text selectorslargestabs,smallestabs,largestreal,smallestreal,bothendsreal,largestimag,smallestimag, andbothendsimag, plus documented short aliases.eigs(A,B,...)solves the generalized problem by reusingeig(A,B)and then selecting the requested subset.- Two outputs return selected right eigenvectors and a diagonal eigenvalue matrix. Three outputs append convergence flag
0because the current exact fallback either succeeds fully or raises an error. - Options supplied as a struct or name-value pairs are validated for MATLAB-compatible field names, value shapes, subspace-dimension minimums, and generalized-problem sigma constraints. Iterative controls such as tolerance, maximum iterations, subspace dimension, start vector, display, and failure treatment do not change the current dense fallback result.
- Single coefficient or StartVector data preserves single output storage, matching the R2025a-and-later precision rule.
- Function-handle
Afunforms are intentionally rejected with a deterministic unsupported-form error until RunMat has iterative operator eigensolver support. - Sparse inputs are materialized to dense host tensors for compatibility only. Very large sparse problems are not a completed high-performance
eigspath and should be queued for a future sparse/provider implementation.
Does RunMat run eigs on the GPU?
The compatibility target does not document GPU Array support for eigs. RunMat retains gpuArray arguments behind its explicit extension mode, gathers them, and returns host tensors because subset eigenvalue selection needs host-side ordering.
The builtin is explicitly marked ResidencyPolicy::GatherImmediately so the runtime does not imply a false GPU fast path.
A future provider implementation should add a true partial eigensolver hook in runmat-accelerate and parity tests against this exact fallback.
Examples
Largest magnitude eigenvalues
A = diag([1 8 -3 4]);
d = eigs(A, 2)Expected output:
d = [8; 4]Smallest magnitude eigenvalues from sparse input
S = sparse(diag([10 2 -4]));
d = eigs(S, 2, 'smallestabs')Expected output:
d = [2; -4]Generalized eigenvalue subset
A = [2 0; 0 9];
B = [1 0; 0 3];
d = eigs(A, B, 1, 'smallestreal')Expected output:
d = 2Using eigs with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how eigs changes the result.
Run a small eigs example, explain the result, then change one input and compare the output.
FAQ
Does eigs use an iterative sparse algorithm?⌄
Not yet. RunMat currently uses a dense fallback through eig, then applies eigs subset ordering. It covers small and medium value-selection cases but does not reproduce iterative convergence, failure-treatment, or performance behavior.
Which sigma selectors are supported?⌄
RunMat supports numeric shifts plus largestabs, smallestabs, largestreal, smallestreal, bothendsreal, largestimag, smallestimag, bothendsimag, and the documented aliases such as lm, sm, lr, sr, la, sa, be, li, and si.
What does the convergence flag mean?⌄
The third output is 0 for successful exact fallback results. If the shared eigendecomposition cannot complete, RunMat raises an error rather than returning nonconverged values.
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 eigs is executed, line by line, in Rust.
- View the source for eigs 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.