xref: /dports/science/nwchem-data/nwchem-7.0.2-release/doc/user/prepare.tex

%
% $Id$
%
\label{sec:prepare}
\def\bmu{\mbox{\boldmath $\mu$}}
\def\bE{\mbox{\bf E}}
\def\br{\mbox{\bf r}}
\def\tT{\tilde{T}}
\def\t{\tilde{1}}
\def\ip{i\prime}
\def\jp{j\prime}
\def\ipp{i\prime\prime}
\def\jpp{j\prime\prime}
\def\etal{{\sl et al.}}
\def\nwchem{{\bf NWChem}}
\def\nwargos{{\bf nwargos}}
\def\nwtop{{\bf nwtop}}
\def\nwrst{{\bf nwrst}}
\def\nwsgm{{\bf nwsgm}}
\def\esp{{\bf esp}}
\def\md{{\bf md}}
\def\prepare{{\bf prepare}}
\def\argos{{\bf ARGOS}}
\def\amber{{\bf AMBER}}
\def\charmm{{\bf CHARMM}}

The \prepare\ module is used to set up the necessary files for a molecular
dynamics simulation with \nwchem. User supplied coordinates can be used to
generate topology and restart files. The topology file contains all static
information about a molecular system, such as lists of atoms, bonded
interactions and force field parameters. The restart file contains all
dynamic information about a molecular system, such as coordinates, velocities
and properties.

Without any input, the prepare module checks the existence of a topology
and restart file for the molecular systems. If these files exist, the module
returns to the main task level without action. The module will generate these
files when they do not exist. Without any input to the module, the generated
system will be for a non-solvated isolated solute system.

To update existing files, including solvation, the module requires input
directives read from an input deck,

\begin{verbatim}
prepare
 ...
end
\end{verbatim}

The prepare module performs three sub-tasks:
\begin{itemize}
\item[{\bf *}]
{\bf sequence generation}\\
This sub-task analyzes the supplied coordinates from a PDB-formatted file
or from the input geometry, and generates a sequence file, containing the
description of the system in terms of basic building blocks found as
fragment or segment files in the database directories for the force field
used. If these files do not exist, they are generated based on the supplied
coordinates. This process constists of generating a fragment file with the
list of atoms with their force field dependent atom types, partial atomic
charges calculated from a Hartree Fock calculation for the fragment, followed
by a restrained electrostatic potential fit, and a connectivity list. From
the information on this fragment file the lists of all bonded interactions
are generated, and the complete lists are written to a segment file.
\item[{\bf *}]
{\bf topology generation}\\
Based on the generated or user-supplied sequence file and the force field
specific segment database files, this sub-task compiles the lists of atoms,
bonded interactions, excluded pairs, and substitutes the force field
parameters. Special commands may be given to specify interaction parameters
that will be changing in a free energy evaluation.
\item[{\bf *}]
{\bf restart generation}\\
Using the user supplied coordinates and the topology file for the chemical
system, this sub-task generates a restart file for the system with coordinates,
velocities and other dynamic information. This step may include solvation
of the chemical system and specifying periodic boundary conditions.
\end{itemize}

