sddsmatrixop

• description: sddsmatrixop performs general matrix operations. The matrices and operations are specified on the command line and the operations will proceed in a rpn-like fashion.

  String columns are ignored and not copied to the output file.

• examples: C = A B would be expressed as
  sddsmatrixop A.matrix C.matrix -push=B.matrix -multiply

  Here A.matrix is the input matrix of the command line. It is pushed on the "matrix" stack. In rpn, we always need one quantity on the stack before doing any operations, so the input file may as well be it. The command "push" pushes a second matrix on the stack. The command -multiply does the multiplication of A.matrix and B.matrix. The matrix at the top of the stack will go in the output file C.matrix.

  A more complicated command would be
  

  $${\rm Y = (1 + (A+B)C)^{-1}}$$
  
  
  sddsmatrixop A.matrix Y.matrix -push=B.matrix -add -push=C.matrix -mult -identity -add -invert
  where the -identity command pushes an identity matrix with the same dimension as the top element on the stack.The above command will be executed as following:

  command          execution                    stack (from top to bottom)   
  A.matrix         push A into stack            A
                                
  -push=B.matrix   push B into stack            B A
  
  -add             pop matrix A,B from stack    temp1
                   execute: temp1=A+B
                   push temp1 into stack
  
  -push=C.matrix   push C into stack            C temp1
  
  -mult            pop C and temp1 from stack   temp2
                   execute: temp2=temp1*C
                   push temp2 into stack
  
  -identity        pop temp2 from stack         I temp2
                   create unit matrix(I) that
                      has the same 
                      dimension as temp2
                   push temp2 into stack
                   push I into stack
  
  -add             pop I and temp2 from stack   temp3
                   execute: temp3=temp2+I
                   push temp3 into stack
  
  -invert         pop temp3 from stack          result
                  execute: result = temp3^(-1)
                  push result into stack.
  
  at the end, the final result matrix is poped from the stack and writtend into output Y.matrix.
  

• synopsis:
  sddsmatrixop [inputmatrix] [outputmatrix] [-pipe=[in|out]] [-verbose] [-push=<matrix>] [-multiply]|[-add]|[-substract]|[-invert]...

• switches:
  • -pipe[=input][,output] -- The standard SDDS Toolkit pipe option.
  • inputmatrix -- SDDS file which contains the input matrix - the first element in the stack.
  • outputmatrix -- The result matrix is written into SDDS file named by outputmatrix.
  • -push=<matrix> -- The matrix that is going to be pushed into stack.
  • -verbose -- Write diagnostic messages to stderr.
  • -identity[=<number>] -- push a unit matrix into stack. If <number> is provided, the unit matrix has the dimension provided by <number>, otherwise, the dimenstion of unit matrix is the same as the top matrix in the stack.
  The available operations are as following:
  • -add -- addition operator.
  • -substract -- substract operator.
  • -multiply[=hadamard] -- matrix multiplication operator. if =hadamard is specified, the matrix multiplication is done element-by-element, similar to addition.
  • -divide=hadamard -- element-by-element division.
  • -swap -- swap the top two elements in the stack.
  • -scalarmultiply=<value> -- multiply the matrix by a constant value.
  • -scalardivide=<value> -- divide the matrix by a constact value.
  • -transpose -- matrix transpose operator.
  • -invert -- matrix inversion operator.
  the -push and operators can be repeated many times as needed.
• author: H. Shang ANL