2.11 Interfacing to CONGEN

A mechanism has been provided to allow casual users of the CONGEN to write their own special purpose subroutines which can be incorporated into the system without threatening its integrity.

There are two "hooks" into the protein system which have been specially provided for casual modifiers. The first is the USER command which invokes the subroutine, USERSB, and performs no other action. USERSB is a subroutine with no arguments. However, parameters may be passed to this subroutine via the system's COMMON blocks. These COMMON blocks store nearly all of the systems data. These common blocks may be obtained by including them from the directory containing the sources for the version of the program you are using.

The second hook is the user energy function USERE. USERE is a subroutine that is called whenever the total energy and its derivatives are calculated. USERE has ten parameters (in order):

EU

to be returned with the user energy

X

Y

Z

the current coordinates

DX

DY

DZ

to be returned with the derivatives if ANALYS is zero

ANALYS

a mode flag set to 0 if the total user energy and its derivatives are needed, and 1 if the atom energies are desired (in analysis)

DATA

to be returned with the atom energies if ANALYS is set to one.

NATOM

the current number of atoms.

Thus the call should be:

     CALL USERE(EU,X,Y,Z,DX,DY,DZ,ANALYS,DATA,NATOM)

EU should be set to the value of the user energy upon return. If this value is non-zero, it will be automatically printed each time the energy is evaluated. The system supplied version of USERE does nothing except set EU to zero. The coordinates are supplied via X, Y, and Z. Derivatives of the user energy must be added to DX, DY, and DZ. All other information used by USERE must be obtained through the system's common blocks as is the case with USERSB. Older versions of USERE that used only the first seven variables of the call can still be linked and run in the main section of the program, but will fail in the analysis section.

When using USERE fill only the arrays that are being requested by ANALYS (otherwise you will get access violations). In the analysis section of the program do not assume that the common block information will be correct for a comparison data structure, it may not be.

To simplify the use of these hooks and to allow users to replace subprograms in CONGEN with their own versions of said subprograms, the makefile, $CGS/usermake, has been provided for Unix, and the equivalent MMS descriptor file, CGS:USERMAKE.MMS has been provided on VMS. These makefiles will produce a private version of CONGEN in your default directory using your version of usersb.flx. If you need to change more files, then copy usermake into your working directory, and modify it accordingly.

Before attempting to write your own user functions, you should familiarize yourself with the information available on the implementation of CONGEN, see Implementation.

There are several utility routines available to a user routine. Some of them are listed below.

CALL GETE(X,Y,Z) will cause the energy and forces to be computed and values are saved in the appropriate common blocks. For this to work properly, NBONDS, HBONDS, and CODES must have been called. This can be done by executing both the NBONds and HBONds command, or by having previously found the energy (minimization, dynamics, etc.).

CALL PRINTE(IUNIT,ICYCLE,LHDR) will write the current energy values (from common block values) to the specified unit, IUNIT. It will also write out the cycle or iteration number, ICYCLE and optionally write out the standard header if LHDR is TRUE.