Files involved in the preparation phase exist in the following hierarchy:
\begin{itemize}
\item[{\bf *}]
{\bf standards}\\
The standard database files contain the original force field information.
These files are to reside in a directory that is specified in the file
\$HOME/.nwchemrc. There will be such a directory for each supported force
field. These directories contain fragment files (with extension frg),
segment files (with extension sgm) and a parameter file (with the name
of the force field and with extension par).
\item[{\bf *}]
{\bf extensions}\\
These database files contain generally accepted extensions to the original
force field and are to reside in a separate directory that is specified in
the file \$HOME/.nwchemrc. There will be such a directory for each supported
force field. These directories contain fragment files (with extension frg),
segment files (with extension sgm) and a parameter file (with the name
of the force field and with extension par).
\item[{\bf *}]
{\bf contributed}\\
These database files contain contributed definitions, also required for
the quality assurance tests and are to reside in a separate directory
that is specified in the file \$HOME/.nwchemrc.
There will be such a directory for each supported
force field. These directories contain fragment files (with extension frg),
segment files (with extension sgm) and a parameter file (with the name
of the force field and with extension par).
\item[{\bf *}]
{\bf user preferences}\\
These database files contain user preferred extensions to the original
force field and are to reside in a separate directory that is specified in
the file \$HOME/.nwchemrc. Separate directories of this type  should be
defined for each supported force field.
This directory may contain fragment files (with extension frg),
segment files (with extension sgm) and a parameter file (with the name
of the force field and with extension par).
\item[{\bf *}]
{\bf temporary files}\\
Temporary database files contain user preferred extensions to the original
force field and are to reside in a separate directory that is specified in
the file \$HOME/.nwchemrc. There may  be such a directory for each supported
force field. This directory may contain fragment files (with extension frg),
segment files (with extension sgm) and a parameter file (with the name
of the force field and with extension par).
\item[{\bf *}]
{\bf current files}\\
Database files that contain user preferred extensions to the original
force field and are to reside in a separate directory that is specified in
the file \$HOME/.nwchemrc. Typically this will be the current working
directory, although it may be defined as a specific directory.
This directory may contain fragment files (with extension frg),
segment files (with extension sgm) and a parameter file (with the name
of the force field and with extension par). If not specified,
files will be taken from the current directory.
\end{itemize}

Data is taken from the database files searched in the above order. If data
is specified more than once, the last found values are used. For example,
if some standard segment is redefined in a temporary file, the latter one
will be used. This allows the user to redefine standards or extensions
without having to modify those database files, which may reside in a
generally available, non-modifyable directory. If a filename is specified
rather than a directory, the filename indicates the parameter file
definition. All other files (frg and sgm files) will be take from the
specified directory.
\par
The most common problems with the \prepare\ module are
\begin{itemize}
\item[{\bf ~}]
The format of the pdb file does not conform to the pdb standard. In
particular, atom names need to correspond with definitions in the
fragment and segment database files, and should adhere to IUPAC
recommendations as adopted by the pdb standard. If this problem
occurs, the pdb file will need to be corrected.
\item[{\bf ~}]
Non-standard segments may contain atoms that could not be atom typed
with the existing typing rules in the force field parameter files.
When this happens, additional typing rules can be included in the
parameter file, or the fragment file may be manually typed.
\item[{\bf ~}]
Parameters for atom types or bonded interactions do not exist in
the force field. When this happens, additional parameters may be
defined in the parameter files, or the segment file may be edited
to include explicit parameters.
\item[{\bf ~}]
The atoms names in the pdb file do not match the names in the
already existing frg or sgm file.  NWChem will remove the unknown
atoms and replace them with the ones it expects, but the geometry
will be changed.  It is best to run the prepare module the first time
with the print level set to debug, and to look for messages like
``Not found: atom''.  Of course, this is to be expected when
using PDB files without explicit hydrogen atoms.
\end{itemize}

\section{Default database directories}

The file \$HOME/.nwchemrc may contain the following entries that determine
which files are used by the prepare module.

\begin{verbatim}
ffield <string ffname>
\end{verbatim}

This entry specifies the default force field. Database files supplied with
\nwchem\ currently support values for \verb+ffname+ of {\bf amber}, referring
to AMBER95, and {\bf charmm}, referring to the academic CHARMM22 force field.

\begin{verbatim}
<string ffname>_(1-9) <string ffdir>[\{<string parfile>\}]
\end{verbatim}

Entries of this type specify the directory \verb+ffdir+ in which force field
database files can be found. Optionally the parameterfile in this directory
may be specified as \verb+parfile+.
The prepare module will only use files in directories
specified here. One exception is that files in the current work directory
will be used if no directory with current files is specified. The directories
are read in the order 1-9 with duplicate parameters taken from the last
occurrence found. Note that multiple parameter files may be specified that will
be read in the order in which they are specified.

