2.6. Maintaining the package

2.6.1. Tailoring

Molcas, as shipped, is configured with some default settings. You can change some of these easily. You can change default settings used in Molcas (like memory usage, default scratch area, policy in saving files, etc.) by editing Molcas resource file: global resource file $MOLCAS/molcasrc or user resource file $HOME/.Molcas/molcasrc.

2.6.1.1. Dynamic memory

Most modules in Molcas utilize dynamic memory allocation. The amount of memory each module allocate is controlled by the environment variable MOLCAS_MEM. The amount of memory allocated is

  • MOLCAS_MEM is undefined — 1024 MB of memory is allocated (on 32 bit installation)

  • MOLCAS_MEM=nn — nn MB is allocated. If this amount cannot be allocated, the module stops.

2.6.1.2. Disk usage

Today many workstations utilize 64-bit integers and addressing. However, old UNIX workstations and PC’s had 32-bit integers resulting in a file size limit of 2 GB. To circumvent these limitations, the I/O routines of Molcas support multifile files, where a “file” is in reality a logical file consisting of several physical files. The size limit of these physical files is controlled by the environment variable MOLCAS_DISK according to

  • MOLCAS_DISK is undefined — The modules will use a 2 GB size of the physical files. This might be the appropriate setting for machines with 32-bit addressing.

  • MOLCAS_DISK=nn — The modules will use a nn MB size of the physical files.

To use files with a size bigger than 2 GB Molcas should be compiled as 64-bit executable.

2.6.1.3. Improving CPU performance

Molcas is shipped with a number of default setup files located in directory cfg/. The defaults in these files are set to a fairly safe level, but not necessary optimal. What you can change to improve performance is

  • Compiler flags

  • Mathematical (blas) libraries

The simplest way to set up optimization level, and/or compile Molcas with various BLAS libraries is to use configure -setup. This interactive script helps to make a proper selection of flags for improvement of Molcas performance.

If you do decide to try to improve the performance we recommend that you create a new setup file, for example, cfg/local.cfg and modify this file. It is not unlikely that your attempts to optimize the codes will lead you to a case where some modules work and others do not. In such a scenario it can be fruitful to have two copies of Molcas, one “safe” where all modules work and one “fast” where some modules do not function properly.

Changing the compiler flags is the easiest. Using the most aggressive optimization flags do sometimes lead to problems for some of the modules. We have tried to choose an optimization level that yields functioning code, but still reasonable fast. For some systems there is a predefined set of compiler flags for aggressive optimization. To compile Molcas with these flags you should run configure with flag -speed fast. Note that this aggressive optimization level is not supported by the Molcas team. In other words, you are using it at your own risk.

For some platforms you can utilize the vendor blas libraries. This will certainly yield better performance, but may not work on all platforms.

During configuration of Molcas it is possible to specify an external BLAS/LAPACK library. Use a flag -blas TYPE to specify the type of BLAS libary: lapack (for a standard lapack library), Goto (for GotoBLAS), Atlas (for ATLAS), MKL (for Intel MKL). You should also specify a flag

-blas_lib -Wl,--start-group -L/path/to/blas -lmy-blas -Wl,--end-group

specifying the link options. For example, to configure Molcas with Intel MKL library, you should issue a command

./configure -compiler intel -blas MKL -blas_lib -Wl,--start-group /opt/intel/mkl/lib/intel64 -lmkl_gf_ilp64 -lmkl_sequential -lmkl_core -Wl,--end-group

To compile Molcas with CUDA BLAS library, first, you have to compile the fortran wrapper provided by nVIDIA:

CUDA=/path/to/cuda/
FLAGS=-m64
gcc $FLAGS -I$CUDA/include/ -I$CUDA/src/ -c $CUDA/src/fortran_thunking.c -o \
$MOLCAS/lib/fortran.o
./configure -blas CUDA -blas_dir $CUDA/lib

or, if on a 64bit system:

./configure -blas CUDA -blas_dir $CUDA/lib64

After making changes to the setup files you have to issue the commands make veryclean, ./configure and make in the Molcas root directory. It is highly recommended to run the verification suite after any changes in configuration file.

2.6.1.4. Customizing handling of files

