USER MANUAL
Version 2.1 (April 1995)
This is the introduction on how to use the program package ASC; for more details read the reference manual.
NOTE: most of the information provided in the users manual and the reference manual is not
really nescessary until you want to write your own script or you
download the ASC package to run your own version.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
USER MANUAL
for the program ASC / GM
Version 2.14 (April 1995/August 2001)
Introduction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
LICENSE AGREEMENT
When using the package ASC/GM the following conditions are accepted.
The program package ASC/GM will be distributed by the author Frank Eisenhaber
free for academic use. The detailed conditions are listed in the header of
any source code file. Commercial users will be given special contracts.
Please cite the following references when making use of this program :
1) Frank Eisenhaber & Patrick Argos
"Improved Strategy in Analytic Surface Calculation for Molecular Systems:
Handling of Singularities and Computational Efficiency"
Journal of Computational Chemistry, volume 14, N11, pp.1272-1280 (1993)
2) Frank Eisenhaber, Philip Lijnzaad, Patrick Argos, Chris Sander &
Michael Scharf
"The Double Cube Lattice Method: Efficient Approaches to Numerical
Integration of Surface Area and Volume and to Dot Surface Contouring of
Molecular Assemblies"
Journal of Computational Chemistry, volume 16, N3, pp.273-284 (1995)
The author made his best to avoid program bugs and algorithmic errors. He
will not accept any responsibility for any losses or disadvantages directly or
indirectly caused by the use of the program. The program is thought for a
professional user aimed at solving various tasks in context with surface
of volume calculations.
In the case of user-specific wishes, problems, obvious errors, or strange
behaviour of the program, please contact the author via
Dr. Frank Eisenhaber
IMP (Research Institute of Molecular Pathology)
Dr. Bohr Gasse 7
A-1030 Vienna
Austria
Frank.Eisenhaber@imp.ac.at
ACKNOWLEDGEMENTS
To Philip Lijnzaad, Eugene Demchuk, Ruben Abagyan, Maxim Totrov,
Dima Kuznetsov and Erik van Heyningen for suggestions and discussion.
*******************************************************************************
INTRODUCTION
The program package ASC / GM is designed for molecular-mechanical calculations
in conjunction with surface computations. Version 2.1 has the following
options:
1) calculation of the surface of a set of intersecting spheres via the new
analytical method (the van-der-Waals surface
or the solvent-accessible surface with any probe radius)
2) numerical determination of the surface via the double cube lattice
method as well as the calculation of volume and of dot surfaces
3) computation of surface energies and hydrophilic/hydrophobic surface
for ensembles of molecules and their constituents
The program is equipped with a command interpreter for a C-like program
language. For each command on-line help can be obtained (see file manual.lib).
The program writes a protocol at the location --> workdir() which can be
analyzed after the session visually (and also by programs). The filename
of the protocol file is formed by default with the execution time of the
program.
The program had been tested on DEC-stations (ULTRIX and OSF1) and
on SGI-computers (IRIX and IRIX64).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Call asc -h in your shell to see the commandline options.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At the beginning of execution the program tries to read the environment
variables :
workdir directory for result and protocol files
objdir directory for object (e.g. PDB) files
libdir directory for libraries
commdir directory for command scripts
prot_file name of a possible protocol file
comm_file name of a possible first command script
It is not a must to define these names. Most of them may be changed also from
inside the program interactively or in command scripts. See in the refence
manual --> workdir, commdir, libdir, objdir, ch_env. Some values may be
influenced also by command line options. Throughout the program, file names
are recognized as absolute locations if they start with (in UNIX) "/" or ".".
In all other cases, the file name is understood relative to workdir, commdir, i
libdir, or objdir.
The preference of the definition of this file is as following:
(1) Command line definition
e.g. with options -p (-np), -c etc.
(2) If there is no command line defintion, the program tries to read
the environment variables.
(3) If there are no definitions in accordance with (1) or (2), the
program takes default values as defined in the small
header file "system.h".
Please ensure that the protocol file name, the command script directory,
and the library directory are completely defined by one of the three
means to ensure regular functioning of the program.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
EXAMPLE of a command script (or an interactive conversation with asc):
include "std.def" # read standard definitions
ch_env OBJDIR "/data/pdb/" # change objdir to PDB-location
r_pdb "5pti.pdb", heavy, _nohyd # read heavy atoms in 5pti without H-at.
sf_set we92 # surface parameter set "we92"
time 1 # monitor cpu-time
asc # surface - analytically
sf_val asc full # results of surface calculation
nsc 600 # surface - numerically for >=600 dots
sfdiff 1. # differences per atom in surface
# areas
# calculated in both ways larger than
# 1 sq.Angstrem
quit # finish ASC
Example of input commands
r_pdb "1crn.brk"
r_msf "1crn.msf", we92
r_msf "1crn_sfty.msf", "sfmcla.sfty"
r_xyzr "1crn.xyzr"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*****************************
* *
* C-like COMMAND LANGUAGE *
* *
*****************************
LEXICAL STRUCTURE
The shell of ASC/GM analyzes command lines (<=256 letters finished by a
non-escaped new-line outside of quotes). Generally, quotes (single and
double) and the escape character \ (backslash) remove the special meaning
of some characters (as in C-shell or C).
Each line may contain a precompilation statement
(see manual.lib)
include, source,
define, alias,
undef, unalias, and chalias,
or one or several commands delimited by semicolons (outside quotes,
non-escaped and outside of parentheses). Commands may be grouped by
curly braces {}. Any identifiers should not be longer than 11 = MAXBEZ-1
letters; the name may consist of uppercase and lowercase letters, underscores
and digits, but starting with a letter or underscore.
Commentaries are C-like /* ... */ or the rest of line after # (the latter
only in command scripts).
Commands/functions are recognized by their command word. They have normally
two effects - one during execution and a second one with their return value
(can be used in expressions). Outside expressions, the syntax may
be very simplified (e.g. the command body may not be enclosed in parentheses,
only the commas after expressions followed by non-white space are necessary).
Example
time 1 # activate time monitoring
but
if (time()) {
...
} # ask for action if time is monitored
The commands may be invoked by using their first letters only. For example,
q, qu, qui are equivalent to quit, if their is no ambiguity to other commands.
But in such cases, the program informs the user about the set of similar
commands.
CONTROL STRUCTURES
The if-else-statement may have the following form
if { command; command; ... }
else { command; command; ... }
the else-component being optional. The control word may be followed by a single
executable command instead of a group of commands in braces. Conditional pre-
compilation is possible, e.g.
for (i=1; i<< >>
6 < <= >= >
7 == !=
8 &
9 ^
10 |
11 &&
12 ||
13 ?:
Operators of level 2 should not be used multiply (except !~+-*) and mixed
(except !~+-). In assingments ("=" statements), type conversions are
carried out without warning. The equality of pointer levels at both sides
is not checked, and the control is on behalf of the user. The decrement
and increment operators may be used only directly for identifiers and arrays
but not in other context:
EXAMPLES: --i; i++; ++a[9]; b[77]--; *p++ are allowed
(*p)-- is not allowed (application on parenthesized expression)
Two non-C string operations are possible :
c = "Hallo";
copies the string Hallo into the location c (c must be a pointer to character
and point into an array of characters, i.e. the commands
char let[200];
char *c;
c = &let[0];
had been invoked before). The command
echo c // ""; returns Hallo
on the screen. The command (// in level 4 of operation preferences)
echo c // " , my darling !";
echoes Hallo, my darling ! (string concatenation); at the same time, the whole
string is now written into the character array beginning with the location c.
echo c // "",", my darling !";
echoes the same string without writing it into location c.
The C-typical built-in-functions sin, cos, tan, asin, acos, atan, atan2, sinh,
cosh, tanh, exp, log, log10, pow, sqrt, ceil, floor, and fabs can be used.
The function m_pi() returns the value of pi as well as the definition PI.
All commands can be used inside expressions as functions (see manual.lib for
full syntax and the description of return values).
ATOM SETS
It is often of interset to work only with a subset of atoms.
Functions with molecular-mechanic action (as asc, nsc_1, sfdiff) operate over
the set of activated atoms (--> active_at). Descriptive functions (e.g.
w_pdb, w_msf, w_xyzr, sf_val, listat, sfatom, ...) use the subset of
selected atoms (--> select_at).
During reading of objects the set of all atoms is formed. The newly added
atoms are by default also included into the set of activated and selected
atoms.
