R: Balance a Square Matrix via LAPACK's DGEBAL

balance {expm} | R Documentation

## Balance a Square Matrix via LAPACK's DGEBAL

### Description

Balance a square matrix via LAPACK's `DGEBAL`. This is an R interface, mainly used for experimentation.

This LAPACK routine is used internally for Eigenvalue decompositions, but also, in Ward(1977)'s algorithm for the matrix exponential.

The name `balance()` is preferred nowadays, where “dgebal” will probably become deprecated.

### Usage

    balance(A, job = c("B", "N", "P", "S"))
     dgebal(A, job = c("B", "N", "P", "S"))

### Arguments

`A` | a square (n x n) numeric matrix.
`job` | a one-letter string specifying the ‘job’ for DGEBAL. P Permutation S Scaling B Both permutation and scaling N None

### Details

An excerpt of the LAPACK documentation about DGEBAL(), describing the result

i1 ("ILO")

  (output) integer

i2 ("IHI")

  (output) integer
  `i1` and `i2` are set to integers such that on exit `z[i,j] = 0` if i > j and j = 1,...,i1-1 or i = i2+1,...,n.

  If `job = 'N'` or `'S'`, `i1 = 1` and `i2 = n`.

scale

  (output) numeric vector of length `n`. Details of the permutations and scaling factors applied to `A`. If `P[j]` is the index of the row and column interchanged with row and column `j` and `D[j]` is the scaling factor applied to row and column j, then `scale[j] = P[j]` for j = 1,...,i1-1
  `= D[j]` for j = i1,...,i2,
  `= P[j]` for j = i2+1,...,n.

  The order in which the interchanges are made is `n` to `i2+1`, then `1` to `i1-1`.

Look at the LAPACK documentation for more details.

### Value

A list with components

`z` | the transformation of matrix `A`, after permutation and or scaling.
`scale` | numeric vector of length n, containing the permutation and/or scale vectors applied.
`i1,i2` | integers (length 1) in \{1,2,…,n\}, denoted by `ILO` and `IHI` respectively in the LAPACK documentation. Only relevant for `"P"` or `"B"`, they describe where permutations and where scaling took place; see the Details section.

### Author(s)

Martin Maechler

### References

LAPACK Reference Manual

### See Also

`eigen`, `expm`.

### Examples

    m4 <- rbind(c(-1,-1, 0, 0),
                c( 0, 0,10,10),
                c( 0, 0,10, 0),
                c( 0,10, 0, 0))
    (b4 <- balance(m4))

    ## --- for testing and didactical reasons : ----

    demo(balanceTst) # also defines the balanceTst() function
                    # which in its tests ``defines'' what
                    # the return value means, notably (i1,i2,scale)

[Package expm version 0.999-2 Index]