\begin{verbatim}
<string solvnam> <string solvfil>
\end{verbatim}

This entry may be used to identify a pure solvent restart file \verb+solvfil+
by a name \verb+solvnam+

An example file \$HOME/.nwchemrc is:

\begin{verbatim}
ffield amber
amber_1  /home/svc-nwchem/nwchem-5.1.1/src/data/amber_s/
amber_2  /home/svc-nwchem/nwchem-5.1.1/src/data/amber_x/amber.par,glycam.par
amber_3  /home/svc-nwchem/nwchem-5.1.1/src/data/amber_q/
spce     /home/svc-nwchem/nwchem-5.1.1/src/data/solvents/spce.rst
thfs     /home/svc-nwchem/nwchem-5.1.1/src/data/solvents/thfs.rst
clfm     /home/svc-nwchem/nwchem-5.1.1/src/data/solvents/clfm.rst
meoh     /home/svc-nwchem/nwchem-5.1.1/src/data/solvents/meoh.rst
charmm_1 /home/svc-nwchem/nwchem-5.1.1/src/data/charmm_s/charmm.par
charmm_2 /home/svc-nwchem/nwchem-5.1.1/src/data/charmm_x/
\end{verbatim}

\section{System name and coordinate source}

\begin{verbatim}
system <string sys_calc>
\end{verbatim}

The system name can be explicitly specified for the \prepare\ module.
If not specified, the system name will be taken from a specification
in a previous \md\ input block, or derived from the run time database
name.

\begin{verbatim}
source ( pdb | rtdb )
\end{verbatim}

The source of the coordinates can be explicitly specified to be from
a PDB formatted file \verb+sys+.pdb, or from a geometry object in the run
time database. If not specified, a pdb file will be used when it exists
in the current directory or the rtdb geometry otherwise.

\begin{verbatim}
model <integer modpdb default 0>
\end{verbatim}

If a PDB formatted source file contains different MODELs, the \verb+model+
keyword can be used to specify which MODEL will be used to generate the
topology and restart file. If not specified, the first MODEL found on the
PDB file will be read.

\begin{verbatim}
altloc <character locpdb default ' '>
\end{verbatim}

The \verb+altloc+ keyword may be used to specify the use of alternate
location coordinates on a PDB file.

\begin{verbatim}
chain <character chnpdb default ' '>
\end{verbatim}

The \verb+chain+ keyword may be used to specify the chain identifier
for coordinates on a PDB file.

\begin{verbatim}
histidine ( hid | hie | hip )
\end{verbatim}
specifies the default protonation state of histidine.

\begin{verbatim}
sscyx
\end{verbatim}

Keyword \verb+sscyx+ may be used to rename cysteine residues that form
sulphur bridges to CYX.

\begin{verbatim}
hbuild
\end{verbatim}

Keyword \verb+hbuild+ may be used to add hydrogen atoms to the
unknown segments of the structure found on the pdb file. Placement
of hydrogen atoms is based on geometric criteria, and the resulting
fragment and segment files should be carefully examined for correctness.

The database directories are used as specified in the file $.nwchemrc$. Specific
definitions for the force field used may be changed in the input file using

\begin{verbatim}
directory_(1-9) <string ffdir>[<string parfile>]
\end{verbatim}

\section{Sequence file generation}

If no existing sequence file is present in the current directory,
or if the \verb+new_seq+ keyword was specified in the \prepare\
input deck, a new sequence file is generated from information
from the pdb file, and the following input directives.

\begin{verbatim}
maxscf <integer maxscf default 20>
\end{verbatim}

Variable maxscf specifies the maximum number of atoms in a segment for
which partial atomic charges will be determined from an SCF calculation
followed by RESP charge fitting. For larger segments a crude partial
charge guestimation will be done.

