View source for Resgrp:comp-photo-dyn/mctdh90.31dv/install/mac

= Software requirements=

For the installation of the MCTDH package, you need a computer with a UNIX (or UNIX-like, e.g. Linux) or MAC OS X operating system. On MS Windows, it is possible to install and run MCTDH inside the Cygwin environment.

The following software is required:

* A FORTRAN 77 compiler

* A C compiler which cooperates with your FORTRAN compiler.

* A bash shell

The MCTDH package uses bash shell-scripts quite extensively. (There is also a small number of C-shell scripts). It will be very difficult to install the MCTDH package without bash. Version 2.0 is recommended, but version 1.14 should do as well.
It is recommended to use always a BASH shell during all this tutorial.

* Latex

You need Latex and a X11 term in MAC OS X to compile some part of the documentation, in particular the MCTDH User's Guide. Nevertheless, this documentation is not essential and it is avaiable via web: 

http://www.pci.uni-heidelberg.de/tc/usr/mctdh/doc/index.html

* GNUPLOT Version 4.0

GNUPLOT is required to take full advantage of the analyse routines. Version 3.7 also works, but offers less functionality.

= Installing the program as an user =

* If you are using other kind of shell different than BASH, change to a bash shell enviroment typing:

     bash

* First of all, you should make a backup of your bash profile if you already have one. During the installation of the MCTDH package your bash profile will be changed, thus saving it is a good preventive measure. Inside your $HOME directory (/Users/$USER):

     cp .bachrc .bashrc_{{CURRENTDAY}}_{{CURRENTMONTH}}_{{CURRENTYEAR}}

* Create the directory DYN inside /Users/$USER/

* Download the compressed files '''mctdh90dev.zip''' and '''dd_generator_12_12_08.zip''' to the folder /Users/$USER/DYN/. Uncompress them with a double-click.

(Link to download '''mctdh90dev.zip''' and '''dd_generator_12_12_08.zip''')

# '''mctdh90dev.zip'' contains the code of the development version of MCDTH 90.
# ''dd_generator_12_12_08.zip''' contains the last version of the code script to generate the inputs of MCTDH. 

We have created the directory  /Users/$USER/DYN/mctdh90dev, which contains all the necessary files for the installation of MCTDH.  This directory will be termed the MCTDH directory during this tutorial.

* We are going to install the MCTDH package version 90dev. The installation script is in the following folder: /Users/$USER/DYN/mctdh90dev/install.

* Go to this folder:

     cd /Users/$USER/DYN/mctdh90dev/install

* Usually the installation would be done simply running the installation script called '''install_mctdh'''. However, we already know that the default choices of compiler and platform are not the most appropriates, thus we are going to set some things "manually".

== Define the name of the machine and the compiler ==

* The file platform.cnf.priv is a file that the script install_mctdh will use to define some variables. Inside the install folder copy the template of this file "'''platform.cnf.priv.template'''" to platform.cnf.priv.

     cp platform.cnf.priv.template platform.cnf.priv

* Inside platform.cnf.priv replace the  "xxx" by the name of your machine. In order to know the name of your machine you just have to type:

     uname -n

In this case the "xxx" has to be substituted by '''quadmac.ch.ic.ac.uk'''.

* Complete the definition of the variable '''$MCTDH_COMPILER''' with the name of a FORTRAN 77 compiler installed in your system. You can find a list of the compilers accepted by MCTDH and the appropriated label at the file '''compile.cnf''' in the same directory. In this case we are going to  use the Portland-Group F77 compiler, the label is pgf77.

     MCTDH_COMPILER=pgf77

== Installation script ==

* Run the installation script typing:

     ./install_mctdh 

This install script can be stopped any time with "Ctrl C", thus if you think you have made a wrong choice, just run it again!

* The install script asks a few simple questions, and automatically generates the executables and documentation:

