doc update

[unres.git] / doc / 3.2.1 / latex / whamman.tex

\documentclass[12pt]{article}
%\usepackage{latex2html}
\usepackage{enumerate}
\usepackage{longtable}
\usepackage{hyperref}
\usepackage{amsmath}
\usepackage{color}
\parindent=0pt
\parskip=12pt
\textheight=24cm
\textwidth=18cm
\topmargin=-2.5cm
\oddsidemargin=-0.5cm
\setcounter{secnumdepth}{5}
\setcounter{tocdepth}{5}
\begin{document}
\sloppy

\title{WHAM \\ (Weighted Histogram Analysis Method)\\
        Processing results of UNRES/MREMD simulations}

\author{Laboratory of Molecular Modeling\\ Faculty of Chemistry\\ University of Gdansk\\ Wita Stwosza 63\\ 80-308 Gdansk, Poland\\
\\
\\
Scheraga Group\\ Baker Laboratory of Chemistry \\
and Chemical Biology\\ Cornell University\\ Ithaca, NY 14853-1301, USA}

\maketitle

\newpage

\tableofcontents

%1. License terms
%2. References
%3. Functions of the program
%4. Installation
%5. Running the program
%6. Input and output files
%6.1. Summary of files
%6.2. The main input file
%6.2.1. General data
%6.2.2. Molecule and energy parameter data
%6.2.2.1. General information
%6.2.2.2. Sequence information
%6.2.2.3. Dihedral angle restraint information
%6.2.2.4. Disulfide-bridge data
%6.2.3. Energy-term weights and parameter files
%6.2.4. (M)REMD/Hamiltonian (M)REMD setting specification
%6.2.5. Information of files from which to read conformations
%6.2.6. Information of reference structure and comparing scheme
%6.3. The structure of the main output file (out)
%6.4. The thermodynamic quantity and ensemble average (stat) files
%6.5. The conformation summary with classification (stat) files
%6.6. The histogram files
%6.7. The rmsd-radius of gyration potential of mean force files
%6.8. The PDB files
%6.9. The compresses Cartesian coordinates (cx) file
%7. Support

\newpage

\section{LICENSE TERMS}
\label{sect:license}

\begin{itemize}

\item
                This software is provided free of charge to academic users, subject to the condition that no part of it be sold or used otherwise for commercial purposes, including, but not limited to its incorporation into commercial software packages, without written consent from the authors. For permission contact Prof. H. A. Scheraga, Cornell University.

\item
                This software package is provided on an ``as is'' basis. We in no way warrant either this software or results it may produce.

\item
                Reports or publications using this software package must contain an acknowledgment to the authors and the NIH Resource in the form commonly used in academic research.

\end{itemize}

\newpage

\section{REFERENCES}
\label{sect:references}

Citing the following references in your work that makes use of the WHAM software is gratefully
acknowledged:

\begingroup
\renewcommand{\section}[2]{}%
\begin{thebibliography}{10}

\bibitem{kumar_1992} 
S. Kumar, D. Bouzida, R.H. Swendsen, P.A. Kollman, J.M. Rosenberg.
The weighted histogram analysis method for free-energy calculations on biomolecules. I. The method.
{\it J. Comput. Chem.}, {\bf 1992}, 13, 1011-1021.

\bibitem{liwo_2007}
A. Liwo, M. Khalili, C. Czaplewski, S. Kalinowski, S. Oldziej, K. Wachucik, H.A. Scheraga.
Modification and optimization of the united-residue (UNRES) potential energy function for canonical simulations. I. Temperature dependence of the effective energy function and tests of the optimization method with single training proteins.
{\it J. Phys. Chem. B}, {\bf 2007}, 111, 260-285.

\bibitem{oldziej_2004}
S. Oldziej, A. Liwo, C. Czaplewski, J. Pillardy, H.A. Scheraga.
Optimization of the UNRES force field by hierarchical design of the potential-energy landscape. 2. Off-lattice tests of the method with single proteins.
{\it J. Phys. Chem. B}, {\bf 2004}, 108, 16934-16949.

\end{thebibliography}

\endgroup

\newpage

\section{FUNCTIONS OF THE PROGRAM}
\label{sect:func}

The program processes the results of replica exchange (REMD) or multiplexed replica exchange molecular 
dynamics (MREMD) simulations with UNRES to compute the probabilities of the obtained conformations to 
occur at particular temperatures. The program is based on the variant of the weighted histogram analysis 
(WHAM) method \cite{kumar_1992} described in ref \cite{liwo_2007}.

The program outputs the following information:

\begin{enumerate}[(a)]

\item
Temperature profiles of thermodynamic and structural ensemble-averaged quantities.

\item
Histograms of native-likeness measure q (defined by eqs 8-11 of ref [\cite{liwo_2007}]).

\item
Optionally the most probable conformations at REMD temperatures.

\item
Optionally the coordinates with information to compute probabilities for the conformations to occur at any temperature.

\end{enumerate}

The program takes usually UNRES compressed coordinate files (cx files) from MREMD obtained by using the TRAJ1FILE option. The user can request to partition the whole run into equal slices (or windows), each starting from, say, snapshot n (for each trajectory) and ending at snapshot n+1.
Alternatively, the UNRES Cartesian coordinate (x files) can be input; however, they must contain only the analyzed portion of the trajectories; they are usually prepared from single trajectories by using xdrf2x.

Two versions of the program are provided:

\begin{enumerate}[(a)]

\item
Canonical version which treats single polypeptide chains; the source code is in WHAM/src directory.

