Next:Running TBMD  Up:TBMD user guide  Previous: Introduction

Installation


This section explains how to download and compile the source code for DoD-TBMD. We will assume that you are familiar with the UNIX operating system environment and that you know how to edit files using editors like vi or emacs.

Getting the code

Access to the DoD-TBMD source code is password protected. If you are interested in using our code please fill out our online registration form and we will get back to you with a user ID and password to gain access to the code. The requested information will help us track the use of the software for the CHSSI program and its successors.

New Instructions for Version 1.10

Download the code as a tarred, gzipped archive from

http://cst-www.nrl.navy.mil/users/mehl/tbmd/code/vers110/TBMD.tar.gz.

Compiling the Code

To compile the code

  1. Obtain the code from the above address and save it in a convenient directory.

  2. Unpack the code. On a Linux or Unix system the command is:

    $ gzip -cd TBMD.tar.gz | tar xvf -

    This will produce a subdirectory TBMD

  3. Run the configuration file: The directory TBMD/Install has a variety of makefile options for the target HPC machines. (If you wish to run the code on another machine, the file TBMD/Install/make_generic.inc.template will help you construct the proper options.) The Install/configure script sets up the compilation.

    $ cd TBMD
    $ Install/configure

    The script will now ask several questions about the setup. In most cases you can accept the default answer (i.e., press Enter), except for the first question. If you want to build a TBMD module which only has support for gamma-point calculations (much faster than the k-point code, but with only one k-point), you must specify this. This example is for the ASC IBM SP3. Similar responses occur on other machines, and the first question is always the same.

    Gamma vs. mult. k-points: ( kpts | gamma ) [default=kpts] gamma
    You chose: 'gamma'
    Spin polarized calculations: ( spin | nospin ) [default=nospin]
    You chose: 'nospin'
    System type: ( linux | rs6000 | sgi ) [default=rs6000]
    You chose: 'rs6000'
    CPU Type: ( p2 | p3 ) [default=p3]
    You chose: 'p3'
    BLAS libray location:
    Trying '/app/lapack/lib/ibm3'. Should I 'ls' this directory (y/n) [default=n] ?
    Is this directory correct (y/n) [default=y] ?
    Trying '/app/lapack/lib/ibm3/liblapack.a':
    Is this correct (y/n) [default=y] ?
    Version: ( serial | mpi ) [default=mpi]
    You chose: 'mpi'
    BLACS libraries location:
    Trying '/app/scalapac/lib/ibm3'. Should I 'ls' this directory (y/n) [default=n] ?
    Is this directory correct (y/n) [default=y] ?
    Trying '/app/scalapac/lib/ibm3/libblacs.a':
    Is this correct (y/n) [default=y] ?
    BLACS libraries location:
    Trying '/app/scalapac/lib/ibm3'. Should I 'ls' this directory (y/n) [default=n] ?
    Is this directory correct (y/n) [default=y] ?
    Trying '/app/scalapac/lib/ibm3/libblacsF77init.a':
    Is this correct (y/n) [default=y] ?
    BLACS libraries location:
    Trying '/app/scalapac/lib/ibm3'. Should I 'ls' this directory (y/n) [default=n] ?
    Is this directory correct (y/n) [default=y] ?
    Trying '/app/scalapac/lib/ibm3/libscalapack.a':
    Is this correct (y/n) [default=y] ?
    rs6000_p3-mpi-gamma-nospin
    copying make_rs6000_p3-mpi-gamma-nospin.inc ../src_rs6000_p3-mpi-gamma-nospin/make.inc
    Now cd into src_rs6000_p3-mpi-gamma-nospin and run make

  4. Compile the code: Follow the commands at the end of the configure script to find the appropriate source directory. Note that you may have multiple src* directories if you previously compiled the code in this directory tree, so pay attention to the output of configure.

    $ cd src_rs6000_p3-mpi-gamma-nospin
    $ make

    Much output and time passes. Eventually the computer will print out something like this:

    cp tbmd ..//bin//tbmd_rs6000_p3-mpi-gamma-nospin

    This tells us that the executable is in the ../bin subdirectory, and gives the name of the executable.

Instructions for older versions of the code can be found below:

Once you have been granted access to the archive you can get the source code either using http or ftp.

