Documentation

# linsolve

Solve linear system of equations

## Syntax

``X = linsolve(A,B)``
``X = linsolve(A,B,opts)``
``[X,r] = linsolve(___)``

## Description

example

````X = linsolve(A,B)` solves the linear system AX = B using one of these methods: When `A` is square, `linsolve` uses LU factorization with partial pivoting.For all other cases, `linsolve` uses QR factorization with column pivoting. `linsolve` warns if `A` is ill conditioned (for square matrices) or rank deficient (for rectangular matrices).```

example

````X = linsolve(A,B,opts)` uses an appropriate solver as determined by the options structure `opts`. The fields in `opts` are logical values describing properties of the matrix `A`. For example, if `A` is an upper triangular matrix, you can set `opts.UT = true` to make `linsolve` use a solver designed for upper triangular matrices. `linsolve` does not test to verify that `A` has the properties specified in `opts`.```

example

````[X,r] = linsolve(___)` also returns `r`, which is the reciprocal of the condition number of `A` (for square matrices) or the rank of `A` (for rectangular matrices). You can use any of the input argument combinations in previous syntaxes. With this syntax, `linsolve` does not warn if `A` is ill conditioned or rank deficient.```

## Examples

collapse all

Solve a linear system with both `mldivide` and `linsolve` to compare performance.

`mldivide` is the recommended way to solve most linear systems of equations in MATLAB ®. However, the function performs several checks on the input matrix to determine whether it has any special properties. If you know about the properties of the coefficient matrix ahead of time, then you can use `linsolve` to avoid time-consuming checks for large matrices.

Create a 10000-by-10000 magic square matrix and extract the lower triangular portion. Set the `LT` field of the `opts` structure to `true` to indicate that `A` is a lower triangular matrix.

```A = tril(magic(1e4)); opts.LT = true;```

Create a vector of ones for the right-hand side of the linear equation $\mathrm{Ax}=\mathit{b}$. The number of rows in `A` and `b` must be equal.

`b = ones(size(A,2),1);`

Solve the linear system $\mathrm{Ax}=\mathit{b}$ using `mldivide` and time the calculation.

```tic x1 = A\b; t1 = toc```
```t1 = 0.1038 ```

Now, solve the system again using `linsolve`. Specify the options structure so that `linsolve` can select an appropriate solver for a lower triangular matrix.

```tic x2 = linsolve(A,b,opts); t2 = toc```
```t2 = 0.0679 ```

Compare the execution times to see how much faster `linsolve` is. As with any timing comparison, the results can vary between different computers and releases of MATLAB.

`speedup = t1/t2`
```speedup = 1.5279 ```

Solve a linear system using `linsolve` with two outputs to suppress matrix conditioning warnings.

Create a 20-by-20 Hilbert test matrix. This matrix is nearly singular, with the largest singular value being about `2e18` larger than the smallest.

`A = hilb(20);`

Solve a linear system involving `A` with `linsolve`. Since `A` is nearly singular, `linsolve` returns a warning.

```b = ones(20,1); x = linsolve(A,b);```
```Warning: Matrix is close to singular or badly scaled. Results may be inaccurate. RCOND = 1.276108e-19. ```

Now, solve the same linear system, but specify two outputs to `linsolve`. MATLAB® suppresses the warning, and the second output `r` contains the reciprocal condition number of `A`. You can use this syntax to handle ill-conditioned matrices with special cases in your code, without the code producing a warning.

`[x,r] = linsolve(A,b)`
```x = 20×1 108 × 0.0000 -0.0000 0.0008 -0.0144 0.1448 -0.8567 3.1338 -7.1545 9.9712 -8.4571 ⋮ ```
```r = 1.2761e-19 ```

## Input Arguments

collapse all

Coefficient matrix. `A` appears in the system of linear equations on the left as AX = B. The number of rows in `A` must equal the number of rows in `B`.

`A` cannot be sparse. To solve a linear system involving a sparse matrix, use `mldivide` or `decomposition` instead.

