Documentation

# `numeric`::`fsolve`

Search for a numerical root of a system of equations

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

## Syntax

```numeric::fsolve(`eq`, `x`, `options`)
numeric::fsolve(`eq`, `x = a`, `options`)
numeric::fsolve(`eq`, `x = a .. b`, `options`)
numeric::fsolve(`eqs`, `[x1, x2, …]`, `options`)
numeric::fsolve(`eqs`, `{x1, x2, …}`, `options`)
numeric::fsolve(`eqs`, `[x1 = a1, x2 = a2, …]`, `options`)
numeric::fsolve(`eqs`, `{x1 = a1, x2 = a2, …}`, `options`)
numeric::fsolve(`eqs`, `[x1 = a1 .. b1, x2 = a2 .. b2, …]`, `options`)
numeric::fsolve(`eqs`, `{x1 = a1 .. b1, x2 = a2 .. b2, …}`, `options`)
```

## Description

`numeric::fsolve(eqs, ...)` returns a numerical approximation of a solution of the system of equations `eqs`.

This is the MuPAD® numerical solver for non-linear systems of equations.

### Note

By default, this routine returns only one numerical solution!

The equations must not contain symbolic objects other than the unknowns that cannot be converted to numerical values via `float`. Symbolic objects such as π or etc. are accepted. The same holds true for starting values and search ranges. Search ranges may contain . Cf. Example 2.

`numeric::fsolve` implements a purely numerical Newton type root search with a working precision set by the environment variable `DIGITS`. Well separated simple roots should be exact within this precision. However, multiple roots or badly separated roots may be computed with a restricted precision. Cf. Example 3.

### Note

For systems of equations, the expressions defining the equations must have a symbolic derivative!

Overdetermined systems (i.e., more equations than indeterminates) are not accepted. However, there may be more indeterminates than equations. Cf. Example 4.

Specifying indeterminates ```[x1, x2, …]``` without starting values or search ranges is equivalent to the search ranges ```[x_1 = -infinity .. infinity, x_2 = -infinity .. infinity, dots]```. Note, however, that the user should assist `numeric::fsolve` by providing specific search ranges whenever possible! If a complex starting point or a search range involving a complex number is specified for at least one of the unknowns, the search is extended to the entire complex plane for all variables for which no explicit search interval is given.

For real equations and real starting points or search ranges, the internal Newton iteration will usually produce real values, i.e., `numeric::fsolve` searches for real roots only (unless square roots, logarithms etc. happen to produce complex values from real input). Use complex starting points or search ranges to search for complex roots of real equations. Cf. Example 5.

Starting values and search ranges can be mixed. Cf. Example 6.

Search ranges should only be provided if a solution is known to exist inside the search range. Otherwise, the search may take some time before `numeric::fsolve` gives up.

Specification of a search range primarily means that starting points from this range are used for the internal Newton search. For sufficiently small search ranges enclosing a solution the search will usually pick out this solution. However, it may also happen that the Newton iteration drifts towards other solutions.

With the default search strategy `RestrictedSearch`, only solutions from the search range are accepted, even if solutions outside the search range are found internally. More specifically, if a search range such as `x = a .. b` is specified for the variable `x`, then solutions satisfying ```min(ℜ(a), ℜ(b)) ≤ ℜ(x) ≤ max(ℜ(a), ℜ(b))``` and ```min(ℑ(a), ℑ(b)) ≤ ℑ(x) ≤ max(ℑ(a), ℑ(b))``` are searched for. Thus, the values `a, b` specify the bottom left and top right corner of a rectangular search area in the complex plane when the `RestrictedSearch` strategy is used.

With the search strategy `UnrestrictedSearch`, any solution inside or outside the search range is accepted and returned. Cf. Example 7.

If starting values for all indeterminates are provided, then a single Newton iteration with these initial data is launched. It either leads to a solution or `numeric::fsolve` gives up and returns `FAIL`. The same holds true if search ranges `x = a .. a` or ```[x_1 = a_1 .. a_1, x_2 = a_2 .. a_2, dots]``` of zero length are specified.

### Note

The risk of failure is high when providing bad starting values! Starting values are appropriate only if a sufficiently good approximation of the solution is known! On the other hand, providing good starting values is the fastest way to a solution. Cf. Example 8.