\item
Version for oligomeric proteins; multiple chains are handled by inserting dummy residues in the sequence; the source code is in WHAM/src-M directory.

\end{enumerate}

\newpage

\section{INSTALLATION}
\label{sect:install}

It is recommended to use Cmake to install the entire package; see the Installation Guide for instructions. 
Step-by-step installation without Cmake is also possible; please follow section 4 of Installation Guide for general
information.

Customize Makefile to your system. See section 7 of the description of UNRES for compiler flags that are used to created executables for a particular force field. There are already several Makefiles prepared for various systems and force fields.

Run make in the WHAM/src directory WHAM/src-M directory for multichain version. Make sure that MPI is installed on your system; the present program runs only in parallel mode.

\newpage

\section{RUNNING THE PROGRAM}
\label{sect:running}

The program requires a parallel system to run. Depending on system, either the wham.csh C-shell script (in WHAM/bin directory) can be started using mpirun or the binary in the C-shell script must be executed through mpirun. See the wham.csh C-shell script and section 6 for the files processed by the program.

\newpage

\section{INPUT AND OUTPUT FILES}
\label{sect:inoutfiles}

\subsection{Summary of the files}
\label{sect:inoutfiles:summary}
The C-shell script wham.csh is used to run the program (see the WHAM/bin directory). The data files that the script needs are mostly the same as for UNRES (see section 6 of UNRES description). In addition, the environmental variable CONTFUN specifies the method to assess whether two side chains are at contact; if CONTFUN=GB, the criterion defined by eq 8 of ref 4 is used to assess whether two side chains are at contact. Also, the parameter files from the C-shell scripts are overridden if the data from Hamiltonian MREMD are processed; if so, the parameter files are defined in the main input file.

The main input file must have inp extension. If it is INPUT.inp, the output files are as follows:

\begin{description}

\item{INPUT.out\_POTxxx} -- output files from different processors (INPUT.out\_000 is the main output file). POT is the identifier of the sidechain-sidechain potential.

\item{INPUT\_POT\_GB\_xxx.stat} or INPUT\_POT\_slice\_YYXXX.stat -- the summary conformation-classification file from processor xxx (each processor handles part of conformations); the second occurs if the run is partitioned into slices.

\item{INPUT.thermal} or INPUT\_slice\_yy.thermal -- thermodynamic functions and temperature profiles of the ensemble averages (the second form if the run is partitioned into slices).

\item{INPUT\_T\_xxx.pdb} or INPUT\_slice\_yy\_T\_xxx.pdb -- top conformations the number of these conformations is selected by the user) in PDB format.

\item{INPUT.cx} -- the compressed UNRES coordinate file with information to compute the probability of a given conformation at any temperature.

\item{INPUT.hist}, INPUT\_slice\_xx.hist, INPUT\_par\_yy.hist, INPUT\_par\_yy\_slice\_zz.x -- histograms of q at MREMD temperatures.

\item{INPUT.ent}, INPUT\_slice\_xx.ent, INPUT\_par\_yy.ent, INPUT\_par\_yy\_slice\_xx.ent -- the histogram(s) of energy density.

\item{INPUT.rmsrgy}, INPUT\_par\_yy.rmsrgy, INPUT\_slice\_xx.rmsrgy or INPUT\_par\_yy\_slice\_xx.rmsrgy -- the 2D histogram(s) of rmsd from the experimental structure and radius of gyration.

\end{description}

\subsection{Main input file}
\label{sect:inoutfiles:main}

This file has the same structure as the UNRES input file; most of the data are input in a keyword-based form (see section 7.1 of UNRES description). The data are grouped into records, referred to as lines. Each record, except for the records that are input in non-keyword based form, can be continued by placing an ampersand (\&) in column 80. Such a format is referred to as the data list format.

In the following description, the default values are given in parentheses.

\subsubsection{General data (data list format)}
\label{sect:inoutfiles:main:general}

\begin{description}

\item{N\_ENE} (N\_ENE\_MAX) -- the number of energy components.

\item{SYM} (1) -- number of chains with same sequence (for oligomeric proteins only).

\item{HAMIL\_REP} -- if present, Hamiltonian process the results of replica exchange runs (replicas with different parameters of the energy function).

\item{NPARMSET} (1) -- number of energy parameter sets ($>$1 only for Hamiltonian replica exchange simulations).

\item{SEPARATE\_PARSET} -- if present, HREMD was run in a mode such that only temperature but not energy-function parameters was exchanged.

\item{IPARMPRINT} (1) -- number of parameter set with which to construct conformational ensembles; important only when HREMD runs are processed.

\item{ENE\_ONLY} -- if present, only conformational energies will be calculated and printed; no WHAM iteration.

\item{EINICHECK} (2) -- $>0$ compare the conformational energies against those stored in the coordinate file(s); 1: compare but print only a warning message if different; 2: compare and terminate the program if different; 0: don't compare.

\item{MAXIT} (5000) -- maximum number of iterations in solving WHAM equations.

\item{ISAMPL} (1) -- input conformation sampling frequency (e.g., if ISAMPL=5, only each 5th conformation will be read).

\item{NSLICE} (1) -- number of ``slices'' or ``windows'' into which each trajectory will be partitioned; each slice will be analyzed independently.

\item{FIMIN} (0.001) -- maximum average difference between window free energies between the current and the previous iteration.

\item{ENSEMBLES} (0) -- number of conformations (ranked according to probabilities) to be output to PDB file at each MREMD temperature; 0 means that no conformations will be output. Non-zero values should not be used when NSLICE$>$1.

