Correction of D-AA to parmread
[unres.git] / doc / 3.2.1 / latex / installman.tex
1 \documentclass[12pt]{article}
2 %\usepackage{latex2html}
3 \usepackage{enumerate}
4 \usepackage{longtable}
5 \usepackage{hyperref}
6 \usepackage{amsmath}
7 \usepackage{color}
8 \parindent=0pt
9 \parskip=12pt
10 \textheight=24cm
11 \textwidth=18cm
12 \topmargin=-2.5cm
13 \oddsidemargin=-0.5cm
14 \setcounter{secnumdepth}{5}
15 \setcounter{tocdepth}{5}
16 \begin{document}
17 \sloppy
18
19 \title{UNRES.3.2.1 -- INSTALLATION GUIDE}
20
21 \author{Dawid Jagie{\l}a, Adam Liwo\\ Laboratory of Molecular Modeling\\ Faculty of Chemistry\\ University of Gdansk\\ Wita Stwosza 63\\ 80-308 Gdansk, Poland}
22
23 \maketitle
24
25 \newpage
26
27 \tableofcontents
28
29 \newpage
30
31 \section{Putting the package on your system}
32 \label{section:put}
33
34 The distribution is contained in the unrespack-v.3.2.1.tar.gz file. To put the package
35 on your system, copy the archive to your UNRES directory (you might want to create
36 an environmental variable, \$UNRESROOT  or so, to define the location of UNRES on
37 your system) and  say:
38
39 \begin{verbatim}
40 gzip -cd unrespack-v.3.2.1.tar.gz | tar xf -
41 \end{verbatim}
42
43 This will produce the directory structure shown in Figure \ref{fig:distr}.
44
45 \begin{figure}
46 {\small
47 \begin{verbatim}
48 $UNRESROOT
49     |
50     |---------doc   (documentation)
51     |
52     |---------PARAM (force field parameters)
53     |
54     |---------source
55     |           |
56     |           |-----unres (UNRES source codes; various versions)
57     |           |       |
58     |           |       |---src_MIN (only energy evaluation and minimization)
59     |           |       |---src_CSA (all functions except MD, includes CSA)
60     |           |       |---src_MD  (all functions except CSA, includes MD, single chains)
61     |           |       |---src_MD-M (all functions except CSA, includes MD, oligomeric proteins)
62     |           |-----wham (weighted analysis method source codes)
63     |           |       |
64     |           |       |---src (single chains)
65     |           |       |---src-M (oligomeric proteins)
66     |           |
67     |           |-----cluster (cluster analysis source coded)
68     |           |       |
69     |           |       |---clust-unres
70     |           |       |         |
71     |           |       |         |----src    (input data from UNRES)
72     |           |       |
73     |           |       |---clust-wham        (input data from WHAM)
74     |           |                 |
75     |           |                 |----src    (for single-chain proteins)
76     |           |                 |----src-M  (for oligomeric proteins)
77     |           |
78     |           |-----xdrfpdb (file format conversion source codes)
79     |                   |
80     |                   |---src     (single chains)
81     |                   |---src-M   (oligomers)
82     |
83     |----------bin (C-shell script, batch scripts, and pre-compiled binaries)
84     |           |
85     |           |-----unres
86     |           |       |
87     |           |       |---CSA
88     |           |       |---MD
89     |           |       |---MINIM
90     |           |-----wham
91     |           |-----cluster
92     |           |-----xdrfpdb
93     |
94     |--------examples
95                 |
96                 |-----unres
97                 |-----wham
98                 |-----cluster
99 \end{verbatim}
100 }
101 \caption{Directory structure of the unres-3.2.1 package}
102 \label{fig:distr}
103 \end{figure}
104
105 \section{Installation options}
106 \label{sect:general}
107
108 The most convenient way to install the package is using Cmake, as described 
109 in section 2. If your system does not run the required version of Cmake or
110 installation does not work, do step-by-step compilation of the components
111 of the package, as described in section 3.
112
113 \subsection{Requirements}
114
115 \begin{description}
116 \item{--} C compiler
117 \item{--} Fortran compiler (must understant the Fortran 77 instructions)
118 \item{--} MPI (for CSA and MREMD)
119 \end{description}
120
121 \section{Installation using Cmake}
122 \label{section:Cmake}
123
124 \subsection{Requirements}
125
126 \begin{description}
127 \item{--} CMake 2.8.0 or later
128 \item{--} C compiler 
129 \item{--} Fortran compiler
130 \item{--} MPI (for CSA and MREMD)
131 \end{description}
132
133 \subsection{Basic installation}
134
135 These instructions give a very basic overview of how to configure, compile and
136 install UNRESPACK on most systems.  If you are using unique install locations
137 and/or libraries that are not automatically detected please consult the 'Advanced'
138 section.
139
140 \begin{enumerate}
141
142 \item
143 Create a 'build' directory in the package source directory.
144
145 \begin{verbatim}
146    mkdir build
147    cd build
148 \end{verbatim}
149
150 \item
151 Configure the build system
152
153 \begin{verbatim}
154    cmake ..
155 \end{verbatim}
156
157 \item
158 Compile
159
160 \begin{verbatim}
161    make 
162 \end{verbatim}
163
164 \item
165 Install
166
167 \begin{verbatim}
168    sudo make install
169 \end{verbatim}
170
171 \noindent or 
172
173 \begin{verbatim}
174    make install
175 \end{verbatim}
176
177 \end{enumerate}
178
179 \subsection{Advanced installation}
180
181 The build system (CMake) provides mechanisms for specifying non-standard
182 build parameters.
183
184 \begin{enumerate}
185
186 \item
187 \underline{Compilers \& installation}
188    
189 \begin{verbatim}
190    -DCMAKE_Fortran_COMPILER=xxx equal to name of Fortran Compiler you wish to use 
191      (ifort, gfortran)
192
193    -DCMAKE_INSTALL_PREFIX=xxx specify the binaries installation prefix
194                             (default UNRESPACK_source_dir/bin)
195 \end{verbatim}
196
197 \item
198 \underline{Force fields}
199
200 \begin{verbatim}
201    -DUNRES_MD_FF=xxx  compiles the MD versions with given force field. 
202      Options are: GAB, E0LL2Y. Default: GAB
203
204    -DUNRES_CSA_FF=xxx compiles the CSA versions with given force field
205      Options are: CASP3, ALPHA, BETA, ALPHABETA, CASP5, 3P, 4P. Default: 4P.
206 \end{verbatim}
207
208 Please read the online documentation on force fields available at 
209  http://unres.eu/unres\#SECTION00090000000000000000
210   
211
212 \item
213 \underline{MPI}
214
215 MPI implementation on your system should be automatically detected ("MPI Found" 
216 message after runing cmake). If not you have two options:
217
218 \begin{enumerate}
219
220 \item
221 Try setting the path to you MPI wrapper implementation
222
223 \begin{verbatim}
224    -DMPI_Fortran_COMPILER=xxx MPI wrapper
225 \end{verbatim}
226
227 \item
228 If option 1 fails or your MPI implementation does not come with a compiler wrapper 
229    try setting both the MPI include and library paths manually. This will circumvent
230    autodetection entirely. 
231
232 \begin{verbatim}
233    -DMPI_Fortran_INCLUDE_PATH=xxx
234    -DMPI_Fortran_LIBRARY="xxx"
235 \end{verbatim}
236
237 \end{enumerate}
238 \end{enumerate}
239
240 \section{Step-by-step installation}
241 \label{sect:stepbystep}
242
243 For this installation, you will need to visit each source directory (see doc/UNRESPACK.txt
244 for directory structure). Specific installation instructions are in the documentation of 
245 of the particular components of the package (UNRES, WHAM, CLUSTER, XDRFPDB). Only general
246 instructions are given here.
247
248 \begin{enumerate}
249
250 \item
251 Go to the respective source directory.
252
253 \item
254 Determine if any of the Makefiles present there matches your needs. The Makefiles for
255 Intel Fortran and Gnu Fortran are present everywhere and are guaranteed to work (provided
256 that your compiler/MPI installation is correct). Use this Makefile as the working Makefile
257
258 If your system uses a different compiler, copy the most matching Makefile to your working
259 Makefile (e.g., to Makefile\_CRAY if you'll be working with Cray Fortran).
260
261 \item
262 Make a symbolic link of the working Makefile to Makefile, e.g.,
263
264 \begin{verbatim}
265 ln -s Makefile_gfortran Makefile
266 \end{verbatim}
267
268 Before that, you'll need to remove the existing symbolic link (in the distribution, it
269 points to Makefile\_ifort). 
270
271 \item
272 Edit the Makefile to define MPI location, libraries, and the binaries directory
273 and executalble names, if you want to use different location/names from those in the
274 distribution Makefiles. The present locations are the subdirectories of the bin 
275 directory and executable names include package component, compiler, MPI information,
276 and force field, e.g. unres\_csa\_gfort\_MPICH\_4P.exe stands for the CSA component, 
277 compiled with GNU Fortran in a parallel mode (using MPICH) to run calculations with
278 the 4P force field.
279
280 \item
281 For the components of XDRFPDB and in the directory cluster/unres/src, say
282
283 \begin{verbatim}
284 make
285 \end{verbatim}
286
287 In other directories say
288
289 \begin{verbatim}
290 make <force_field>
291 \end{verbatim}
292
293 to create the respective executable.
294
295 The compiler flags are specified for the 4P (also covers the 3P, and CASP5 ff),
296 GAB (also covers E0G), and E0LL2Y force fields for all components; the CASP3 force field
297 is also specified for the CSA and MINIM component.
298 \end{enumerate}
299
300 \section{TECHNICAL SUPPORT CONTACT INFORMATION}
301 \label{sect:support}
302
303    Dawid Jagie{\l}a\\
304    Faculty of Chemistry, University of Gdansk\\
305    ul. Wita Stwosza 63, 80-308 Gdansk Poland.\\
306    fax: +48 58 523 5012\\
307    e-mail: \href{mailto:lightnir@gmail.com}{lightnir@gmail.com}\\
308
309 \small{
310         Prepared by Dawid Jagie{\l}a and Adam Liwo, 4/12/2014\\
311 }
312
313 \end{document}