CHARMM Element doc/developer.doc 1.1#File: Develop, Node: Top, Up: (chmdoc/charmm.doc), Previous: (chmdoc/testcase.doc), Next: (chmdoc/changelog.doc) CHARMM Developer GuideThis is to provide a guide to someone who wants to understand howCHARMM is implemented, and a variety of rules that should be followedby anyone who wishes to modify it. Anyone who wishes to modify CHARMMis advised to read through everything in this document.* Menu:* Implement:: CHARMM Implementation and Management* Directories:: What directories are used to store what information* Standards:: Standards (rules) for writing CHARMM code* Tools:: Tools for CHARMM developers* Modify:: The procedure for modifying anything in CHARMM* Document:: How to document CHARMM commands and features* Checkin:: How to deposit your development version into the central library#File: Develop, Node: Implement, Up: Top, Previous: Top, Next: Directories CHARMM Implementation and Management CHARMM is implemented as a single program package, which isdeveloped on a variety of platforms. As a result, it includes somemachine specific implementations and makes heavy use of the virtualmemory capabilities. By placing everything together, the task ofmodifying the program is made more reliable because errors inmodifying the program are more likely to be noticed. The singlesource package concept helps us to maintain integrity of CHARMM as theparadigmatic macromolecular research software system running on avariety of platforms. CHARMM was originally written in FLECS, FORTRAN77 and C languages.In the past, before FORTRAN77, FLECS allowed us to use a variety ofcontrol constructs, e.g., WHEN-ELSE, WHILE, UNLESS, etc. A FLECS toFORTRAN translator was used to process FLECS source code to produceFORTRAN source. FORTRAN77 provide us some structured languageconstructs. We began to program directly in FORTRAN77. The initialproject in CHARMM23 development was to convert all FLECS source codesinto FORTRAN. CHARMM 23f2 and later versions are fully in FORTRANexcept some machine specific codes written in the C language. All newcode should be written in FORTRAN77. Since CHARMM version 22, all files are maintained by utilizingsoftware engineering tools. We use the CVS (Concurrent VersionsSystem) utility to maintain the CHARMM source code, the documentationand other supporting files. The CVS repository resides ontammy.harvard.edu (Convex C220 running under UNIX). CVS is a supersetof RCS (Revision Control System); file and code management is carriedout with CVS and RCS commands. The CHARMM manager will be the soleowner of all CHARMM files and he will schedule/checkin/mergecontributions from both in-house and remote developers.#File: Develop, Node: Directories, Up: Top, Previous: Implement, Next: StandardsCHARMM Directory StructureCHARMM files are organized in the following directories. We use UNIXpathnames throughout the document. ~/ is the parent directory thatcontains the CHARMM main directory, ~/cnnXm. nn is the versionnumber, X is the version trunk designator (a for alpha ordevelopmental, b for beta release and c for gamma or general release)and m is the revision number. For example, c24b1 is CHARMM version 24beta release revision 1.Directory Purpose------------------ ---------------------------------------------------~/cnnXm The main directory of the current CHARMM version. install.com procedure runs in this directory.~/cnnXm/source Source and include files.~/cnnXm/doc Documentation~/cnnXm/test Testcases~/cnnXm/toppar Standard topology and parameter files.~/cnnXm/support Holds various support programs and data files for CHARMM. See *note Support: (chmdoc/support.doc).~/cnnXm/tool Contains the preprocessor, prefx, and other CHARMM processing/management tools. ~/cnnXm/build Contains Makefile, module makefiles and the log file of the install make command for each machine in the subdirectory named after the machine type.~/cnnXm/lib Contains library files~/cnnXm/exec Will hold executables#File: Develop, Node: Standards, Up: Top, Previous: Directories, Next: Tools Standards (rules) for writing CHARMM codeBecause CHARMM is implemented by a group, there are a number ofconventions which must be observed in order for the program to remainmodifiable, usable, and transferable. The rules which have beenestablished towards this end are listed below. 1) Gross subroutine organization: All INCLUDE statements are processed by the preprocessor to handle machine dependent INCLUDE'ing. ##INCLUDE is the preprocessor keyword. nn as in charmm_nn denotes the version number. Each subroutine should have the following structure. Note that any data statements come after all declarations and parameter statements, but before the first line of executable code. SUBROUTINE DOTHIS(ARG1,ARG2,....CC A comment which describes the purpose of this subroutine.C This may include important variables and what their use isC to aid in understanding and modifying the routine.CC A description of all passed arrays and arguments ifC users need to call this routine. C##INCLUDE '~/charmm_fcm/impnon.fcm' (required)##INCLUDE '~/charmm_fcm/dimens.fcm' (if dimensioned common blocks are included)##INCLUDE '~/charmm_fcm/exfunc.fcm' (if external functions are called)##INCLUDE '~/charmm_fcm/number.fcm' (if commonly used real*8 numbers are used)C declare all passed variables hereC##INCLUDE '~/charmm_fcm/what_i_need.fcm'##INCLUDE '~/charmm_fcm/more_i_need.fcm'CC local Declarations of ALL local variables and parameters. . data statements at end of declarations.CC begin . . Code (liberally documented through comments) . . END 2) All code should be written clearly. Since the code must be largely self-documenting, clarity should not be sacrificed for insignificant gains in efficiency. Variable names should be chosen with care so as to illustrate their purpose. Avoid using one or two letter variable names except for scratch variables. Comments should be used where the function of code is not obvious. 3) Input/Output a) The RDCMND routine should be used to read lines from