Sections in this Chapter describe technical aspects of \MODELLER. 
They include:

\begin{itemize}
\item miscellaneous rules and features of \MODELLER\ (Section~\ref{SECTION:misc});

\item dealing with stereochemical parameters and molecular topology
      (Section~\ref{SECTION:topology});

\item handling of atomic coordinates 
      (Section~\ref{SECTION:model});

\item comparing and searching of sequences and structures 
      (Section~\ref{SECTION:compare}); 

\item calculating spatial restraints 
      (Section~\ref{SECTION:restraints}), 

\item deriving the model by minimizing the restraints 
      (Section~\ref{SECTION:energy}).

% \item modeling of loops
%       (Section~\ref{SECTION:loops}).
\end{itemize}

\section{Miscellaneous rules and features of \MODELLER}
\label{SECTION:misc}

This Section describes several features of the program, including 
file naming conventions, various file types, and the control of the 
amount of output.

\subsection{\MODELLER\ system}

One of the main aims of \MODELLER\ is to allow for flexible 
exploration of various modeling protocols to facilitate 
the development of better modeling methods. \MODELLER\ can
be seen as an interpreted language that is specialized for
modeling of protein 3D structure. \MODELLER's organization
is hierarchical and modular: \\

User script files. \\
\noindent\rule{10mm}{0cm} \MODELLER\ tasks (\eg, \Z{model}). \\
     \rule{20mm}{0cm} Library of \MODELLER's routines. \\
        \rule{30mm}{0cm} \TOP\ interpretor commands. \\
           \rule{40mm}{0cm} \TOP\ intepretor. \\
               \rule{50mm}{0cm} \MODELLER\ source code. \\[1cm]


\subsection{Running \MODELLER\ scripts}\index{script file}

\MODELLER\ is run by
\begin{verbatim}
mod script_file_name
\end{verbatim}
where \V{script\_file\_name} is the name of the script file with
instructions for \MODELLER. This file contains commands 
in the \TOP\ language. Each command line consist of the name of the
command and optional variable assignments that control the action of
the command. The scope of the variables is global; that is, once a
variable is assigned on any command line, the assigned value remains
in effect, in the main program and all subroutines, until explicitly 
changed by another assignment or, in a few cases, by \MODELLER. 
All the commands and the default values
of the variables are listed in Section~\ref{SECTION:topini}. This 
Chapter describes the \TOP\ commands that are used for dealing with
proteins; the general \TOP\ commands (\eg, assignment, flow control,
arithmetic operations) are described in Chapter~\ref{CHAPTERTOP}.

See directory \V{examples} for examples of the \TOP\ scripts that use
commands described in this Chapter. In particular, sub-directory
\V{examples/commands} contains the examples used in this Chapter.
Another set of \TOP\ scripts that you could use as templates can be 
found in the \V{scripts} directory.

\subsection{Controlling breakpoints and the amount of output}\index{breakpoint}
\label{SECTION:breakpoint}

Some errors are recoverable. For those errors, \TOP\ variable 
\K{MODELLER\_STATUS}
becomes 1. A test is then performed: If \K{MODELLER\_STATUS} is equal 
or greater then \K{STOP\_ON\_ERROR}, execution stops; otherwise, the control 
is passed back to the calling \TOP\ routine where execution continues with
the next \TOP\ command. It is then up to your
\TOP\ script to deal sensibly with the failure of the preceding command.
For example, this flexibility allows derivation of multiple models and
searching for many sequences, even if some cases abort due to convergence 
problems.

