dms/dms.1

.TH DMS 1 "" "\fBAPPENDIX 6\fP" "\fBUCSF MidasPlus\fP"
.iX zd start
.SH NAME
dms \- calculate a solvent-accessible molecular surface
.SH SYNOPSIS
.B dms
\fIfile\fR [
.B \-a
] [
.B \-d
\fIdensity\fR] [
.B \-g
\fIfile\fR] [
.B \-i
\fIfile\fR] [\fB\-n\fR] [\fB\-w
\fIradius\fR] [\fB\-v\fR] \fB\-o\fI file\fR
.SH DESCRIPTION
.I Dms
calculates the molecular surface of a molecule.
The molecular surface resembles the van der Waals
surface of a molecule,
except that crevices between atoms are smoothed over
and interstices too small
to accommodate the probe are eliminated.
The surface includes cavities in the interior
of the molecule,
even if they are not accessible to a solvent molecule
coming from the outside.
.LP
The molecular surface
calculated is that defined by
F. M. Richards (1977,
.I "Ann. Rev. Biophys. Bioeng."
).
In particular,
the calculated molecular surface is that traced out by the \fIsurface\fP
of the probe sphere rather that the probe sphere's \fIcenter\fP.
According to Richards' definition
the molecular surface consists of two parts:
.I "contact surface"
and
.I "reentrant surface."
The contact surface is
made up of
``those parts of the molecular van der Waals
surface that can actually be in contact
with the surface of the probe.''
The reentrant surface is defined by
``the interior-facing part of the probe
when it is simultaneously
in contact with more than one atom.''
.I Dms
reports the amounts of contact and reentrant surface area,
and the combined total surface area on the standard error output
(see the \fB\-g\fP flag below).
.LP
.I File
is an input file of coordinates.
The input file must be in the Protein Data Bank format.
The first letter or first two letters
of the atom name is used
to determine the element type.
By default, implicit hydrogens are
included for carbon,
nitrogen and oxygen atoms,
thus aromatic carbons
and nitrogens
will have van der Waals radii
that are somewhat too big.
Note that
only amino acid and nucleic acid residues
will be included unless \fB\-a\fR is also specified.
.LP
.SL
.I Dms
can be set up to run on multiple machines
simultaneously for increased performance.
By default, it only runs on the local host.
The
.SM UCSF
MidasPlus Installation Guide
that came with the MidasPlus
.SM CD-ROM
contains instructions
on how to configure
.I dms
to use multiple machines.
.EL
.LP
.SL
If it is desired to simply visualize a small molecular surface
from within 
.SM MIDAS\c
, it may be easier to use the \fImakems\fP(1) delegate,
rather than run \fIdms\fP directly.
Consult the \fImakems\fP manual page for further details.
.EL
.SH OPTIONS
The flags may be in any order.
The meanings of the flags are described below:
.IP \fB\-a\fR
Include all atoms,
not just those in amino acid and nucleic acid residues.
.IP \fB\-d\fR
Change the density of points on the surface.
.I Density
is a factor affecting
the density of points on the surface;
the default of 1.0 produces about 5 points
per square angstrom.
Only values between 0.1 and 10.0 are permitted.
For large proteins,
a density of 0.5 is recommended.
.IP \fB\-g\fR
Write all the informative messages to
.I file,
instead of the standard error output.
Genuine errors still go to the standard error output.
This file is not rewound at any time,
so messages from several runs may be accumulated.
.IP \fB\-i\fR
.iX 36
Calculate the molecular surface
only for those residues and atoms
specified in
.I file,
but keeping the rest of the molecule
for collision checks.
The file consists of a series of lines
such as the following:
.nf
ASP  205 CA
TYR   13 *
GLY  116 FRM
HIS  178 TO
.fi
.IP
The asterisk means all atoms of the residue
and the ``FRM'' and ``TO'' mean all residues
from 116 to 178 inclusive.
The sequence number may contain letters,
and if the
.SM PDB
input file contains chain identifiers,
then those should be appended on the right of the sequence number.
Residue insertion codes (if any) should be placed between
the sequence number and any chain identifier.
Residues contained in \fCHETATM\fP records should have
an asterisk appended to the end of the residue identifier.
The surface generated using the \fB\-i\fR flag
is not always the same as the surface
generated by running the entire molecule
and afterwards selecting out the desired atoms.
The first surface will not include
reentrant surface lying between
an atom in the \fB\-i\fR file and atoms not in the file.
.iX bd
The
.IR pdb2site (1)
utility may be useful for generating site files.
Consult the
.I pdb2site
manual page for further details.
.IP \fB\-n\fR
Include the unit normals
to the surface with
each surface point record.
.IP \fB\-v\fR
Produce more verbose output.
.I Dms
will announce each computation phase as it is entered
as well as a count of the atom types in the molecule
and the number of computation requests handled by each
host that participated in the
.I dms
calculation.
.IP \fB\-o\fR
The output is written to
.I file.
This flag is not optional.
.IP \fB\-w\fR
Change the water probe radius from the default
radius of 1.4 angstroms.
This parameter must be between
1.0 and 201.0.
.LP
The output consists of
a series of atom and surface point records,
with the same format for the
first six fields.
Each atom is followed by
the surface points (if any)
which belong to it.
These first six fields
are in the following format:
residue name,
sequence number,
atom name,
x coordinate,
y coordinate,
z coordinate.
For an atom record,
the seventh field is ``A.''
For a surface point record,
the seventh field begins
with an ``S,''
followed by a ``C,'' ``R,'' or ``S''
according to whether
the point is part of
contact, reentrant, or ``saddle'' surface
(``saddle'' is a type of reentrant surface
where the probe is in contact with exactly
two atoms).
This is followed a digit
used for depicting
different density levels.
The eighth field is the
molecular surface area associated
with the point in
square angstroms.
If the \fB\-n\fR flag is specified,
the next three fields are
the unit normal vector
pointing outward from the surface.
Informative messages and errors are
written to the standard error output
unless a \fB\-g\fR file is specified.
.LP
.iX 27 start
The chemical elements and radii
that the program handles are detailed
in the table below.
The program gets these values from the file
.IR /usr/local/midas/resource/dms/radii .
If there is a file in the current directory called
.IR radii ,
then
.I dms
will use that file instead.
So in order to add uncommon elements or
use different radii, one should copy the
default file and modify it.
The file format is documented in the file itself.
.sp
.RS 1i
.TS
box;
c c
a n.
Element	Radius
_	_
H	1.20
C	1.90
N	1.50
O	1.40
F	1.35
P	1.90
S	1.85
Cl	1.8
Fe	0.64
Cu	1.28
Zn	1.38
Br	1.95
I	2.15
Other	1.90
.TE
.RE
.SH "SEE ALSO"
.SL
pdb2site(1),
The UCSF MidasPlus Installation Guide
.EL
.SH "AUTHOR"
Conrad Huang
.br
University of California, San Francisco
.SH FILES
/usr/local/midas/resource/dms/radii        default atomic radii
.iX 27 stop
.br
.SH DIAGNOSTICS
Many and varied.
.iX 37
Be sure to examine the \fB\-g\fR file before you leave
a background job running overnight.
.iX zd stop