All molecular modeling programs generally need to know what are the atoms
in all residue types, what are the atom pairs that are covalently bonded
to each other (\ie, molecular topology), and what are the ideal bond lengths, 
angles, dihedral angles, and improper dihedral angles (\ie, internal 
coordinates and stereochemical restraints). For a given MODEL, these 
data are constructed mostly from information in the residue topology 
and parameter libraries. This section describes the commands for reading 
and writing parameter and residue topology libraries, and for generating, 
patching, and mutating molecular topology.

\subsection{Modeling residues with non-existing or incomplete entries in the 
            topology and parameter libraries}

Defining new residue types is
generally one of the more painful areas in developing and using a molecular 
modeling program. \MODELLER\ has two quick-and-dirty solutions described 
in the next two sections that are often sufficient for comparative modeling 
involving new residue types. On the other hand, if you are willing to spend 
some time and define a new entry or complete an incomplete entry in the residue 
topology or parameter libraries, see the FAQ Section~\ref{SECTION:faq}, 
Question~\ref{FAQ:restop}.

\subsubsection{Residues with defined topology, but with missing 
parameters} \label{SECTION:restopundefined}

The parameter library is used by the \C{MAKE\_RESTRAINTS} command 
to construct bond, angle, dihedral angle, improper dihedral angle, 
and non-bonded Lennard-Jones restraints. If some parameters for
these restraints are missing, they are guessed on the fly from the 
current Cartesian 
coordinates of the MODEL. Thus, when there are missing parameters,
the MODEL coordinates must be defined before calling \C{MAKE\_RESTRAINTS}.
The coordinates can be defined by the \C{BUILD\_MODEL} command
(from the IC entries in the residue topology library), by the \C{READ\_MODEL}
command (from an existing coordinate file for MODEL), or by the 
\C{TRANSFER\_XYZ} command (from template coordinate files aligned
with MODEL). The bonds, angles, and improper dihedral angles are 
restrained by a harmonic potential with the mean equal to the value in the
current structure and a force constant typical for chemical bonds, angles,
and improper dihedral angles, respectively. The dihedral angles are restrained 
by a tri-modal cosine term with the mean equal to the angle in the current
structure. A message detailing \MODELLER's improvization is written 
to the \logf\ file.


\subsubsection{Block (BLK) residues with undefined 
topology and parameters}\index{BLOCK residues}\label{SECTION:block}

