This Chapter explains how the restraints are represented
in a restraint file and also describes commands for reading, 
writing, generating, and manipulating restraints.
See Section~\ref{SECTION:eqs} for equations
defining the restraints and their derivatives with respect
to atomic positions. See Section~\ref{SECTION:energy} for
commands for calculating the objective function and
Section~\ref{SECTION:energydesc} for optimization methods.
See the original papers for the most detailed definition
and description of the restraints \cite{SalBlu93,SalOve94}.


\subsection{Specification of restraints}

\subsubsection{Static and dynamic restraints}

{\it Static} restraints are read from the restraints file or are generated by
the \K{MAKE\_RESTRAINTS} command. All other restraints are {\it dynamic} 
restraints and are created on the fly; they currently include
restraints on non-bonded atom pairs.


\subsubsection{Formats of the restraints file}
\label{SECTION:atomid}

Restraints may be read from a restraints file in two formats, MODELLER
or USER. The files in the MODELLER and USER formats have to begin with 
the lines \Z{MODELLER5 VERSION: MODELLER FORMAT} and \Z{MODELLER5 VERSION: USER 
FORMAT}, 
respectively. In both formats, there is one entry per line. The format is
free, except that the first character has to be at the beginning of the
line. There are three different entry types in the MODELLER format:

% {\footnotesize
\begin{verbatim}
R Form Modality Feature Group Numb_atoms Numb_parameters 0 Atom_indices Parameters
E Atom_index_1 Atom_index_2
P Pseudo_atom_index Pseudo_atom_type Numb_real_atoms Real_atom_indices
\end{verbatim}
% }

For example,
\begin{verbatim}
R    3   1   1   1   2   2   0  437   28       1.5000    0.1000
E    120 540
P    1   3   3    120 121 122
\end{verbatim}

When the line starts with \Z{R}, it contains a restraint, \Z{E} indicates
a pair of atoms to be excluded from the calculation of the dynamic non-bonded
pairs list, and \Z{P} indicates a pseudo atom definition 
(Section~\ref{SECTION:pseudo}).

The USER format recognizes only the \V{R} entries. The fields of a line in 
the USER format are:

% {\footnotesize
\begin{verbatim}
Id Form Modality Feature Group Numb_atoms Numb_parameters 0 Parameters Atom_ids
\end{verbatim}
% }

For example,
\begin{verbatim}
R   3  1  1  1  2  2  0    1.5000    0.1000   NH#:1:A    CA:2:A
\end{verbatim}
 
The seven integer indices used to specify various restraint properties
are listed in Tables~\ref{tab:restrtypes}--\ref{tab:physrsrtypes}.
They are: {\tt Form} specifies the mathematical form of the restraint.
{\tt Modality} should be viewed as the
argument to {\tt Form}. It specifies the number of single
Gaussians in a poly-Gaussian pdf, periodicity $n$ of the cosine in the
cosine potential, and the number of spline points for cubic splines.
Only certain combinations of {\tt Form} and {\tt Modality} are
possible. Any {\tt Feature} can be used with any {\tt Form/Modality}
pair. {\tt Group} or ``physical feature type'' groups
restraints for reporting purposes in \C{ENERGY}, \etc. 
The number of atoms and parameters for the restraint are specified 
by {\tt Numb\_atoms} and {\tt Numb\_prms}, respectively. 
The seventh integer index can be ignored.
{\tt Atom\_indices} and {\tt Parameters} have to match the
hard-wired conventions.  The format of the atom id is
ATOM\_NAME:RESIDUE\_\#[:CHAIN\_ID], where ATOM\_NAME is
the four character IUPAC atom name as found in a PDB file,
RESIDUE\_\# is a five character residue number as it occurs
in the PDB file of a model, and the optional CHAIN\_ID is
the single character chain id as it occurs in the PDB file.
For example, the carbonyl oxygen (O) in residue \Z{10A} in
chain \Z{A} is specified by \Z{O:10A:A}; if the chain has no chain id,
the name would be only 'O:10A'.


