balance: Balance a Square Matrix via LAPACK's DGEBAL

In expm: Matrix Exponential, Log, 'etc'

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, and “dgebal()” has been deprecated (finally, after 9 years ...).

Usage

balance(A, job = c("B", "N", "P", "S"))
## Deprecated now:
##   dgebal(A, job = c("B", "N", "P", "S"))

Arguments

A	a square (n\times n) numeric, logical or complex matrix.
job	a one-letter string specifying the ‘job’ for DGEBAL / ZGEBAL. P Permutation S Scaling B Both permutation and scaling N None

Details

An excerpt of the LAPACK documentation about DGEBAL() or ZGEBAL(), respectively, 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,\dots,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, https://netlib.org/lapack/, balancing ‘gebal’, currently at https://www.netlib.org/lapack/explore-html/df/df3/group__gebal.html.

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 : ----
if(expm:::doExtras()) withAutoprint({
    sessionInfo()
    packageDescription("Matrix")
    "expm installed at"
    dirname(attr(packageDescription("expm"), "file"))
})

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

expm documentation built on Sept. 11, 2024, 8:58 p.m.