\item{CLASSIFY} -- if present, each conformation will be assigned a class, according to the scheme described in 
ref \cite{oldziej_2004}.

\item{DELTA} (0.01) -- one dimension bin size of the histogram in q.

\item{DELTRMS} (0.05) -- rms dimension bin size in rms-radius of gyration histograms.

\item{DELTRGY} (0.05) - radius of gyration bin size in rms-radius of gyration histograms.

\item{NQ} (1) -- number of q's (can be for entire molecule, fragments, and pairs of fragments).

\item{CXFILE} -- produce the compressed coordinate file with information necessary to compute the probabilities of conformations at any temperature.

\item{HISTOUT} -- if present, the histograms of q at MREMD temperatures are constructed and printed to main output file.

\item{HISTFILE} -- if present, the histograms are also printed to separate files.

\item{ENTFILE} -- if present, histogram of density of states (entropy) is constructed and printed.

\item{RMSRGYMAP} -- if present, 2D histograms of radius of rmsd and radius of gyration at MREMD temperatures are constructed and printed.

\item{WITH\_DIHED\_CONSTR} -- if present, dihedral-angle restraints were imposed in the processed MREMD simulations.

\item{RESCALE} (1) -- Choice of the type of temperature dependence of the force field.

\item{NSAXS} -- number of distance-distribution bins corresponding to to SAXS

\item{SCAL\_RAD} -- scaling factor of sidechain radii in calculating Gaussian-smoothed distance distribution.

\item{BOXX, BOXY, BOXZ} - periodic-box dimensions.

\begin{description}

\item{$>0$} -- no temperature dependence.

\item{1} -- homographic dependence (not implemented yet with any force field).

\item{2} -- hyperbolic tangent dependence \cite{liwo_2007}.

\end{description}

\end{description}

\subsubsection{Molecule data}
\label{sect:inoutfiles:main:molecule}

\paragraph{General information}
\label{sect:inoutfiles:main:molecule:geninfo}

\begin{description}

\item{SCAL14} (0.4) -- scale factor of backbone-electrostatic 1,4-interactions.

\item{SCALSCP} (1.0) -- scale factor of SC-p interactions.

\item{CUTOFF} (7.0) -- cut-off on backbone-electrostatic interactions to compute 4- and higher-order correlations.

\item{DELT\_CORR} (0.5) -- thickness of the distance range in which the energy is decreased to zero.

\item{ONE\_LETTER} -- if present, the sequence is to be read in 1-letter code, otherwise 3-letter code.

\end{description}

\paragraph{Sequence information \\ \\}
\label{sect:inoutfiles:main:molecule:sequence}


1st record (keyword-based input):

NRES -- number of residues, including the UNRES dummy terminal residues, if present

Next records: amino-acid sequence

3-letter code: Sequence is input in format 20(1X,A3)

1-letter code: Sequence is input in format 80A1

\paragraph{Dihedral angle restraint information \\ \\}
\label{sect:inoutfiles:main:molecule:restraints}


This is the information about dihedral-angle restraints, if any are present.
It is specified only when WITH\_DIHED\_CONSTR is present in the first record.

1st line: ndih\_constr -- number of restraints (free format).

2nd line: ftors -- force constant (free format).

Each of the following ndih\_constr lines:

idih\_constr(i),phi0(i),drange(i) (free format)

\begin{description}

\item{idih\_constr(i)} -- the number of the dihedral angle gamma corresponding to the ith restraint.

\item{phi0(i)} -- center of dihedral-angle restraint.

\item{drange(i)} -- range of flat well (no restraints for phi0(i) +/- drange(i)).

\end{description}

\paragraph{Disulfide-bridge data\\ \\}
\label{sect:inoutfiles:main:molecule:disulfide}


1st line: NS, (ISS(I),I=1,NS) (free format)

\begin{description}

\item{NS} -- number of cystine residues forming disulfide bridges.

\item{ISS(I)} -- the number of the Ith disulfide-bonding cystine in the sequence.

\end{description}

nd line: NSS, (IHPB(I),JHPB(I),I=1,NSS) (free format)

\begin{description}

\item{NSS} -- number of disulfide bridges

\item{IHPB(I),JHPB(I)} - the first and the second residue of ith disulfide link

\end{description}

Because the input is in free format, each line can be split.

\subsubsection{Energy-term weights and parameter files}
\label{sect:inoutfiles:main:weights}

There are NPARMSET records specified below.
All items described in this section are input in keyword-based mode.

1st record: Weights for the following energy terms:

\begin{description}

\item{WSC} (1.0) -- side-chain-side-chain interaction energy.
\item{WSCP} (1.0) -- side chain-peptide group interaction energy.
\item{WELEC} (1.0) -- peptide-group-peptide group interaction energy.
\item{WEL\_LOC (1.0)} -- third-order backbone-local correlation energy.
\item{WCORR} (1.0) -- fourth-order backbone-local correlation energy.
\item{WCORR5} (1.0) -- fifth-order backbone-local correlation energy.
\item{WCORR6} (1.0) -- sixth-order backbone-local correlation energy.
\item{WTURN3} (1.0) -- third-order backbone-local correlation energy of pairs of peptide groups separated by a single peptide group.
\item{WTURN4} (1.0) -- fourth-order backbone-local correlation energy of pairs of peptide groups separated by two peptide groups.
\item{WTURN6} (1.0) -- sixth-order backbone-local correlation energy for pairs of peptide groups separated by four peptide groups.
\item{WBOND} (1.0) -- virtual-bond-stretching energy.
\item{WANG} (1.0) -- virtual-bond-angle-bending energy.
\item{WTOR} (1.0) -- virtual-bond-torsional energy.
\item{WTORD} (1.0) -- virtual-bond-double-torsional energy.
\item{WSCCOR} (1.0) -- sequence-specific virtual-bond-torsional energy.
\item{WDIHC} (0.0) -- dihedral-angle-restraint energy.
\item{WHPB} (1.0) -- distance-restraint energy.
\item{WSAXS=number} (real) (1.0d0) -- weight of the maximum-likelihood SAXS-restraint term.

