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.
The matrix of 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
sddspseudoinverse [<input>] [<output>] [-pipe=[input][,output]]
[-minimumSingularValueRatio=<value> | -largestSingularValues=<number>]
[-deleteVectors=<list of vectors separated by comma>]
[-oldColumnNames=<string>] [-root=<string> [-digits=<integer>] |
-newColumnNames=<column>] [-sFile=<file>[,matrix]] [-uMatrix=<file>] [-vMatrix=<file>]
[-reconstruct=<file>] [-symbol=<string>] [-ascii] [-verbose] [-noWarnings]
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.
- -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 column-orthogonal matrix
to a file. The SVD decomposition follows the convention
. The ``transformed'' are , and
the ``transformed'' are .
- -vmatrix=file -- writes the column-orthogonal matrix to a file.
- -removeDCVectors -- Removes the eigenvectors which have an overall DC component.
-- 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 where is the weight vector
turned into a diagonal matrix and is the input matrix.
The matrix solution returned is where means taking
the pseudoinverse. The u matrix now has a different interpretation:
the ``transformed'' are , as before, but the
``transformed'' are .
- -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