matpow {matpow}

Matrix Powers

Description

Computes matrix powers, with optional application-specific callbacks. Accommodates (external) parallel multiplication mechanisms.

Usage

  matpow(m,k=NULL,squaring=FALSE,genmulcmd=NULL,dup=NULL,callback=NULL,...)

Arguments

m

input matrix.

k

desired power. If NULL, it is expected that the initialization portion of the user's callback function will set k.

squaring

if TRUE, saves time by first squaring m, then squaring the result and so on, until a power is reached of k or more.

genmulcmd

function to generate multiplication commands, in quoted string form. For the ordinary R "matrix" class this is function(a,b,c) paste(c," <- ",a," %*% ",b), supplied as genmulcmd.vanilla with the package.

dup

function to make a deep copy of a matrix.

callback

application-specific callback function.

...

application-specific arguments

Details

Multiplication is iterated until the desired power k is reached, with these exceptions: (a) If squaring is TRUE, k may be exceeded. (b) The callback function can set stop in ev, halting iterations; this is useful, for instance, if some convergence criterion has been reached.

One key advantage of using matpow rather than direct iteration is that parallel computation can be accommodated, by specifying genmulcmd. (The word "accommodated" here means the user must have available a mechanism for parallel computation; matpow itself contains no parallel code.)

For instance, if one is using GPU with gputools, one sets genmulcmd to genmulcmd.gputools, which calls gpuMatMult() instead of the usual %*%. So, one can switch from serial to parallel by merely changing this one argument. If genmulcmd is not specified, the code attempts to sense the proper function by inspecting class(m), in the cases of classes "matrix" and "big.matrix".

Of course, if the user's R is configured to use a parallel BLAS, such as OpenBLAS, this is automatically handled via the ordinary R "matrix" class.

Another important advantage of matpow is the ability to write a callback function, which enables much flexibility. The callback, if present, is called by matpow after each iteration, allowing application-specific operations to be applied. For instance, cgraph determines the connectivity of a graph, by checking whether the current power has all of its entries nonzero.

The call form is callbackname(ev,init,...) where ev is the R environment described above, and init must be set to TRUE on the first call, and FALSE afterward.

Since some types of matrix multiplication do not allow the product to be in the same physical location as either multiplicand, a "red and black" approach is taken to the iteration process: Storage space for powers in ev alternatives between prod1 and prod2, for odd-numbered and even-numbered iterations, respectively.

Value

An R environment ev, including the following components:

prod1

matrix, the final power.

stop

boolean value, indicating whether the iterations were stopped before the final power was to be computed.

i

number of the last iteration performed.

Application-specific data, maintained by the callback function, can be stored here as well.

Examples

## Not run: 
m <- rbind(1:2,3:4)
ev <- matpow(m,16)
ev$prod1
# prints
#              [,1]        [,2]
# [1,] 115007491351 1.67615e+11
# [2,] 251422553235 3.66430e+11

ev$i  # prints 15
matpow(m,16,squaring=TRUE)$i  # prints 4, same prod1

## End(Not run)

# see further examples in the callbacks