The Implementation of CONGEN

The implementation of CONGEN is complex, because of the age of many parts of the code, the desire to preserve useful functions from CHARMM, the requirements of portability, and the need to provide as much functionality as possible. This chapter of the manual and the following one on storage management are essential to anyone interested in modifying the program.

CONGEN is implemented as single program. As a result, it is big. However, because of the use of dynamic storage allocation, it requires less initial storage than many contemporary modeling programs. By placing everything together, the task of modifying the program is made more reliable because errors in modifying the program are more likely to be noticed. This philosophy requires that testing be an integral part of the implementation of CONGEN. Ideally, there should be tests that exercise every line of code in CONGEN. As changes are made, the pre-existing tests are run to verify that changes were made correctly. As new features are added, new tests are constructed to ensure their correct operation.

CONGEN is implemented using FORTRAN, the FLECS preprocessor, and C. The reason for this mix is largely inertia. Early work on CHARMM was in FORTRAN because of its "easy" portability and convenience for numerical processing. Later, FLECS was used to make the program easier to read and modify. When the conformational search code was added, recursion became essential which lead to the use of C. There are no plans to rewrite CONGEN into one language because it is anticipated that others may wish to add Fortran code into the program.

The use of two languages in CONGEN requires an interlanguage interface. Most modern computers provide a mechanism for communication between C and Fortran. However, these interfaces are invariably machine dependent. In order to reduce the portability problems this entails, the program, wrapgen, has been written to localize the machine dependencies into one place, and free the CONGEN programmer from this problem while working on the regular code.

Besides the problem of the interlanguage interface, portability is a very important aspect in the implementation of CONGEN. In general, most operations in CONGEN are implemented using standard language features, but there are instances where machine dependent features are essential. In order to accommodate these machine dependencies, all the source code in CONGEN is run through a preprocessor. For the C code, the normal C preprocessor is used. For the FLECS/Fortran code, a modified version of the GNU Emacs C preprocessor is used, namely fcpp, or Fortran C PreProcessor. Certain C preprocessor variables are defined which indicate compilation on a particular machine, and these variables are used to determine which code to compile. A configuration file, `config.h' is used to determine the settings of generic preprocessor variables.

Binaries for different platforms can be kept under one directory tree and mounted using NFS. See section Installation of CONGEN on UNIX, for more information.

Please note that this section of the manual is intended to be an overview. There is no substitute for studying the source code carefully. Although it is an important goal to keep this documentation up to date, one should not trust this documentation too much since it is effectively a copy of information which is always being changed. If there are any doubts about accuracy, the source code is the final arbiter.

• Overall Organization: The structure of CONGEN
• Programming Environment Programming environment in CONGEN
• Fcpp: The Fortran C Preprocessor
• Wrapgen: Fortran/C Interlanguage calls
• Mkproto: ANSI C prototype generator
• config.h: A header file which controls the compilation.
• Making CONGEN: Makefile description
• Storage Management: Storage Management in Fortran
• Coding Standards: Standards (rules) for writing CONGEN code
• Tools: Programming Tools
• Tests: A description of currently available tests.
• Modifications: The procedure for modifying anything in CONGEN
• New Versions: The procedure for generating a new version of CONGEN
• VMS Installation: How to install CONGEN on VMS
• UNIX Installation: How to install CONGEN on UNIX

The Structure of CONGEN

CONGEN has a very simple organization. The main program is primarily a command dispatcher. It reads each command from the input file, parses the first word which is a command verb, and executes code to parse the remainder of the command and then perform its function. Data storage is simple in principle -- there are several dozen COMMON blocks which store information about the system being modeled, and the commands normally act to use or modify these COMMON blocks. Thus, many of the subroutines are independent of each other since they only depend on the data in the COMMON blocks.

Within CONGEN, there are also a large number of subroutines and functions that provide a convenient programming environment. For example, there are string manipulation routines, array manipulation routines, storage management capabilities, and operating system interfaces. Most of these routines are found in the source files; `string.flx', `array.flx', `util.flx', `cutil.flx', and `cgutil.flx'; and others can be found scattered throughout the program. The programming tool, autodoc, see section Programming Tools, can be used to list the comments from the subprograms within FLECS files.

Programming Environment

CONGEN is implemented using Fortran 77, the FLECS Fortran preprocessor, and C. All code is passed through a C preprocessor in order to handle conditional compilation. In general only standard features of the languages are used, but this rule is violated when there are strong reasons for doing so. (For example, the six letter maximum length of identifiers in Standard Fortran is far too onerous to bear, so the C limit of 31 characters is used, and there is a tool, makeshort, which can generate C preprocessor definitions to reduce the size of the variables to whatever machine dependent limits are necessary).

