The Fortran 77 Cambridge Crystallographic Subroutine Library (CCSL).

P. Jane Brown

Institut Laue Langevin, BP 156, Grenoble, Cedex France,
E-mail:
brown@ill.fr– WWW: http://www.ill.fr/dif/ccsl/html/ccsldoc.html

Introduction

CCSL is a library of subroutines for doing crystallographic and related calculations. It was designed not so much as a system for determining crystal structures but as a toolbox to allow the crystallography of non-trivial structures to be easily introduced into user programs. The CCSL originated in the now defunct Crystallographic Laboratory of the Cavendish Laboratory, Cambridge in the early 1970's when the University first installed a computer which could interpret FORTRAN. It has subsequently been developed at the ILL by the present author, and at the Rutherford Laboratory by Judy Matthewman (now deceased), Bill David, and Bruce Forsyth amongst others. The main library now contains more than 500 subroutines and the master file some 50,000 lines of code. Full documentation is available on the web at http://www.ill.fr/dif/ccsl/html/ccsldoc.html.

There are three main areas in which a set of crystallographic subroutines can prove particularly useful to the solid state physicist; they are crystal symmetry, lattice geometry and scattering. The use of crystal symmetry is fundamental in CCSL; procedures are available to determine the constraints imposed by symmetry by the requirement that physical quantities, such as a bond length or an electron density, be invariant under the operations of the symmetry group. These determine the constraints, which must be, imposed in least squares refinements. For crystal geometry CCSL contains subroutines to manipulate vectors in real and reciprocal space which can be used in calculations of scattering angles, bond lengths etc. Subroutines, which calculate both atomic and magnetic structure factors and their derivatives with respect to the crystal parameters, are included. The system uses a common data structure to hold details of the crystal structure and the experiment being analysed. The data are given in the crystal data file which is a set of records up to 80 characters long; each identified by an initial letter indicating what kind of data it carries.

Use of CCSL

As noted above CCSL was designed to be used as a toolbox. The user is expected to provide a main program to do a particular job. This program should call CCSL procedures as necessary to set up the crystallography of the problem, do the required computation and report the results. The CCSL master file does however contain a number of main programs which have been written to accomplish common tasks and are maintained along with the library. They include programs for data analysis, straight forward crystallographic calculations such as structure factors and bond lengths, and several different types of least squares refinement. The modular nature of CCSL makes it easy to modify an existing main program or to write a completely new one since most of the work is done by calls to subroutines.

