DelPhi: Statements and Functions

DelPhi now uses a command interpreter allowing english-like commands to be used in the parameter file.

The concept of the command in DelPhi comes in two forms, statements and functions.
Statements have the form:

Variable=value

e.g.

Scale=2.0
grid size=33
periodic boundary=x
frc write=true

etc.
Commands have the form:

operation(specifier,file="xxx.yyy",format=abc")

e.g.

in(pdb,file="lys.pdb")
out(phi,unit=20,format=2)
center(file="test.pdb")

etc.

(Note the (intentional) similarity to FORTRAN open statements) The difference is one of complexity. Statements merely set values or flags, functions cause operations to occur within the function and include moderators to influence these operations.

Formats

It should also be noted as to how DelPhi tells them apart. It does so by noticing that every statement has an equals sign that this is not inside of any brackets. I mention this because inevitably typos will occur and the interpreter will get confused occasionally. I have tried to anticipate some input errors and to inform the user of them, but the hardest part of every comlpex program is error handling, and at the moment DelPhi will only pipe back to you what it doesnt understand, and continue on with the program. So, be careful with equal signs. The other thing to use with care are commas. The interpretor uses (non-bracketed) commas to decide how many commands it is being faced with. For instance,

Scale=2.0, gridsize=65,center(file="mid.pdb")

is fine, but

frcwrite=on, out,(eps),

will get you a warning, and quite rightly so. One does not have to use commas to seperate commands, DelPhi will also tolerate "|" and ":", which are less ambiguous, but I find less natural. Do not use periods, since these can be confused with numerical values.

The commands are not case sensitive, although file names will be, i.e.

in(pdb,file="lys.pdb")

and

in(pdb,file="Lys.pdb")

are distinguished.

Spaces are fine, the interpreter discards them anyway. Comments can be added via exclamation marks. Anything to the right of an ititial "!" is ignored until another "!" or the end of the line is reached. For instance:

!set scale! scale=1.5 ! probe radius=1.4

will cause the scale to be set but not the probe radius, whereas,

scale=1.5! now set probe radius! probe radius=1.4

causes both to be set.

You can put as many commands as you like on a line, suitable seperated by commas of course, or put one per line. Also, if you reach the end of the line and want to continue on to the next you can use a continuation slash as in FORTRAN. For instance:

membrane=true,ion radius=\
2.0, gridsize=33

is read as,

membrane=true,ion radius=2.0, gridsize=33

(I doubt this will get used much, but one never can tell.)

You might have noticed that I said that if DelPhi fails to interpret something it will go ahead and run anyway. This might seem odd since older versions have tended to crash if one does not give them all the parameters they need. DelPhi is a step away from this in that it contains a complete set of parameters at run time. These default parameters will execute a DelPhi run (80% box fill) without any externally supplied parameters, i.e. the parameter file can be completely absent. This can, of course lead to inadvertent runs being done, but that is part of the price of the increase easy of use, i.e. one only needs to set those parameters which are different from the default. I, at least have noticed that relatively few parameters change from run to run which is the reason behind this "prepackaged" DelPhi. Finally, as we shall get into later, one can devise ones own set of default parameter if the system defaults are not to ones liking.

Shorthand and longhand statements

There are a set of abbreviations for each statement type. This come in two forms, two letter codes and six letter codes. Actually six letter codes are six to three letter codes. The reason for including these is that they are more compact (though less readable) than long descriptions, and as such they are less prone to typing error (once one knows them!). They are a matter of taste. A complete listing of abbrevations and the allowable long versions appears in an APPENDIX at the end of this document.

Yes, No, Maybe

When setting logical vaules the following are case insensitive and equivalent:

yes, on, true, t
no, off, false, f

Functions: In Detail

The present set of allowed functions are:

CENTER
ACENTER
READ/IN (Equivalent)
WRITE/OUT (Equivalent)
ENERGY
QINCLUDE

We shall cover these one by one since they vary somewhat more in format than statements. But first some of the common features

Function(file="test.file)

will open the file test.file, whether for centering, output or input.

Function(unit=14)

will do the same but with fort.14 or whatever is linked to it.

Function(format=abc)

will perform operations on files with a particular format, or in a specified way. The default format is always zero (i.e. "0"). The format can be a number or a string. For instance, if one wanted to write a formatted phimap one would write,

out(phi, format=1)

or if one wanted to write an frc file in Marilyns favorite format

out(frc,form=Marilyn)

Note that "format", "frm" and "form" are all equivalent. As one can begin to see this makes functions very flexible.

There are no shorthands for functions.

Center

Center(0.2,3,2)

will offset the molecule by 0.2 grids in the x direction, 3 in the y and 2 in the z, just as in the standard parameter file. So why make it a function? Because of the possibilities of needing to open a file to get the center

Center(unit=15)

will open fort.15, read all the atoms in it and make their center the center for the run.

There is a possiblity of adding a format quantifier to enable this to read, say unformatted file, but this hasnt been done yet.

To read just the first atom of a file and use its coordinates use the following,

Center(file="whatever",an=1)

Why the "an=1"? Why not just use a format specifier or something? The reason is that "an=1" is GRASP language for atom number one. At sometime in the future I may want to include the ability to add GRASP qualifiers to select parts of files for a function, e.g. in an frc file to only write those atoms which are charged etc. So this is just a bridgehead into the future so to speak.

Acenter

This hardly deserves to be a function, but I couldnt decide how to fit it in any other way. Acenter takes three absolute coordinates, i.e. in Å and uses those as the center, so

Acenter(1.0,5.6,7.0)

centers the molecule at x=1.0Å, y=5.6Å, z=7.0Å.

Energy

This replaces the energy line in the old style parameter file. At present it takes as its argument any of the following:

G or GRID for the grid energy,
S or SOL or SOLVATION for the corrected reaction field energy
C or COULOMBIC or COU for the coulombic energy
AS or ANASURF or ANALYTICALSURFACE for the analytical surface energy
AG or ANAGRID or ANALYTICALGRID for the analytical grid energy

separated by commas. (As always there is no case sensitivity here.)

So, for example,

energy(s,g,Cou)

gives the solvation, coulombic and grid energies.

Here also it would be nice to be able to select out part of the molecule, i.e. to find the energies associated with a portion of the molecule. All good things will come to those who wait.

Read/In

Obviously this function deals with file input. It comes with several specifiers, namely:

SIZ: for radius files
CRG: for charge file
PDB: for the pdb file
FRC: for the file use to determine site potentials
PHI: for the phimap used in focussing

The main use, at present will be to give the user flexibity to specify the file name or unit number of any of these files. At a later date functionality will be added so, for instance, a GRASP command file could set the sizes or charges, different format of pdb file could be read in etc. Note that the default files for all read (and write) operations are the standard DelPhi ones.

Write/Out

Equally obviously this deals with output. The specifiers are:

PHI: for phimaps
FRC: for site potentials
EPS: for epsmaps
MODPDB: for modified pdb files
UNPDB: for unformatted pdb file
UNFRC: for unformatted frc files

Clearly there is some redundancy here, for instance the unformatted pdb and frc files could fall under the PDB and FRC rubric with different format types. But for now we shall hone close to what we are used to. As an example of use,

write(eps)

writes an epsmap, standard format.

out(modpdb, file="test.out")

writes a modified pdb file called "test.out"

Note that all writes are turned OFF initially, including eps and phi.

The Parameter File

One will have noticed that using th above commands one can specify the unit number or file name of every file DelPhi normally uses, except the parameter file. Here we run into a catch-22 situation, there is no point being able to change the input file name from within the input file! Instead we have opted to allow the user to pass the name of the input file to DelPhi. For instance if one wants to use the parameter file "test.prm" as the parameter file one types:

delphi test.prm

Typing

delphi

defaults to fort.10 as usual. Any additional parameters are ignored, i.e. only the first is used as the input file. So,

delphi test.prm test2.prm

only uses test.prm

Qinclude

The qinclude function works in the same way as an include statement works in FORTRAN or C, i.e., it inserts lines from another file into the current one. For instance, suppose we have the following files:

test.prm:

scale=3.0, write(frc),write(modpdb,file="test.out")
acenter(0.123,4.55,2.34)

test2.prm:

boundary type=2, read(pdb,file="test.pdb")

then the file:

scale=3.0, write(frc),write(modpdb,file="test.out")
qinclude(test2.prm)
acenter(0.123,4.55,2.34)

is equivalent to:

scale=3.0, write(frc),write(modpdb,file="test.out")
boundary type=2, read(pdb,file="test.pdb")
acenter(0.123,4.55,2.34)

or one could even write:

qinclude(test1.prm)
qinclude(test2.prm)

Clearly the motivation behind this form is to allow the user to build up his/ her own default file and qinclude this file at the begining of any subaequent parameter file. Hence one then needs only a qinclude statement plus a line or lines indicating those parameters we want to change from the default file.

Note that qinclude is immediate, i.e. it includes the lines from the indicated file at the position of the qinclude command. This is important to remember since in DelPhi if you multiply define quantities, then the last instance is the current one, i.e.

scale=2.0
scale=3.0

leaves the scale set to 3 grids/Å. This then is the reason we include a write(specifier,off) command, so that if we have a default file which enables a write, we can still turn it off without modifying the default file.

Can a qinclude file contain a qinclude file? But of course. At present you can nest qinclude files upto ten deep, and I dare anyone to require more than that EVER!

If a qinclude file does not exist DelPhi will tell you so and move on to the next command. If there is no file passed to qinclude, i.e.

qinclude()

then the default include file ~/qpref.prm is passed, if it exists. Qinclude is a special command and as such always requires its own line, i.e. do NOT add more commands to a line which (must) start with a qinclude command (not even comments).

A sample parameter file

scale=2.0                            ! sets scale to 2 grids/Å
perfil=90                            ! sets percent box fill to 90%
indi=2                                 ! interior dielectric = 2
!bndcon=3                         ! focussing boundary condition-not enabled
in(pdb,file="ala.pdb")     ! reads in ala.pdb
in(crg,file="ala.crg")       ! reads in charge file ala.crg
in(siz,file="ala.siz")         ! reads in size file ala.siz
!in(phi,unit=18)               ! reads in a previously created potential
                                             ! map for focussing calcs - not enabled
!out(phi,unit=14)             ! outputs a potential map in default file
!out(phi,file="ala.phi")   ! outputs potential map in ala.phi
out(modpdb)                    ! outputs pdb file with radii and charges
energy(c,s)                        ! outputs coulombic and reaction field
                                            ! (solvation) energies
in(frc,file="self")             ! uses pdb file entries to output potential
out(frc,file="ala.frc")      ! and field values in ala.frc

Questions

Anthony Nicholls (nicholls@cumbig.bioc.columbia.edu)

Address questions to delphi@flash62.bioc.columbia.edu