SourceForge.net Logo
MCCCS Towhee (code manual)

 

 

Overview
    This section explains the general structure of the Towhee program and also includes instructions on compiling Towhee. This page is only maintained for the current version of the Towhee code. It was last updated for version 6.2.14.
Compiling
    Towhee versions 3.9.8 or later have a sophisticated configure and Makefile setup that should allow automatic setting of the Makefile parameters on most platforms. This requires the use of two fairly standard freely available programs.
    autoconf Version 2.59 or later and
    automake Version 1.7.4 or later

    Compiling on a Unix/Linux Operating System using compilers similar to GNU
    In the top level directory issue the command
    ./configure
    This should automatically set up Makefiles in the Source directory which will create an optimal build for your machine. Then go into the Source directory
    cd Source
    and type
    make towhee
    Please note that the majority of compilations on Linux machines will require the
    ./configure --enable-fix-GNU
    option to be turned on. Please see the Configure Options Section below for more information.

    Compiling on an Apple OS-X Operating System
    Useful instructions and software for high performance computing on OS-X is available at http://hpc.sourceforge.net/.
    Compiling Towhee on OS-X is very similar to compiling on a Unix/Linux operating system. Users on older versions of OS-X may experience something similar to the following error message when they compile.
      ld: Undefined symbols:
      restFP
      saveFP
      make: *** [towhee] Error 1
    If this happens then you need to configure including the following option
    ./configure LDFLAGS=-lcc_dynamic
    and recompile.

    Compiling on a Windows Operating System using Cygwin
    Towhee is designed for compilation in a Unix style environment. In order to compile on a Windows machine we suggest the freely available Cygwin software. Once you have installed the Cygwin environment, and the appropriate additional software (Fortran compiler, C compiler, autoconf and automake) you then follow the normal Towhee compilation procedure with one important exception. Cygwin appends a '.exe' to any executable so the commands for compilation include an extra '.exe' compared with the Unix/Linux environment.
    ./configure
    cd Source
    make towhee.exe

    Compiling on a Windows Operating System using Intel's Visual Fortran and Microsoft's Visual C++.
    In addition to the standard towhee code, the following standard unix functionality is provided:
    • dirent.h : dirent API for MSVC++ (located in towhee-x.x.xx\vs_towhee\dirent)
    • unistd.h : a subset of the complete Unix file is used (located in towhee-x.x.xx\vs_towhee\dirent)
    • getopt: atgtable is an ANSI C library for parsing GNU style command line options (located in towhee-x.x.xx\vs_towhee\argtable2-12)
    Microsoft Visual Studio 2008 and Intel Visual Fortran (11.1.xxx) should be installed. Fortran libraries path should be added in the CV++ directories (Tools/Options | Projects and Solutions | VC++ Directories). Open the towhee solution (towhee-x.x.xx\vs_towhee\towhee\towhee.sln), select the desired configuration and press build. The produced executables will be placed under towhee-x.x.xx\vs_towhee\towhee\Release directory for the release configuration. Please note that the mpi version is not currently supported.

    Configure options in Towhee
    • ./configure --enable-safe-compare
      Using this flag turns on some slightly more expensive comparison routines that serve to make the results for the Examples exactly match between different machines. It also sets bounds checking and turns on compiler warning messages. This option is used to create the answer_current and par_answer_current files in the Examples directory.
    • ./configure --enable-mpi
      This option builds an MPI version of Towhee. Note that for some machines it is actually easier to get the machine to compile using the MPI options and you can still run single processor jobs with this version. Consult the towhee_parallel manual for more information about this option.
    • ./configure --enable-fix-GNU
      This option turns on the -fno-second-underscore flag on the fortran compile line in order to remove double underscores trailing a routine when there is already an underscore in the routine name. If you are seeing errors that involve double underscores, such as
        undefined reference to '_twh_moltyp__'
      and you are using the GNU compilers, then this option might solve your problems.
    • ./configure --enable-internal
      Some compilers do not include the error function intrinsics. Towhee includes some internal versions of the error function routines for use when the intrinsics are lacking and this option forces Towhee to use the internally provided functions instead of the intrinsic versions.
    • ./configure FFLAGS='-fbounds-check'
      where the items between the single quotes are the flags used for the Fortran compilation.
    • ./configure F77='pgf77' CC='pgcc'
      Sets the Fortran and C compilers to user specified values. This example shows the command needed to set the compilers to PGI pgf77 and pgcc
    • ./configure ADDLIB='-L/usr/whoever/lib/'
      Adds user specified libraries into the link command.
    • ./configure --enable-tramonto
      Links the Tramonto classical density functional code into Towhee for use as a really fancy implicit solvent. This option requires access to the Tramonto code compiled as a library. See the Tramonto web site for more information.
    • ./configure --enable-lcao
      Links the Quest quantum density functional code into Towhee for use as a really expensive force field. This option requires access to the Quest code compiled as a library. See the Quest web site for more information.
    • ./configure --enable-openkim
      Links the Open Knowledgebase of Interatomic Models libraries into Towhee to all the use of them as an external potential.
      • Requires a compiled version of openkim with the $KIM_DIR shell variable set to the location of the openkim installation. Remember to include the trailing / on the directory name as required by the KIM installation.
      • Create a KIM model library using the following command
        ar -r ${KIM_DIR}KIM_API/libkimmodels.a ${KIM_DIR}*/*/model*.o
    • ./configure --disable-command-line-args
      Removes the ability of the code to read command line arguments. This also defaults to a parallel style of "jobfarm" when combined with an --enable-mpi configure option. This option exists for users whose machines are unable to properly handle command line arguments, especially for certain parallel machines.
    • ./configure FFLAGS=''
      This turns off all of the Fortran compiler flags. This is useful when compiling the forcefield utility as some of the subroutines for assigning force field parameters are so large that optmization can cause some machines to run out of memory.

    Compiling the lcao version on the srnsquall machine
      The srnsquall machine at Sandia was the main development platform for the combination of Towhee with the Quest quantum DFT code. The procedure for compiling the combined version has been simplified.
    • ./configure --enable-internal --enable-mpi --enable-lcao --enable-link-srnsquall ADDLIB=-L/questpath
      where questpath is replaced with the directory path that contains the liblcao.a library. You also need to edit the Source/Makefile produced by this configure to remove two spurious ' symbols that appears in the link line.

    Compiling the lcao version on the Spirit machine
      These are the directions for compiling the Towhee-LCAO version on the Sandia computer Spirit.
    • ./configure --enable-mpi --enable-lcao --enable-link-spirit ADDLIB=-L/questpath
      where questpath is replaced with the directory path that contains the liblcao.a library. An lcao library is in the publicly readable /home/marmart/Lib directory on that machine so using that as the questpath should work properly.
    Compiling the forcefield utlitity
      Please note that the vast majority of users only need to compile the towhee portion of the code and do not need the forcefield utility as that is only required if you wish to generate the towhee_ff files. As the towhee_ff files come packaged with the download, and the forcefield utility contains routines that are large enough to give some compilers trouble, you should not attempt to compile that package unless you know why you want it.
      cd Source
      make forcefield
The .h files
  • preproc.h
    The preproc.h file is the only program file that a casual user will ever need to modify. This file contains parameters which control the dimensions of many of the most important arrays in Towhee. Depending on your preproc.h settings, and the simulation you are trying to perform, the code may produce an error message informing you that some variable exceeds some other variable. If that is the case then you will need to modify the appropriate variable in preproc.h in order to accommodate your system. You also might need to decrease some of the variables in preproc.h if your machine does not have enough memory for the arrays. Finally, some of the variables in preproc.h control certain settings that almost never change, but may be useful for debugging purposes.
    • MAXBOX the maximum number of simulation boxes in the system. Minimum value of MAXBOX is 1. No Maximum value for MAXBOX, but if it is set to more than 10 boxes then the pdb output will no longer function properly.
    • NUMAX the maximum number of atoms in any molecule. Minimum value is 1. No maximum value.
    • NTMAX the maximum number of types of molecules in the simulation. Minimum value is 1. No maximum value.
    • MAXKMAX the maximum value for kmax in the Ewald sum. Minimum value is 1. No maximum value.
    • VECTORMAX the maximum number of reciprocal space vectors in the Ewald sum. Starting with version 3.17.0 this variable is set based upon the value of MAXKMAX.
    • MAXBLOCK the maximum number of blocks for the block averaging. Minimum value is 1. No maximum value.
    • FLDMAX the maximum number of external fields in the system. Minimum value is 1. No maximum value.
    • NNTYPE the maximum number of different types of atoms allowed in the simulation.
    • CROSSTYPEMAX the maximum number of cross types, currently set to depend upon NNTYPE.
    • MAXTABTYPE the maximum number of types of atoms for tabular potentials. Minimum value is 1. Maximum value is NNTYPE.
    • MAXTABLE the maximum number of entries to describe a tabular potential. Minimum value is 1. Maximum value is NNTYPE.
    • TVIBMAX the maximum number of different types of vibrations in the simulation.
    • TBENMAX the maximum number of different types of bending angles in the simulation.
    • TTORMAX the maximum number of different types of regular torsions in the simulation.
    • TIMPMAX the maximum number of different types of improper torsions in the simulation.
    • TAAMAX the maximum number of different types of angle-angle terms in the simulation.
    • TOFMAX the maximum number of different types of special one-five terms in the simulation.
    • THBONDMAX the maximum number of different types of special hydrogen bond force field terms in the simulation.
    • TBIMAX the maximum number of different types of bond increment terms in the simulation.
    • NNBOND the maximum number of bonds from any atom. Minimum value is 1. No maximum value, and currently set to a default of 6.
    • MMBOND the maximum number of bonds from any atom for use in computing the maximum number of all of the intramolecular terms that are not just the number of vibrations. It is completely safe to set this to the same value as NNBOND, but that can lead to overly large arrays dimensions beyond a value of 4. Current default value is 4 and that should work for almost all systems as the larger value of NNBOND is there mainly for small molecule ions.
    • SMALLEST a value close to the smallest double precision number a computer can handle. This is usually set to 1d-300. There is no reason to adjust this unless your machine can handle significantly smaller numbers.
    • MAXPBOX maximum number of simulation box combinations for the volume moves. Currently set as a function of MAXBOX.
    • MAXTOR maximum number torsions originating from any single atom. Currently set as a function of NNBOND.
    • MAXBEND maximum number angles originating from any single atom. Currently set as a function of NNBOND.
    • MAXAA maximum number of angle-angle terms originating from any single atom. Currently set as a function of NNBOND.
    • MAXIMPROP maximum number of improper torsion terms originating from any single atom. Currently set as a function of NNBOND.
    • MAXOF maximum number of special one-five terms originating from any single atom. Currently set as a function of NNBOND.
    • MAXDIRLENGTH maximum number of characters in the directory length. This is used with some of the parallel features.
    • MAXIMPLICITTYPE maximum number of types of atoms for the implicit force fields.
    • MAXPIVOTBIN maximum number of bins for the pivot bookkeeping.
    • NDUMPHIST maximum allowable number of histogram computations before an output to file.
    • MAXBAPROP maximum number of properties to average using the block averages routine.
    • MAX_FOREIGN_LAMBDA maximum number of (lambda_lj,lambda_c) pairs for which energy evaluations will take place. Relevant only for Scaled Lennard-Jones classical potential.
    • Pound define aliases the remainder of this file contains a series of variables that are pound defined to be integers. This allows us to use sensible variables to describe things like classical potential styles, but still have the computational expediency of integer compares versus the relative expense of character string compares.
  • globalc.h
    contains all of the global variables for the C portion of the code.
The .F files The .c files Bug Reports
    In a code of this magnitude there will invariably be bugs from time to time. Hopefully all of the big ones are out of the code, but there is a continual process of adding features (rebugging) and testing the features (debugging). If you do find a problems with the code, please let us know so we can fix it for the benefit of everyone who is using the program. The more detail you can provide in your bug report the better. If you have a specific case that crashes then sending copies of the input files will greatly expedite the debugging process. We are now using the Bug Tracking software at SourceForge. To submit a bug just head to the Towhee Bug Tracker site and click on the "submit new" button. The best option is for you to log into SourceForge (creating an account is free) and use that account to submit the bug, in which case it will automatically notify you of the progress resolving the bug. Alternatively, you can send an email about your bug to towhee-bugs@lists.sourceforge.net. Your posting to this list is automatically held until we can verify it is not spam.
Return to the main towhee web page

 


Send comments to: Marcus G. Martin

Last updated: January 09, 2012