The location and attributes of files used by Molcas are defined in PRGM files. The master copy of these files is located at the data directory in the Molcas root. A user can copy these files and modify them. The highest priority is given to the files located in the subdirectory prgm in the current (CurrDir) directory, next the $HOME/.Molcas and finally the original location at $MOLCAS/data.

The simplest way to manipulate prgm files is to use the molcas prgm command. A command molcas prgm init global makes a copy of the prgm files in the .Molcas directory. molcas prgm init local creates a prgm subdirectory, and copies the prgm files into it. The editing of the files can be performed by your favourite editor, or by the molcas prgm script.

The structure of PRGM files is simple. The field (file) is followed by the FORTRAN name (as this file is known for Molcas), real file name (as this file is known by the Operating system), and finally the attributes.

The attributes are listed here:

ro

the file is accessed for reading

rw

the file is accessed for reading and writing

s

the file will be saved (copied) from the scratch area

m

the file will be saved (moved) from the scratch area

g

the file can be visualized by program “gv/luscus”

t

the file is an ASCII text

*

multifile

.

multifile (for internal use)

l

use lustre filesystem in parallel run

p

the file will be deleted

e

the file will be placed to memory (see FiM)

f

use an alternative file location (FastDir)

A command molcas prgm +x ScfOrb will add the attribute x to all ScfOrb files. A regexp can be used for a filename. An opposite command molcas prgm -x ScfOrb will remove the attribute x. A command molcas prgm comp [global] shows the list of modifications in the local (prgm), or global (.Molcas) directories.

2.6.1.5. Improving I/O performance

In order to activate this technology for a Molcas scratch file, one needs to do three things. First, please edit an external resource *.prgm (for example, $MOLCAS/data/seward.prgm) from the $MOLCAS/data/ directory. If you don’t have access to the root Molcas directory, then you can simply copy the needed resource file into your home $HOME/.Molcas/ directory and edit it there. The editing of the file consists in adding the “e” character to its attributes:

original: (file) ORDINT "$WorkDir/$Project."OrdInt rw*
modified: (file) ORDINT "$WorkDir/$Project."OrdInt rw*e

Second, you need to set up the MOLCAS_FIM environment variable to 1 i.e.:

export MOLCAS_FIM=1

The third and the final step is to specify the MOLCAS_MAXMEM (\(\geq\)MOLCAS_MEM) parameter such that the MOLCAS_MAXMEM−MOLCAS_MEM difference (in MW) is sufficient to host an entire file in RAM. In other words, the MOLCAS_MAXMEM−MOLCAS_MEM difference should exceed the original filesize.

In general, not all Molcas files are suitable for placing in RAM. In particular, it is a bad idea to activate FiM for RUNFILE. In order to identify which Molcas’s files are proper candidates for FiM, you can simply inspect the section II. I/O Access Patterns from a Molcas’s output. All files with high ratio of I/O random Write/Read calls are good candidates for FiM. In particular case of the SEWARD module, the ORDINT file is a very good candidate for FiM:

II. I/O Access Patterns
- - - - - - - - - - - - - - - - - - - -
Unit  Name               % of random
                       Write/Read calls
- - - - - - - - - - - - - - - - - - - -
 1  RUNFILE             28.6/  11.5
 2  ORDINT             100.0/  24.0
 3  DNSMAT               0.0/   0.0
 4  TWOHAM               0.0/   0.0
 5  GRADIENT            88.9/   0.0
 6  DNSMAX               0.0/   0.0
 7  TWOHAX               0.0/   0.0
 8  SODGRAD             85.7/   0.0
 9  SOXVEC              85.7/   0.0
10  SODELTA             88.9/   0.0
11  SOYVEC              88.9/   0.0
12  ONEINT             100.0/  53.3
- - - - - - - - - - - - - - - - - - - -

2.6.2. Applying patches

All program systems do contain bugs and Molcas is certainly no exception. We prepare patches for all problems as soon as we identify and fix the problem.

For important updates we provide Service Packs. A service pack is a shell script, which makes a backup of your current Molcas installation, and installs updates.

2.6.2.1. Local modifications

Molcas is shipped with source code so you can make modifications yourself. You are, of course, responsible for the correctness of any such modification.

If you do make changes/additions to the source code that you feel is of interest to other users, we encourage you to make these available. Perhaps the best mechanism is to use the bulletin board on out homepage: http://www.molcas.org.

Check Molcas Programming Guide for a detailed description of development and distribution of modified code in Molcas.