We have bundled all the necessary files for compiling and running DoD-TBMD for each supported platform a gzipped tar file called tbmd.tar.gz. There is a different tbmd.tar.gz file for each supported platform each stored in separate directories: 

    rs6000/tbmd.tar.gz
    sgi/tbmd.tar.gz
    linux/tbmd.tar.gz
    cray-t3e/tbmd.tar.gz
there is also a generic tbmd.tar.gz file which does not contain any binaries, in case your platform isn't supported.

Installing the source code and examples

Once you have retrieved and transfered the archive file for your target machine you will need to create a new directory and move the tbmd.tar.gz file to it, for instance: 
   mkdir ${HOME}/Tbmd
   mv tbmd.tar.gz ${HOME}/Tbmd
To install the code simply type: 
   cd ${HOME}/Tbmd
   gunzip -c tbmd.tar.gz | tar xvf -
which will extract all the files and directories from the archive and will create the following directory tree: 
   Examples/
   Install/
   Parameters/
   bin/
   include/
   lib/
   configure
   src.tar.gz
   tbmd.tar.gz
The directory tree created by unpacking tbmd.tar.gz will have directories with names dependent on the target platform. In general we abbreviate the name of the platform as PLAT (PLAT = sgi, rs6000, ...) and the name of the version as VER (VER = mpi or serial).
configure This is the utility that is used to configure (!) and install the code on your machine. It will unpack the source code (which is in src.tar.gz), create a proper make file for your machine and version, and setup libraries. 
Install/ Several Perl scripts used by configure to setup the machine specific files are placed here. The different make_*.inc files generated for all the supported platforms have also been placed there (they can be used in case the configure utility doesn't work). 
src_PLAT-VER/ This directory will be created by configure and contains the source code itself. 
bin/ will contains the executable tbmd_PLAT-VER after compilation and as well as other utilities.
lib/PLAT/ the libraries required by tbmd are placed in this directory. These can be the libraries themselves but more likely they will be symbolic links to the relevant files. 
include/PLAT/ the include files required to compile tbmd are found in this directory. These can be the files themselves but more likely they will be symbolic links to the relevant files. 

Requirements and supported platforms

TBMD has mainly been written in Fortran 90 (F90), so you will need a F90 compiler. In order to facilitate maintenance of the source code, we use preprocessing to generate different versions of the code (e.g. parallel vs. serial). This means that you will need the cpp preprocessor. The timing routines are also written in C so, in addition you will require a C compiler (although precompiled versions are included in the distribution for supported platforms).

DoD-TBMD has been written to run on the HPC machine of the DoD. Officially we support the code for running on the following machines:

However the code has been compiled and run successfully on the following parallel platforms (using MPI and ScaLAPACK): In addition the serial version can run on: In order to compile DoD-TBMD you will the following libraries on the target machine: 
    BLAS
    LAPACK
    MPI
    ScaLAPACK
NOTE: since LAPACK90 was very often not available on the machines we had access to, the new version of the code, DoD-TBMD V1.0, does not require LAPACK90  and it is not included in the distribution anymore.

In addition you will also need a library file containing platform specific timings routines. These files (called libtime_PLAT.a, where PLAT is the name of your platform) can also be found in lib, just copy the one for your platform in your "lib/PLAT" directory (see next section). Again if you downloaded a machine specific tbmd.tar.gz you already have the right libtime_PLAT.a file in lib/PLAT/.

The ScaLAPACK and MPI libraries are only required for the parallel version of the code.
NOTE: the binaries for ScaLAPACK and MPI are not provided in the machine dependent tbmd.tar.gz files.

If your target machine is missing some of the mentioned libraries you will not be able to compile the code.  However since all these libraries are in the public domain and you can downloaded  the missing one from Netlib.

Compiling TBMD

The compilation of the code is done using the make utility which requires a file called Makefile and another one called make.inc which is automatically include in Makefile (both are located in the src_PLAT-VER/ directory). Make sure these files are present in the src_PLAT-VER directory. The source code itself is in several files with the extensions .F or .c. The files ending in .F are files that will be processed using the C preprocessor (usually called cpp) and transformed into .f files. The preprocessing is an important aspect of compilation because it controls which version of code will be compiled (e.g. the serial or the parallel MPI version).

We emphasize that since the program uses dynamic allocation the code needs to be compiled only once.

1)  Configuration of make.inc

