Home Icon  Home  Legal Icon  Legal Note  Contact Icon  Contact 
IMP Bioinformatics Group Leftlogo IMP Bioinformatics Group Rightlogo

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.