1) The script requests your permission to modify your .bashrc profile.

     For your convenience I will write some statements to your
     configuration files 
     (i.e. to  ~/.profile or ~/.bashrc or ~/.cshrc or ~/.kshrc).
     "Your old ~/.XXX configuration file will be saved to ~/.save-XXX-$$."

     Choose: b) write the commands to my ~/.bashrc file
     (for bash users).
     Or    : c) rather write them to my ~/.cshrc file
     (for csh and tcsh users).'
     Or    : k) rather write them to my ~/.kshrc file
    (kcsh users).
     Or    : p) please, rather write them to my ~/.profile file.
               (alternative for ksh and bash users (not recommended)).
     Or    : y) yes, write the commands to my ~/.bashrc file.
      (same as b))
     Or    : n) no, do not touch my configuration files.

     (b|c|k|p|y|n) ? : 

     Please answer "b", "c", "k", "p", or "y" or "n"'

* Answer "yes"

2) The script requests your permission to copy the file .mctdhrc to your $HOME directory.

     The file mctdhrc may be copied to $HOME/.mctdhrc.
     The .bashrc will then source .mctdhrc.
     Doing so, the bash-functions cdm and minstall will be available
     and a link $HOME/mctdh -> $MCTDH_DIR will be installed.

     Shall I copy mctdhrc to $HOME/.mctdhrc (y/n) ? : 

* Answer "yes"

3) In UNIX there are two variants of how to place the bytes in a word. These variants are called LITTLE ENDIANS (le) and BIG ENDIANS (be). Select the kind of endians of your machine, in this case you have to choose the LITTLE ENDIANS format:

     In UNIX there are two variants of how to place the bytes in a word.
     These variants are called LITTLE ENDIANS (le) and BIG ENDIANS (be).
     You will be able to read binary files created on different machines
     as long as they all use the same format, i.e. all are either le or be.
     If you use the g77, you are tied to the le format, but when you use
     the IBM compiler you are tied to the be format.
     The compilers:  alpha, intel, absoft, and pfg77 can perform a
     byte swap to either format.
     Do you want the le or be format for those compilers? Choose from:
     "y" or "le" if you want the LITTLE ENDIANS format.
     "n" or "be" if you want the BIG ENDIANS format.
     (If you do not know what to do, choose "y".)
    (y|n) ? :  

* Answer "yes"

4) The program asks you about compile the stored documentation in Latex files. 

 * Answer "No"

5) The script shows you the parameters chosen for the installation. You should see the name of your platform and the name of the fortran compiler that you selected.

For example:

     Operating system     : Darwin
     Platform             : i386
     Compilers (F77 / C)  : pgf77    pgcc

6) The script asks you about compiling the progam.

     Would you like to compile the programs now ?
 
     Choose: y) yes
     Or    : n) no

* Answer "No". We need to compile the program "manually" in order to set some options of the compiler. 

* If the installation has been successful, you should see the message:

     ********************************************************************************
     ********************  Finished Installation (install_mctdh) ********************
     ********************   Tue Dec  9 19:48:29 GMT 2008         ********************
     ********************************************************************************

* At the end of the installation process, don't forget to  source your .bashrc in order to set some environment variables. Simply type:

     source ~/.bashrc

When the .bashrc is sourced, the the hidden file .mctdhrc will then be sourced as well. The .mctdhrc script sets the link:

     mctdh -> /Users/$USER/DYN/mctdh90dev

and defines the bash-function cdm and menv. 

* Now you should notice that:

# A link to the folder /home/gaussian-devel/mctdh has been created in your HOME directory.
# Now you have two new commands:
    
cdm: the command cdm cd-es to /Users/$USER/DYN/mctdh90dev and any subdirectory

menv: the MCTDH environment variables are listed

dd_generator: script which allows to create the required files to run dynamics calculation. The script asks a few simple questions, and automatically generates all the necessary files.

== Compilation ==

* Go to the folder: /Users/$USER/DYN/mctdh90dev/source/propwf