The make.inc file contains all the platform and version specific definitions needed for compiling and linking the code (e.g. the name of the compiler, libraries, etc, ...). The first step is therefore to create a make.inc file that is specific for your platform and for the version you want to run. There are two ways to do this, we will describe both.

NOTE: we will assume that you installed TBMD in a directory called ~/Tbmd.

1a)  Generating make.inc using configure

In an effort to simplify the process of generating a correct make.inc file, we have written a simple shell script called configure to do this for you. This utility will attempt to identify the machine you are running on, ask you which version you want to compile (MPI or serial, Gamma-point or multiple k-points version) and accordingly install the source code (in a directory src_PLAT-VER) and generate an appropriate make.inc. Please be aware that configure assumes the availability of Perl on your system, if not you'll have to use the method describes in the next subsection. Using configure is very simple, just type: 

  >cd ~/Tbmd
  >./configure
and follow the instructions. You will find an example of a configure session here.

After configure ran successfully you will have a new make.inc file in the src_PLAT-VER directory. Check that it is correct (see section 1b).

1b) using predefined make.inc files

In case the configure utility does not work on your platform we have provided predefined versions of make.inc files for different platforms and versions. First unpack the source code: 


    gunzip -c src.tar.gz | tar xvf -
this will create a directory called src. Rename the directory: 

   >mv src src_PLAT-VER
where PLAT is the name of the platform and VER the name of the version. Second change to the Install directory: 

  >cd ~/Tbmd/Install
then simply choose the list of available make_*.inc files: 

  >ls make_*.inc
  make_cray-t3e-mpi.inc
  make_cray-t3e-serial.inc
  make_rs6000-mpi.inc
  make_rs6000-serial.inc
  make_sgi-mpi.inc
  make_sgi-serial.inc
  make_linux-serial.inc
and copy the one you want to the src_PLAT-VER directory. So for instance if your platform is an SGI and you want to compile the MPI version you would do the following: 

  >cp make_sgi-mpi.inc ../src_sgi-mpi/make.inc
Now you will need to edit make.inc to check that the definitions of paths and directories are correct. For example here are the first lines of make.inc files from the previous example: 

###### Machine specific settings for the Makefile
## This file is for the mpi version of TBMD
## setup to run on the sgi architecture

SHELL           = /bin/csh
PLATFORM        = sgi
TBMD            = /home/flo/Tbmd/
SRC             = $(TBMD)/src/
LIB             = $(TBMD)/lib/
BIN             = $(TBMD)/bin/
INC             = $(TBMD)/include/
F77PATH         = 
F90PATH         = 
CCPATH          = 
CPPPATH         = /usr/lib/
LINKPATH        = 
PERLPATH        = 
FLTPATH         = 
FCMPIPATH       = 
 
        ...
In any case check that the line starting with TBMD show the directory where you have installed TBMD after the equal sign (in V1.0 this should be $(PWD)/../). The "*PATH" variables should be defined in case your default path doesn't contain the path to the corresponding binary (e.g. F77PATH is the path to the f77 compiler defined by the F77C variable).

2) Configuration of the lib and include directories

NOTE: The newest version of configure does this setup for you, making this section obsolete. To understand the setup of the directories it is nevertheless useful to read this section anyway.

This may well be the trickiest part of setting up the code for compilation. In order to avoid having to add countless paths to the make.inc file we assume that all libraries can be found in the ~/Tbmd/lib directory and all include files are in the ~/Tbmd/include directory. The easiest way to do this is to create symbolic links to the real libraries, but making sure you use the correct library names, as expected in make.inc.

Since the location of library and include files can widely vary we will only give an example here to give you a general understanding on how this is supposed to work. You will have to adapt the example to your own platform after finding found out where all the necessary libraries are located. For instance on the SGI Origin 2000 at NCSA we use the following commands, to setup the links to the mpif.h header file and ScaLAPACK libraries:

Example: 


  >cd ~/Tbmd/include/sgi/
  >ln -s /usr/include/mpif.h
  >cd ~/Tbmd/lib/sgi/
  >set L = /usr/local/apps/math/scalapack/libn32
  >ln -s ${L}/tools_O2K.a libtools.a
  >ln -s ${L}/redist_O2K.a libredist.a
  >ln -s ${L}/pblas_O2K.a libpblas.a
  >ln -s ${L}/scalapack_O2K.a libscalapack.a
  >set L = /usr/local/apps/math/blacs/LIBN32
  >ln -s ${L}/blacsCinit_MPI-O2K-0.a libblacsCinit.a
  >ln -s ${L}/blacsF77init_MPI-O2K-0.a libblacsF77init.a
  >ln -s ${L}/blacs_MPI-O2K-0.a libmpiblacs.a