\end{description}

2nd record: Parameter files. If filename is not specified that corresponds to particular parameters, the respective name from the C-shell script will be assigned. If no files are to be specified, an empty line must be inserted.

\begin{description}
\item{BONDPAR} -- bond-stretching parameters.
\item{THETPAR} -- backbone virtual-bond-angle-bending parameters.
\item{ROTPAR} -- side-chain-rotamer parameters.
\item{TORPAR} -- backbone-torsional parameters.
\item{TORDPAR} -- backbone-double-torsional parameters.
\item{FOURIER} -- backbone-local -- backbone-electrostatic correlation parameters.
\item{SCCORAR} -- sequence-specific backbone-torsional parameters (not used at present).
\item{SIDEPAR} -- side-chain-side-chain-interaction parameters.
\item{ELEPAR} -- backbone-electrostatic-interaction parameters.
\item{SCPPAR} -- backbone-side-chain-interaction parameters.
\end{description}

\subsubsection{(M)REMD/Hamiltonian (M)REMD setting specification}
\label{sect:inoutfiles:main:MREMD}

If HAMIL\_REP is present in general data, read the following group of records only once; otherwise, read for each parameter set (NPARSET times total).

\begin{description}

\item{NT} (1) -- number of temperatures.

\item{REPLICA} -- if present, replicas in temperatures were specified with this parameter set.

\item{UMBRELLA} -- if present, umbrella-sampling was run with this parameter set.

\item{READ\_ISET} -- if present, umbrella-sampling-window number is read from the compressed Cartesian coordinate (cx) file even if the data are not from umbrella-sampling run(s). ISET is present in the cx files from the present version of UNRES.

\end{description}

Following NT records are for consecutive temperature replicas; each record is
organized as keyword-based input:

\begin{description}

\item{TEMP} (298.0) - initial temperature of this replica (replicas in MREMD).

\item{FI} (0.0) - initial values of the dimensionless free energies for all q-restraint windows for this replica (NR values).

\item{KH} (100.0) - force constants of q restraints (NR values).
Q0 (0.0d0) - q-restraint centers (NR values)</p>

\end{description}

\subsubsection{Information of files from which to read conformations}
\label{sect:inoutfile:main:conffiles}

If HAMIL\_REP is present in general data, read the following two records only once; otherwise, read for each parameter set (NPARSET times total).

1st record (keyword-based input):.

For temperature replica only ONE record is read; for non-(M)REMD runs, NT records must be supplied. The records are in keyword-based format.

\begin{description}
\item{NFILE\_ASC} -- number of files in ASCII format (UNRES Cartesian coordinate (x) files) for current parameter set.

\item{NFILE\_CX} -- number of compressed coordinate files (cx files) for current parameter set.

\item{NFILE\_BINi} -- number of binary coordinate files (now obsolete because it requires initial conversion of ASCII format trajectories into binary format).

\end{description}

It is strongly recommended to use cx files from (M)REMD runs with TRAJ1FILE option. Multitude of trajectory files which are opened and closed by different processors might impair file system accessibility. Should you wish to process trajectories each one of which is stored in a separate file, better collate the required slices of them first to an x file by using the xdrf2x program piped to the UNIX cat command.

coordinate file name(s) without extension.

\subsubsection{Information of reference structure and comparing scheme}
\label{sect:inoutfile:main:reference}

The following records pertain to setting up the classification of conformation aimed ultimately at obtaining a class numbers. Fragments and pairs of fragments are specified and compared against those of reference structure in terms of secondary structure, number of contacts, rmsd, virtual-bond-valence and dihedral angles, etc. Then the class number is constructed as described in ref 3. A brief description of comparison procedure is as follows:

\begin{enumerate}

\item
Elementary fragments usually corresponding to elements of secondary or supersecondary structure are selected. Based on division into fragments, levels of structural hierarchy are defined.

\item
At level 1, each fragment is checked for agreement with the corresponding fragment in the native structure. Comparison is carried out at two levels: the secondary structure agreement and the contact-pattern agreement level.

At the secondary structure level the secondary structure (helix, strand or undefined) in the fragment is compared with that in the native fragment in a residue-wise manner. Score 0 is assigned if the structure is different in more than 1/3 of the fragment, 1 is assigned otherwise.

The contact-pattern agreement level compares the contacts between the peptide groups of the backbone of the fragment and the native fragment and also compares their virtual-bond dihedral angles gamma. It is allowed to shift the sequence by up to 3 residues to obtain contact pattern match. A score of 0 is assigned if more than 1/3 of native contacts do not occur or there is more than 60 deg (usually, but this cutoff can be changed) maximum difference in gamma. Otherwise score 1 is assigned.

The total score of a fragment is an octal number consisting of bits hereafter referred to S (secondary structure) C (contact match) and H (sHift) (they are in the order HCS). Their values are as follows:

\begin{description}
\item{S} -- 1 native secondary structure; 0 otherwise,
\item{C} -- 1 native contact pattern; 0 otherwise,
\item{H} -- 1 contact match obtained without sequence shift 0 otherwise.
\end{description}

