Accelerating the pace of engineering and science

# Documentation Center

• Trial Software
• Product Updates

# lsqr

## Syntax

x = lsqr(A,b)
lsqr(A,b,tol)
lsqr(A,b,tol,maxit)
lsqr(A,b,tol,maxit,M)
lsqr(A,b,tol,maxit,M1,M2)
lsqr(A,b,tol,maxit,M1,M2,x0)
[x,flag] = lsqr(A,b,tol,maxit,M1,M2,x0)
[x,flag,relres] = lsqr(A,b,tol,maxit,M1,M2,x0)
[x,flag,relres,iter] = lsqr(A,b,tol,maxit,M1,M2,x0)
[x,flag,relres,iter,resvec] = lsqr(A,b,tol,maxit,M1,M2,x0)
[x,flag,relres,iter,resvec,lsvec] = lsqr(A,b,tol,maxit,M1,M2,x0)

## Description

x = lsqr(A,b) attempts to solve the system of linear equations A*x=b for x if A is consistent, otherwise it attempts to solve the least squares solution x that minimizes norm(b-A*x). The m-by-n coefficient matrix A need not be square but it should be large and sparse. The column vector b must have length m. You can specify A as a function handle, afun, such that afun(x,'notransp') returns A*x and afun(x,'transp') returns A'*x.

Parameterizing Functions explains how to provide additional parameters to the function afun, as well as the preconditioner function mfun described below, if necessary.

If lsqr converges, a message to that effect is displayed. If lsqr fails to converge after the maximum number of iterations or halts for any reason, a warning message is printed displaying the relative residual norm(b-A*x)/norm(b) and the iteration number at which the method stopped or failed.

lsqr(A,b,tol) specifies the tolerance of the method. If tol is [], then lsqr uses the default, 1e-6.

lsqr(A,b,tol,maxit) specifies the maximum number of iterations.

lsqr(A,b,tol,maxit,M) and lsqr(A,b,tol,maxit,M1,M2) use n-by-n preconditioner M or M = M1*M2 and effectively solve the system A*inv(M)*y = b for y, where y = M*x. If M is [] then lsqr applies no preconditioner. M can be a function mfun such that mfun(x,'notransp') returns M\x and mfun(x,'transp') returns M'\x.

lsqr(A,b,tol,maxit,M1,M2,x0) specifies the n-by-1 initial guess. If x0 is [], then lsqr uses the default, an all zero vector.

[x,flag] = lsqr(A,b,tol,maxit,M1,M2,x0) also returns a convergence flag.

Flag

Convergence

0

lsqr converged to the desired tolerance tol within maxit iterations.

1

lsqr iterated maxit times but did not converge.

2

Preconditioner M was ill-conditioned.

3

lsqr stagnated. (Two consecutive iterates were the same.)

4

One of the scalar quantities calculated during lsqr became too small or too large to continue computing.

Whenever flag is not 0, the solution x returned is that with minimal norm residual computed over all the iterations. No messages are displayed if you specify the flag output.

[x,flag,relres] = lsqr(A,b,tol,maxit,M1,M2,x0) also returns an estimate of the relative residual norm(b-A*x)/norm(b). If flag is 0, relres <= tol.

[x,flag,relres,iter] = lsqr(A,b,tol,maxit,M1,M2,x0) also returns the iteration number at which x was computed, where 0 <= iter <= maxit.

[x,flag,relres,iter,resvec] = lsqr(A,b,tol,maxit,M1,M2,x0) also returns a vector of the residual norm estimates at each iteration, including norm(b-A*x0).

[x,flag,relres,iter,resvec,lsvec] = lsqr(A,b,tol,maxit,M1,M2,x0) also returns a vector of estimates of the scaled normal equations residual at each iteration: norm((A*inv(M))'*(B-A*X))/norm(A*inv(M),'fro'). Note that the estimate of norm(A*inv(M),'fro') changes, and hopefully improves, at each iteration.

## Examples

### Example 1

```n = 100;
on = ones(n,1);
A = spdiags([-2*on 4*on -on],-1:1,n,n);
b = sum(A,2);
tol = 1e-8;
maxit = 15;
M1 = spdiags([on/(-2) on],-1:0,n,n);
M2 = spdiags([4*on -on],0:1,n,n);

x = lsqr(A,b,tol,maxit,M1,M2);```

displays the following message:

```lsqr converged at iteration 11 to a solution with relative
residual 3.5e-009```

### Example 2

This example replaces the matrix A in Example 1 with a handle to a matrix-vector product function afun. The example is contained in a function run_lsqr that

• Calls lsqr with the function handle @afun as its first argument.

• Contains afun as a nested function, so that all variables in run_lsqr are available to afun.

The following shows the code for run_lsqr:

```function x1 = run_lsqr
n = 100;
on = ones(n,1);
A = spdiags([-2*on 4*on -on],-1:1,n,n);
b = sum(A,2);
tol = 1e-8;
maxit = 15;
M1 = spdiags([on/(-2) on],-1:0,n,n);
M2 = spdiags([4*on -on],0:1,n,n);
x1 = lsqr(@afun,b,tol,maxit,M1,M2);

function y = afun(x,transp_flag)
if strcmp(transp_flag,'transp')      % y = A'*x
y = 4 * x;
y(1:n-1) = y(1:n-1) - 2 * x(2:n);
y(2:n) = y(2:n) - x(1:n-1);
elseif strcmp(transp_flag,'notransp') % y = A*x
y = 4 * x;
y(2:n) = y(2:n) - 2 * x(1:n-1);
y(1:n-1) = y(1:n-1) - x(2:n);
end
end
end```

When you enter

`x1=run_lsqr;`

MATLAB® software displays the message

```lsqr converged at iteration 11 to a solution with relative
residual 3.5e-009```

## References

[1] Barrett, R., M. Berry, T. F. Chan, et al., Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia, 1994.

[2] Paige, C. C. and M. A. Saunders, "LSQR: An Algorithm for Sparse Linear Equations And Sparse Least Squares," ACM Trans. Math. Soft., Vol.8, 1982, pp. 43-71.

## See Also

Was this topic helpful?