\begin{sidewaystable}[ht]
{\small
\begin{tabular}{rllll} \hline
\# & {\tt Form} & Parameters & Violation & Reference \\ \hline
1 & left Gaussian (harmonic lower bound) &  
  $\bar{f}, \sigma$ & 
  $(f-\bar{f})/\sigma$ &
  Eq.~\ref{eq:lgaussian} \\ 
2 & right Gaussian (harmonic upper bound) & 
  $\bar{f}, \sigma$ & 
  $(f-\bar{f})/\sigma$ &
  Eq.~\ref{eq:rgaussian} \\ 
3 & single Gaussian (harmonic potential) & 
  $\bar{f}, \sigma$ & 
  $(f-\bar{f})/\sigma$ &
  Eq.~\ref{eq:gaussian}\\ 
4 & multiple Gaussian & 
  $(\omega_i)_n, (\bar{f}_i)_n, (\sigma_i)_n$ & 
  $\max_{\omega_i} (f-\bar{f}_i)/\sigma_i$ &
  Eq.~\ref{eq:poly2gauss} \\
5 & Lennard-Jones potential & 
  $A, B$ & 
  0.0 &
  Eq.~\ref{eq:lennard} \\
6 & Coulomb point-to-point potential & 
  $q_1, q_2$ & 
  0.0 &
  Eq.~\ref{eq:coulomb} \\
7 & Cosine potential & 
  $a,b$ & 
  $c$ &
  Eq.~\ref{eq:cosine} \\
8 & undefined & & & \\
9 & multiple binormal & 
  $(\omega_i)_n, (\bar{f}_{1i}, \bar{f}_{2i})_n, (\sigma_{1i}, \sigma_{2i})_n,(\rho)_n$ &
  $\max_{\omega_i} \sqrt{
              -\frac{1}{2 (1-\rho_i^2)}
               \left[
               \left(\frac{f_1-\bar{f}_{1i}}{\sigma_{1i}}\right)^2 -
               2 \rho_i \frac{f_1-\bar{f}_{1i}} {\sigma_{1i}}
                        \frac{f_2-\bar{f}_{2i}} {\sigma_{2i}} +
               \left(\frac{f_2-\bar{f}_{2i}}{\sigma_{2i}}\right)^2
               \right] } $ &
  Eq.~\ref{eq:poly2gauss} \\
10& cubic spline & $p_i$, for $i=1, 6 + n$ & 
  $(f-f_{min})/\sigma$ &
  Eq.~\ref{eq:spline} \\ \hline
\end{tabular}
}
\newcommand{\restrtypes}{{\em List of mathematical forms of restraints.}}
\caption[\restrtypes]
{\latex{\restrtypes} The parameters and their order in the restraint file
are also given ({\tt Params} above). $(\ldots)_n$ indicates that $(\ldots)$ is 
repeated $n$ times, where $n$ is specified by the second integer parameter
of the restraint, {\tt modality} (see above). {\tt Modality} also defines 
periodicity of the cosine restraint, corresponding to parameter $n$ 
in Eq~\ref{eq:cosine}, and the number of interpolating points for the
spline restraint (Eq.~\ref{eq:spline}). Feature $f$ can generally be either 
a measure of solvent exposure (undocumented), 
a distance, an angle, or a dihedral
angle, with the exception of restraint form 9 that only works with a pair
of dihedral angles. The angle unit in the restraints file is radians. 
The internal angle unit of \MODELLER\ is radians, too. Column \Z{Violation}
defines the ``relative heavy violations'' used in \C{PICK\_HOT\_ATOMS}.
For cubic splines, $f_{min}$ is the feature value that results in the
smallest value of the restraint and $\sigma$ is the standard deviation
of the Gaussian function fitted locally around $f_{min}$. The parameters
$p_i$ for a spline restraint are: the scaling factor ($p_1$), the smallest 
value at which interpolation is done, $x_1$ ($p_2$), the largest interpolating 
value $x_n$ ($p_3$), the interval between interpolating points, 
$\Delta x$ ($p_4$), the first derivative at $x_1$ ($p_5$), the first 
derivative at $x_n$ ($p_6$). The following $n$ values are the values of 
the restraint at the interpolating $x_i$ points. The \MODELLER-4 format has
additional $n$ values, which are the second derivatives of the restraint 
at the interpolating $x_i$ points.
}
\label{tab:restrtypes}
\underfigtab
\end{sidewaystable}


\begin{table}[bt]
\begin{center}

\begin{tabular}{rl} \hline
Index & {\tt Feature} \\ \hline
1 & distance \\
2 & angle  \\
3 & dihedral angle \\
4 & a pair of dihedral angles (points 1--4 and 5--8) \\
5 & distance between gravity centers of two groups of atoms \\
6 & minimal distance between several pairs of atoms \\
7 & atomic area exposed to solvent in $\Ang^2$ \\
8 & number of neighbouring atoms \\ \hline
\end{tabular}

\end{center}
\newcommand{\feattypes}{{\em List of feature types that can be restrained.}}
\caption[\feattypes]
{\latex{\feattypes}}
\label{tab:feattypes}
\underfigtab
\end{table}


\begin{table}[bt]
\begin{center}

\begin{tabular}{rl} \hline
Index & {\tt Group} \\ \hline
 1 &  Bond length potential \\
 2 &  Bond angle potential  \\
 3 &  Stereochemical cosine dihedral potential \\
 4 &  Stereochemical improper dihedral potential \\
 5 &  soft-sphere overlap restraints \\
 6 &  Lennard-Jones 6--12 potential \\
 7 &  Coulomb point-point electrostatic potential \\
 8 &  H-bonding potential \\
 9 &  Distance restraints 1 (\Calpha--\Calpha) \\
