Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
In MATLAB, svds computes a few singular values (and optionally the matching singular vectors) of a large matrix, by default the six largest. Call s = svds(A) for the values, s = svds(A,k) for k of them, or [U,S,V] = svds(A,k) to also get the singular vectors. It is intended for matrices that are typically, but not always, large and sparse, where a full decomposition would be wasteful.
This guide follows the current MathWorks reference page for svds (read 2026-11-12) and adds what the reference spreads across several paragraphs: a table of the sigma modes with their limits, a troubleshooting order for convergence problems, notes on reproducibility, and a mapping to the SciPy function of the same name.
What svds is used for in research
A singular value decomposition factors a matrix A into U, S and V so that A = U*S*V’. Research workflows rarely need all of it. A low-rank approximation of a large term-document, gene-expression, network or imaging matrix needs only the leading singular triplets, and a conditioning check on a sparse matrix needs only the smallest. svds returns just the requested subset, which is why it is preferred to svd when A is large and sparse.
The reference page states the trade-off directly: for a small dense matrix, svd(full(A)) can be quicker than svds. If you know the tolerance you can accept but not the rank you need, the page points to svdsketch instead. For the related eigenvalue problem see eigenvalues in MATLAB; for building and indexing the matrices themselves see matrices in MATLAB; for the sparse formats used on the Python side see SciPy sparse matrices.
The same leading singular vectors underlie principal component analysis; for the statistical interpretation see principal component analysis plots, and for the matrix that PCA decomposes see covariance matrices.
How to install or access it
svds is a function documented in the core MATLAB reference, so it is available in a MATLAB installation without a separate download. MathWorks’ installation documentation (read 2026-11-12) describes the routes: sign in to your MathWorks account and download the installer; on Windows double-click the installer, on Linux unzip it and run the install script, and on macOS mount the disk image. MATLAB Online can be opened at matlab.mathworks.com after signing in with a MathWorks account. Licensing terms depend on your institution’s agreement and are set by MathWorks, so confirm them with your research computing or IT office rather than from a web page.
Two features need an additional product: running svds on GPU arrays or distributed arrays requires Parallel Computing Toolbox, per the reference page’s extended-capabilities section. The function fully supports thread-based environments.
Step-by-step: compute singular values with svds
These steps use the examples from the MathWorks reference page.
- Build or load a matrix. The reference’s first example creates a sparse matrix with
A = delsq(numgrid('C',15));. In your own work, A is typically a sparse matrix of classdoubleorsingle; complex values are allowed. - Request the six largest singular values.
s = svds(A)returns a column vector. Six is the default fork. - Change how many you want.
s = svds(A,k)returnskvalues. Ifkexceedsmin(size(A)), fewer values come back. - Choose which end of the spectrum.
s = svds(A,5,'smallest')returns the five smallest. Other modes appear in the table below. - Ask for the vectors.
[U,S,V] = svds(A)returns the left vectors, a diagonal matrix of values, and the right vectors. - Check convergence.
[U,S,V,cflag] = svds(A);adds a flag.cflag = 0means every requested value converged. - Tune if needed.
s = svds(A,6,'largest','SubspaceDimension',60)is the reference page’s example of a Name-Value option.
Syntax forms
The documented call patterns are svds(A), svds(A,k), svds(A,k,sigma), svds(A,k,sigma,Name,Value), svds(A,k,sigma,opts), svds(Afun,n,___), and the output forms [U,S,V] = svds(___) and [U,S,V,flag] = svds(___). The opts structure (fields tol, maxit, p, u0, v0, disp, fail) is marked “not recommended” on the reference page; use Name-Value pairs in new code.
Choosing sigma: modes and their limits
| sigma value | Returns | Limits stated in the reference |
|---|---|---|
'largest' (default) |
The largest singular values | Required for a function handle Afun; required for GPU and distributed arrays (which must also be double) |
'smallest' |
The smallest singular values | On a nearly singular matrix it can warn “Large residual norm” and be inaccurate |
'smallestnz' |
The smallest nonzero singular values | Example: C = gallery('neumann',100); snz = svds(C,10,'smallestnz') |
| A numeric scalar | The values closest to that scalar | SubspaceDimension is ignored; FailureTreatment defaults to 'drop' |
Passing a function handle instead of a matrix
When the matrix is never formed explicitly, supply a function Afun and the matrix size n as [m n]: svds(Afun,n,k). The handle must return A*x when called as Afun(x,'notransp') and A'*x when called as Afun(x,'transp'). The reference example is s = svds(@(x,tflag) Afun(x,tflag,B,C,n),[1000 1000],10). This form works only with sigma = 'largest'.
Output and how to read it
s is a column vector of nonnegative singular values in decreasing order. In the three-output form, U is m-by-k with orthonormal columns, S is a k-by-k diagonal matrix holding the values, and V is n-by-k with orthonormal columns. The product U*S*V' is the rank-k approximation built from the singular triplets you requested; it equals A only when k covers all nonzero singular values.
Reading the convergence flag
With a fourth output, flag = 0 means all requested values converged. Requesting the flag also suppresses the convergence warnings, so check it yourself rather than assuming success. For non-numeric sigma values, entries that did not converge are replaced with NaN by default (FailureTreatment = 'replacenan'); for numeric sigma they are dropped by default ('drop'); 'keep' leaves them in place.
Reproducibility
The start vectors come from a private random stream, so calling rng does not change the output; since R2016a, repeated calls give the same result. Singular vectors are determined only up to sign, and signs may differ between machines or releases, but A = U*S*V' still holds. If you compare results across systems, compare singular values or the reconstructed product, not raw vector signs. Single-precision input is supported from R2025a.
Troubleshooting
The reference page advises this order for convergence trouble:
- Increase
'SubspaceDimension'first. It defaults tomax(3*k,15)and must be at leastk+2. - Then raise
'MaxIterations'(default 100) or loosen'Tolerance'(default 1e-10, or 1e-5 when A or a start vector is single precision). - Use a larger
kif singular values repeat. The page notes this helps with repeated singular values.
“Large residual norm” warning with ‘smallest’
For a nearly singular matrix, 'smallest' may return inaccurate values with this warning. The reference’s workaround factors the matrix first: after computing a QR factorization so that R is the triangular factor, call [U,S,V] = svds(R,20,'s'); U = Q*U;.
Start vectors
LeftStartVector and RightStartVector let you supply a starting guess, but you can give only one of the two.
Name-Value defaults at a glance
The data table below lists the Name-Value options with their documented defaults and constraints, for quick checking in a script review.
Free alternatives
If you do not have MATLAB, SciPy provides a function with the same name in scipy.sparse.linalg. The two differ in defaults and conventions, which matters when porting code or comparing results.
| Item | MATLAB svds |
SciPy scipy.sparse.linalg.svds |
|---|---|---|
| Default number of values | k = 6 |
k = 6 |
| Which values | sigma: 'largest', 'smallest', 'smallestnz', or a scalar |
which: 'LM' or 'SM' |
| Default tolerance | 1e-10 (1e-5 for single precision) |
tol = 0 |
| Solver | Not selectable | solver: 'arpack' (default), 'propack', 'lobpcg' |
| Return order | Decreasing, documented | “Not guaranteed” |
| Outputs | U, S, V |
u, s, vh (note: vh is the transposed right vectors) |
Allowed k |
Fewer returned if k > min(size(A)) |
1 to min(M,N)-1 (min(M,N) for propack) |
Because SciPy does not guarantee the order of the singular values, sort them explicitly when porting a MATLAB script. For sparse inputs on the Python side, see SciPy sparse matrices.
Common mistakes
- Using
svdson a small dense matrix; the reference suggestssvd(full(A))may be quicker. - Passing
Afunwith'smallest'; function handles are limited to'largest'. - Expecting
SubspaceDimensionto change a numeric-sigmarun; it is ignored there. - Requesting the flag output and then not reading it, which hides convergence warnings.
- Comparing singular-vector signs between runs on different machines.
FAQ
What does svds do in MATLAB?
It returns a subset of the singular values and, optionally, vectors of a matrix, by default the six largest, using an iterative method suited to large sparse matrices.
What is the difference between svd and svds?
svd computes the full decomposition; svds computes only k singular triplets. For a small dense matrix svd(full(A)) may be faster, per MathWorks.
How do I get the smallest singular values?
Use svds(A,k,'smallest'), or 'smallestnz' for the smallest nonzero values. On nearly singular matrices see the QR workaround above.
Why does svds return NaN?
Values that did not converge are replaced with NaN when sigma is non-numeric and FailureTreatment is its default 'replacenan'. Increase SubspaceDimension first.
Is there a Python equivalent?
Yes, scipy.sparse.linalg.svds; see the comparison table above for differences in defaults and ordering.
Sources
- MathWorks, “svds” reference page, mathworks.com/help/matlab/ref/svds.html, read 2026-11-12.
- MathWorks, “Install Products with Internet Connection”, mathworks.com/help/install, read 2026-11-12.
- SciPy, “scipy.sparse.linalg.svds”, docs.scipy.org, read 2026-11-12.
Data: MATLAB svds Name-Value options: documented defaults and constraints
Name-Value options of the MATLAB svds function with their documented default values and constraints, compiled from the current MathWorks svds reference page.
Period covered: 2026.
| Option | Documented default | Constraint or note |
|---|---|---|
| Tolerance | 1e-10 (1e-5 if A or start vector is single) | Convergence tolerance |
| MaxIterations | 100 | Maximum number of iterations |
| SubspaceDimension | max(3*k,15) | Must be at least k+2; ignored when sigma is numeric |
| LeftStartVector / RightStartVector | Private random stream | Only one of the two may be supplied |
| FailureTreatment | 'replacenan' (non-numeric sigma); 'drop' (numeric sigma) | Also accepts 'keep' |
| Display | false | Shows iteration progress when enabled |
Sources
- MathWorks svds reference (accessed 2026-11-12)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