For example,
octal 7 (111) corresponds to native secondary structure, native contact pattern, and no need to shift the sequence for contact match;
octal 1 (001) corresponds to native secondary structure only (i.e., nonnative contact pattern).

\item
At level 2, contacts between (i) the peptide groups or (ii) the side chains within pairs of fragments are compared. Case (i) holds when we seek contacts between the strands of a larger beta-sheet formed by two fragments, case (ii) when we seek the interhelix or helix-beta sheet contacts. Additionally, the pairs of fragments are compared with their native counterparts by rmsd.

Score 0 is assigned to a pair of fragments, if it has less than 2/3 native contacts and too large rmsd (a cut-off of 0.1 A/residue is set), score 1 if it has enough native contacts and sufficiently low rmsd, but the sequence has to be shifted to obtain a match, and score 2, if sufficient match is obtained without shift.

\item
At level 3 and higher, triads, quadruplets,..., etc. of fragments are compared in terms of rmsd from their native counterparts (the last level corresponds to comparing whole molecules). The score (0, 1, or 2) is assigned to each composite fragment as in the case of level 2.

\item
The TOTAL class number of a structure is a binary number composed of parts of scores of fragments, fragment pairs, etc. It is illustrated on the following example; it is assumed that the molecule has three fragment as in the case of 1igd.

\end{enumerate}

\begin{verbatim}
level 1      level 2                   level 3
123 123 123||1-2 1-3 2-3 1-2 1-3 2-3 || 1-2-3 | 1-2-3 ||
sss|ccc|hhh|| c   c   c | h   h   h  ||   r   |   h   ||
\end{verbatim}

Bits s, c, and h of level 1 are explained in point 2; bits c and h of level 2 pertain to contact-pattern match and shift; bits r and h of level 3 pertain to rmsd match and shift for level 3.

The input is specified as follows:

1st record (keyword-based input):

\begin{description}

\item{VERBOSE} -- if present, detailed output in classification (use if you want to fill up the disk).

\item{PDBREF} -- if present, the reference structure is read from the pdb.

\item{BINARY} -- if present, the class will be output in octal/quaternary/binary format for levels 1, 2, and 3, respectively.

\item{DONT\_MERGE\_HELICES} -- if present, the pieces of helices that contain only small breaks of hydrogen-bonding contacts (e.g., a kink) are not merged in a larger helix.

\item{NLEVEL=n} -- number of classification levels.

\item{n$>$0} -- the fragments for n levels will be defined manually.

\item{n$<$0} -- the number of levels is -n and the fragments will be detected automatically.

\item{START=n} -- the number of conformation at which to start.

\item{END=n} -- the number of conformation at which to end.

\item{FREQ=n} (1) - sampling frequency of conformations; e.g. FREQ=2 means that every second conformation will be considered.

\item{CUTOFF\_UP=x} - upper boundary of rmsd cutoff (the value is per 50 residues).

\item{CUTOFF\_LOW=x} -- lower boundary of rmsd cutoff (per 50 residues).

\item{RMSUP\_LIM=x} -- lower absolute boundary of rmsd cutoff (regardless of fragment length).

\item{RMSUPUP\_LIM=x} -- upper absolute boundary of rmsd cutoff (regardless of fragment length).

\item{FRAC\_SEC=x} (0.66666) the fraction of native secondary structure to consider a fragment native in secondary structure.

\end{description}

2nd record:

For nlevel$<$0 (automatic fragment assignment):

\begin{description}

\item{SPLIT\_BET=n} (0) : if 1, the hairpins are split into strands and strands are considered elementary fragment.

\item{ANGCUT\_HEL=x} (50): cutoff on gamma angle differences from the native for a helical fragment.

MAXANG\_HEL=x (60) : as above but maximum cutoff

\item{ANGCUT\_BET=x} (90), MAXANG\_BET=x (360), ANGCUT\_STRAND=x (90), MAXANG\_STRAND=x (360) -- same but for a hairpin or sheet fragment.

\item{FRAC\_MIN=x} (0.6666) -- minimum fraction of native secondary structure.

\item{NC\_FRAC\_HEL=x (0.5)} -- fraction of native contacts for a helical fragment.

\item{NC\_REQ\_HEL=x} (0) -- minimum required number of contacts.

\item{NC\_FRAC\_BET=x} (0.5), NC\_REQ\_BET=x (0) -- same for beta sheet fragments.

\item{NC\_FRAC\_PAIR=x} (0.3), NC\_REQ\_PAIR=x (0) : same for pairs of segments.

\item{NSHIFT\_HEL=n} (3), NSHIFT\_BET=n (3), NSHIFT\_STRAND=n (3), NSHIFT\_PAIR=n (3) -- allowed sequence shift to match native and compared structure for the respective types of secondary structure.

\item{RMS\_SINGLE=n} (0), CONT\_SINGLE=n (1), LOCAL\_SINGLE=n (1), RMS\_PAIR=n (0).

\item{CONT\_PAIR=n} (1) -- types of criteria in considering the geometry of a fragment or pair native; 1 means that the criterion is turned on.

\end{description}

For nlevel$>$0 (manual assignment):

Level 1:

1st line:

\begin{description}

\item{NFRAG=n} -- number of elementary fragments.

\end{description}

Next lines (one group of lines per each fragment):

1st line:

\begin{description}

\item{NPIECE=n} -- number of segments constituting the fragment.

\item{ANGCUT}, MAXANG, FRAC\_MIN, NC\_FRAC, NC\_REQ -- criterial numbers of native-likeness as for automatic classification.