A simple example is given below of a program which could be used to design a diffraction experiment. It first finds reflections in a given range of sinq/l and calculates a quality factor which measures their sensitivity to the information sought in the experiment. This list in then sorted in order of decreasing quality factor. For each non-zero entry, the set of equivalent reflections which are accessible with the chosen diffractometer geometry, is generated and printed.

  • PROGRAM EXAMPL

    C

    CH Example program to demonstrate use of CCSL

    C

    PARAMETER (NREFS=100)

    DIMENSION H(3,NREFS),K(3),QUAL(NREFS),IP(NREFS),HSYM(3,24),PH(24)

    &,ANG(4)

    LOGICAL NOMORE,LERCHK,VISIBL,ABSENT

    COMMON /IOUNIT/LPT,ITI,ITO,IPLO,LUNI,IOUT

    C

    C Setting up phase

    CALL PREFIN('EXAMPL') !Initialise and read crystal data file

    CALL SETFC !Prepare for structure factor calculation

    CALL SETDC !Read diffraction geometry

    CALL SYMUNI !Makes an asymmetric unit in recip space

    CALL FUDGE !Fudges the LSQ pointers (see later)

    C

    LUNO=NOPFIL(2)

    CALL ASK('Give limit in sin theta/lambda')

    CALL RDREAL(SLIM,1,IPT,20,IER)

    IF (IER.NE.0) STOP 'Error giving limit'

    CALL ASK('Number of equivalents wanted')

    CALL RDINTG(NUMEQ,1,IPT,20,IER)

    IF (IER.NE.0) STOP 'Error giving number'

    CALL SETGEN(SLIM) !Prepare for reflection generation

    C Stop if there have been errors in the set-up phase

    CALL ERRCHK(0,0,'in EXAMPL')

    C End of set-up

    C

    NUM=1

    1 CALL GETGEN(H(1,NUM),NOMORE) !Generate hkl within an asymmetric unit

    IF (NOMORE) GO TO 2

    C Calculate quality factor

    QUAL(NUM)=QFACTR(H(1,NUM))

    IF (QUAL(NUM) .LT. .0001) GO TO 1

    IF (LERCHK(2,NUM,NREFS,-1,'reflections generated increase NREFS'))

    & GO TO 1

    C

    2 WRITE (LPT,11)

    11 FORMAT (/' h k l theta nu rho QFactr')

    NUM=NUM-1

    CALL SORTX(QUAL,IP,NUM)

    DO 3 N=NUM,1,-1

    NP=IP(N)

    NUMES=1

    CALL SYMREF(H(1,NP),HSYM,NSYM,PH) !Generate equivalent indices

    DO 4 J=1,NSYM

    C ANGD3 is not in the main library it is a subroutine of the

    C main program GENREF

    CALL ANGLD3(HSYM(1,J),ANG,ABSENT)

    IF (ABSENT) GO TO 4

    C visible should return .TRUE. if angles ANG are accessible.

    C IF (.NOT.VISIBL(ANG)) GO TO 4

    CALL INDFIX(HSYM(1,J),K)

    C Report results

    WRITE (LUNO,12) K

    12 FORMAT (3I5)

    WRITE (LPT,10) K,(ANG(I),I=2,4),QUAL(NP)

    10 FORMAT (1X,3I4,3F8.2,2X,F10.4)

    NUMES=NUMES+1

    IF (NUMES.GT.NUMEQ) GO TO 3

    4 CONTINUE

    3 CONTINUE

    STOP

    END

    C

    C

    SUBROUTINE FUDGE

    CH Fudges the pointers so that the only derivative calculated is

    CH The x parameter of the first atom

    C

    COMMON /PRBLEM/NFAM,NGENPS(6,1),NSPCPS(6,1),

    & LF1SP(5),LF3SP(10,1,1),LVFST1(6,1,1),

    & LBFST1(6,1,1),NVARF(6,1,1),

    & NBARF(6,1,1),LF6SP(3,1)

    COMMON /POSNS/NATOM,X(3,250),KX(3,250),AMULT(250),

    & TF(250),KTF(250),SITE(250),KSITE(250),

    & ISGEN(3,250),SDX(3,250),SDTF(250),SDSITE(250),

    & ATESDS,KOM17

    LOGICAL ATESDS

    C

    C Zero offsets

    LVFST1(2,1,1)=0

    NVARF(2,1,1)=1

    C Derivative 1 to be x of atom 1

    KX(1,1)=1

    RETURN

    END

    C

    C

    FUNCTION QFACTR(H)

    DIMENSION H(3)

    COMMON /FCAL/FC,DERIVT(200),FCMOD,COSAL,SINAL,FCDERS(200)

    COMPLEX FC,DERIVT

    C This could be anything, but for simplicity assume we want reflections

    C sensitive to the x parameter of the first atom in the atom list

    CALL LFCALC(H) !Calculate structure factor and derivatives

    QFACTR=FCMOD

    IF (FCMOD .GT.0.0001) QFACTR=ABS(FCDERS(1)/FCMOD)

    RETURN

    END

  • Modifying the tools

    The main programs provided with CCSL can rather easily be used to try out ideas for a new formulation of some physical process. It could be a new extinction model, a different form-factor representation, a new peak-function in profile refinement etc. The first step is to identify the subroutine or subroutines which are involved, usually there is a setting up routine, a calculation routine and, for least squares applications, one which deals with shifts in the parameters. They may often be combined in a single multiple entry subroutine. These routines must then be modified, without change of name, to reflect the new formulation. After compilation the new subroutines are included in the link step before the CCSL library search so that they are used rather than the originals.

    The CCSL Master file

    CCSL is written in FORTRAN 77 and conforms very closely to the ANSI standard (X3.9-1978). This has many advantages as it makes the system relatively easy to install on diverse operating systems. It does however have several disadvantages associated with the FORTRAN language. In particular the sizes of all arrays have to be fixed when the library is compiled. To allow maximum flexibility while minimising problems of maintenance, the complete set of CCSL routines and main programs is held in a Master File. The code in the master file is not quite FORTRAN 77, as in addition to the FORTRAN code it also containscontrol codes which allow:

    1. The code to be split into sections. Current sections include:

    LIB    the main subroutine library
    MAI    main programs which use only routines from LIB
    PR    the profile refinement library
    PF    library of peak fitting functions
    PMA    main programs for profile refinement
    PIG    graphics routines for different types of hardware andsoftware

    2. The dimensions of some arrays to be varied.

    The arrays used for storing information about atomic positions, numbers of form-factors, maximum sizes of Fourier maps etc, are fixed by default to relatively modest sizes so as not to produce excessively large storage requirements. These quantities are held as symbolic parameters in the master file so that they can be customised when building a library.

    3 The labelled COMMON blocks to be kept consistent

    Within the master file the labelled common blocks used by each subroutine are indicated by including just their names e.g.:

    /IOUNIT/

    /SYMDA/    and so on.

    When the library is built these are replaced by the full COMMON declarations which are held in a single block near the top of the master file, and the appropriate substitution for symbolic variables is made

    4 System dependent features to be customised:

    Lines which are operating system or site dependent are tagged with labels of the form CWXYZ where WXYZ may be any of

        LAX     Use an extension to FORTRAN 77 recognised by most compilers

        PICKY    To enforce strict compliance with the FORTRAN 77 standard

        [-]VMS    [don't] Include only if the operating system isVMS

        [-]UNIX    [don't] Include only if the operating system is UNIX

        ILL     Use ILL preferences: (extension for crystal data files is .cry listing file named program_name.lis)

        RAL     Use RAL preferences: (extension for crystal data files is .ccl name for listing file is demanded interactively)

    A set of perl scripts is used to manipulate the master file. They can be downloaded along with the master file by anonymous ftp from ftp://ftp.ill.fr/pub/dif/ccsl/.