10. Machine-dependent features

MOLSCAT is written in standard FORTRAN 77 as far as possible, but there are inevitably a number of features which depend on the particular computer being used. These will be described briefly here.

10.1 Main program

The MOLSCAT main program does not do any processing; it simply allocates storage and calls DRIVER to do all the work.

If MOLSCAT terminates with the message

 
     CHKSTR.  CANNOT PROVIDE REQUESTED STORAGE.

then it is usually sufficient to modify the main program to increase the parameter MXDIM and recompile.

Most of MOLSCAT's input is in NAMELIST format. This is not standard FORTRAN 77, but is implemented in most compilers and is too attractive a feature to forego. It does, however, introduce some quirks; for example, older CRAY versions of NAMELIST could not cope with CHARACTER variables, so the variable LABEL is handled in a peculiarly complicated manner.

For compilers that do not provide NAMELIST, it is usually possible to simulate it using other compiler extensions. Code for doing this is provided in commented-out form in the routines that read data, and the extra routines needed are available from JMH.

10.3 Integer length

MOLSCAT obtains working storage by partitioning an array of 8-byte real elements. On most machines, integers occupy only 4 bytes, so it is possible to pack 2 integers into each 8-byte element. The variable NIPR, set in subroutine DRIVER, must be equal to the number of integers that may be packed into 8 bytes. NIPR should be 2 on most machines, but 1 on a CRAY.

10.4 Date and time routines

MOLSCAT obtains the date and time of a run for output in the header by calls to routines GDATE and GTIME. These are not standard, and must be simulated. GDATE must return the current date as a CHARACTER*11, and GTIME must return the time of date as a CHARACTER*9. In the last resort, they can be replaced by routines that just return spaces.

10.5 CPU time routines

MOLSCAT outputs information on the CPU time taken by various steps, which it obtains by calls to subroutine GCLOCK. This must also be simulated in a machine-dependent manner; it is required to return the CPU time taken so far, in seconds. As a last resort, it may return a result of zero.

10.6 Floating point underflow

Various routines used by MOLSCAT require that the result of an arithmetic operation causing floating point underflow should be zero. MOLSCAT calls subroutine MASK in order to set this, and MASK should call an appropriate machine-dependent routine to suppress underflow. Some machines do this automatically, or use compiler options to achieve the effect; for example, a VAX ignores floating-point underflow if the compiler is invoked with the qualifier /CHECK=NOFLOATUNDER.

Take care that the routine used does not use excessive CPU time. For example, the routine ERRSET can be very expensive indeed on some IBM machines, because a complicated error-handling routine is called every time floating-point underflow occurs; if available the IBM VS FORTRAN, CALL XUFLOW(0), is generally preferable.

10.7 Linear algebra

LAPACK and BLAS

In version 12, MOLSCAT was modified to use LAPACK linear algebra routines wherever possible. LAPACK is the successor to LINPACK and EISPACK, and is designed to provide near-optimum performance for large problems on as wide a range of architectures as possible. Suppliers such as NAG and CRAY have already included substantial parts of LAPACK in their standard libraries, and will be including more in the future.

If possible, you should run MOLSCAT using LAPACK routines that are optimised for your particular computer. However, if this is not possible, you can obtain FORTRAN versions of the LAPACK routines from a NETLIB server: simply send an email message containing a line such as

     send dsyevx from lapack

to a NETLIB server such as netlib@ornl.gov (Oak Ridge National Lab) to obtain the source for the LAPACK routine DSYEVX.

The LAPACK routines use BLAS (basic linear algebra subroutines) as much as possible. BLAS level 1, level 2 and level 3 routines exist. You should use BLAS routines optimised for your particular computer if possible. However, if no optimised routines are available, you can get FORTRAN versions of the BLAS from a NETLIB server by sending an email message containing a line such as

     send dblas2 from core

to obtain the double-precision level 2 BLAS routines.

It is important that any user who implements new options in MOLSCAT should perform matrix operations by calls to the routines described below, both for ease of maintenance and to simplify the creation of efficient versions for other computers.

LINEAR ALGEBRA routines supplied with MOLSCAT

 
DGEMUL      Matrix multiplication
DGESV       Solve linear equations
SYMINV      Invert symmetric matrix
F02AAF      Diagonalise symmetric matrix without eigenvectors
F02ABF      Diagonalise symmetric matrix with eigenvectors

MOLSCAT also calls BLAS (basic linear algebra subroutines) such as DAXPY, DDOT etc (or single precision SAXPY, SDOT etc in the CRAY version) in many places.

Subroutine ODPROP (for efficient single-channel propagation) also requires special treatment for vectorisation to be achieved, and there is a special version of this routine for CRAYs and similar machines.

1) Matrix multiplication

MOLSCAT calls DGEMUL, which is a routine from the IBM ESSL library. In the distributed version, DGEMUL calls the BLAS routine DGEMM. If the real ESSL DGEMUL routine is available, use it; otherwise, use the best BLAS version of DGEMM that you can find.

2) Symmetric matrix inversion

MOLSCAT calls SYMINV. Two versions of SYMINV are recommended. The first, distributed with MOLSCAT, calls the LAPACK routines DSYTRF and DSYTRI to carry out the inversion. The second is a pure FORTRAN routine, which on most machines is faster than LAPACK equivalents for relatively small problems (N .lt 70). For optimum performance, you need to test both routines on your machine.

Note that MOLSCAT really does require matrix inversion, despite the usual rule to use linear equation solvers instead. This is because the propagators involved save information from one step to the next, and this advantage is lost if the problem is formulated in terms of linear equation solvers.

3) Linear equation solver

The speed of this routine is not critical for most propagators. MOLSCAT calls the LAPACK routine DGESV directly.

4) Eigenvalues and eigenvectors of symmetric matrices

These routines are important for INTFLG = 3, 4, 7 and 8. MOLSCAT calls diagonalisers by the NAG names F02AAF and F02ABF, and the NAG routines give acceptable performance on most machines. However, the distributed version of MOLSCAT provides routines that simulate F02AAF and F02ABF by calls to the LAPACK routine DSYEVX.

10.8 File handling

MOLSCAT adheres to the FORTRAN 77 standard in its use of READ and WRITE statements (including direct access files).

The OPEN statements do not use FILE='fname' parameters and you will have to provide files with the naming convention for your system. For example, IBM OS/MVS and CMS use FTnnF001 as the filename for UNIT=nn; IBM AIX uses filename fort.NN.

The following files may be used by MOLSCAT, depending on the value of parameter in the &INPUT data set.

 
      unit   formatted     use
     ------  ---------  ------------------------
     ISCRU     no       Propagator scratch unit 
                          used if ISCRU .ne. 0
     ISAVEU    no       S-matrix file written if 
                          ISAVEU .gt. 0
     ISIGU     yes,DA   Updated cross section file 
                          if ISIGU .gt. 0
     KSAVE     yes      Saved values for resonance 
                          search if KSAVE .gt. 0

In the VAX implementation, it is also convenient to OPEN the main data file and a supplied ISCRU file with the keywords SHARED and READONLY, so that several jobs can access them simultaneously. The resulting OPEN statements are nonstandard, and are commented out in the distribution version of MOLSCAT.

MOLSCAT always writes state-to-state cross sections (card images) to unit 7 at the end of a run, and it is necessary to supply a (system dependent) dummy data set if this output is not wanted.

On to the References