\begin{verbatim}
qscale <real qscale default 1.0>
\end{verbatim}

Variable qscale specifies the factor with which SCF/RESP determined
charges will be multiplied.

\begin{verbatim}
modify sequence { <integer sgmnum>:<string sgmnam> }
\end{verbatim}

This command specifies that segment {\bf sgmnam} should be used
for segment with number {\it sgmnum}. This command can be used
to specify a particular protonation state. For example, the
following command specifies that residue 114 is a hystidine
protonated at the N$_\epsilon$ site and residue 202 is a hystidine
protonated at the N$_\delta$ site:

\begin{verbatim}
modify sequence 114:HIE 202:HID
\end{verbatim}

Links between atoms can be enforced with

\begin{verbatim}
link <string atomname> <string atomname>
\end{verbatim}

For example, to link atom {\rm SG} in segment 20 with atom {\rm FE}
in segment 55, use:

\begin{verbatim}
link 20:_SG 55:FE
\end{verbatim}

\par
The format of the sequence file is given in Table~\ref{tbl:nwmdseq}.
In addition to the list of segments this file also includes links
between non-standard segments or other non-standard links.
These links are generated based on distances found between
atoms on the pdb file. When atoms are involved in such non-standard
links that have not been identified in the fragment of segment
files as a non-chain link atom, the prepare module will ignore
these links and report them as skipped. If one or more of these links
are required, the user has to include them with explicit link
directives in the sequence file, making them forced links.
Alternatively, these links can be made forced-links by changing
\verb+link+ into \verb+LINK+ in the sequence file.

\begin{verbatim}
fraction { <integer imol> }
\end{verbatim}

Directive \verb+fraction+ can be used to separate solute molecules
into fractions for which energies will be separately reported
during molecular dynamics simulations. The listed molecules will be
the last molecule in a fraction. Up to 10 molecules may be
specified in this directive.

\begin{verbatim}
counter <integer num> <string ion>
\end{verbatim}

Directive \verb+counter+ adds \verb+num+ counter ions of type
\verb+ion+ to the sequence file. Up to 10 \verb+counter+
directives may appear in the input block.

\begin{verbatim}
counter <real factor>
\end{verbatim}

This directive scales the counter ion charge by the specified factor
in the determination of counter ions positions.

\section{Topology file generation}

\begin{verbatim}
new_top [ new_seq ]
\end{verbatim}

Keyword \verb+new_top+ is used to force the generation of a new topology
file. An existing topology file for the system in the current directory
will be overwritten. If keyword \verb+new_seq+ is also specified, an
existing sequence file will also be overwritten with a newly generated
file.

\begin{verbatim}
amber | charmm
\end{verbatim}

The prepare module generates force field specific fragment, segment and
topology files. The force field may be explicitly specified in the prepare
input block by specifying its name.
Currently \amber\ and \charmm\ are the supported force fields.
A default force field may be specified in the file \$HOME/.nwchemrc.

\begin{verbatim}
standard <string dir_s>[<string par_s>]
extensions <string dir_x>[<string par_x>]
contributed <string dir_q>[<string par_q>]
user <string dir_u>[<string par_u>]
temporary <string dir_t>[<string par_t>]
current <string dir_c>[<string par_c>]
\end{verbatim}

The user can explicitly specify the directories where force field
specific databases can be found. These include force field standards,
extensions, quality assurance tests, user preferences, temporary , and
current database files.\\
Defaults for the directories where database files reside may be specified
in the file \$HOME/.nwchemrc for each of the supported force fields.
Fragment, segment and sequence files generated by the \prepare\ module are
written in the temporary directory. When not specified, the current
directory will be used.
Topology and restart files are always created in the current directory.


The following directives control the modifications of a
topology file. These directives are executed in the order in which
they appear in the \prepare\ input deck. The topology modifying
commands are not stored on the run-time database and are, therefor,
not persistent.

