## `numeric::inverse` -- the inverse of a matrix

#### Introduction

`numeric::inverse``(A, ..)` returns the inverse of the matrix `A`.

#### Call(s)

`numeric::inverse(A <, Symbolic>)`

#### Parameters

`A` | - | a square matrix of domain type `DOM_ARRAY` or of category `Cat::Matrix`

#### Options

`Symbolic` | - | prevents conversion of input data to floats

#### Returns

a matrix of domain type `DOM_ARRAY`. `FAIL` is returned, if the inverse cannot be computed.

#### Side Effects

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

#### Related Functions

`linsolve`, `linalg::matlinsolve`, `numeric::linsolve`, `numeric::matlinsolve`, `solve`

#### Details

- Option Symbolic should be used, if the matrix contains symbolic objects that cannot be converted to floating point numbers.
- Without the option Symbolic all entries of `A` must be numerical. Floating point arithmetic is used, the working precision is set by the environment variable `DIGITS`. etc. are accepted and converted to floats. If symbolic entries are found in the matrix, then `numeric::inverse` automatically switches to Symbolic, issuing a warning.

- Invertibility of the matrix can only be detected with exact arithmetic, i.e., using Symbolic. Cf. example 2.

- Matrices `A` of a matrix domain such as `Dom::Matrix``(..)` or `Dom::SquareMatrix``(..)` are internally converted to arrays over expressions via `A::dom::expr(A)`. Note that `1/A` must be used, when the inverse is to be computed over the component domain. Cf. example 3. Note that Symbolic should be used, if the entries cannot converted to numerical expressions.

- We recommend to use `numeric::linsolve`, if a system of linear equations is to be solved. In particular, this routine is more efficient than `numeric::inverse` for large sparse systems. It uses sparse input and output via symbolic equations and features internal sparse arithmetic.

#### Option: Symbolic

- This option prevents conversion of the input data to floats. With this option symbolic entries are accepted.

- This option should not be used for floating point matrices! No internal pivoting is used, unless necessary. Consequently, numerical instabilities may occur in floating point operations. Cf. example 4.

#### Example 1

Numerical matrices can be processed with or without the option Symbolic:

    >> A := array(1..2, 1..2, [[1, 2], [3, PI]]):

    >> numeric::inverse(A), numeric::inverse(A, Symbolic)

                                               +-                    -+
                                               |     PI         2     |
            +-                             -+  |   ------,  - ------  |
            |  -1.099071012,  0.6996903372  |  |   PI - 6     PI - 6  |
            |                               |, |                      |
            |   1.049535506, -0.3498451686  |  |      3        1      |
            +-                             -+  |  - ------,  ------   |
                                               |    PI - 6   PI - 6   |
                                               +-                    -+

Matrices of category `Cat::Matrix` are accepted. Note, however, that the inverse is returned as an array:

    >> A := Dom::Matrix()([[2, PI], [0, 1]]):

    >> numeric::inverse(A); domtype(%)

                              +-                   -+
                              |  0.5, -1.570796327  |
                              |                     |
                              |   0,       1.0      |
                              +-                   -+

                                     DOM_ARRAY

    >> delete A:

#### Example 2

The following matrix is not invertible:

    >> A := array(1..2, 1..2, [[PI, PI^2], [PI^2, PI^3]]):

With exact arithmetic `numeric::inverse` detects this fact:

    >> numeric::det(A, Symbolic), numeric::inverse(A, Symbolic)

                                      0, FAIL

Due to internal round-off the matrix is regarded as invertible, if float arithmetic is used:

    >> numeric::det(A), numeric::inverse(A)

                               +-                                  -+
                               |   1.896479859e18, -6.036682882e17  |
              1.796747287e-17, |                                    |
                               |  -6.036682882e17,  1.921535841e17  |
                               +-                                  -+

    >> delete A:

#### Example 3

The following matrix has domain components:

    >> A := Dom::Matrix(Dom::IntegerMod(7))([[6, -1], [1, 6]])

                              +-                  -+
                              |  6 mod 7, 6 mod 7  |
                              |                    |
                              |  1 mod 7, 6 mod 7  |
                              +-                  -+

Note that `numeric::inverse` computes the inverse of the following matrix:

    >> A::dom::expr(A), numeric::inverse(A)

                      +-      -+  +-                      -+
                      |  6, 6  |  |        0.2,      -0.2  |
                      |        |, |                        |
                      |  1, 6  |  |  -0.03333333333,  0.2  |
                      +-      -+  +-                      -+

The overloaded arithmetic should be used, if the inverse is to be computed over the component domain `Dom::IntegerMod``(7)`:

    >> 1/A

                              +-                  -+
                              |  3 mod 7, 4 mod 7  |
                              |                    |
                              |  3 mod 7, 3 mod 7  |
                              +-                  -+

    >> delete A:

#### Example 4

The option Symbolic should not be used for float matrices, because no internal pivoting is used to stabilize the numerical algorithm:

    >> A := array(1..2, 1..2, [[1.0/10^20, 1.0], [1.0, 1.0]]):

    >> bad = numeric::inverse(A, Symbolic),
       good = numeric::inverse(A)

                   +-                -+         +-                 -+
                   |  0.0,    1.0     |         |  -1.0,    1.0     |
             bad = |                  |, good = |                   |
                   |  1.0, -10.0e-21  |         |   1.0, -10.0e-21  |
                   +-                -+         +-                 -+

    >> delete A, bad, good:

#### Background

- Gaussian elimination with partial pivoting is used. Partial pivoting is switched off by the option Symbolic.

#### Changes

- Conversion of `Cat::Matrix` objects now uses the method `"expr"` of the matrix domain.
- The return type was changed to `DOM_ARRAY`.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000