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

# `numeric`::`rank`

Numerical estimate of the rank of a matrix

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::rank(`A`, <`eps`>, `options`)
```

## Description

`numeric::rank(A)` returns an integer indicating the rank of the matrix A.

All entries of the input matrix must be numerical, i.e., they must be floating-point numbers or expressions that can be converted to floating-point numbers.

The rank of a matrix coincides with the number of non-zero singular values.

A numerical estimate of the rank is computed by counting all singular values that are larger than epssmax, where smax is the largest singular value. (All smaller singular values are regarded as round-off artifacts and treated as zero.)

## Environment Interactions

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

## Examples

### Example 1

We consider a quadratic matrix of rank 2:

```A := matrix([[1, 1, I], [1, 2, 3], [2, 4, 6]]): numeric::rank(A)```

Hilbert matrices have full rank. However, they are extremely ill-conditioned and it is difficult to compute their rank numerically. The 10×10 Hilbert matrix has rank 10. Numerically, however, some of the singular values are so small that they may be regarded as zero resulting in a smaller numerical rank. In particular, with the default value `eps` = , two singular values are smaller than epssmax where `smax` = is the maximal singular value:

```A := linalg::hilbert(10): numeric::singularvalues(A)```

`numeric::rank(A)`

We specify a second argument ```eps = 10- 14``` to allow smaller singular values to be regarded as non-zero. Now, the numerical rank is 10:

`numeric::rank(A, 10^(-14))`

`delete A:`

### Example 2

We consider a non-square matrix of rank 1:

```A := matrix([[0, 0], [I, 1], [I, 1]]): numeric::rank(A)```

`delete A:`

### Example 3

We demonstrate the difference between hardware floats and software floats:

```A := linalg::hilbert(15): numeric::rank(A, 10^(-20), SoftwareFloats), numeric::rank(A, 10^(-20), HardwareFloats)```

`delete A:`

## Parameters

 `A` An m×n matrix of domain type `DOM_ARRAY`, `DOM_HFARRAY`, or of category `Cat::Matrix` `eps` Relative tolerance: regard all singular values `s` of `A` as zero if they satisfy s ≤ eps smax, where smax is the largest singular value of `A`. The default value of `eps` is .

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

### Note

For ill-conditioned matrices, the results returned with `HardwareFloats` and `SoftwareFloats` may differ significantly! See Example 3.

## Return Values

Positive integer.