\item{LOCAL}, ELCONT, SCCONT, RMS : types of criteria implemented, as for automatic classification except that ELECONT and SCCONT mean that electrostatic or side-chain contacts are considered, respectively.

\end{description}

NPIECE following lines:

IFRAG1=n, IFRAG2=n -- the start and end residue of a continuous segment constituting a fragment.

Level 2 and higher:

1st line:

\begin{description}

\item{NFRAG=n} -- number of fragments considered at this level.

\end{description}

For each fragment the following line is read:

\begin{description}

\item{NPIECE=n} -- number of elementary fragments (as defined at level 1) constituting this composite fragment.

\item{IPIECE=i1 i2 ... in} -- the numbers of these fragments.

\item{NC\_FRAC}, NC\_REQ : contact criteria (valid only for level 2).

\item{ELCONT}, SCCONT, RMS : as for level 1; note, that for level 3 and higher the only criterion of nativelikeness is rms.

\end{description}

3rd (for nlevel$<$0) or following (for n$>$0) line:

Name of the file with reference structure (e.g., the pdb file with the experimental structure)

\subsection{The structure of the main output file (out)}
\label{sect:inoutfiles:output:main}

The initial portion of the main output file, named INPUT.out\_POT\_000 contains information of parameter files specified in the C-shell script, compilation info, and the UNRES numeric code of the amino-acid sequence.
Subsequently, actual energy-term weights and parameter files are printed. If lprint was set at .true. in parmread.F, all energy-function parameters are printed. If REFSTR was specified in the control-data list, the program then outputs the read reference-structure coordinates and partition of structure into fragments.
Subsequently, the information about the number of structures read in and those that were rejected is printed followed by succinct information form the iteration process. Finally, the histograms (also output separately to specific histogram files; see section 6.6) and the data of the dependence of free energy, energy, heat capacity, and conformational averages on temperature are printed (these are also output separately to file described in section \ref{sect:inoutfiles:histograms}).