3) Selecting the version to be compiled and changing flags in make.inc

In addition to platform specifics, the make.inc file also contains the preprocessor directives controlling the compilation. In make.inc there is one line, starting with DEFS which defines the preprocessor flags. For instance for the MPI version on the SGI Origin 2000 this line looks something like this: 

   DEFS = -DSGI -DMPI -DSCALAPACK -DNO_FREEMEM -DTIMING
There are several changes you may want to consider:

3a) Compile the gamma-point version

From version 1.0 on the multiple k-point version is installed by default. If you want to compile the gamma-point version you should add a -DGAMMA flag to the DEFS = ... line. So taking the previous example we would have: 

   DEFS = -DGAMMA -DSGI -DMPI -DSCALAPACK -DNO_FREEMEM -DTIMING

3b) Disable timing

To disable timing of the code you should delete the -DTIMING flag from the DEFS = ... line.

3c) Compile the serial version

NOTE: to compile the serial version use configure!

If you want to generate the serial code remove the . For generating the serial code we suggest that you create a new directory src_PLAT-serial copy the content of src_PLAT-mpi to it. You may then make the following changes to the make.inc file in the new directory:

4) Choosing a tight-binding model

TBMD has been written to be independent of any particular tight-binding model. All the model specifics are found in a source file called tb_model_module.F. We provide several tb*model_module.F files for different TB models, they can be found in src_PLAT-VER/Models: 


  >cd ~/Tbmd/src_PLAT-VER/
  >ls Models
  tb_gengsp_model.F
  tb_lanl_model.F
  tb_lj_model.F
  tb_ms_model.F
  tb_nrl_model.F
examine the headers to find more details about the models themselves. When you have chosen a model you should copy it to tb_model_module.F (in this instance the NRL model): 

  >cp Models/tb_nrl_model.F tb_model_module.F
Note: If you cannot find a module for the model you wish to use or if you are interested in implementing another model contact the author to see if we have already implemented it, this could save you some precious time! If not we will be happy to give you some guidance on how to implement a new TB model.

5) Compiling the code

Now that you have created the make.inc file, setup the lib and include directories, chosen which version to compile and which tight-binding model you want to run you are ready to compile the code. Before compiling make sure that the directory is cleaned of any product of a previous compilation by typing : 

  >make clean
if this fails make sure you have the clean script in bin and that it is executable (e.g. chmod 744 ../bin/clean).

Now you should be ready to compile the code: 

  >make tbmd
The compilation may take a while. There may well be some warning messages, but if the compiler doesn't stop you can safely ignore them. If the compilation has been successful you should have a new copy of the executable called tbmd, check that this is the most recent file in the directory: 
  >ls -lrt | tail
  -rw-r-----    1 fkirchho quy        21796 Dec 17 13:09 input_module.o
  -rw-r-----    1 fkirchho quy        57548 Dec 17 13:09 PBC_MODULE.mod
  -rw-r-----    1 fkirchho quy        46096 Dec 17 13:09 pbc_module.o
  -rw-r-----    1 fkirchho quy       137944 Dec 17 13:09 OUTPUT_MODULE.mod
  -rw-r-----    1 fkirchho quy        44608 Dec 17 13:09 output_module.o
  -rw-r-----    1 fkirchho quy       163076 Dec 17 13:09 IONS_DYN_MODULE.mod
  -rw-r-----    1 fkirchho quy        88048 Dec 17 13:09 ions_dyn_module.o
  -rw-r-----    1 fkirchho quy        20396 Dec 17 13:09 tbmd.o
  -rwxr-x---    1 fkirchho quy      2474700 Dec 17 13:09 tbmd*
 A copy of the newly created executable tbmd is also placed in ~/Tbmd/bin/tbmd_PLAT-VAR. If such is the case you are all set to run TBMD and try out the examples.

Good luck!

Next:Running TBMDUp:InstallationPrevious:Introduction
Florian Kirchhoff

Tue Jun 9 16:34:36 EDT 1998