AFNI program: 1dmatcalc

Usage: 1dmatcalc [-verb] expression

Evaluate a space delimited RPN matrix-valued expression:

 * The operations are on a stack, each element of which is a
     real-valued matrix.
   * N.B.: This is a computer-science stack of separate matrices.
           If you want to join two matrices in separate files
           into one 'stacked' matrix, then you must use program
           1dcat to join them as columns, or the system program
           cat to join them as rows.
 * You can also save matrices by name in an internal buffer
     using the '=NAME' operation and then retrieve them later
     using just the same NAME.
 * You can read and write matrices from files stored in ASCII
     columns (.1D format) using the &read and &write operations.
 * The following 5 operations, input as a single string,
     '&read(V.1D) &read(U.1D) &transp * &write(VUT.1D)'
   - reads matrices V and U from disk (separately),
   - transposes U (on top of the stack) into U',
   - multiplies V and U' (the two matrices on top of the stack),
   - and writes matrix VU' out (the matrix left on the stack by '*').
 * Calculations are carried out in single precision ('float').
 * Operations mostly contain characters such as '&' and '*' that
   are special to Unix shells, so you'll probably need to put
   the arguments to this program in 'single quotes'.

 STACK OPERATIONS
 -----------------
 number     == push scalar value (1x1 matrix) on stack;
                 a number starts with a digit or a minus sign
 =NAME      == save matrix on top of stack as 'NAME'
 NAME       == push NAME-ed matrix onto top of stack;
                 names start with an alphabetic character
 &clear     == erase all named matrices (to save memory)
 &read(FF)  == read ASCII (.1D) file onto top of stack from file 'FF'
 &write(FF) == write top matrix to ASCII file to file 'FF';
                 if 'FF' == '-', writes to stdout
 &transp    == replace top matrix with its transpose
 &ident(N)  == push square identity matrix of order N onto stack
                 N is an fixed integer, OR
                 &R to indicate the row dimension of the
                    current top matrix, OR
                 &C to indicate the column dimension of the
                    current top matrix, OR
                 =X to indicate the (1,1) element of the
                    matrix named X
 &Psinv     == replace top matrix with its pseudo-inverse
                 [computed via SVD, not via inv(A'*A)*A']
 &Sqrt      == replace top matrix with its square root
                 [computed via Denman & Beavers iteration]
               N.B.: not all real matrices have real square
                 roots, and &Sqrt will fail if you push it
               N.B.: the matrix must be square!
 &Pproj     == replace top matrix with the projection onto
                 its column space; Input=A; Output = A*Psinv(A)
               N.B.: result P is symmetric and P*P=P
 &Qproj     == replace top matrix with the projection onto
                 the orthogonal complement of its column space
                 Input=A; Output=I-Pproj(A)
 *          == replace top 2 matrices with their product;
                   stack = [ ... C A B ] (where B = top) goes to
                   stack = [ ... C AB ]
                 if either of the top matrices is a 1x1 scalar,
                 then the result is the scalar multiplication of
                 the other matrix; otherwise, matrices must conform
 +          == replace top 2 matrices with sum A+B
 -          == replace top 2 matrices with difference A-B
 &dup       == push duplicate of top matrix onto stack
 &pop       == discard top matrix
 &swap      == swap top two matrices (A <-> B)