# linsolve

Solve a system of linear equations

### Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

## Syntax

```linsolve(`eqs`, `options`)
linsolve(`eqs`, `vars`, `options`)
```

## Description

`linsolve(eqs, vars)` solves a system of linear equations with respect to the unknowns `vars`.

`linsolve(eqs, < vars , < ShowAssumptions >>)` solves the linear system `eqs` with respect to the unknowns `vars`. If no unknowns are specified, then `linsolve` solves for all indeterminates in `eqs`; the unknowns are determined internally by `indets(eqs,PolyExpr)`.

`linsolve(eqs, vars, Domain = R)` solves the system over the domain `R`, which must be a field, i.e., a domain of category `Cat::Field`.

 Note:   Note that the return format does not allow to return kernel elements if elements of the domain `R` cannot be multiplied with the symbolic unknowns that span the kernel. In such a case, `linsolve` issues a warning and returns only a special solution. The kernel can be computed via `linalg::matlinsolve` for any field `R`.

Each element of `eqs` must be either an equation or an arithmetical expression `f`, which is considered to be equivalent to the equation `f = 0`.

The unknowns in `vars` need not be identifiers or indexed identifiers; expressions such as `sin(x)`, `f(x)`, or `y^(1/3)` are allowed as well. More generally, any expression accepted as indeterminate by `poly` is a valid unknown.

If the option `ShowAssumptions` is not given and the system is solvable, then the return value is a list of equations of the form `var = value`, where `var` is one of the unknowns in `vars` and `value` is an arithmetical expression that does not involve any of the unknowns on the left side of a returned equation. Note that if the solution manifold has dimension greater than zero, then some of the unknowns in `vars` will occur on the right side of some returned equations, representing the degrees of freedom. See Example 2.

If `vars` is a list, then the solved equations are returned in the the same order as the unknowns in `vars`.

The function `linsolve` can only solve systems of linear equations. Use `solve` for nonlinear equations.

`linsolve` is an interface function to the procedures `numeric::linsolve` and `linalg::matlinsolve`. For more details see the `numeric::linsolve`, `linalg::matlinsolve` help pages and the background section of this help page.

The system `eqs` is checked for linearity. Since such a test can be expensive, it is recommended to use `numeric::linsolve` or `linalg::matlinsolve` directly when you know that the system is linear.

 Note:   `linsolve` does not react to properties of identifiers set by `assume`.

## Examples

### Example 1

Equations and variables may be entered as sets or lists:

```linsolve({x + y = 1, 2*x + y = 3}, {x, y}), linsolve({x + y = 1, 2*x + y = 3}, [x, y]), linsolve([x + y = 1, 2*x + y = 3], {x, y}), linsolve([x + y = 1, 2*x + y = 3], [x, y])```

Also expressions may be used as variables:

```linsolve({cos(x) + sin(x) = 1, cos(x) - sin(x) = 0}, {cos(x), sin(x)})```

Furthermore, indexed identifiers are valid, too:

```linsolve({2*a[1] + 3*a[2] = 5, 7*a[2] + 11*a[3] = 13, 17*a[3] + 19*a[1] = 23}, {a[1], a[2], a[3]})```

Next, we demonstrate the use of option `Domain` and solve a system over the field 23 with it:

```linsolve([2*x + y = 1, -x - y = 0], Domain = Dom::IntegerMod(23))```

The following system does not have a solution:

`linsolve({x + y = 1, 2*x + 2*y = 3}, {x, y})`

### Example 2

If the solution of the linear system is not unique, then some of the unknowns are used as "free parameters" spanning the solution space. In the following example the unknown `z` is such a parameter. It does not appear on the left side of the solved equations:

`eqs := [x + y = z, x + 2*y = 0, 2*x - z = -3*y, y + z = 0]:`
`vars := [w, x, y, z]:`
`linsolve(eqs, vars)`

### Example 3

If you use the `Normal` option, `linsolve` calls the `normal` function for final results. This call ensures that `linsolve` returns results in normalized form:

`linsolve([x + a*y = a + 1, b*x - y = b - 1], {x, y})`

If you specify `Normal = FALSE`, `linsolve` does not call `normal` for the final result:

`linsolve([x + a*y = a + 1, b*x - y = b - 1], {x, y}, Normal = FALSE)`

### Example 4

Solve this system:

`eqs := [x + a*y = b, x + A*y = b]:`
`linsolve(eqs, [x, y])`

Note that more solutions exist for `a = A`. `linsolve` omits these solutions because it makes some additional assumptions on symbolic parameters of this system. To see the assumptions that `linsolve` made while solving this system, use the `ShowAssumptions` option:

`linsolve(eqs, [x, y], ShowAssumptions)`

`delete eqs:`

## Parameters

 `eqs` A list or a set of linear equations or arithmetical expressions `vars` A list or a set of unknowns to solve for: typically identifiers or indexed identifiers

## Options

 `Domain` Option, specified as `Domain = R` Solve the system over the field `R`, which must be a domain of category `Cat::Field`. `Normal` Option, specified as `Normal = b` Return normalized results. The value `b` must be `TRUE` or `FALSE`. By default, `Normal = TRUE`, meaning that `linsolve` guarantees normalization of the returned results. Normalizing results can be computationally expensive. By default, `linsolve` calls `normal` before returning results. This option affects the output only if the solution contains variables or exact expressions, such as `sqrt(5)` or `sin(PI/7)`. To avoid this additional call, specify `Normal = FALSE`. In this case, `linsolve` also can return normalized results, but does not guarantee such normalization. See Example 3. `ShowAssumptions` Return information about internal assumptions that `linsolve` made on symbolic parameters in `eqs`. With this option, `linsolve` returns a list ```[Solution, Constraints, Pivots]```. `Solution` is a list of solved equations representing the complete solution manifold of `eqs`, as described above. The lists `Constraints` and `Pivots` contain equations and inequalities involving symbolic parameters in `eqs`. Internally, these were assumed to hold true when solving the system. See Example 4. When Gaussian elimination produces an equation ```0 = c``` with nonzero `c`, `linsolve` without `ShowAssumptions` returns `FAIL`. If `c` involves symbolic parameters, try using `linsolve` with `ShowAssumptions` to solve such systems. If the system is solvable, you will get the solution. In this case, an equation `0 = c` is returned in the `Constraints` list. If the system is not solvable, `linsolve` with `ShowAssumptions` returns ```[FAIL, [], []]```.

## Return Values

Without the `ShowAssumptions` option, a list of simplified equations is returned. It represents the general solution of the system `eqs`. `FAIL` is returned if the system is not solvable.

With `ShowAssumptions`, a list ```[Solution, Constraints, Pivots]``` is returned. `Solution` is a list of simplified equations representing the general solution of `eqs`. The lists `Constraints` and `Pivots` contain equations and inequalities involving symbolic parameters in `eqs`. Internally, these were assumed to hold true when solving the system.

## Algorithms

If the option `Domain` is not present, the system is solved by calling `numeric::linsolve` with the option `Symbolic`.

If the option `Domain = R` is given and `R` is either `Dom::ExpressionField``()` or `Dom::Float`, then `numeric::linsolve` is used to compute the solution of the system. This function uses a sparse representation of the equations.

Otherwise, `eqs` is first converted into a matrix and then solved by `linalg::matlinsolve`. A possibly sparse structure of the input system is not taken into account.