SeqQuest Programming Style Manual

Conventions

Units outline

• Rydberg energy units (1 Ry = 0.5 Hartree = 13.605 eV)
• Bohr distance units (1 bohr = 0.52918 Ang = 0.052918 nm)

Main program outline

• Computation should be in subroutines, not the main routine.
• do-loops are heartily discouraged in the main routine.
• write statements are self-documenting (no orphaned numbers in output!).
• Memory is tightly controlled
• File open/close done using FLxxxx routines, NOT the fortran primitive OPEN/CLOSE.
• Unit numbers for file i/o are named integer variables. No undirected write(*,*) and no write(14,*).
• All data communicated to subroutines through passed arguments

Memory outline

All large-scale memory is taken from a single large workspace in wk(maxwkd), where maxwkd is a parameter set in the main parameter file, using pointer-like integers. The routine WKMEM is the most important routine in the code: it partitions memory within wk(), and checks for memory sufficiency FOR THE ENTIRE CODE. Hence, WKMEM should be consulted before attempting any use of space within wk().

The wk() array is sectioned into pieces at the beginning of the code by pointer-like integer variables i01-i12, with spacing dictated by the size of big arrays. The first four, i01-i04, reserve enough space for either orbital matrices (nmat=nk*norb**2) or grid fields (nptr=n1r*n2r*n3r). (NB: this assumption is subject to change, check WKMEM for latest). The last eight spaces, i05-i12, only guarantee enough space for grid fields. Each of these spaces may be used as temporary space, and the intermittent comments "MEM" enumerate the contents of all the active "pointers" at that point in the code.

• No dynamic memory.
• Orbital matrices/grid fields must come from main workspace wk() and be given descriptive local names (and documented in main program).
• O(N) work arrays should be passed from wksmX() in main program.
• Memory is tightly scheduled - be careful not to overstep boundaries.

File I/O outline

I/O to all files is carefully structured to try and reduce the size of files, and to make data more easily accessible to the program without churning up disk. The FLxxxx routines have been set up to manage files. They allocate available (free) unit numbers (unit numbers are not to be hard-coded!), connect to correct directory structure (as needed), and complete the file names.

• Files will be explicitly opened using FLxxxx routines, not a fortran OPEN/CLOSE.
• I/O is always to named units (IRD,IWR,isetdat,ianalyz, etc.) and not to explicit numbers. I.e. write(6,*) is forbidden. Sole exception: exception/error handling in a deep routine that does not have IWR locally can write diagnostics using "write(*,fmt)".
• NO "print" statements, use "write" instead.
• standard input unit is IRD [from call FLGETIRD( IRD )].
• standard output unit is IWR [from call FLGETIWR( IWR )].
• Format labels are 8xxx for a read, 9xxx for a write.
• A write to the user output files should be carefully formatted and documented with a descriptive (preferably uniquely "grep-"able string) comment. For example,

        write(IWR,*)  engy

  should be replaced with something more descriptive:

        write(IWR,9020) 'TOTAL energy (Ry) =',engy
   9020 format(1x,a,f20.10)
  

• The preference is to do I/O from the top-level program, rather than called routines.
• Read/write of long records (grid fields, orbital matrices) should be done through a special set of routines in the code (WRITBIG/READBIG/BACKBIG/READSKP) that break up the long record into smaller pieces (The read/write of long records has been a problem on some Alpha-based machines).

Variable names outline

• All lower case.
• Restrict to eight characters or less (this convention may be relaxed at a future time, but, for now, keep them short).
• All variables with names beginning with i-n are integers, and v.v.
  Exception: logicals may begin with a capital "L".
• Dimensioning parameters end in "d", e.g. nkd, norbd, natmd.
• For passed variables, use the same name in the subroutine as was used in the calling routine, except for big arrays from main workspace wk(), which should be given a descriptive local name.
• Local variables will have the same names, where available, as they do in other routines. E.g., iatm and jatm are used to index atoms, not ia and ja, because the former are conventionally used elsewhere in the code. Always best to use existing routines as a model.
• No underscore characters, except for logicals.
• Logicals should have names that lead to descriptive use in an "if" statement. E.g. "if( do_neb )then" or "if( EVEN )then".

Upper/lower case outline

• Upper case used for:
  • subroutine and functions names (call FOO( x ))
  • file manipulations (e.g.,REWIND)
  • declarations (DIMENSION/DATA/PARAMETER/CHARACTER, etc.)
  • routine exits (STOP/RETURN/END)
  • standard unit numbers (IRD,IWR being standard in/out)
  • first character "L" in logical variable ("Loptall")
• Lower case used:
  • everything else

Subroutines/function calls outline