The output files corresponding to non-master processors (INPUT.out\_POT\_xxx where xxx$>$0 contain only the information up to the iteration protocol. These files can be deleted right after the run.

\subsection{The thermodynamic quantity and ensemble average (thermal) files}
\label{sect:inoutfiles:outpput:thermo}

The files INPUT.thermal or INPUT\_slice\_yy.thermal contain thermodynamic, ensemble-averaged conformation-dependent quantities and their temperature derivatives. The structure of a record is as follows:

\begin{tabular}{p{2cm}p{2cm}p{2cm}p{2cm}p{2cm}p{2cm}p{2cm}}
   T&           F&             E&      $q_1...q_n$&  rmsd&    Rgy&     Cv\\
  298.0&     -83.91454&    -305.28112&  0.30647&  6.28347& 11.61204&0.70886E+01\\
\end{tabular}

\begin{tabular}{p{2.5cm}p{2.5cm}p{2.5cm}p{2.5cm}p{2.5cm}p{2.5cm}}
       $var(q_1) ...$         &  var(rmsd)&    var(Rgy)&  $cov(q_1,E) ...$           & cov(rmsd,E)& cov(Rgy,E)\\
                    $var(q_n)$&           &            &                 $cov(q_n,E)$&            &           \\
    0.35393E-02&    0.51539E+01&    0.57012E+00&    0.43802E+00& 0.62384E+01&    0.33912E+01\\
\end{tabular}

where:

\begin{description}

\item{T} -- absolute temperature (in K),

\item{F} -- free energy at T,

\item{E} -- average energy at T,

\item{$q_1..q_n$}: ensemble-averaged q values at T (usually only the total q corresponding to whole molecule is requested, as in the example above, but the user can specify more than one fragment or pair of fragments for which the q's are calculated, If there is no reference structure, this entry contains a 0,

\item{rmsd} -- ensemble-averaged root mean square deviation at T,

\item{Rgy} -- ensemble-averaged radius of gyration computed from Calpha coordinates at T,

\item{$C_v$} -- heat capacity at T,

\item{$var(q_1)...var(q_n)$} -- variances of q's at T,

\item{var(rmsd)} -- variance of rmsd at T,

\item{var(Rgy)} -- variance of radius of gyration at T,

\item{$cov(q_1,E)...cov(q_n,E)$} -- covariances of q's and energy at T,

\item{cov(rmsd,E)} -- covariance of rmsd and energy at T,

\item{cov(Rgy,E)} -- covariance of radius of gyration and energy at T.

\end{description}

According to Camacho and Thirumalali (Europhys. Lett., 35, 627, 1996), the maximum of the variance of the radius of gyration corresponds to the collapse point of a polypeptide chain and the maximum variance of q or rmsd corresponds to the midpoint of the transition to the native structure. More precisely, these points are inflection points in the plots of the respective quantities which, with temperature-independent force field, are proportional to their covariances with energy.

\subsection{The conformation summary with classification (stat) files}
\label{sect:inoutfiles:class}

The stat files (with names INPUT\_POT\_xxx.stat or INPUT\_POT\_sliceyyxxx.stat; where yy is the number of a slice and xxx is the rank of a processor) contain the output of the classification of subsequent conformations (equally partitioned between processors). The files can be concatenated by processor rank to get a summary file. Each line has the following structure (example values are also provided):


\begin{tabular}{|c|cccc|}\hline
&&\multicolumn{3}{c|}{whole molecule}\\
\cline{2-5}
No&energy&rmsd&q&ang\\ \hline
 9999&  -122.42&  4.285&0.3751& 47.8\\ \hline
\end{tabular}

\begin{tabular}{|cccccccccccc|c|}\hline
\multicolumn{13}{|c|}{level 1}\\ \hline
\multicolumn{6}{|c}{frag 1}&\multicolumn{3}{c}{frag 2}&\multicolumn{3}{c|}{frag 3}&class 1\\ \cline{1-12}
n1&n2&n3&rmsd&q&ang&rmsd&q&ang&rmsd&q&ang&\\ \hline
 4&10&21 & 0.6&0.33& 16.7& 3.6&0.42& 56.3& 0.7&0.12& 16.5&737 \\ \hline
\end{tabular}

\begin{tabular}{|cccccc|c|cc|c|c|} \hline
\multicolumn{7}{|c|}{level 2}&\multicolumn{3}{c|}{level 3}&\\
\cline{1-10}
nc1&nc2&rmsd&q&rmsd&q&class 2&rmsd&q&class 3&class\\ \hline
9& 0&  1.6&0.20& 4.3&0.20&20& 0&  4.0&2&737.20.2\\ \hline
\end{tabular}

%                                      |                           level 1                           |       level 2                |    level3 |
%                                      |                                                             |                              |           |
%                      whole mol       |            frag1           frag2            frag3       cl1 |                              |           |
%No      energy    rmsd  q      ang dif|n1n2 n3   rms  q    ang   rms  q    ang   rms  q    ang      | nc1nc2 rms q     rms q    cl2|    rms cl3|class
% 9999   -122.42   4.285 0.3751  47.8  |4 10 21   0.6 0.33  16.7  3.6 0.42  56.3  0.7 0.12  16.5 737 | 9  0   1.6 0.20  4.3 0.20 20 | 0   4.0 2 |737.20.2

where

\begin{description}

\item{No} -- the number of the conformation.

\item{``whole molecule''} denotes the characteristics of the whole molecule q = 1-Wolynes'q.

\item{level 1, 2, and 3} denote the characteristics computed for the respective fragments as these levels.

\item{n1, n2, n3} -- number of native contacts for a given segment.

\item{cl1, cl2, cl3} -- group of segment classes for segments at level 1, 2, and 3, respectively.

\item{class} -- total class of the conformation.

\end{description}

The octal/quaternary/binary numbers denoting the class for a fragment at level 1, 2, and 3, respectively, are described in ref. \cite{oldziej_2004}.

\subsection{The histogram files}
\label{sect:inoutfiles:histograms}

The histogram file with names INPUT\_[par\_yy][\_slice\_xx].hist where xx denotes the number of the slice and yy denotes the number of the parameter if SEPARATE\_PARSET was specified in input contain histograms of q at replica temperatures and energy-parameter sets; with SEPARATE\_PARSET histograms corresponding to subsequent parameter sets are saved in files with par\_yy infixes. The histograms are multidimensional if q is a vector (usually, however, q corresponds to the entire molecule and, consequently, the histograms are one-dimensional). The histogram files are printed if histfile and histout was specified in the control data record.

Each line of a histogram file corresponds to a given (multidimensional) bin in q contains the following:


\begin{itemize}

\item
$q_1,...,q_n$ at a given bin (format f6.3 for each)

\item
histogram values for subsequent replica temperatures (format e20.10 for each)

\item
iparm (the number of parameter set; format i5)

\item
If SEPARATE\_PARSET was not specified, the entries corresponding to each parameter follow one another.

\end{itemize}

The state density is printed to file(s) INPUT[\_slice\_xx].ent. Each line contains the left boundary of the energy bin and ln(state density) followed by ``ent'' string. At present, the state density is calculated correctly only if one energy-parameter set is used.</p>

\subsection{The rmsd-radius of gyration potential of mean force files}
\label{sect:inoutfiles:rmsd-rgy}

These files with names INPUT[\_par\_yy][\_slice\_xx].rmsrgy contain the two-dimensional potentials of mean force in rmsd and radius of gyration at all replica-exchange temperatures and for all energy-parameter sets.
A line contains the left boundaries of the radius of gyration -- rmsd bin (radius of gyration first) (format 2f8.2) and the PMF values at all replica-exchange temperatures (e14.5), followed by the number of the parameter set. 
With SEPARATE\_PARSET, the PMFs corresponding to different parameter sets are printed to separate files.

\subsection{The PDB files}
\label{sect:inoutfiles:PDB}

The PDB files with names INPUT\_[slice\_xx\_]Tyyy.pdb, where Tyyy specifies a given replica temperature contain the conformations whose probabilities at replica temperature T sum to 0.99, after sorting the conformations 
by probabilities in descending order. The PDB files follow the standard format; see \href{ftp://ftp.wwpdb.org/pub/pdb/doc/format_descriptions/Format_v33_Letter.pdf}{\textcolor{blue}{ftp://ftp.wwpdb.org/pub/pdb/doc/format\_descriptions}}.
%/Format_v33_Letter.pdf">ftp://ftp.wwpdb.org/pub/pdb/doc/format_descriptions/Format_v33_Letter.pdf</a>. 
For single-chain proteins, an example is as follows:

\begin{verbatim}
REMARK CONF    9059 TEMPERATURE  330.0 RMS   8.86
REMARK DIMENSIONLESS FREE ENERGY   -1.12726E+02
REMARK ENERGY   -2.22574E+01 ENTROPY   -7.87818E+01
ATOM      1  CA  VAL     1       8.480   5.714 -34.044
ATOM      2  CB  VAL     1       9.803   5.201 -33.968
ATOM      3  CA  ASP     2       8.284   2.028 -34.925
ATOM      4  CB  ASP     2       7.460   0.983 -33.832
.
.
.
ATOM    115  CA  LYS    58      28.446  -3.448 -12.936
ATOM    116  CB  LYS    58      26.613  -4.175 -14.514
TER
CONECT    1    3    2
.
.
.
CONECT  113  115  114
CONECT  115  116
\end{verbatim}

where

\begin{description}

\item{CONF} is the number of the conformation from the processed slice of MREMD trajectories.

\item{TEMPERATURE} is the replica temperature.

\item{RMS} is the Calpha rmsd from the reference (experimental) structure.

\item{DIMENSIONLESS FREE ENERGY} is -log(probability) (equation 14 of ref 2) for the conformation at this replica temperature calculated by WHAM.

\item{ENERGY} is the UNRES energy of the conformation at the replica temperature (note that UNRES energy is in general temperature dependent).

\item{ENTROPY} is the omega of equation 15 of ref 2 of the conformation.

\end{description}

In the ATOM entries, CA denotes a Calpha atom and CB denotes UNRES side-chain atom. The CONECT entries specify the C$^\alpha_i\cdots$C$^\alpha_{i-1}$, C$^\alpha_i\cdots$C$^\alpha_{i+1}$ and C$^\alpha_i\cdots$SC$_i$ links.

The PDB files generated for oligomeric proteins are similar except that chains are separated with TER and molecules with ENDMDL records and chain identifiers are included. An example is as follows:

\begin{verbatim}
REMARK CONF     765 TEMPERATURE  301.0 RMS  11.89
REMARK DIMENSIONLESS FREE ENERGY   -4.48514E+02
REMARK ENERGY   -3.58633E+02 ENTROPY    1.51120E+02
ATOM      1  CA  GLY A   1      -0.736  11.305  24.600
ATOM      2  CA  TYR A   2      -3.184   9.928  21.998
ATOM      3  CB  TYR A   2      -1.474  10.815  20.433
.
.
.
ATOM     40  CB  MET A  21      -4.033  -2.913  27.189
ATOM     41  CA  GLY A  22      -5.795 -10.240  27.249
TER
ATOM     42  CA  GLY B   1       6.750  -6.905  19.263
ATOM     43  CA  TYR B   2       5.667  -4.681  16.362
.
.
.
ATOM    163  CB  MET D  21       4.439  12.326  -4.950
ATOM    164  CA  GLY D  22      10.096  14.370  -9.301
TER
CONECT    1    2
CONECT    2    4    3
.
.
.
CONECT   39   41   40
CONECT   42   43
.
.
.
CONECT  162  164  163
ENDMDL
\end{verbatim}

\subsection{The compressed Cartesian coordinates (cx) files}
\label{sect:inoutfiles:cx}

These files contain compressed data in the Europort Data Compression XDRF library format written by Dr. F. van Hoesel, Groeningen University (\href{http://hpcv100.rc.rug.nl/xdrfman.html}{http://hpcv100.rc.rug.nl/xdrfman.html}.
The files are written by the cxwrite subroutine. The resulting cx file contains the omega factors to compute probabilities of conformations at any temperature and any energy-function parameters if Hamiltonian replica 
exchange was performed in the preceding UNRES run. The files have general names INPUT[\_par\_yy][\_slice\_xx].cx where xx is slice number and yy is parameter-set.

The items written to the cx file are as follows (the precision is 5 significant digits):

\begin{enumerate}
\item
Cartesian coordinates of Calpha and SC sites</p>
\item
nss (number of disulfide bonds)
\item
if nss$>$0:
\begin{enumerate}
\item
ihpb (first residue of a disulfide link)
\item
jhpb (second residue of a disulfide link)
\item
UNRES energy at that replica temperature that the conformation was at snapshot-recording time,
\item
ln(omega) of eq 15 of ref \cite{liwo_2007},
\end{enumerate}
\item
C$^\alpha$ rmsd
\item
conformation class number (0 if CLASSIFY was not specified).
\end{enumerate}

\newpage

\section{SUPPORT}
\label{sect:support}

        Dr. Adam Liwo\\
        Faculty of Chemistry, University of Gdansk\\
        ul. Wita Stwosza 63, 80-308 Gdansk Poland.\\
        phone: +48 58 523 5124\\
        fax: +48 58 523 5012\\
        e-mail: \href{mailto:adam@sun1.chem.univ.gda.pl}{\textcolor{blue}{adam@sun1.chem.univ.gda.pl}}\\

        Dr. Cezary Czaplewski\\
        Faculty of Chemistry, University of Gdansk\\
        ul. Wita Stwosza 63, 80-308 Gdansk Poland.\\
        phone: +48 58 523 5126\\
        fax: +48 58 523 5012\\
        e-mail: \href{mailto:cezary.czaplewski@ug.edu.pl}{\textcolor{blue}{cezary.czaplewski@ug.edu.pl}}\\
\\

        Dr. Adam Sieradzan\\
        Faculty of Chemistry, University of Gdansk\\
        ul. Wita Stwosza 63, 80-308 Gdansk Poland.\\
        phone: +48 58 523 5124\\
        fax: +48 58 523 5012\\
        e-mail: \href{mailto:adasko@sun1.chem.univ.gda.pl}{\textcolor{blue}{adasko@sun1.chem.univ.gda.pl}}\\

Prepared by Adam Liwo, 02/19/12.

\LaTeX version, 09/27/12.

Revised by Adam Liwo, 12/04/14

\end{document}