There are five kinds of messages that \MODELLER\ writes to the 
\logf\ file, indexed 1 to 5: long output from the \MODELLER\ commands, 
short notes to do with the execution of the program (files opened, \etc.), 
warnings identified by {\tt `\_W>'}, errors 
identified by {\tt `\_E>'}, and the messages about the status of dynamic
memory allocation. The five elements in the \TOP\ variable 
\K{OUTPUT\_CONTROL}[1:5] can assume values of 0 or `not 0'; 0 indicates that 
the corresponding information is not written out, `not 0' indicates that it
is.\footnote{This has not been implemented for all the output yet.}
Thus, different amounts of output can be selected. If everything is
well, \K{OUTPUT\_CONTROL} = 1 0 0 1 0 is convenient because no execution
messages, warnings, and dynamic memory reports are written out; 
for debugging, use \K{OUTPUT\_CONTROL} = 1 1 1 1 1. To increase the
detail of the dynamic memory status reports, set the last flag to 2.

\subsection{File naming}\index{file naming}
 \label{SECTIONFILENAME}

There are several filename generating mechanisms that facilitate file handling.
Not all of them apply to all file types.

\subsubsection{Environment variables}

There can be \UNIX\ shell environment variables in any input or output 
filename. The environment variables have to be in the format 
\V{\$\{VARNAME\}} or \V{\$(VARNAME)}. Also, four predefined macros are 
available for string variables: 

\begin{itemize}
\item \V{\$\{LIB\}} is expanded into the \V{\$LIB\_MODELLER} variable
      defined in {\tt modlib/libs.lib} (equal to \V{\$MODINSTALL6/modlib});
\item \V{\$\{DIR\}} is expanded into the \TOP\ variable \K{DIRECTORY};
\item \V{\$\{JOB\}} is expanded into the root of the \TOP\ script filename;
\item \V{\$\{DEFAULT\}} is expanded into 
      \V{(ROOT\_NAME)(FILE\_ID)(ID1)(ID2)(FILE\_EXT)},
      where \K{ROOT\_NAME}, \K{FILE\_ID}, \K{ID1}, \K{ID2}, and \K{FILE\_EXT} 
      are \TOP\ variables. \K{FILE\_ID} is a string that may be set to
      \Z{default}. In that case, a hard-wired short string is used instead of
      \K{FILE\_ID}. Otherwise, the explicitly specified \K{FILE\_ID} is
      applied. In any case, \K{FILE\_ID} is not modified by the
      filename generation routine so that it can be used more than once
      without resetting it to the \Z{default} value. Four digits are used
      for both \K{ID1} and \K{ID2}. For example, \Z{2ptn.B99990001}
      results from \K{ROOT\_NAME} = \Z{2ptn}, \K{FILE\_EXT} = \Z{.B}, 
      \K{ID1} = 9999, and \K{ID2} = 1.
\end{itemize}


\subsubsection{Automatic filename generation}

For any filename, input or output, 
if the value of the variable is \Z{default} (case 
insensitive), the actual filename is constructed within the routine 
that will use the filename. The name is constructed by the same rule as that 
for the \V{\$\{DEFAULT\}} environment variable (Section~\ref{SECTIONFILENAME}). 
The only difference between the 
two cases is that {\tt SET FILE = 'default'} may not work as expected if
the \TOP\ variables defining the filename change between the \C{SET}
command and the command that will use the filename,
whereas {\tt SET FILE = '\$\{DEFAULT\}'} will work as expected because
the filename \K{FILE} is actually constructed during the \C{SET} 
command.\footnote{The \Z{default} substitution will be phased out because
it is a subset of the \V{\$\{DEFAULT\}} substitution.}


\subsubsection{Directory prefixes}

\paragraph{Input.}

For many input filenames, the full filename is obtained by
looking for the file in the list of directories specified in the 
\TOP\ variable \K{DIRECTORY}. The directories in
\K{DIRECTORY} are separated by colons (':') (\eg, `dir1:dir2:dir3:...'). 
\K{DIRECTORY} can also contain the current directory (` ' or `./').

The directory prefix for the input atom coordinate filenames is obtained in 
a similar way, except that \K{ATOM\_\-FILES\_\-DIRECTORY} is used instead of 
\K{DIRECTORY}. Moreover, there is an additional mechanism for reading
an atom coordinate file that requires specifying the protein code only 
(see below in Section on coordinate files and derivative data).

The list of directories is not scanned for the input filenames that 
start with '/'.

In contrast, the \K{INCLUDE\_FILE} file is looked for in
the distribution's \V{\$BIN\_MODELLER6} directory (equal to 
\V{\$MODINSTALL6/bin} directory) in addition to the \K{DIRECTORY}
directories. This allows for an easy inclusion of the predefined 
system \Z{\_\_*.top} files by the \C{INCLUDE} command.


\paragraph{Output.}

For all output filenames, except for those that start with '/', 
the full output filename is obtained by pre-fixing the filename with
\K{OUTPUT\_DIRECTORY}.


\subsubsection{Coordinate files and derivative data}
\label{SECTION:pdbent}

When accessing an atom file, a specified filename is tried
first. If this is unsuccessful, \MODELLER\ automatically 
expands the original filename by adding extension \Z{.Z}.
This allows it to detect atom files compressed with the \UNIX\ 
\V{compress} command. If the compressed file exists, \MODELLER\ 
automatically uncompresses it, reads it, and puts it back into the 
original state 
after the reading is finished. If the specified file is still not found, 
the extensions \Z{.atm}, \Z{.pdb}, \Z{.ent}, and \Z{.crd} 
are tried in this order, without and with extension \Z{.Z},
then also with the \Z{pdb} prefix. This search for the atom file
is repeated through all the directories in \K{ATOM\_FILES\_DIRECTORY}
(directories are separated by \Z{:}), unless input atom filename starts
with \Z{/}, in which case \K{ATOM\_FILES\_DIRECTORY} is neglected. Finally, 
if still unsuccessful and the file specified by the environment variable 
\V{\$PDBENT} exists, the coordinate filename (\eg, the 4 character PDB 
code) is matched to the list of the full PDB filenames in \V{\$PDBENT} 
(compressed and uncompressed). For example, \V{\$PDBENT} file may be:

\begin{verbatim}
/disk2/pdb/pdb.pdb.bnl.gov/all_entries/uncompressed_files/pdb1ema.ent
/disk2/pdb/pdb.pdb.bnl.gov/all_entries/uncompressed_files/pdb1hbp.ent
/disk2/pdb/pdb.pdb.bnl.gov/all_entries/uncompressed_files/pdb1gpy.ent
/disk2/pdb/pdb.pdb.bnl.gov/all_entries/uncompressed_files/pdb6gpb.ent
/disk2/pdb/pdb.pdb.bnl.gov/all_entries/uncompressed_files/pdb1fia.ent
etc.
\end{verbatim}

Any derivative data that \MODELLER\ may need, including residue solvent
accessibilities, hydrogen bonding information, dihedral angles, residue
neighbors, \etc., are calculated on demand from the atomic
coordinates. The most time consuming operation is calculating
solvent accessibility, but even this calculation takes less than 1 
sec for a 200 residue protein on a Pentium III workstation.

\MODELLER\ stores the filenames of coordinate sets in the alignment 
arrays. These arrays are used by \C{COMPARE}, \C{MAKE\_RESTRAINTS},
\C{MALIGN3D}, \C{ALIGN2D}, and several other commands. If these filenames 
do not change when the structures are needed for the second time, 
the coordinate files are not re-read because they should already be
in memory. This creates a problem only when the contents of a structure 
file changes since it was last read during the current job.


\subsection{File types}\index{file types}

\MODELLER\ uses a number of standard filename extensions to indicate the
type of data stored in a file (Table~\ref{tab:filetypes}). The 
extensions are generally not mandatory, only very helpful.


\subsection{Format of the command description}

For each command, the list of arguments, brief description, and an example 
are given. Additional background information may be found in 
Chapter~\ref{CHAPTER:methods}. The variable types are described as 
follows (see also Table~\ref{tab:vartypes}):

\begin{table}[h]
\begin{center}
\begin{tabular}{ll}
\Integer{1}\         & an integer variable or constant \\
\Real{1}\            & a real variable or constant \\
\String{1}\          & a string variable or constant \\
\Logical{1}\         & a logical variable or constant \\
\Integer{0}\         & a vector of any length with elements \Integer{1} \\
\Integer{N}\         & a vector of $N$ elements \Integer{1} \\
\etc.                & the same for real, string, and logical types \\
\end{tabular}
\end{center}
\end{table}

\vspace{10mm}

\begin{table}[H]
\begin{center}
\begin{tabular}{ll} \hline
Extension & Description \\ \hline
\V{.top}   & TOP script with instructions for a \MODELLER\ job \\
\V{.log}   & log output produced by a \MODELLER\ run \\
\V{.ali}   & alignment or sequences in the PIR format \\
\V{.pap}   & alignment or sequences in the PAP format \\
\V{.aln}   & alignment or sequences in the \QUANTA\ format \\
\V{.aln}   & alignment or sequences in the \INSIGHT\ format \\
\V{.seq}, \V{.chn} & sequence(s) in the PIR alignment format \\
\V{.cod}   & list of sequence codes \\
\V{.grp}   & list of families in PDB \\
\V{.atm}, \V{.pdb}, \V{.ent}  &  atom coordinates in the PDB or \GRASP\ format \\
\V{.crd}   & atom coordinates in the \CHARMM\ format \\
\V{\_fit.pdb} & fitted protein structures in the PDB format \\
\V{.ini}   & initial \MODELLER\ model \\
\V{.B*}    & \MODELLER\ model in the PDB format \\
\V{.D*}    & the progress of optimization \\
\V{.BL*}   & \MODELLER\ model in the PDB format, in loop modeling \\
\V{.DL*}   & the progress of optimization, in loop modeling \\
\V{.IL*}   & initial \MODELLER\ model, in loop modeling \\
\V{.V*}    & violations profile \\
\V{.E*}    & energy profile \\
\V{.rsr}   & restraints in MODELLER or USER format \\
\V{.sch}   & schedule file for the variable target function optimization \\
\V{.mat}   & matrix of pairwise protein distances from an alignment \\
\V{.mat}   & matrix of pairwise residue type--residue type distance scores \\
\V{.sim.mat} & matrix of pairwise residue type--residue type similarity scores \\
\V{.lib}   & various \MODELLER\ libraries \\
\V{.psa}   & residue solvent accessibilities \\
\V{.sol}   & atomic solvent accessibilities \\
\V{.ngh}   & residue neighbors \\
\V{.dih}   & mainchain and sidechain dihedral angles \\
\V{.ssm}   & secondary structure assignment \\
\V{.var}   & sequence variability profile from multiple alignment \\
\V{.asgl}  & data for plotting by \ASGL\ \\ \hline
\end{tabular}
\end{center}
\newcommand{\filetypes}{{\em List of file types.}}
\caption[\filetypes]
{\latex{\filetypes}}
\label{tab:filetypes}
\underfigtab
\end{table}

\clearpage