The management of revisions is done using RCS, the Revision Control System. We use version 5.5 obtained from the Free Software Foundation. Every source file should be kept under RCS control.

• Fortran: Fortran and FLECS
• C: C

Use of Fortran and FLECS

The main reasons for using Fortran as a base language is its widespread usage among the molecular modeling community and its wide availability. Most hardware manufacturers concentrate their compiler optimization capabilities into Fortran. However, Fortran lacks good control constructs, data structures, and operating system interfaces, so steps have been taken to circumvent these limitations. The control constructs are provided by using FLECS, data structures are provided through either an elaborate storage management scheme (see section Storage Management in Fortran) or by using C, and the operating system interfaces are generally provided using C.

FLECS is a Fortran preprocessor that allows us to use a much more robust set of control constructs than normally provided in Fortran. This allows for much more readable and understandable code than could be obtained via Fortran alone. In addition, the use of FLECS allows the development of new programs much more quickly because much less time must be spent working out the flow of control. It is described in detail in section `Introduction' in FLECS Manual.

Specifically, FLECS provides a block structured IF -- THEN --- ELSE clause, a structured iteration clause, WHILE and REPEAT WHILE clause as well as their inverses, CONDITIONAL and SELECT clauses, and internal procedures. The internal procedures are especially valuable because they allow long subroutines to be broken into small pieces while leaving all variables accessible. In addition, one can give very long names to these procedures which makes their purpose far more clear. For example, INTERPRET-COMMAND-AND-BUILD-CLAUSES tells you a lot more than CALL INTCBC or GOTO 285 does.

FLECS operates by translating any FLECS constructs into Fortran. Any non-FLECS constructs are merely copied. The Fortran compiler must be then be invoked to compile the translated code into machine language.

To invoke FLECS, type FLECS file1 file2 .... Any number of files can be translated. The default file extension for FLECS programs is `.flx'. The Fortran translations will be produced in files whose extension is `.f' or `.for' depending on the machine FLECS is executed on. The FLECS listing files appear with extension, `.fli'.

Concerning the portability of FLECS, FLECS was written in itself. It was designed to be transported and has been modified to use the C preprocessor to encode machine dependencies.

Not all of CONGEN has been written using FLECS, as the preprocessor was not adopted until August 1979. All new code should be written using it, and old code in needed of major modification should use FLECS as well.

Two non-standard feature of most Fortran compilers is routinely used, variable name lengths and memory overlays. Variable names can be any length. There is a programming tool, makeshort which can be found in `$CGP', which can be used to translate all long names into short names. (In this day, six character variable names is really quite an anachronism!)

The dynamic storage allocation schemes, see section Storage Management in Fortran, depend on mapping arrays of one type onto arrays of another type. It is necessary that REAL variables occupy the same amount of space as INTEGER variables. Numeric arrays are not mixed with character arrays, which avoids many alignment problems.

Use of C

C was first used in CONGEN for implementing the conformational search algorithm. This algorithm required complicated data structure processing and recursion, for which the language is eminently suitable. Later on, C was used for operating system interfaces because many of the operating system calls in C are portable. For example, the storage management Fortran library uses malloc in the C library to obtain additional storage from the operating system without a requirement for machine dependent code.

One limitation in the use of C is I/O. The Fortran and C I/O libraries are not compatible. Therefore, all I/O from C must be done using Fortran routines. See the source code for for_printf, for_scanf, etc. in `cutil.c' for routines which provide this functionality.

FCPP -- The Fortran C Preprocessor

FCPP is a modified version of the GNU Emacs C Preprocessor. This preprocessor provides all the functionality of the old style C preprocessor as well as #elif and the macros; __LINE__, __DATE__, __FILE__, and __TIME__. In addition, it contains additional features for Fortran code, and it has been ported to the VAX/VMS operating system in addition to other Unix platforms.

It is used on all Flecs code in CONGEN, and is described in greater detail in the fcpp manual page.

