4.65 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₁₂ 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 [<input>] [<output>] [-pipe=[input][,output]] [-minimumSingularValueRatio=<value> | -largestSingularValues=<number>] [-smallestSingularValues=<number>] [-deleteVectors=<list of vectors separated by comma>] [-economy] [-printPackage] [-oldColumnNames=<string>] [-root=<string> [-digits=<integer>] | -newColumnNames=<column>] [-sFile=<file>[,matrix]] [-uMatrix=<file>] [-vMatrix=<file>] [-weights=<file>,name=<columnname>,value=<columnname>] [-reconstruct=<file>] [-symbol=<string>] [-ascii] [-verbose] [-noWarnings] [-multiplyMatrix=<file>[,invert]]

• 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.
  • -deleteVectors -deleteVectors=n1,n2,n3,... which will set the inverse singular values of modes n1,n2,n3, ect to zero. The order in which the SV removal options are processed is minimumSingularValueRatio, largestSingularValues and then deleteVectors.
  • -economy — If given, only the first min(m,n) columns for the U matrix are calculated or returned where m is the number of rows and n is the number of columns. This can potentially reduce the computation time with no loss of useful information. economy option is highly recommended for most pratical applications since it uses less memory and runs faster. If economy option is not give, a full m by m U matrix will be internally computated no matter whether -uMatrix is provided.
  • -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.
  • -multiplyMatrix=file[,invert] — if invert is not provided, then the output matrix is the inverse of the input matrix multiplying by this matrix; otherwise, the output matrix is the product of multiply matrix and the inverse of the input matrix.
  • -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).
  • -sFile=file — writes the singular values vector to file.
  • -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 = uSv^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)^Iw 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 wy.
  • -symbol=string — The string for the symbol field of data column definitions.
  • -reconstruct — speficy a file which will reconstruct the original matrix with only the singular values retained in the inversion.
  • -printPackage — prints out the linear algebra package that was compiled.
  • -ascii — Produces an output in ascii mode. Default is binary.
  • -verbose — Prints out incidental information to stderr.
• author: L. Emery ANL