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
 244 Figure \ref{fig:distr}
 245 for directory structure). Specific installation instructions are in the documentation of
 246 of the particular components of the package (UNRES, WHAM, CLUSTER, XDRFPDB). Only general
 247 instructions are given here.
 248
 249 \begin{enumerate}
 250
 251 \item
 252 Go to the respective source directory.
 253
 254 \item
 255 Determine if any of the Makefiles present there matches your needs. The Makefiles for
 256 Intel Fortran and Gnu Fortran are present everywhere and are guaranteed to work (provided
 257 that your compiler/MPI installation is correct). Use this Makefile as the working Makefile
 258
 259 If your system uses a different compiler, copy the most matching Makefile to your working
 260 Makefile (e.g., to Makefile\_CRAY if you'll be working with Cray Fortran).
 261
 262 \item
 263 Make a symbolic link of the working Makefile to Makefile, e.g.,
 264
 265 \begin{verbatim}
 266 ln -s Makefile_gfortran Makefile
 267 \end{verbatim}
 268
 269 Before that, you'll need to remove the existing symbolic link (in the distribution, it
 270 points to Makefile\_ifort).
 271
 272 \item
 273 Edit the Makefile to define MPI location, libraries, and the binaries directory
 274 and executalble names, if you want to use different location/names from those in the
 275 distribution Makefiles. The present locations are the subdirectories of the bin
 276 directory and executable names include package component, compiler, MPI information,
 277 and force field, e.g. unres\_csa\_gfort\_MPICH\_4P.exe stands for the CSA component,
 278 compiled with GNU Fortran in a parallel mode (using MPICH) to run calculations with
 279 the 4P force field.
 280
 281 \item
 282 For the components of XDRFPDB and in the directory cluster/unres/src, say
 283
 284 \begin{verbatim}
 285 make
 286 \end{verbatim}
 287
 288 In other directories say
 289
 290 \begin{verbatim}
 291 make <force_field>
 292 \end{verbatim}
 293
 294 to create the respective executable.
 295
 296 The compiler flags are specified for the 4P (also covers the 3P, and CASP5 ff),
 297 GAB (also covers E0G), and E0LL2Y force fields for all components; the CASP3 force field
 298 is also specified for the CSA and MINIM component.
 299 \end{enumerate}
 300
 301 \section{TECHNICAL SUPPORT CONTACT INFORMATION}
 302 \label{sect:support}
 303
 304    Dawid Jagie{\l}a\\
 305    Faculty of Chemistry, University of Gdansk\\
 306    ul. Wita Stwosza 63, 80-308 Gdansk Poland.\\
 307    fax: +48 58 523 5012\\
 308    e-mail: \href{mailto:lightnir@gmail.com}{lightnir@gmail.com}\\
 309
 310 \small{
 311         Prepared by Dawid Jagie{\l}a and Adam Liwo, 4/12/2014\\
 312 }
 313
 314 \end{document}