If at least one of the indeterminates has a non-trivial search range, then `numeric::fsolve` uses several Newton iterations with different starting values from the search range. Cf. Example 9. Search ranges in conjunction with the option `UnrestrictedSearch` provide a higher chance of detecting roots than (bad) starting values!

### Note

User defined assumptions such as `assume(x > 0)` are not taken into account in the numerical search! Provide search ranges instead! Cf. Example 2.

### Note

Convergence may be slow for multiple roots! Furthermore, `numeric::fsolve` may fail to detect such roots!

Use `linsolve` or `numeric::linsolve` for systems of linear equations.

Use `numeric::realroots`, if all real roots of a single non-polynomial real equation in a finite range are desired.

Use `polylib::realroots`, if all real roots of a real univariate polynomial are desired.

Use `numeric::polyroots`, if all real and complex roots of a univariate polynomial are desired.

Use `numeric::solve`, if all roots of a multivariate polynomial system are desired.

The routine `numeric::solve` provides a common interface to all these numerical solvers.

## Environment Interactions

The function is sensitive to the environment variable `DIGITS`, which determines the numerical working precision.

## Examples

### Example 1

We compute roots of the sine function:

`numeric::fsolve(sin(x) = 0, x)`

With the option `Random`, several calls may result in different roots:

`numeric::fsolve(sin(x), x, Random)`

`numeric::fsolve(sin(x), x, Random)`

Particular solutions can be chosen by an appropriate starting point close to the wanted solution, or by a search interval:

```numeric::fsolve(sin(x), x = 3), numeric::fsolve(sin(x), x = -4 .. -3)```

The solutions found by `numeric::fsolve` can be used in `subs` and `assign` to substitute or assign the indeterminates:

```eqs := [x^2 = sin(y), y^2 = cos(x)]: solution := numeric::fsolve(eqs, [x, y])```

`eval(subs(eqs, solution))`

`assign(solution): x, y`

`delete eqs, solution, x, y:`

### Example 2

We demonstrate the use of search ranges. The following system has solutions with positive and negative x. The solution with x ≥ 0 is obtained with the search interval ```x = 0 .. infinity```:

`numeric::fsolve([x^2 = exp(x*y), x^2 = y^2], [x = 0 .. infinity, y])`

We search for a solution with x ≤ 0:

`numeric::fsolve([x^2 = exp(x*y), x^2 = y^2], [x = -infinity .. 0, y])`

### Example 3

Multiple roots can only be computed with a restricted precision:

`numeric::fsolve(expand((x - 1/3)^5), x = 0.3)`

### Example 4

The following system of equations is degenerate and has a 1-parameter family of solutions. Each call to `numeric::fsolve` picks out one random solution:

`numeric::fsolve([x^2 - y^2, x^2 - y^2], [x, y], Random) \$ i = 1 .. 3`

The equation may also be specified as an underdetermined system:

`numeric::fsolve([x^2 - y^2], [x, y])`

### Example 5

The following equation has no real solution. Consequently, the numerical search with real starting values fails:

`numeric::fsolve(sin(x) + cos(x)^2 = 3, x)`

With a complex starting value, a solution is found:

`numeric::fsolve(sin(x) + cos(x)^2 = 3, x = I)`

Also complex search ranges may be specified. In the following, the internal starting point is a random value on the line from ```2 + I``` to `3 + 2*I`. Solutions are accepted if they lie in the complex rectangle with the bottom left corner ```2 + I``` and the top right corner `3 + 2*I`:

`numeric::fsolve(sin(x) + cos(x)^2 = 3, x = 2 + I .. 3 + 2*I)`

### Example 6

Starting values and search intervals can be mixed:

```numeric::fsolve([x^2 + y^2 = 1, y^2 + z^2 = 1, x^2 + z^2 = 1], [x = 1, y = 0 .. 10, z])```

### Example 7

With `UnrestrictedSearch`, search intervals are only used for choosing starting values for the internal Newton search. The numerical iteration may drift towards a solution outside the search range:

```eqs := [x*sin(10*x) = y^3, y^2 = exp(-2*x/3)]: numeric::fsolve(eqs, [x = 0 .. 1, y = -1 .. 0], UnrestrictedSearch)```

With the default strategy `RestrictedSearch`, only solutions inside the search range are accepted:

`numeric::fsolve(eqs, [x = 0 .. 1, y = -1 .. 0])`

