sddspseudoinverse

• description: sddspseudoinverse views the numerical tabular data of the input file as though it formed a matrix, and produces an output file with data corresponding to the pseudo-inverse of the input file matrix. At present the pseudo-inversion is done using a singular value decomposition. Other methods may be made available in the future.

  Command line options specifies the number of singular values to be used in the inversion process.

  The column names for the output file are generated either from the data in a selected string column in the input file, from the value of the command line option -root, or from an internal default.

  The column names of the input file are collected and made into a string column in the output file.

• examples: The matrix of $R_{12}$ values for some accelerator beamline called LTP is stored in file LTP.R12. The pseudo-inverse (useful for trajectory correction), named LTP.InvR12, is created with:
  sddspseudoinverse LTP.R12 LTP.InvR12
• synopsis:
  sddspseudoinverse [-pipe=[input][,output]] inputFile outputFile [-minimumSingularValueRatio=value | -largestSingularValues=number] [-oldColumnNames=string] [{-root=string [-digits=integer] | -newColumnNames=column}] [-umatrix=file] [-vmatrix=file] [-removeDCVectors] [-weights=file,name=columnName,value=columnName] [-symbol=string] [-ascii] [-verbose] [-noWarnings]
• files: The input file contains the data for the matrix to be inverted. The output file contains the data for the inverted matrix. If only one file is specified, then the input file is overwritten by the output.

  Multiple data pages of the input file will be processed and written to the outptu file if all the data pages of the input file have the same number of rows. The processing will stop at the first data page which doesn't have the same number of rows as that of the first page. If applicable, the string column selected to generate column names for the output file is assumed to be the same in all input data sets. The string columns of only the first data set are read.

• switches:
  • -pipe[=input][,output] -- The standard SDDS Toolkit pipe option.
  • -minimumSingularValueRatio=realValue -- Used to remove small singular values from the calculation. The smallest singular value retained for the inverse calculation is determined by multiplying this ratio value with the largest singular value of the input matrix.
  • -largestSingularValues=integer -- Used to remove small singular values from the calculation. The largest integer singular values are kept.
  • -oldColumnNames=string -- A string column of name string is created in the output file, containing the column names of the input files as string data. If this option is not present, then the default name of ``OldColumnNames'' is used for the string column.
  • -root=string -- A string used to generate columns names for the output file data. The first data column is named ``string000'', the second, ``string001'', etc.
  • -digits=integer -- minimum number of digits used in the number appended to root of the output file column names. (Default value is 3).
  • -newColumnNames=string -- Specifies a string column of the input file which will be used to define column names of the output file.
  • -umatrix=file -- writes the $u$ column-orthogonal matrix to a file. The SVD decomposition follows the convention $A = u S v^T$. The ``transformed'' $x$ are $v^T x$, and the ``transformed'' $y$ are $u^T y$.
  • -vmatrix=file -- writes the $v$ column-orthogonal matrix to a file.
  • -removeDCVectors -- Removes the eigenvectors which have an overall DC component.
  • -weights=file,name=columnName,value=columnName] -- Specifies a file which contains weights for each of the rows of the matrix, thus giving different weights for solving the linear equations of the pseudoinverse problem. The equation that is solved is $wAx = wy$ where $w$ is the weight vector turned into a diagonal matrix and $A$ is the input matrix. The matrix solution returned is $(wA)^I w$ where $()^I$ means taking the pseudoinverse. The u matrix now has a different interpretation: the ``transformed'' $x$ are $v^T x$, as before, but the ``transformed'' $y$ are $u^T w y$.
  • -symbol=string -- The string for the symbol field of data column definitions.
  • -ascii -- Produces an output in ascii mode. Default is binary.
  • -verbose -- Prints out incidental information to stderr.
• author: L. Emery ANL