Note:, since fcpp is derived from the GNU Emacs C Preprocessor, it is licensed under the GNU Emacs License, which provides for more freedom to redistribute it than is available with CONGEN itself. Please see the license text in the source file, `cccp.c', or in your CONGEN license agreement, which incorporates the GNU Emacs License.

WRAPGEN -- The Wrapper Generator

The program, wrapgen, is used to generate the interfaces between Fortran and C. It is described in greater detail in the wrapgen manual page. Briefly, wrapgen takes a file of prototypes which describe functions written in either C or Fortran, and it generates procedures which can be called from the Fortran or C, respectively. The wrappers takes care of the machine dependencies inherent in character string representations, character string lengths, call by value or reference, and naming rules, so that the programmer need not be concerned about these details. All source code must include a wrapper header file generated by wrapgen in order to correctly handle the substitution of wrapper function names.

MKPROTO -- Make C Function Prototypes

The program, mkproto, will generate ANSI C function prototypes for all the procedures in a C source file. It is described in greater detail in the mkproto manual page.

In CONGEN, mkproto is used to avoid duplicating all the function definitions when preparing prototypes. Currently, it is used for all C files, except for `tree23.c' and `noproto.c'. The file, `tree23.c', is not run through mkproto because it is anticipated that it will be released as a separate procedure. The file, `noproto.c', is used for procedures for which mkproto doesn't work correctly. Presently, this occurs only with files containing machine dependencies where function definitions require the declaration of structures that are specific to a machine. Any necessary prototypes from this file can be put directly into `funct.h'.

The Configuration File, `config.h'

In order to simplify the use of machine dependent features, preprocessor variables have been defined which describe particular features. For example, the declarations of double precision variables in Fortran is given by the symbol, DOUBLE_TYPE. On most machines, this translates into DOUBLE PRECISION, but on the Cray, it translates to REAL. The source code file, `config.h', contains all these configuration variables. The values are set using a small number of machine identifiers which are set by the makefiles used to build CONGEN.

Making CONGEN

CONGEN is constructed using either the make command on Unix machines or the MMS utility on VMS. There is a master `makefile' or `descrip.mms' file in `CG', which will invoke all the necessary `makefile's needed to build the entire system. These `makefile's work fine on most machines, but have trouble on the Convex because their make program is older.

In order to handle the different compiler names and flags necessary for each different machine, many of the CONGEN directories have a file named `makefile.gen' which is missing definitions for these macros. In the `CG' directory, there are a set of `*.make' files which contain the macros needed for each type of machine. The names of the `*.make' files is as follows:

`sgi...'

There are several files for Silicon Graphics workstations which are described in section Installation of CONGEN on UNIX. Currently, there are four versions of these files, sgi_r10k_i6.4_c7.1_m4_a64.make, sgi_r3k_i5.3_c5.3_m1_a32.make, sgi_r4k_i5.3_c5.3_m2_a32.make, and sgi_r8k_i6.1_c6.1_m4_a64.make

`unicos'

Cray YMP running Unicos.

`rs6000'

IBM RS/6000 workstation running AIX.

`convex'

Convex computers.

`hpux'

Hewlett Packard 700 series workstations running HPUX.

`sparc'

Sun Sparcstations using gcc as the C compiler.

`alphaosf'

DEC Alpha machines running OSF.

`fujitsu'

Fujitsu VP240.

There is a program, fixmake, in the `CG' directory which will take one of these files, and incorporate into a `makefile'.

The selection of machine is done via the CGPLATFORM environment variable which is set in `$CG/cgdefs' or `$CG/cgprofile'.

The master `makefile' has several different targets that can be specified to build parts of the system. Use them with care. They are listed as follows:

prepare

Prepare for rebuilding the entire system. This will set up to rebuild everything including binary data files. It should be used only when porting CONGEN to a new machine, or when file structures are changed.

clean

Clean up unnecessary copies of executables, intermediate data files, objects, etc.

all

Make everything in place. Executables made by this target are not copied to the directories which are included into user PATH environment variables.

install

Make everything and put them where users will access them. Note that the install script from the X window system is used.(36)

tovax

Copy files to dino. This should be used only at Bristol-Myers Squibb, but will not have any effect on other sites except if the file name `/u/dino/fc/congen/...' leads someplace real.

setup

This will construct all the `makefile's from the `makefile.gen's.

In order to construct CONGEN from scratch on a brand new machine, the following steps must be followed:

1. Modify `$CG/cgdefs' and `$CG/cgprofile' to reflect your directory structure and the hardware platform.
2. Create a platform file in `$CG' which specifies the necessary switches for compilation.
3. Set your default directory to `$CG'.
4. Do a make prepare.
5. Do a make install. Some of the utility programs like peer may not build correctly on all SGI platforms. This should not interfere with the installation of CONGEN.
6. Compare the test cases found in `$CGT'.

To make a new directory tree for a different SGI platform, perform the following steps:

1. Verify that the master tree name in $CGROOT/master_machine is correct.
2. Add a new platform file in `CG' which specifies the necessary switches for compilation.
3. Execute cd $CGROOT
4. Execute ./update_tree new_platform_name
   The script, ./update_tree, copies all the files from the master directory stored in the file $CGROOT/master_machine into the directory specified above as new_platform_name. It sets up links for all RCS directories except the test case archive, which is duplicated for the new platform, because it is likely that the test values will change slightly.
