1.7. Subroutine Design Conventions and Constraints ___________

1.7.1. ARPS’ discrete operator methodology

The development of complex hydrodynamic numerical models is an arduous task that typically consumes tens of thousands of person hours over periods of years or even decades. The proper maintenance and continued improvement of such codes are even more time consuming and challenging, due in part to a lack of knowledge by scientists of appropriate software development strategies typically known only to or understood by professional software engineers. Another contributing cause, however, is the fact that most computer languages used in the scientific and engineering communities (e.g., FORTRAN, C) do not provide constructs directly analogous to the "native language" of a user, e.g., derivatives, integrals, etc. As a result of these and other factors, many existing models require considerable investments of time to learn and use and are unable to be adapted to rapid advances in technology (e.g., massively parallel computers) because their design is tied to prevailing standards, languages and architecture rather than more elemental and stable mathematical expressions.

In an effort to overcome some of these problems, and to establish a methodology for the rapid design and validation of complex models that are easily maintainable and operable across a variety of computer architecture, including those anticipated during the next 20 or so years, CAPS has developed a new strategy for solving differential equations based on the use of discrete numerical operators (Droegemeier et al., 1995). By design, the operators preserve the formal algebraic structure of the hydrodynamic equations, producing a code that, upon visual inspection, resembles the equations themselves rather than unwieldy expressions involving multiple increments to array subscripts. As fundamental units of discrete computation, the operators preserve the fine granularity inherent in hydrodynamics computations (e.g., multiplication of two dependent variables, single and multiple derivatives), giving the user an ability to distribute this granularity and associated parallelism in a manner most appropriate for the target computer architecture. The simplicity of the operators facilitates code validation, maintainability, ease of modification, and ease of learning, and therefore greatly reduces the time required to develop and, most importantly, to debug and validate complex models.

The operator-based strategy is illustrated in detail for a scalar advection equation in Appendix A.

1.7.2. Rules and conventions used in ARPS subroutines

Subroutine layout:

SUBROUTINE SUBNAME ( input_argument_list, output_argument_list, work_arrays)

The following information, separated by a full line of "###" characters, is provided at the beginning of each subroutine:

Purpose
Author, date, and modification history
Input and output list and definitions
Variable declarations (the IMPLICIT NONE construct is always used)
Include files
Executable code
RETURN
END

Subroutine Conventions:

  • The subroutine and its name are in CAPITAL letters.
  • The ordering of subroutine arguments is as follows: input; output; and work arrays.
  • Major comment blocks are separated by a full line of "###" characters.
  • Comment lines start with a "c" and the text starts in the 7th column.
  • The executable code in each routine begins immediately following the block of characters given below:

c
c@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
c
c Beginning of executable code...
c
c@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
c

This allows one to search for the beginning of executable code in each subroutine by simply searching for the string "@".
  • Key commands including IF, THEN, ELSE, ENDIF, DO, CONTINUE, RETURN, STOP, END, OPEN, CLOSE, CALL are given in CAPITAL letters.
  • Statements inside IF and DO blocks are indented successively by 2 spaces.
  • The "implicit none" construct is always enforced, and thus all variables and constants must be explicitly declared.
  • All temporary work arrays (e.g., tem1, tem2, etc.) are local to the routine in which they appear. They may be overwritten once the routine in which they are used is exited.
  • A colon (:) is used as the continuation mark.
  • Tabs are not used.