4.49 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

  

  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