# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

# numeric::spectralradius

Spectral radius of a matrix

MuPAD® notebooks are not recommended. 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::spectralradius(`A`, <`x0`>, <`n`>, <`mode`>, <`ReturnType = t`>, <NoWarning>)
```

## Description

`numeric::spectralradius(A)` returns data corresponding to the eigenvalue of the matrix `A` that has the largest absolute value.

The spectral radius of a matrix with eigenvalues λi is max(|λi|).

The return value `lambda` is an approximation of the corresponding eigenvalue: `abs(lambda)` is the spectral radius.

The return value `x` is the corresponding normalized eigenvector: .

The return value provides an error estimate for the eigenvalue. For Hermitian matrices this is a rigorous upper bound for the error |lambda - λexact|, where λexact is the exact eigenvalue.

`numeric::spectralradius` implements the power method to compute the eigenvalue and the associated eigenvector defining the spectral radius: the vector iteration “converges” towards the eigenspace associated with the spectral radius. The starting vector x0 is provided by the second argument of `numeric::spectralradius`. If no starting vector is provided by the user, a randomly chosen vector is used.

### Note

The iteration does not converge (converges slowly), if the spectral radius is generated by several distinct eigenvalues with the same (similar) absolute value.

Internally, the iteration stops, when the approximation of the eigenvalue becomes stationary within the relative precision given by `DIGITS`. If this does not happen within n iterations, then a warning is issued and the present values are returned. Cf. Example 4.

`numeric::spectralradius` and `numeric::spectralRadius` are equivalent.

## Environment Interactions

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

## Examples

### Example 1

We let the routine choose a random starting vector:

```A := matrix(2, 2, [[10, 1], [1, 20]]): numeric::spectralradius(A)```

We define a starting vector as a 1-dimensional array and allow a maximum of 1000 internal iterations:

```A := array(1..2, 1..2, [[1, 2], [5, -10]]): x0 := array(1..2, [1, 1]): numeric::spectralradius(A, x0, 1000)```

Next, we use a list to specify a starting vector:

```A := array(1..2, 1..2, [[I, 3], [3, I]]): numeric::spectralradius(A, [1, 1], 1000)```

`delete A, x0:`

### Example 2

With the default setting of `DIGITS` = 10, the following result is computed using `HardwareFloats`.

```A := hfarray(1..2, 1..2, [[10^4, 10^4], [50, 60]]): x0 := array(1..2, [1, 1]): numeric::spectralradius(A, x0)```

We request `SoftwareFloats` in the next call. Note the difference in the trailing digits:

`numeric::spectralradius(A, x0, Soft)`

`delete DIGITS, A, x0:`

### Example 3

The eigenvector that is returned can have various types. If no starting vector is provided, the type of the matrix determines the type of the eigenvector:

```A:= array(1..2, 1..2, [[1, 2], [3, 4]]): [l, x, residue]:= numeric::spectralradius(A);```

`domtype(x)`

```A:= hfarray(1..2, 1..2, [[1, 2], [3, 4]]): [l, x, residue]:= numeric::spectralradius(A): domtype(x)```

```A:= matrix(2, 2, [[1, 2], [3, 4]]): [l, x, residue]:= numeric::spectralradius(A): domtype(x)```

If a starting vector is provided, its type determines the type of the return vector:

```A:= hfarray(1..2, 1..2, [[1, 2], [3, 4]]): x0:= [1, 1]: [l, x, residue]:= numeric::spectralradius(A, x0): domtype(x)```

```x0:= array(1..2, [1, 1]): [l, x, residue]:= numeric::spectralradius(A, x0): domtype(x)```

```x0:= hfarray(1..2, [1, 1]): [l, x, residue]:= numeric::spectralradius(A, x0): domtype(x)```

```x0:= matrix([1, 1]): [l, x, residue]:= numeric::spectralradius(A, x0): domtype(x)```

The return type can be requested explicitly:

```[l, x, residue] := numeric::spectralradius(A, x0, ReturnType = DOM_LIST): domtype(x)```

```[l, x, residue] := numeric::spectralradius(A, x0, ReturnType = DOM_HFARRAY): domtype(x)```

`delete A, x0, l, x, residue:`

### Example 4

The following matrix has two distinct eigenvalues 1 and -1 of the same absolute value. The power method must fail.

`A := array(1..2, 1..2, [[1, 0], [0, -1]]):`

We allow a maximum of 1000 internal steps. The call results in a warning. The large residue also indicates that the power method did not converge:

`numeric::spectralradius(A, [1, 1], 1000)`
```Warning: No convergence of vector iteration. [numeric::spectralradius] ```

`delete A:`

## Parameters

 `A` An m×m array of domain type `DOM_ARRAY` or `DOM_HFARRAY` or a matrix of category `Cat::Matrix` `x0` A starting vector: a 1-dimensional array, or an hfarray, or a list of length m. Also 2-dimensional arrays (`array(1..m, 1..1, ...)`, ```hfarray(1..m, 1..1, ...)```) and matrices representing vectors are accepted. `n` The maximal number of iterations: a positive integer. The default value is 1000. `mode` One of the flags `Hard`, `HardwareFloats`, `Soft`, or `SoftwareFloats`

## Options

 `Hard`, `HardwareFloats`, `Soft`, `SoftwareFloats` With `Hard` (or `HardwareFloats`), computations are done using fast hardware float arithmetic from within a MuPAD® session. `Hard` and `HardwareFloats` are equivalent. With this option, the input data are converted to hardware floats and processed by compiled C code. The result is reconverted to MuPAD floats and returned to the MuPAD session. With `Soft` (or `SoftwareFloats`) computations are dome using software float arithmetic provided by the MuPAD kernel. `Soft` and `SoftwareFloats` are equivalent. `SoftwareFloats` is used by default if the current value of `DIGITS` is larger than 15 and the input matrix `A` is not of domain type `DOM_HFARRAY`. Compared to the `SoftwareFloats` used by the MuPAD kernel, the computation with `HardwareFloats` may be many times faster. Note, however, that the precision of hardware arithmetic is limited to about 15 digits. Further, the size of floating-point numbers may not be larger than approximately 10308 and not smaller than approximately 10- 308. If no `HardwareFloats` or `SoftwareFloats` are requested explicitly, the following strategy is used: If the current value of `DIGITS` is smaller than 16 or if the matrix `A` is a hardware float array of domain type `DOM_HFARRAY`, then hardware arithmetic is tried. If this is successful, the result is returned. If the result cannot be computed with hardware floats, software arithmetic by the MuPAD kernel is tried. If the current value of `DIGITS` is larger than 15 and the input matrix `A` is not of domain type `DOM_HFARRAY`, or if one of the options `Soft`, `SoftwareFloats` or `Symbolic` is specified, MuPAD computes the result with its software arithmetic without trying to use hardware floats first. There may be several reasons for hardware arithmetic to fail: The current value of `DIGITS` is larger than 15.The data contains symbolic objects.The data contains numbers larger than 10308 or smaller than 10- 308 that cannot be represented by hardware floats. If neither `HardwareFloats` nor `SoftwareFloats` is specified, the user is not informed whether hardware floats or software floats are used. If `HardwareFloats` are specified but fail due to one of the reasons above, a warning is issued that the (much slower) software floating-point arithmetic of the MuPAD kernel is used. Note that `HardwareFloats` can only be used if all input data can be converted to floating-point numbers. The trailing digits in floating-point results computed with `HardwareFloats` and `SoftwareFloats` may differ. `ReturnType` Option, specified as `ReturnType = t` Return the eigenvector associated with the spectral radius as a vector of domain type `t`. The following return types are available: `DOM_ARRAY`, or `DOM_HFARRAY`, or `DOM_LIST`, or `Dom::Matrix()`, or `Dom::DenseMatrix()`. `NoWarning` Suppresses warnings

## Return Values

A list `[lambda, x, residue]` is returned. The floating-point number `lambda` is an approximation of the eigenvalue of largest absolute value. The vector `x` is a numerical eigenvector corresponding to `lambda`. `residue` is a floating-point number indicating the numerical quality of `lambda` and `x`.

If no return type is requested via the `ReturnType` option, the type of the returned vector `x` coincides with the type of the input vector x0 (i.e., it is a 1-dimensional array of type `DOM_ARRAY` or `DOM_HFARRAY`, respectively, or a list, or a column vector of type `matrix` or `densematrix`. If no starting vector is specified, the type of `x` is determined by the type of `A`.

Was this topic helpful?

Watch now