\begin{verbatim}
modify atom <string atomname> [set <integer mset> | initial | final] \
	( type <string atomtyp> |  charge <real atomcharge> |  \
	  polar <real atompolar> | dummy | self | quantum | quantum_high )
\end{verbatim}

These \verb+modify+ commands change the atom type, partial atomic charge,
atomic polarizability, specify a dummy, self-interaction and quantum atom,
respectively. If \verb+mset+ is specified, the modification will only
apply to the specified set, which has to be 1, 2 or 3. If not specified,
the modification will be applied to all three sets. The quantum region in
QM/MM simulations is defined by specifying atoms with the \verb+quantum+
or \verb+quantum_high+ label. For atoms defined \verb+quantum_high+
basis sets labeled \verb+X_H+ will be used.
The \verb+atomnam+
should be specified as \verb+<integer isgm>:<string name>+, where
\verb+isgm+ is the segment number, and \verb+name+ is the atom name. A
leading blank in an atom name should be substituted with an underscore.
The modify commands may be combined. For example, the following directive
changes for the specified atom the charge and atom type in set 2 and
specifies the atom to be a dummy in set 3.

\begin{verbatim}
modify atom 12:_C1 set 2 charge 0.12 type CA set 3 dummy
\end{verbatim}

With the following directives modifications can be made for entire
segments.

\begin{verbatim}
modify segment <integer isgm> \
   [protonation <integer iprot> | set <integer mset> | initial | final] \
   ( dummy | self | uncharged | quantum | quantum_high )
\end{verbatim}

where \verb+protonation+ specifies a modification of the default protonation
state of the segment as specified in the segment file. This option only applies
to Q-HOP simulations.

Modifications to bonded interaction parameters can be made with the
following modify commands.

\begin{verbatim}
modify ( bond <string atomtyp> <string atomtyp> |  \
	 angle <string atomtyp> <string atomtyp> <string atomtyp> |        \
 	 torsion <string atomtyp> <string atomtyp> <string atomtyp>        \
		 <string atomtyp> [ multiplicity <integer multip> ] |      \
	 plane <string atomtyp> <string atomtyp> <string atomtyp>          \
		 <string atomtyp> ) [set <integer mset> | initial | final] \
	 <real value> <real forcon>
\end{verbatim}

where \verb+atomtyp+ and \verb+mset+ are defined as above, \verb+multip+
is the torsion ultiplicity for which the modification is to be applied,
\verb+value+ is the reference bond, angle, torsion angle of out-of-plane
angle value respectively, and \verb+forcon+ is the force constant for
bond, angle, torsion angle of out-of-plane angle. When \verb+multip+
or \verb+mset+ are not defined the modification will be applied to
all multiplicities and sets, respectively, for the identified bonded
interaction.

After modifying atoms to quantum atoms the bonded interactions in which
only quantum atoms are involved are removed from the bonded lists using

\begin{verbatim}
update lists
\end{verbatim}

Error messages resulting from parameters not being defined for bonded
interaction in which only quantum atoms are involved are ignored using

\begin{verbatim}
ignore
\end{verbatim}

To specify that a free energy calculation will be carried out using the
topology file, the following keyword needs to be specified,

\begin{verbatim}
free
\end{verbatim}

To specify that a Q-HOP simulation will be carried out using the topology
file, the following keyword needs to be specified,

\begin{verbatim}
qhop
\end{verbatim}

To specify that only the first set of parameters should be used, even if multiple
sets have been defined in the fragment or segment files, the following keyword needs
to be specified,

\begin{verbatim}
first
\end{verbatim}

Note that keywords \verb+free+, \verb+qhop+ and \verb+qhop+ are mutually exclusive.
\section{Appending to an existing topology file}

\begin{verbatim}
noe <string atom1> <string atom3> \
  <real dist1> <real dist2>  <real dist3> <real forc1> <real forc2>