10 &  Distance restraints 2 (N--O) \\
11 &  Mainchain $\Phi$ dihedral restraints \\
12 &  Mainchain $\Psi$ dihedral restraints \\
13 &  Mainchain $\omega$ dihedral restraints \\
14 &  Sidechain $\chi_1$ dihedral restraints \\
15 &  Sidechain $\chi_2$ dihedral restraints \\
16 &  Sidechain $\chi_3$ dihedral restraints \\
17 &  Sidechain $\chi_4$ dihedral restraints \\
18 &  Disulfide distance restraints \\
19 &  Disulfide angle restraints \\
20 &  Disulfide dihedral angle restraints \\
21 &  X lower bound distance restraints \\
22 &  X upper bound distance restraints \\
23 &  Distance restraints 3 (SDCH--MNCH) \\ 
24 &  Sidechain $\chi_5$ dihedral restraints \\
25 &  $(\Phi, \Psi)$ binomial dihedral restraints \\
26 &  Distance restraints 4 (SDCH--SDCH) \\ 
27 &  Distance restraints 5 (X--Y) \\ 
28 &  NMR distance restraints 6 (X--Y) \\ 
29 &  NMR distance restraints 7 (X--Y) \\
30 &  Minimal distance restraints \\ 
31 &  Non-bonded spline restraints \\ 
32 &  Atomic accessibility restraints \\
33 &  Atom density restraints \\ \hline
\end{tabular}

\end{center}
\newcommand{\physrsrtypes}{{\em List of ``physical'' restraint types.}}
\caption[\physrsrtypes]
{\latex{\physrsrtypes}}
\label{tab:physrsrtypes}
\underfigtab
\end{table}


\subsection{Specification of pseudo atoms}
\label{SECTION:pseudo}

There are virtual and pseudo atoms.  A virtual atom is an atom that
occurs in the actual molecule, but whose position is not represented
explicitly in the MODEL and topology file.  A pseudo atom is a
position that does not correspond to an actual atom in a molecule, but
is some sort of an average of positions of real atoms. \MODELLER\
follows \GROMOS\ definitions for the seven types of pseudo and virtual
atoms: gravity center, V41, V31, P2, V42, P3, and P6.  These names are
constructed using the following rules: \Z{V} and \Z{P} indicate
virtual and pseudo atoms, respectively.  The second digit indicates
the number of substituents on the central atom (for \Z{V}) and the
number of protons whose positions are averaged (for \Z{P}).  The last
digit indicates the number of protons on the central atom (for \Z{V}).

\begin{verbatim}
  GROMOS ROUTINE #DEF DESCRIPTION
  TYPE   NAME    ATM 
--------------------------------------------------------------------------
     1  PSD       N  gravity center

     2  VCH1      4  virtual aliphatic proton on a tetrahedral carbon (->CH),
                     defined by the central C and the three other substituents;

     3  VCH1A     3  virtual aromatic proton on a trigonal carbon (=CH),
                     defined by the central C and the two C atoms bonded 
                     to the central C;

     4  PCH2      3  pseudo aliphatic proton on a tetrahedral carbon (>CH2)
                     not assigned stereospecifically; its position is
                     between the two real protons; defined by the central
                     C and the other two substituents;
               
     5  VCH2      3  virtual aliphatic proton on a tetrahedral carbon (>CH2)
                     assigned stereospecifically; defined by the central
                     tetraedral atom and the other two substituents on it;

     6  PCH31     2  pseudo aliphatic proton on a tetrahedral carbon (-CH3), 
                     defined by the central C and the heavy atom X in X-CH3;
                     its position is the average of the three real protons;

     7  PCH32     3  pseudo aliphatic proton between two unassigned -CH3
                     groups; defined by X in CH3 - X - CH3 and the two
                     C atoms from the two CH3 groups (Val, Leu!);
                     its position is the average of the six real protons;
    
     0    -       -  delta and epsilon protons on rapidly flipping aromatic
                     rings should refer directly to real gamma and delta C
                     atoms, respectively.
\end{verbatim}

In a restraints file, pseudo atoms are indexed from NATM+1 to
NATM+NPSEUDO where NPSEUDO is the number of pseudo atoms. The
restraints (the R entries) are exactly the same as for the real atoms,
except that the pseduo atom integer indices are used (indices are
larger than NATM). The pseudo atoms are defined in the P entries:
 
\begin{verbatim}
 P  i  j  k   a1  a2  a3
\end{verbatim}

where \V{i} is atom index of pseudo atom i, \V{j} is the type of the
pseudo atom i (see the table above), \V{k} is the number of real atoms
defining the current pseudo atom (3 in this case), and \V{a1 a2 a3}
are the integer indices of real atoms defining the current pseudo
atom.
 
For example, if you want to define a pseudo atom which is a gravity
center of atoms 4, 7, and 10, and there are 101 real atoms in the
protein:

\begin{verbatim} 
 P 102 1 3 4 7 10 
\end{verbatim}


\clearpage
% \afterpage{\clearpage}
