.TH QUATFIT 1OSC "6 Oct 1992" OSC "OSC utilities"
.SH NAME
quatfit \- superimpose atoms of two molecules given in XYZ format
.SH SYNOPSIS
.B quatfit 
[
.B -r
.I ref-mol
]
[
.B -f
.I fit-mol
]
[
.B -p
.I pairs
]
[
.B -o
.I fit-out
]
[
.B -s
.I statfile
]
.br
.SH DESCRIPTION
Program
.B quatfit
superimposes specified atoms of two molecules so they are as close as
possible (in a least squares sense). The orientation of the
reference molecule is
kept fixed, while the fitted molecule is rotated and translated as a rigid
body to fulfill the fit. As the first step, the reference and fitted
molecule are translated, so their geometric centers are located at the
origin of the coordinate system. Then the rotation matrix is found by
the quaternion method and the fitted molecule is rotated. Then both
molecules are translated to the original center of the reference molecule.
If normal modes are present, they are also rotated. The pairs of
atoms to be fitted may have assigned weights (the weights represent the
onverse of the atom pair distance, a larger weight will force a thighter
fit for the pair).
The XYZ format used in the Xmol program (Xmol is a product of 
Research Equipment Inc. and Minnesota
Supercomputer Center, Inc., and is available via anonymous ftp at ftp.msc.edu
in /pub/xmol) was chosen to represent input files for the reference
and fitted molecules. The format is: 
.br
.in +3m
.I line 1: 
.B number of atoms
.br
.I line 2: 
.B descriptive title
.br
.I line 3, etc.: 
.B Atomic-Symbol  X  Y  Z
[
.B Charge
]  [
.B Mode-X  Mode-Y  Mode-Z
]
.br
.in -3m
If 
.B Charge 
is present, it is in 5th column. If normal modes are present, they
occupy last 3 columns. The file specifying atom pairs starts with a
line containing the number of fitted pairs; the next lines have the format:
.in +3m
.br
.B ref-atom  fit-atom  weight
.br
.in -3m
where 
.B ref-atom
is the atom number in the reference molecule, 
.B fit-atom 
is the corresponding atom in the fitted molecule, and
.B weight 
represents the tightness of the fit for this pair. Coordinates of the
superimposed fitted molecule (and normal modes, if present) are stored in the
.I fit-out 
file and information about the goodness of fit is stored in the 
.I statfile
which lists distances between fitted atom pairs, the RMS, and dot
product of normal modes from the reference and the fitted molecule. When
any of the I/O options is omitted, the corresponding file is read from(sent to)
standard input(standard output). The order of files in the standard input
stream is \fIref-mol\fR, \fIfit-mol\fR, \fIpairs\fR. The order of files in
the standard output is \fIfit-out\fR, \fIstatfile\fR.
.SH OPTIONS
.IP "\fB-r\fP \fIref-mol\fP"
The
.I ref-mol 
is a file name of XYZ file for reference molecule. If this
option is absent, the information is taken from standard input.
.IP "\fB-f\fP \fIfit-mol\fP"
The 
.I fit-mol
is an XYZ file with fitted molecule, i.e., the molecule which will be
translated and rotated. If this option is missing, the information
is taken from the standard input.
.IP "\fB-p\fP \fIpairs\fP"
The 
.I pairs
is the file with atom pairs and their weights. It starts with the number
of fitted pairs as a top line and is followed by 3 columns: 1st column
is a list of reference molecule atoms, 2nd is a list of fitted molecule
atoms, and 3rd column represents weights. If \fB-p \fInone\fR is specified,
the weights are not read in but they are all set to 1.0, and fitted atom pairs
are set to consecutive natural numbers,
i.e., 1 \(em 1, 2 \(em 2, 3 \(em 3 ..., up to the number of atoms in the
smaller molecule. You might want to use \fB-p \fInone\fR option if you
compare geometry of the same molecule calculated by different methods,
provided that atom numbering is the same.
.IP "\fB-o\fP \fIfit-out\fP"
This option specifies the output file for the transformed fitted molecule.
If absent, the file is sent to standard output.
.IP "\fB-s\fP \fIstatfile\fP"
The file name for fit statistics. If this option is absent, this information
is sent to standard output.
.SH EXAMPLE
cat rm.xyz fm.xyz | quatfit -o fmmod.xyz -p none > stat.txt
.br
is equivalent to
.br
quatfit -r rm.xyz -f fm.xyz -p none -o fmmod.xyz -s stat.txt
.br
i.e., the reference molecule (kept fixed) file is rm.xyz, the fitted molecule
file is fm.xyz, file for translated and rotated coordinates of fitted molecule
is fmmod.xyz, and stat.txt contains the information about goodness of the fit.
Atom pairs to be fitted and their weights are assigned automatically by the
program in this example.
If the weights were given explicitly, the command could look like:
.br
cat rm.xyz fm.xyz pairs.tab | quatfit -o fmmod.xyz > stat.txt
.br
which is equivalent to:
.br
quatfit -r rm.xyz -f fm.xyz -p pairs.tab -o fmmod.xyz -s stat.txt
.br
where pairs.tab is the file with fitted pairs and weights.

.SH DIAGNOSTICS
Most error messages are self-explanatory.
.SH BUGS
Report bugs to the authors.
.SH AUTHORS
David Heisterberg, Ohio Supercomputer Center,
1224 Kinnear Rd, Columbus, OH 43212-1163
e-mail: djh@ccl.net, DJH@OHSTPY.BITNET. Translation from FORTRAN to C and
input/output by Jan Labanowski, Ohio Supercomputer Center,
1224 Kinnear Rd, Columbus, OH 43212-1163.
e-mail: jkl@ccl.net, JKL@OHSTPY.BITNET.
.SH COPYRIGHT
Program can be copied and distributed freely, provided that the Copyright
Notice is not removed from the program source. You may acknowledge the use
of this program in published material as: David J. Heisterberg, 1990,
unpublished results.