\end{verbatim}

This directive specifies a distance restraint potential between atoms
$atom1$ and $atom2$, with a harmonic function with force constant
$forc1$ between $dist1$ and $dist2$, and a harmonic function with
force constant $forc2$ between $dist2$ and $dist3$. For distances
shorter than $dist1$ or larger than $dist3$, a constant force is
applied such that force and energy are continuous at $dist1$
and $dist3$, respectively. Distances are given in nm, force constants
in kJ mol$^{-1}$ nm$^{-2}$.

\begin{verbatim}
select <integer isel> { <string atoms> }
\end{verbatim}

Directive \verb+select+ specifies a group of atoms used in the
definition of potential of mean force potentials.

The selected atoms are specified by the string \verb+atoms+ which
takes the form

\begin{verbatim}
[{isgm [ - jsgm ] [,]} [:] [{aname[,]}]
\end{verbatim}

For example, all carbon and oxygen atoms in segments 3
and 6 through 12 are selected for group 1 by

\begin{verbatim}
3,6-12:_C????,_O????
\end{verbatim}

\begin{verbatim}
pmf [all] [bias] zalign <integer isel> <real forcon1> <real forcon2>
pmf [combine] [bias] xyplane <integer isel> <real forcon1> <real forcon2>
pmf [constraint] [bias] (distance | zdistance) <integer isel> <integer jsel> \
             <real dist1> <real dist2> <real forcon1> <real forcon2>
pmf [bias] angle <integer isel> <integer jsel> <integer ksel> \
             <real angle1> <real angle2> <real forcon1> <real forcon2>
pmf [bias] torsion <integer isel> <integer jsel> <integer ksel> <integer lsel> \
             <real angle1> <real angle2> <real forcon1> <real forcon2>
pmf [bias] basepair <integer isel> <integer jsel> \
             <real dist1> <real dist2> <real forcon1> <real forcon2>
pmf [bias] (zaxis | zaxis-cog) <integer isel> <integer jsel> <integer ksel> \
             <real dist1> <real dist2> <real forcon1> <real forcon2>
\end{verbatim}

Directive \verb+pmf+ specifies a potential of mean force potential
in terms of the specified atom selection. Option \verb+zalign+ specifies
the atoms in the selection to be restrained to a line parallel to the
z-axis. Option \verb+xyplane+ specifies the atoms in the selection to
be restrained to a plane perpendicular to the z-axis. Options
\verb+distance+, \verb+angle+ and \verb+torsion+, are defined in terms
of the center of geometry of the specified atom selections.
Keyword \verb+basepair+ is used to specify a harmonic potential between
residues \verb+isel+ and \verb+jsel+. Keywords \verb+zaxis+ and \verb+zaxis-cog+
can be used to pull atoms toward the z-axis.
Option \verb+all+ may be specified to apply an equivalent pmf to each
of the equivalent solute molecules in the system.
Option \verb+combine+ may be specified to apply the specified pmf to
the atoms in all of the equivalent solute molecules.
Option \verb+constraint+ may be specified to a distance pmf to treat
the distance as a contraint.
Option \verb+bias+ may be specified to indicate that this function
should be treated as a biasing potential. Appropriate corrections
to free energy results will be evaluated.

\section{Generating a restart file}

\begin{verbatim}
new_rst
\end{verbatim}

Keyword \verb+new_rst+ will cause an existing restart file to be
overwritten with a new file.

The follwing directives control the manipulation of restart
files, and are executed in the order in which they
appear in the \prepare\ input deck.

\begin{verbatim}
solvent name <string*3 slvnam default ``HOH''> \
        model <string slvmdl default ``spce''>
\end{verbatim}

The solvent keyword can be used to specify the three letter solvent name
as expected on the PDB formatted file, and the name of the solvent model
for which solvent coordinates will be used.

\begin{verbatim}
solvate   [ < real rshell default 1.2 > ] \
        ( [ cube [ <real edge> ]] |  \
          [ box [ <real xedge> [ <real xedge> [ <real xedge> ]]]] | \
          [ sphere <real radius> ] |
          [ troct <real edge> ])
\end{verbatim}

Solvation can be specified to be in a cubic box with specified edge,
rectangular box with specified edges, or in a sphere with specified
radius. Solvation in a cube or rectangular box will automatically also
set periodic boundary conditions. Solvation in a sphere will only allow
simulations without periodic boundary conditions. The size of the cubic
and rectangular boxes will be expanded by a length specified by the
expand variable. If no shape is specified, solvation will be done for
a cubic box with an edge that leaves rshell nm between any solute atom and
a periodic image of any solute atom after the solute has been centered.
An explicit \verb+write+ is not needed to write the restart file.
The \verb+solvate+ will write out a file \verb+sys_calc+.rst.
If not specified, the dimension of the solvation cell will be as large
as to have at least a distance of \verb+rshell+ nm between any solute atom
and the edge of the cell. The experimental \verb+troct+ directive generates
a truncated octrahedral box.

\begin{verbatim}
touch <real touch default 0.23>
\end{verbatim}

The variable \verb+touch+ specifies the minimum distance between a solvent
and solute atom for which a solvent molecule will be accepted for solvation.

\begin{verbatim}
envelope <real xpndw default 0.0>
\end{verbatim}
sets the expand vealues to be used in \verb+solvate+ operations.

\begin{verbatim}
expand <real xpndw default 0.1>
\end{verbatim}

The variable \verb+xpndw+ specifies the size in nm with which the simulation
volume will be increased after solvation.

\begin{verbatim}
read [rst | rst_old | pdb] <string filename>
write [rst | [solute [<integer nsolvent>]] ( [large] pdb | xyz)] <string filename>
\end{verbatim}

These directives read and write the file \verb+filename+ in the specified
format. The \verb+solute+ option instructs to write out the coordinates
for solute and all, or if specified the first \verb+nsolvent+, crystal solvent
molecules only.
If no format is specified, it will be derived from the extension of the
filename. Recognized extensions are rst, rst\_old (read only), pdb, xyz
(write only) and pov (write only).
Reading and then writing the same restart file will cause the
sub-block size information to be lost. If this information needs to be
retained a shell copy command needs to be used.
The \verb+large+ keyword allows PDB files to be written with more than 9999
residues. Since the PDB file will not conform to the PDB convention, this
option should only be used if required. NWChem will be able to read the
resulting PDB file, but other codes may not.

\begin{verbatim}
scale <real scale default -1.0>
\end{verbatim}

This directive scales the volume and coordinates written to povray files.
A negative value of scale (default) scales the coordinates to lie
in [-1:1].

\begin{verbatim}
cpk [<real cpk default 1.0>]
\end{verbatim}

This directive causes povray files to contain cpk model output. The
optional value is used to scale the atomic radii. A neagtive value
of cpk resets the rendering to stick.

\begin{verbatim}
center | centerx | centery | centerz
\end{verbatim}

These directives center the solute center of geometry at the origin,
in the y-z plane, in the x-z plane or in the x-y plane, respectively.

\begin{verbatim}
orient
\end{verbatim}

This directive orients the solute principal axes.

\begin{verbatim}
translate [atom | segment | molecule] \
	 <integer itran> <integer itran> <real xtran(3)>
\end{verbatim}

This directive translates solute atoms in the indicated range by xtran,
without checking for bad contacts in the resulting structure.

\begin{verbatim}
rotate [atom | segment | molecule] \
	 <integer itran> <integer itran> <real angle> <real xrot(3)>
\end{verbatim}

This directive rotates solute atoms in the indicated range by angle
around the vector given by xrot,,
without checking for bad contacts in the resulting structure.

\begin{verbatim}
remove solvent [inside | outside] [x <real xmin> <real xmax>] \
[y <real ymin> <real ymax>] [z <real zmin> <real zmax>]
\end{verbatim}

This directive removes solvent molecules inside or outside the
specified coordinate range.

\begin{verbatim}
periodic
\end{verbatim}

This directive enables periodic boundary conditions.

\begin{verbatim}
vacuo
\end{verbatim}

This directive disables periodic boundary conditions.

\begin{verbatim}
grid <integer mgrid default 24> <real rgrid default 0.2>
\end{verbatim}

This directive specifies the grid size of trial counter-ion positions and
minimum distance between an atom in the system and a counter-ion.

%\begin{verbatim}
%fix ( atoms | segments ) ( beyond | within ) <real rfix> <string atmfix>
%\end{verbatim}
%
%The \verb+fix+ keyword may be used to specify that the identified
%atoms should remain fixed during any operation.
%

\begin{verbatim}
crop
\end{verbatim}
prints minimum and maximum solute coordinates.

\begin{verbatim}
boxsize
\end{verbatim}
specifies to redetermine the box size.

\begin{verbatim}
cube
\end{verbatim}
specifies to redetermine the smallest cubic box size.

\begin{verbatim}
box <real xsize> <real ysize>  <real zsize>
\end{verbatim}

The \verb+box+ directive resets the box size.

\begin{verbatim}
align <string atomi> <string atomj> <string atomk>
\end{verbatim}

The \verb+align+ directive orients the system such that
\verb+atomi+ and \verb+atomj+ are on the z-axis, and \verb+atomk+
in the x=y plane.

\begin{verbatim}
repeat [randomx | randomy | randomz] [chains | molecules | fractions ] \
 <integer nx> <integer ny> <integer nz> [<real dist>] [<real zdist>]
\end{verbatim}

The \verb+repeat+ directive causes a subsequent \verb+write pdb+
directive to write out multiple copies of the system, with \verb+nx+
copies in the x, \verb+ny+ copies in the y, and \verb+nz+ copies in
the z-direction, with a minimum distance of \verb+dist+ between any
pair of atoms from different copies. If \verb+nz+ is -2, an inverted
copy is placed in the z direction, with a separation of \verb+zdist+ nm.
If \verb+dist+ is negative, the box dimensions will be used.
For systems with solvent, this directive should be used with a negative
\verb+dist+.
Optional keywords \verb+chains+, \verb+molecules+ and \verb+fractions+
specify to write each repeating solute unit as a chain, to repeat
each solute molecule, or each solute fraction separately. Optional
keywords \verb+randomx+, \verb+randomy+, and \verb+randomz+ can be used
to apply random rotations for each repeat unit around a vector through
the center of geometry of the solute in the x, y or z direction.

\begin{verbatim}
skip <integer ix> <integer iy> <integer iz>
\end{verbatim}

The \verb+skip+ directive can be used to skip single repeat unit
from the \verb+repeat+ directive. Up to 100 \verb+skip+ directives
may be specified, and will only apply to the previously specified
\verb+repeat+ directive.

\begin{verbatim}
(collapsexy | collapsez) [ <integer nmoves>]
\end{verbatim}
specifies to move all solute molecules toward the \verb+z+-axis or
\verb+x=y+-plane, respectively, to within a distance of \verb+touch+
nm between any pair of atoms from different solute molecules. Parameter
\verb+nmoves+ specifies the number of collapse moves that will be made.
Monatomic ions will move with the nearest multi-atom molecule.

\begin{verbatim}
collapse_group <integer imol> <integer jmol>
\end{verbatim}
specifies that molecule jmol will move together with molecule imol in
collapse operations.

\begin{verbatim}
merge <real xtran(3)> <string pdbfile>
\end{verbatim}
specifies to merge the coordinates found on the specified pdb file
into the current structure after translation by xtran(3).