matpow {matpow} | R Documentation |
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
|
squaring |
if TRUE, saves time by first squaring |
genmulcmd |
function to generate multiplication commands, in
quoted string form. For the ordinary R |
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