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.

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:

Parameters

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.

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
typet. 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.