Maintaining the package ======================= .. only:: html .. contents:: :local: :backlinks: none 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 :file:`$MOLCAS/molcasrc` or user resource file :file:`$HOME/.Molcas/molcasrc`. .. _sec\:dynamic_memory: Dynamic memory .............. Most modules in |molcas| utilize dynamic memory allocation. The amount of memory each module allocate is controlled by the environment variable :variable:`MOLCAS_MEM`. The amount of memory allocated is * :variable:`MOLCAS_MEM` is undefined --- 1024 MB of memory is allocated (on 32 bit installation) * :variable:`MOLCAS_MEM`\=\ ``nn`` --- ``nn`` MB is allocated. If this amount cannot be allocated, the module stops. .. _sec\:disk_usage: 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 :variable:`MOLCAS_DISK` according to * :variable:`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. * :variable:`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. Improving CPU performance ......................... |molcas| is shipped with a number of default setup files located in directory :file:`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 :command:`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, :file:`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 :command:`configure` with flag :command:`-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. .. compound:: During configuration of |molcas| it is possible to specify an external BLAS/LAPACK library. Use a flag :command:`-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 .. compound:: 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 .. It is also possible to make a manual installation of a vendor supplied BLAS library. One should issue commands :command:`molcas uninstall blas_util`, :command:`molcas uninstall essl_util` and :command:`molcas uninstall %lapack_util` to remove BLAS/LAPACK related directories from the |molcas| source code, then export XLIB variable to set the location of blas library, e.g. :command:`XLIB="-lblas"; export XLIB`, and finally reconfigure and build |molcas|. If the library is in a nonstandard location you may have to issue the command :command:`XLIB="-Lpath_to_lib -lblas"; export XLIB`. Alternatively, define XLIB in the system specific configuration file. After making changes to the setup files you have to issue the commands :command:`make veryclean`, :command:`./configure` and :command:`make` in the |molcas| root directory. It is highly recommended to run the verification suite after any changes in configuration file. .. MT:sec:prgm: 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 :file:`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 :file:`prgm` in the current (:variable:`CurrDir`) directory, next the :file:`$HOME/.Molcas` and finally the original location at :file:`$MOLCAS/data`. The simplest way to manipulate prgm files is to use the :command:`molcas prgm` command. A command :command:`molcas prgm init global` makes a copy of the prgm files in the :file:`.Molcas` directory. :command:`molcas prgm init local` creates a :file:`prgm` subdirectory, and copies the prgm files into it. The editing of the files can be performed by your favourite editor, or by the :command:`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 :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 :command:`molcas prgm -x ScfOrb` will remove the attribute ``x``. A command :command:`molcas prgm comp [global]` shows the list of modifications in the local (:file:`prgm`), or global (:file:`.Molcas`) directories. .. _MT\:sec:fim: 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 :file:`*.prgm` (for example, :file:`$MOLCAS/data/seward.prgm`) from the :file:`$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 :file:`$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 :variable:`MOLCAS_FIM` environment variable to ``1`` i.e.: :: export MOLCAS_FIM=1 The third and the final step is to specify the :variable:`MOLCAS_MAXMEM` (:math:`\geq`\ :variable:`MOLCAS_MEM`) parameter such that the :variable:`MOLCAS_MAXMEM`\ |-|\ :variable:`MOLCAS_MEM` difference (in MW) is sufficient to host an entire file in RAM. In other words, the :variable:`MOLCAS_MAXMEM`\ |-|\ :variable:`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 :file:`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 :program:`SEWARD` module, the :file:`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 - - - - - - - - - - - - - - - - - - - - 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. .. You can get these patches from our web server in an easy and automatic way. 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. 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: |MolcasWWW|. Check Molcas Programming Guide for a detailed description of development and distribution of modified code in |molcas|.