Data Types: `single` | `double`
Complex Number Support: Yes

Input array, specified as a vector or matrix. `B` appears in the system of linear equations on the right as AX = B. If `B` is a matrix, then each column in the matrix represents a different vector for the right-hand side.

The number of rows in `A` must equal the number of rows in `B`.

Data Types: `single` | `double`
Complex Number Support: Yes

Coefficient matrix properties, specified as a structure. Use this structure to specify properties of `A` that `linsolve` uses to select an appropriate solver for the linear system. The fields in the structure contain `true`/`false` values to indicate whether `A` has each property. By default all fields in the structure are assumed to be `false`. This table lists the possible fields in `opts` and their corresponding matrix properties.

FieldMatrix Property

`LT`

Lower triangular (nonzero values appearing only on or below the main diagonal)

`UT`

Upper triangular (nonzero values appearing only on or above the main diagonal)

`UHESS`

Upper Hessenberg (all zero values below the first subdiagonal)

`SYM`

Real symmetric or complex Hermitian (matrix equal to its transpose)

`POSDEF`

Positive definite (all positive eigenvalues)

`RECT`

Rectangular matrix (different number of rows and columns)

`TRANSA`

Conjugate transpose — Specifies whether the function solves `A*X = B` (when `opts.TRANSA = false`) or the transposed problem `A'*X = B` (when ```opts.TRANSA = true```)

Example: `opts.UT = true` specifies that `A` is upper triangular.

Example: `opts.SYM = true, opts.POSDEF = true` sets two fields to specify that `A` is symmetric and positive definite.

#### Valid Combinations

The rows of this table list all combinations of field values in `opts` that are valid for `linsolve`. Empty cells are the default value of `false`, and a `true`/`false` entry indicates that `linsolve` accepts either value.

`LT`

`UT`

`UHESS`

`SYM`

`POSDEF`

`RECT`

`TRANSA`

`A` is lower triangular

`true`

`true`/`false`

`true`/`false`

`A` is upper triangular

`true`

`true`/`false`

`true`/`false`

`A` is upper Hessenberg

`true`

`true`/`false`

`A` is symmetric

`true`

`true`/`false`

`true`/`false`

`A` is rectangular

`true`/`false`

`true`/`false`

#### Notes on Usage

• If `A` has the properties in `opts`, then `linsolve` is faster compared to `mldivide`, because `linsolve` invokes the appropriate solver immediately and does not perform any tests to verify that `A` has the specified properties.

• If `A` does not have the properties that you specify in `opts`, then `linsolve` returns incorrect results and does not return an error message. Therefore, if you are unsure whether `A` has the specified properties, use `mldivide` or `decomposition` instead.

Data Types: `struct`

## Output Arguments

collapse all

Linear system solution, returned as a vector or matrix that satisfies AX = B (or ATX = B if `opts.TRANSA = true`). The size of `X` depends on whether `opts.TRANSA = true`:

• If `A` is `m`-by-`n` and `B` is `m`-by-`k`, then `X` is `n`-by-`k` and is the solution to AX = B.

• If `opts.TRANSA = true`, then `A` is `m`-by-`n` and `B` is `n`-by-`k`. In this case, `X` is `m`-by-`k` and is the solution to ATX = B.

Reciprocal condition number or rank, returned as a scalar.

• If `A` is a square matrix, then `r` is the reciprocal condition number of `A`.

• If `A` is a rectangular matrix, then `r` is the rank of `A`.

• If `opts` is specified, then `r` is the reciprocal of the condition number of `A` unless `RECT` is `true` and both `LT` and `UT` are `false`, in which case, `r` gives the rank of `A`.

## Tips

• The speed benefit of `linsolve` can vary depending on the matrix structure and the relative optimization of the underlying algorithms. In some cases (such as with small matrices) there might not be any speed-up compared to `mldivide`. The speed benefit with `linsolve` arises by avoiding costly checks on the properties of large matrices, or by choosing an algorithm that is better suited to the input than the choice that `mldivide` makes.