In the last search, also the previous solution outside the search range was found. With the option `MultiSolutions`, `numeric::fsolve` returns a sequence of all solutions that were found in the internal search:

`numeric::fsolve(eqs, [x = 0 .. 1, y = -1 .. 0], MultiSolutions)`

`delete eqs:`

### Example 8

Usually, most of the time is spent internally searching for some (crude) approximations of the root. If high precision roots are required, it is recommended to compute first approximations with moderate values of `DIGITS` and use them as starting values for a refined search:

```eq := exp(-x) = x: DIGITS := 10: firstApprox := numeric::fsolve(eq, x)```

This output is suitable as input defining a starting value for x:

`DIGITS := 1000: numeric::fsolve(eq, firstApprox)`

`delete eq, firstApprox, DIGITS:`

### Example 9

Specifying starting values for the indeterminates launches a single Newton iteration. This may fail, if the starting values are not sufficiently close to the solution:

```eq := [x*y = x + y - 4, x/y = x - y + 4]: numeric::fsolve(eq, [x = 1, y = 1])```

If a search range is specified for at least one of the unknowns, then several Newton iterations with random starting values in the search range are used, until a solution is found or until `numeric::fsolve` gives up:

`numeric::fsolve(eq, [x = 1, y = 0 .. 10])`

`delete eq:`

## Parameters

 `eq` An arithmetical expression or an equation in one indeterminate `x`. An expression `eq` is interpreted as the equation ```eq = 0```. `eqs` A list, set, `array`, or `matrix` (`Cat::Matrix`) of expressions or equations in several indeterminates `x1`, `x2`, ... Expressions are interpreted as homogeneous equations. `x`, `x1, x2, …` Identifiers or indexed identifiers to be solved for. `a`, `a1, a2, …` Real or complex numerical starting values for the internal search. Typically, crude approximations of solution. `a .. b`, ```a1 .. b1, a2 .. b2, …``` Ranges of numerical values defining search intervals for the numerical root.

## Options

 `RestrictedSearch` Makes `numeric::fsolve` return only numerical roots in the user-defined search range `x = a .. b` and ```[x_1 = a_1 .. b_1, x_2 = a_2 .. b_2, Symbol::hellip]```, respectively. This is the default search strategy, if a search range is specified for at least one of the unknowns. Once a root with components (r1, r2, …) is found, it is checked whether min(ℜ(ai), ℜ(bi)) ≤ ℜ(ri) ≤ max(ℜ(ai), ℜ(bi)) and min(ℑ(ai), ℑ(bi)) ≤ ℑ(ri) ≤ max(ℑ(ai), ℑ(bi)) is satisfied. If the root is not inside the search range, the search is continued. Note that solutions outside the search range may be found internally. These may be accessed with the option `MultiSolutions`. See Example 7. `UnrestrictedSearch` Allows `numeric::fsolve` to find and return solutions outside the specified search range. With this option, the search range is only used to choose random starting points for the internal numerical search. This option switches off the search strategy `RestrictedSearch`. With `UnrestrictedSearch`, `numeric::fsolve` stops its internal search whenever a root is found, even if the root is not inside the specified search range. Starting points for the internal Newton search are taken from the search range. `MultiSolutions` Makes `numeric::fsolve` return all solutions found in the internal search This option only has an effect when used with the default search strategy `RestrictedSearch`. A sequence of all roots found in the internal search is returned. Cf. Example 7. `Random` With this option, several calls to `numeric::fsolve` with the same input parameters may produce different roots. With this option, random starting values are chosen for the internal search. Consequently, calling `numeric::fsolve` several times with the same parameters may lead to different solutions. This may be useful when several roots of one and the same equation or set of equations are desired.

## Return Values

Single numerical root is returned as a list of equations ```[x = value]``` or ```[x1 = value1, x2 = value2, …]```, respectively. `FAIL` is returned if no solution is found. With the option `MultiSolutions`, sequences of solutions may be returned.

## Algorithms

Internally the set of equations f(x) = 0 is solved by a modified Newton iteration with some adaptively chosen step size t. For degenerate or ill-conditioned Jacobians a minimization strategy for is implemented. For scalar real equations, `numeric::realroot` is used, if a real finite search range is specified.

#### Mathematical Modeling with Symbolic Math Toolbox

Get examples and videos