5. Execute source cgundef
6. Follow the procedure for building CONGEN above starting at the cd $CG step.

Standards (Rules) for Writing CONGEN Code

The following set of rules is designed to help keep CONGEN readable and modifiable.

1. All routines should have similar organization. Each Fortran subroutine should have the following structure:

         SUBROUTINE DOTHIS(ARG1,ARG2,....
   C
   C     A comment which describes the purpose of this subroutine.
   C     This comment is essential because it provides the only
   C     documentation for nearly all subroutines in CONGEN. The
   C     program, AUTODOC, can be used to get this comment from all
   C     subroutines.
   C     
         <Declarations>
   C
         <Code>
   

   The separation of the code from the declarations by a blank comment aids in reading the code. It becomes obvious where executed code begins. Each C procedure should be written like this:

   dothis(type par1, type par2,...)
   /*
   *   A comment which describes the purpose of the routine. This
   *   comment must come here so that automatic documentation can
   *   be implemented (a program similar to AUTODOC is planned.)
   */
   
   {
       local declarations
   
       code
   }
   

2. Prototypes for all the C functions should be provided through the use of mkproto, see section MKPROTO -- Make C Function Prototypes. See the makefile for CONGEN for details of the mechanism. Note that not all files can be processed correctly, such as functions which are declared with structures or types that are machine dependent. All such functions should be placed in the file, `noproto.c'.
3. All source files must have a copyright notice at the top. See any source file for the appropriate text.
4. All C source files must include `config.h' and `wrappers_c.h' in that order. It is a good idea to use an existing source file to provide the copyright and includes to get started.
5. All FLECS source files must include `config.h' and `wrappers_f.h'.
6. All code should be written clearly. Since the code must be largely self-documenting, clarity should not be sacrificed for insignificant gains in efficiency. The use of C and the FLECS preprocessor is encouraged as it graphically illustrates the flow of control and allows for internal procedure calls. Variable names should be chosen with care so as to illustrate their purpose. Avoid using one or two letter variable names in any COMMON blocks. Comments should be used where the function of code is not obvious.
7. All usages of integers, floats, doubles in C code must use the F77_INTEGER, F77_REAL, and F77_DOUBLE macros defined in `config.h'. Boolean variables should use the BOOLEAN macro, and Fortran logical variables defined in Fortran should use the F77_LOGICAL macro. The F77_INTEGER macro should declare to a long int. If not, you must review calls to the different scanf and printf functions to ensure correct typing.
8. Be careful to distinguish between Fortran 77 logical variables and C integers being used to hold Boolean variables. The testing conditions are machine dependent. Use the macros provided in `macros.h' for Fortran logicals.
9. Be careful that the type of any numeric constant match correctly with its usage across the various platforms that CONGEN is implemented on. For example, there may be problems with using a real constant in an intrinsic function call with multiple variables in Fortran, eg. SIGN(1.0,P). If P is DOUBLE_DECL, you will have a problem because DOUBLE_DECL can map to either REAL or DOUBLE PRECISION depending on the machine. In such cases, it is better to use a variable or parameter to store the constant.
10. All usages of DOUBLE PRECISION variables in Fortran must be declared using the DOUBLE_DECL macro. This allows CONGEN to switch double precision variables to single precision on 64-bit computers.
11. Any variable in Fortran code that holds a pointer to be used by the C code must be declared using the POINTER_DECL macro. On 64 bit architectures, this macro will expand to 64 bit integers. The equivalent type in C is given by the F77_POINTER macro.
12. Any subroutine defined in C which can be called from FLECS code must have its prototype entered into the source file `wrap_cdef.proto'. Likewise, any subroutine defined in FLECS which can be called from C must have its prototype entered into the source file `wrap_fdef.proto'.
13. Whenever Fortran common blocks are accessed within C, you must use the predefined macro for the common block name. The macro is the upper case name for the common block. Header files (suffix `.h') are defined for all common blocks used in C code. For example, if you want to refer to the X coordinate array in C, use COORD.x.
14. There are number of rules associated with input and output:
    1. All input commands should be free field. The command processor should check that the entire command is consumed.
    2. Short outputs, messages, warnings, and error should be sent to unit 6 for output.
    3. All inputs should be echoed to unit 6. All values read by the command should also be output to unit 6.
    4. All warning and fatal messages should state what subroutine generated it, so that one find the location in the source code where the problem arose.
    5. All data structures output with unformatted I/O statements must have a HDR, ICNTRL, and TITLE in the first two records. See any existing binary output subroutines for the exact format.
    6. Unformatted I/O file formats should remain upward compatible. Use an ICNTRL array element to indicate which version of CONGEN wrote the file. Such upward compatibility must be maintained only across production versions of CONGEN. In other words, a file format for the developmental version may be freely changed until a new version is generated, at which point all future versions must be able to read it.
    7. All I/O must be done through Fortran I/O. C I/O is not to be used. See the procedures in the source code file, `CUTIL.C', for useful analogs of C I/O functions to make this rule easy to follow.
15. All error conditions must terminate with a CALL DIE. The subroutine, DIE, provides a traceback or core dump so the program statements causing the error can be seen.
16. Large or variable storage requirements for Fortran code must be met on the stack or heap. In C, cgalloc and cgfree should be used for all variable storage needs.
17. Array overflows must always be checked for when arrays are being written. This is especially important when the array being constructed might be dynamically allocated. Error checking in general should be as complete as feasible.
18. The code should use a minimum of non-standard Fortran or C features. All non-standard features must be conditionally compiled so that any CONGEN programmer is informed that the code is special.
19. In order to make subroutines callable from different contexts, parameter passing should be done through the subroutine call rather than through COMMON blocks.
20. All common blocks which are shared between multiple subprograms are to be placed in files and #include'd into the program. The common blocks should have comments describing each variable in the common block so that new users will know what's there. No directory should be specified for the #include'd files, so that the -I option to the C preprocessor can be used to select the directory at will. If a common block is to be shared between C and Fortran code, use the existing code in the *.h files to implement the needed name equivalence.
21. Avoid the use of static memory for initialization purposes. As more sections of CONGEN are implemented on parallel computers, making the subroutines reentrant is essential. Also, avoid the use of EQUIVALENCE and DATA statements in Fortran, since all storage referenced by these statements is allocated statically on the Iris.
22. When using scanf functions in C, use only long int's or doubles for your I/O, and then convert to your type. This avoids the need to control for machine dependent variations in data lengths.

Programming Tools

Presently, there is one tool for assisting in the development of CONGEN besides the language tools described within this section.

The program, autodoc, will collect information on all the entry points in a large Fortran or Flecs program and write them out using several different methods. For each entry point, the program collects the module name if different than the entry name, the file that entry point is in, the definition line of entry point, and the first block of comments which hopefully document the function of the routine. The files to be scanned are specified on the command line, and are written to file whose name is requested from the user when the program executes.

When autodoc is run, it will read the command line for files, and if none are found, it will ask you for files. Then, it will ask for an output file. It will then scan the files, and subsequently, it will ask you if you wish to sort the entry points by name. If not, the output will be in the order the files were read. Then it will ask if you want the short form of the listing. The short form is all the information on each entry except the comments. You will then be presented a list of subroutines which have no comments.

CONGEN Test Cases

The test cases may be found in `CGT' (as well as their developmental counterparts). All of these file generate output files which are to be compared with previous runs. In addition, some of the tests will generate other files which have the same file name, and these should be compared too. Scratch files have file names of `FOO' and file types which begin with the file name. For example, `DYNTEST1' generates a number of scratch files named, `FOO.DYNTEST1_nn', where nn is the unit number. These files should be deleted when the runs complete. The CPU time listed below is given in minutes for version 2 of CONGEN running on a single CPU of a Silicon Graphics 4D/200 series workstation.

Test cases run on platforms other than the Iris can be found in subdirectories under `$CGT' whose names match the platforms. For example, the Cray test case outputs are found in `$CGT/unicos'.

All the tests are run using the equivalent of the RUNCG command. On Unix machines, there are makefiles in both directories for running the test cases, and on VMS machines, there is a `descrip.mms' file. A target of diffs will make difference files for all the test cases.

The differences are always run through the program, `ndiffpost', see section ndiffpost -- Numerical Difference Postprocessor, and the output are written to files which have a suffix of `.dif'. The raw difference files are output to files which have a suffix of `.dif.raw'.

@multitable {AM94TEST7} {Time*} {Test D amino acid construction. Modified from CGTEST14.}