Here you can find the module '''directdyn.F'''. Restore the backup of this file for serial platforms: directdyn.F.addwr.  

    cp directdyn.F.addwr directdyn.F

Modify the line 486, which is a compressed definition of  DO and that our FORTRAN compiler does not accept.

Change:

     'q=',qcenter(1:gdof,e) 

to

     'q=',(qcenter(k,e),k=1,gdof)

and add the variable k to the integer definitions at the line 23

     integer    hl,gdof,dim1,ista,zeig,zeig1,zeig2,e,s1,
     +           dddegen(dim1),isort(100),k

* One change more stills remaining. Inside the install folder, open the file compile.cnf. 

Between lines 423 and 441 there are the default settings for the Portland-Group F77/CC compiler (v5.2). The variables $FC and $CC define the FORTRAN and C compilers respectively. As you can see the default Portland compiler is '''pgf77''', which is right, but the C compiler is the the Portland-Group CC compiler '''pgcc'''. 

       pgf77)  # Linux linker, make, ..., with Portland-Group F77/CC compiler (v5.2)
         export FC=pgf77
         export CC=pgcc

Unfortunately, we do not have the license of this compiler, but you can easily use the free GNU version. Define the variable $CC=gcc and $MCTDH_CFLAGS="-O2 -m64". You should have:

       pgf77)  # Linux linker, make, ..., with Portland-Group F77/CC compiler (v5.2)
         export FC=pgf77
         export CC=gcc

and

     MCTDH_CFLAGS="-O2 -m64"

The option -O2 is in order to ... and -m64 to set 64 bits.

* Now, finally we can compile MCTDH. Type:

     compile -n 2s mctdh

The option -n is to choose a particular module to compile. We want to compile the version: mctdh_2s, which is the one designed to run MCTDH at the second state as a higher root with full diagonalization. If you were interested there are other modules which can be compiled:

2s => Higher root: second state, S0/S1, full diagonalization

2s-lanczos => Higher root: second state, S0/S1, Lanczos and full diagonalization at the last step

3s =>Higher root: third state, S1/S2, full diagonalization 

* If  you did all the steps correctly and in the right order, you should see the message:

     Congratulations, the compilation was successful.
 
     ------  compile  ---  Tue Dec 9 20:13:29 GMT 2008 ---  good bye!  --------------
     --------------------------------------------------------------------------------

---

mctdh90dev/source/propwf/directdyn.F

directdyn.F            directdyn.F.addwr      directdyn.F.addwr_omp  directdyn.F.omp        directdyn.F.original

mctdh90dev/source/opfuncs/external.F

external.F                 external.F.2s_lanczos      external.F.3s              external.F.omp
external.F.2s              external.F.2s_lanczos_omp  external.F.3s_omp          external.F.original

== Generation of MCTDH input files ==

* Download and uncompress the zip file ''' dd_generator_12_12_08.zip'''  contains the latest version of the script '''dd_generator'''.

(Link to download ''' dd_generator_12_12_08.zip''')

This zip file contain:

# dd_generator: the latest version of dd_generator for the HPC Cluster and Mac OS X 
# dd_generator_MAC: the latest versions of dd_generator Mac OS X  
# dd_filegen.f: a FORTRAN program that is used by dd_generator
# template: one of the essential input files for MCTDH. This file is the template for the GAUSSIAN inputs.

* MCTDH stills in a stage of development, thus you must obtain and update this scripts to generate the inputs for MCTDH.

* Compile the fortran program '''dd_filegen.f'''

     pgf77 -o dd_filegen.out dd_filegen.f

* Copy the executable file '''dd_filegen.out''' and the script '''dd_generator_MAC''' to the bin folder of MCTDH (/Users/$USER/DYN/mctdh90dev/bin)

     cp dd_filegen.out /Users/$USER/DYN/mctdh90dev/bin

     cp  dd_generator_MAC /Users/$USER/DYN/mctdh90dev/bin