• Subroutine and function names are all upper case.
• Subroutine and function names try to be eight characters or less.
• Use generics for math calls where possible. For the error function, there is not a safe generic, so use ERF or DERF as necessary. Also, IABS and ABS to distinguish integer encouraged.
• Use "call MKZERO( len, arr )" to clear array arr(len).
• Use explicit arithmetic for 3-vectors and 2-vectors (complex) rather than function/subroutine calls. E.g., prefer this:

        adotb = a(1)*b(1) + a(2)*b(2) + a(3)*b(3)

  rather than

        adotb = DDOT( 3, a,1, b,1 )

• Communicate data through passed arguments rather than common.
• Avoid compound calls. E.g., replace "call FOO( BAR(x) )" with "call FOO( barx )" where "barx = BAR( x )".
• Should be space on the inside of parentheses of arguments.

Routine structure outline

• The typical routine has the following elements:
  • name banner (five comments lines, middle line >>>>> {name}
  • the routine declaration: subroutine/function FOO( .... )
  • main documentation section: purpose/author/revision history
  • more detailed comments/notes/variable descriptor comments
  • IMPLICIT DOUBLE PRECISION (a-h,o-z) or IMPLICIT NONE
  • variable declarations, by kind (input/output/scratch/local).
  • DATA declarations
  • statement functions (HIGHLY discouraged)
  • c >>>> EXECUTABLE CODE:
  • executable part of code
  • c That's all, Folks!
  • RETURN/END
• These elements are formatted in detail, use an existing routine for a model.
• Passed arguments take the same name as in the calling routine, except that big arrays passed from big workspace "wk()" in main routine should be given names descriptive of their use.
• I/O units should be passed first, dimension variables next, data arrays next, and arrays from workspace wk() last. Try to conform to order seen in other calls. Arrays out of workspace should be documented in calling program as to name and type (i-input, o-output, s-scratch). E.g.:

        call VESSLO( IWR, ibndpot, n1r,n2r,n3r,nptr, weight,
       $ ws(is1),ws(is2),ws(is3),ftarray,
       $ wk(i11),  wk(i06),  wk(i08) )
  c -->  rhoslo-io espot-2os gvecmag-i
       

  where i11=slow density, i06=electrostatic pot'l, i08=g-vectors mags.
• RETURN from anywhere other than the end of a routine is discouraged.

Routine families outline

Loops outline

• Loops are via do/continue or do/enddo, not do while
• Do NOT pass loop index into subroutine, e.g.,

       do  i=1,n
         call VERYBAD( i )
       enddo
       

  is to be avoided at all costs. Some optimizing compilers will get this wrong.
• No compound label-sharing loops. E.g.,

        do 10 j=1,n
          do 10 i=1,n
            s1
     10 continue
       

  should be written as two loops:

        do 20 j=1,n
          do 10 i=1,n
            s1
     10   continue
     20 continue
       

• do/enddo used for short loops without jumps to outside of loops.
• labelled loops otherwise (long loops, branches, complicated). This is fine:

        do  i=1,n
          s1
        enddo
       

  But, this should be changed:

        do  i=1,n
          if( foobar ) goto 11
        enddo
     11 continue
       

  to a labelled loop:

        do 10 i=1,n
          if( foobar ) goto 11
     10 continue
     11 continue
       

• Note that labels are right-justified, and two-space indenting.
• Note that exception goto label is indexed 11 to the loop's 10.
• Labelled do-loop ends with "continue" statement, not active statement.

Labels outline

• Labels are right-justified, NOT left-justified.
• Special label numbers reserved for specific purposes:
  • 8xxx reserved for "read" format statements
  • 9xxx reserved for "write" format statements
  • "13" reserved for error/exception handling (e.g., 13xx, xx13).
  • 999 reserved for final jump location before routine exit
  • 99x reserved for exit with some final processing
• Labels should be in numerical order, but with special treatment of I/O labels, and other exceptional labels.
• read/write labels 8xxx/9xxx should be in numerical order as well, where the "xxx" suggests the location within routine.

Indenting outline

• Code indent is by TWO spaces.
• NO tabs
• Open the first line after a "do" statement, close last line before the final continue in a do-loop:

        do 10 i=1,n
          s1
          ...
     10 continue
       

• Open within the branch points of an if-block:

        if( log1 )then
          s1
        elseif( log2 )then
          s2
        else
          s3
        endif
       

• Indent in continuation is one space:

        call FOO( arga,argb, ... ,argn,
       $ argo, ... ,argz )
       

• Note: continuation character is a "$"
• On (very) rare occasions, loops get deep enough that there is little code space left on a fortran 72-character line. In those cases, forego indenting in top level loops, or, better yet, try to use subroutine calls. Use good judgment, with code clarity being the goal rather than mindless adherence to a rule.

Space outline