The second relatively easy way of dealing with missing entries in the 
residue topology and/or parameters libraries is to use a ``block'' 
residue. These residues are restrained more or less as rigid bodies 
to the conformation of the equivalent residue(s) in the template(s). 
No chemical information is used. The template residues
can themselves be defined as block residues. The symbol for the block
residues is `BLK' in the four- and three-letter codes and `.' in the 
single-letter code. The atoms in a BLK residue include all uniquely 
named atoms from the equivalent residues in all the templates.
The atom type of all BLK atoms is the \CHARMM\ type {\tt `undf'}. 
The IUPAC atom names (as opposed to the atom types) are the
same as in the templates. The {\tt `undf'} atom type for all BLK 
atoms facilitates using the \C{PICK\_ATOMS} command for generating 
restraints on the `BLK' residues.

The {\tt `undf'} atoms are treated differently from the other atoms 
during preparation of dynamic restraints: No pairs of intra-BLK atoms 
are put on the dynamic non-bonded list. Only the ``inter-BLK'' atom pairs 
and ``BLK--other'' atom pairs are considered for the dynamic non-bonded 
restraints. The radius of all block atoms is obtained from the
\V{\$RADII\_LIB} library using the block atom names (as written out to
a PDB file), not the {\tt `undf'} atom type. All intra-BLK and inter-residue 
BLK restraints other than the non-bonded restraints have to be derived 
separately and explicitly by \C{MAKE\_RESTRAINTS} command using 
\K{RESTRAINT\_TYPE} = \V{'distance'}. See script {\tt scripts/\_\_homcsr.top} 
for the routine that makes block restraints for comparative modeling
by the {\tt `model'} script. Lennard-Jones, electrostatic, and 
general non-bonded spline terms involving {\tt `undf'} atoms are 
ignored by \MODELLER.

For an example of how to use block residues, see the FAQ Section~\ref{SECTION:faq},
Question~\ref{FAQ:block}.

\beautypb

\Command      {READ\_RESTYP\_LIB}{read residue type library}

\Options{
\OptLine{RESTYP\_LIB\_FILE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command reads residue types from the residue 
type library specified by variable \K{RESTYP\_LIB\_FILE}.
See the FAQ Section~\ref{SECTION:faq}, Question~\ref{FAQ:restop} 
for the format of this file. \MODELLER\ reads the default residue 
type library during startup; this command can be used to read 
residue type definitions for new residue types defined by the user
without editing the default residue type library.
}


\Example{../examples/commands/read_restyp_lib.top}



\Command      {READ\_TOPOLOGY}{read residue topology library}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ADD\_TOPOLOGY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command reads residue topologies
from the topology library, such as the \CHARMM~22 topology file
\cite{CHARMM98} (it also reads which subsets of atoms correspond
to each \K{TOPOLOGY\_MODEL} from library \Z{MODELS\_LIB}). This
file must include atomic connectivities of residues and patching
residues, and the internal coordinates for minimum energy residue
conformations. Patching residues modify residues; for example,
N-terminus, C-terminus and disulfide bonds are defined by patching the
original topology. This information is used for generating the
molecular topology and possibly for calculating an initial
conformation. The default topology for comparative modeling by
\MODELLER\ includes only non-hydrogen atoms (\K{TOPOLOGY\_MODEL} = \V{3}).
To define your entries in the topology library,
see the FAQ Section~\ref{SECTION:faq}, Questions~\ref{FAQ:restop} and
\ref{FAQ:respatch}.

If \K{ADD\_TOPOLOGY} is \V{on}, the new residue topologies are added to the
existing 
residue topologies, otherwise the new topology file replaces the old one. 
If the topology for a residue is duplicated only the last definition is kept.

Not all the features of the \CHARMM~22 topology library are implemented in
\MODELLER, although a \CHARMM\ file should be read in successfully. A
variety of topology files for different kinds of models can be
prepared by the \C{MAKE\_TOPOLOGY\_MODEL} command.  

The filename for the library is \K{DIRECTORY}/\K{FILE}.
}

\SeeExample{\C{PATCH}}


\Command      {READ\_PARAMETERS}{read parameters library}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ADD\_PARAMETERS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command reads the parameters from the parameter
library, such as the \CHARMM~22 parameter file for proteins with
all atoms \cite{CHARMM98}. This file contains the values for 
bond lengths, angles,
dihedral angles, improper dihedral angles, and non-bonded interactions.
\MODELLER\ relies on slightly modified \CHARMM-22 parameters to reproduce the
protein geometry in the \MODELLER\ environment. For example, for the
default non-hydrogen atoms model, the $\omega$ dihedral angle restraints
are stronger than the original \CHARMM~22 values which apply to
the all-hydrogen model. For a sparse discussion of the parameter
library, see the FAQ Section~\ref{SECTION:faq}, Question~\ref{FAQ:restop}.

If \K{ADD\_PARAMETERS} is \V{on}, the new parameters are added to the existing
parameter list, otherwise the contents of the new parameter file 
replaces the old one.

The filename for the library is \K{DIRECTORY}/\K{FILE}.
}

\SeeExample{\C{PATCH}}


\Command      {READ\_ATOM\_CLASS}{read classification of atom types}

\Options{
\OptLine{ATOM\_CLASSES\_FILE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command reads a \MODELLER\ classification of atom 
types from file
\K{ATOM\_CLASSES\_FILE}. This particular atom type classification is used 
for calculation of the special non-bonded terms other than the soft-sphere,
Lennard-Jones or Coulomb terms (for which the \CHARMM\ atom type classification
is used). These terms are usually the statistical potentials of mean force
described by non-bonded spline restraints, including single body and two 
body terms. The default atom classification is read during \MODELLER\ 
initialization.
}

\Example{../examples/commands/read_atom_classes.top}


\Command      {GENERATE\_TOPOLOGY}{generate MODEL topology}     

\Options{
\OptLine{ADD\_SEGMENT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{PATCH\_DEFAULT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ALIGN\_CODES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SEQUENCE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ATOM\_FILES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ATOM\_FILES\_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{WATER\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HETATM\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HYDROGEN\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{TOPOLOGY\_MODEL}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {topology and parameter libraries}

\Description  {This command calculates MODEL's covalent topology (\ie,
atomic connectivity) and internal coordinates, and assigns \CHARMM\ atom types,
\MODELLER\ atom types for non-bonded spline restraints, atomic charges, 
and atomic radii.

If a protein with code \K{SEQUENCE} is found in the current 
alignment (codes of proteins in the current alignment are stored in
\K{ALIGN\_CODES}), this protein's topology is calculated. If no
\K{SEQUENCE} entry exists or if the alignment does not exist, the
sequence of the MODEL is used. If the MODEL does not exist, an error
is reported. The MODEL can be read in from an atomic coordinates file
with the \C{READ\_MODEL} command.

The new sequence is added to the list of segments of the MODEL if
\K{ADD\_SEGMENT} is \V{on}, otherwise this list is initiated. 

A sequence in the alignment can use any non-patching residue listed in
the single-character code column of the \V{\$RESTYP\_LIB} library
(\Z{modlib/restyp.lib}).
Examples of non-standard residue types include water (\Z{w}), zinc 
(\Z{z}), calcium (\Z{3}), heme (\Z{h}), and many others.  
Patching residues must not
be used here, but with the subsequent \C{PATCH} commands. Unrecognized
residues are ignored. A special allowed residue type is the chain
break `/'.  This can be used to construct a protein that consists of
several chains separated by chain breaks. 
Chain breaks before a non-standard residue
type (there are 23 standard residue types, including \Z{-}, \Z{Asx} and
\Z{Glx}) are inserted automatically and do not have to be specified 
explicitly in the sequence. 

The \C{GENERATE\_TOPOLOGY} command generates only the topology of the
MODEL, not its Cartesian coordinates; the Cartesian coordinates
are assigned by the \C{BUILD\_MODEL}, \C{TRANSFER\_XYZ}, or 
\C{READ\_MODEL} commands.

In general, the \C{GENERATE\_TOPOLOGY} command has to be executed before
any energy commands (\C{ENERGY}, \C{OPTIMIZE}, \C{PICK\_HOT\_ATOMS}). 
The reason is that reading the Cartesian coordinates by 
the \C{READ\_MODEL} command does not generate all the data usually needed
for energy evaluation. However, if the order and number of atoms in the input
file correspond exactly to the order and number of atoms implied by the
restraint atom indices and if you are not using dynamic restraints
that rely on non-existing data, such as bond, angle, and dihedral
angle lists, atomic charges, radii, Lennard-Jones parameters, 
\MODELLER\ atom  types, or \CHARMM\ atom types
(which are used to determine the atomic radii), it is sufficient
to do only \C{READ\_MODEL} and omit \C{GENERATE\_TOPOLOGY} before the 
energy commands. In short, if you use static restraints alone and if the 
atom file has the atoms in the correct order, you do not have to call
\C{GENERATE\_TOPOLOGY} before calculating energy.

The variables \K{ATOM\_FILES}, \K{ATOM\_FILES\_DIRECTORY},
\K{WATER\_IO}, \K{HETATM\_IO}, \K{HYDROGEN\_IO}, and \K{TOPOLOGY\_MODEL}
are necessary only when the \Z{BLOCK} residues are present in the sequence
whose topology is generated. In that case, the template PDB files are
read in.}

\SeeExample{\C{PATCH}}


\Command      {PATCH}{patch MODEL topology}     

\Options{
\OptLine{RESIDUE\_IDS}{TYPE}{VALUES}{DEFAULT}{identifiers of the patched residues} 
\OptLine{RESIDUE\_TYPE}{TYPE}{VALUES}{DEFAULT}{patching residue type} 
\OptLine{TOPOLOGY\_MODEL}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command uses a \CHARMM\ patching residue to patch 
the topology of the MODEL. \CHARMM\ patch rules are observed.

\K{RESIDUE\_TYPE} is the type of the patching residue (\V{PRES} entry in
the topology library), such as \Z{DISU}, \Z{NTER}, \Z{CTER}, \etc.  You do not
have to apply explicitly the N- and C-terminal patches to protein chains
because the \Z{NTER} and \Z{CTER} patches are applied automatically to the 
appropriate residue types at the termini of each chain at the
end of each \C{GENERATE\_TOPOLOGY} command. 

\K{RESIDUE\_IDS} are residue identifiers of the patched
residues (Section~\ref{alignmentformat}). The first residue is
the patched residue 1, the second residue is the patched residue 2, \etc;
for example, the \Z{DISU} patching residue has two patched Cys residues
while the \Z{ACE} patching residue has only one patched residue.
The order of the residue identifiers here has to match the definition
of the patching residue in the topology library.

It is not allowed to patch an already patched residue. Since the
N- and C-terminal residues of each chain are automatically patched
with the \Z{NTER} and \Z{CTER} patching residues, respectively,
a user who wants to patch the N- or C-terminal residues with other
patches, should turn the default patching off before executing 
\C{GENERATE\_TOPOLOGY}. This is achieved by 
\C{SET} \K{PATCH\_DEFAULT} = \V{off}.
}


\Example{../examples/commands/patch.top}





\Command      {PATCH\_SS\_TEMPLATES}{guess MODEL disulfides from templates}        

\Options{
\OptLine{ALIGN\_CODES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ATOM\_FILES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ATOM\_FILES\_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{WATER\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HETATM\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HYDROGEN\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{TOPOLOGY\_MODEL}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {alignment}

\Output {\K{DISTANCE\_ATOMS}}

\Description  {This command defines and patches disulfide bonds in the
MODEL using an alignment of the MODEL sequence with one or more template 
structures. The MODEL sequence has to be the last sequence in the alignment.
The template structures are all the other proteins in the alignment. All
Cys--Cys pairs in the target sequence that are aligned with at least
one template disulfide are defined as disulfide bonds themselves.
The covalent connectivity is patched accordingly.

If no alignment exists, a default 1:1 alignment is constructed.
Variable \K{ATOM\_FILES} can be used to specify template structures. 

This command should be run after \C{GENERATE\_TOPOLOGY} and before
\C{MAKE\_RESTRAINTS} to ensure that the disulfides are restrained
properly by the bond length, angle, and dihedral angle restraints and
that no SG--SG non-bonded interactions are applied. 

The disulfide
bond, angle and dihedral angle restraints have their own physical
restraint type separate from the other bond, angle and dihedral angle
restraints (Table~\ref{tab:physrsrtypes}).

\K{DISTANCE\_ATOMS} becomes \V{CA} \V{SG}.
}


\Example{../examples/commands/patch_disulfides.top}





\Command      {PATCH\_SS\_MODEL}{guess MODEL disulfides from model structure}        
\Options{
\OptLine{TOPOLOGY\_MODEL}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {model}

\Description  {This command defines and patches disulfide bonds in MODEL 
using MODEL's current structure. A disulfide bridge is declared between 
all pairs of Cys residues whose SG--SG distances are less than 2.5\Ang. 
The covalent connectivity is patched accordingly.

This command should be run after \C{READ\_MODEL} and before
optimization to ensure that the disulfides are fixed properly
and that no SG--SG non-bonded interactions are applied. 

\K{TOPOLOGY\_MODEL} is needed to make sure the correct atomic radii
are used in CYS--CYS patching.
}

 
\SeeExample{\C{PATCH\_SS\_TEMPLATES}}
 




\Command      {MUTATE\_MODEL}{mutate selected MODEL residues}

\Options{
\OptLine{RESIDUE\_TYPE}{TYPE}{VALUES}{DEFAULT}{new residue type} 
}

\Description  {This command mutates the selected residues of the MODEL
to the type specified by \K{RESIDUE\_\-TYPE}. \CHARMM\ 4-character
residue type names are used (see library file \V{\$RESTYP\_LIB}).  To select
the residues for mutation, use \C{PICK\_ATOMS} command. All the 
residues with at least one atom in the selected set 1 of atoms 
are mutated. To produce
mutants, employ this command with \C{SEQUENCE\_TO\_ALI} and
\C{WRITE\_ALIGNMENT}.  It is usually necessary to write the mutated 
sequence out and read it in before proceeding, because not all
sequence related information about MODEL is changed by this command
(\eg, internal coordinates, charges, and atom types and radii 
are not updated).  }


\Example{../examples/commands/mutate_model.top}




\Command      {MAKE\_TOPOLOGY\_MODEL}{make a subset topology library}
\label{make-topology-model}

\Options{
\OptLine{TOPOLOGY\_MODEL}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command makes a residue topology library
from the most detailed \CHARMM\ topology library, which contains all atoms,
including all hydrogens (corresponding to \K{TOPOLOGY\_MODEL} = 1). There are 
currently ten residue topologies, all of which are defined in library {\tt
\$MODELS\_LIB}. For example, the default non-hydrogen atom topology is selected
by \K{TOPOLOGY\_MODEL} = 3. For each \K{TOPOLOGY\_MODEL} and residue
type, the {\tt \$MODELS\_LIB} library lists those atoms in the full 
atom set that are part of the specified topology. This command works
by deleting all the entries that contain non-existing atoms from the
original topology file. One must carefully test topology files produced in
this way. Library {\tt \$RADII\_LIB} must specify atomic radii for each
atom in each residue type for each topology model. \K{TOPOLOGY\_MODEL} must
be an integer from 1 to 10. For more information about the topology
library, see the FAQ Section~\ref{SECTION:faq}, Questions~\ref{FAQ:restop} and
\ref{FAQ:respatch}. }



\Example{../examples/commands/make_topology_model.top}



\Command      {WRITE\_TOPOLOGY\_MODEL}{write residue topology library}
\label{write-topology-model}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{OUTPUT\_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command writes a residue topology library to 
the specified file. It is usually used after \beautylb
\C{MAKE\_\-TOPOLOGY\_MODEL}.  }

\SeeExample{\C{MAKE\_TOPOLOGY\_MODEL}}

\vfill
