Skip to main content
v2026.11,986 entries · CC-BY 4.0

MATLAB svds: Syntax, Options and Troubleshooting

How to use svds in MATLAB for the largest or smallest singular values of a large sparse matrix, with options and convergence fixes.

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.

  1. 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 class double or single; complex values are allowed.
  2. Request the six largest singular values. s = svds(A) returns a column vector. Six is the default for k.
  3. Change how many you want. s = svds(A,k) returns k values. If k exceeds min(size(A)), fewer values come back.
  4. Choose which end of the spectrum. s = svds(A,5,'smallest') returns the five smallest. Other modes appear in the table below.
  5. Ask for the vectors. [U,S,V] = svds(A) returns the left vectors, a diagonal matrix of values, and the right vectors.
  6. Check convergence. [U,S,V,cflag] = svds(A); adds a flag. cflag = 0 means every requested value converged.
  7. 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:

  1. Increase 'SubspaceDimension' first. It defaults to max(3*k,15) and must be at least k+2.
  2. Then raise 'MaxIterations' (default 100) or loosen 'Tolerance' (default 1e-10, or 1e-5 when A or a start vector is single precision).
  3. Use a larger k if 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 svds on a small dense matrix; the reference suggests svd(full(A)) may be quicker.
  • Passing Afun with 'smallest'; function handles are limited to 'largest'.
  • Expecting SubspaceDimension to change a numeric-sigma run; 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

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.

MATLAB svds Name-Value options: documented defaults and constraints
OptionDocumented defaultConstraint or note
Tolerance1e-10 (1e-5 if A or start vector is single)Convergence tolerance
MaxIterations100Maximum number of iterations
SubspaceDimensionmax(3*k,15)Must be at least k+2; ignored when sigma is numeric
LeftStartVector / RightStartVectorPrivate random streamOnly one of the two may be supplied
FailureTreatment'replacenan' (non-numeric sigma); 'drop' (numeric sigma)Also accepts 'keep'
DisplayfalseShows iteration progress when enabled

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about MATLAB svds: Syntax, Options and Troubleshooting

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →