A S C The Analytic Surface Calculation Package
REFERENCE MANUAL
Version 2.1 (April 1995)
This is the reference manual for the program package ASC; we recommend to read the users manual first.
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.
****************************************************************************
***
*** REFERENCE MANUAL "manual.lib"
***
*** program package ASC/GM
*** version 2.14 (April 1995/August 2001)
***
*** Author: Frank Eisenhaber
***
*** Copyright Notice:
*** All rights reserved, whether the whole or part of the program is
*** concerned. The software may not be used without specific, prior
*** written permission of the author.
***
*** An academic licence agreement for the package ASC/GM or its parts
*** is granted if you make the following commitments:
*** 1) In using this software, the user will respect the interests of
*** the author.
*** 2) The use of the software in commercial activities is not allowed
*** without a prior written commercial licence agreement.
*** 3) Other interested research groups will be redirected
*** to the author. The user will not redistribute the code outside
*** his immediate research group.
*** 4) The copyright messages will not be modified or suppressed.
*** 5) The reference given below will be cited in any publication
*** of scientific results based in part or completely on use of the
*** program.
*** 6) Bugs will be reported to the author.
***
*** Permission to use, copy, and modify this software and
*** its documentation is hereby granted without fee for
*** academic use, provided
*** that the above copyright notices and this permission notice appear in
*** all copies of the software and related documentation.
***
*** THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF
*** ANY KIND,
*** EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
*** WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
***
*** IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
*** ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
*** OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
*** WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
*** LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
*** OF THIS SOFTWARE.
***
***
*** contact address :
*** Dr. Frank Eisenhaber
*** IMP (Research Institute of Molecular Pathology)
*** Dr. Bohr Gasse 7
*** A-1030 Vienna
*** Austria
***
*** Frank.Eisenhaber@imp.ac.at
***
***
*** Please send your contact address to get information on updates and
*** new features. Questions will be answered as soon as possible.
***
***
*** Please read file "manual.int" as introduction and use "manual.lib"
*** as reference material.
***
*** references :
*** 1) F.Eisenhaber, P.Argos
*** "Improved Strategy in Analytic Surface Calculation for Molecular
*** Systems: Handling of Singularities and Computational Efficiency"
*** Journal of Computational Chemistry (1993) v.14, N11, pp.1272-1280
*** 2) F.Eisenhaber, P.Lijnzaad, C.Sander, P.Argos, M.Scharf
*** "The Double Cubic Lattice Method: Efficient Approaches to
*** Numerical Integration of Surface Area and Volume and to Dot
*** Surface Contouring of Molecular Assemblies"
*** Journal of Computational Chemistry (1995) v.16, N3, pp.273-284
***
****************************************************************************
COMMAND manual
COMMAND man
COMMAND help
syntax help word[*]
The help-man-manual command is thought to supply short on-line explanations
for various commands. Normally all synonyms of commands are listed together
with the command syntax. It is advisable to have a look into the file
"manual.int" with introductory information.
The string following the help-man-manual command word can be finished by
a wild card *. In this case, the information on all commands having at least
one synonym with its first letters matching the string will be given.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND include
COMMAND source
syntax include string-expression
source string-expression
e.g. source "file"
ATTENTION: precompilation command
1) no other command is expected on this line )
2) the command words "include" or "source" may not be shortened
(no automatic search for matching first letters of command)
3) alias/definition-substitution is suppressed in precompilation lines
The command changes the control to a file which is expected to contain
other precompilation statements, commands and control statements. Take
into account that the command sequence inside the file is automatically
enclosed by braces so that control sequences (if-else-statements and
cycles) are expected to be closed inside this command sequence.
The file name may be given literally inside double quotes or with an expression
yielding a value of type (char *).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND alias
COMMAND define
syntax alias [string1] [string2]
define [string1] [string2]
ATTENTION: precompilation command
1) no other command is expected on this line )
2) the command words "include" or "source" may not be shortened
(no automatic search for matching first letters of command)
3) alias/definition-substitution is suppressed in precompilation lines
The first string is considered as name of the alias/definition, the second
string is the substitution sequence. It is advisable to maintain the C-style
convention to name a definition with identifiers consisting of uppercase
letters and underscores, but other identifiers are also allowed. The number
of alias/definition-substitutions in command lines is limited by
MAX_SUBSTITUTION. The first word of a command line may not be substituted more
than once by the same definition. Inside quotes alias substitution is sup-
pressed.
If the second string is missing, the existence of the definition with the
name of the first string is checked (equivalent to command "chalias"). The
naked command alias/define gives a list of all current definitions.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND unalias
COMMAND undef
syntax unalias string
undef string
ATTENTION: precompilation command
1) no other command is expected on this line )
2) the command words "include" or "source" may not be shortened
(no automatic search for matching first letters of command)
3) alias/definition-substitution is suppressed in precompilation lines
The string is considered as name of the alias/definition, which will be removed
from the definition list. It is not an error to remove an non-existing alias.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND chalias
syntax chalias string
ATTENTION: precompilation command
1) no other command is expected on this line )
2) the command words "include" or "source" may not be shortened
(no automatic search for matching first letters of command)
3) alias/definition-substitution is suppressed in precompilation lines
The string is considered as name of the alias/definition, the existence
of which will be checked. A message with the meaning of the definition
is returned.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND int
syntax int identifier=expression, identifier[expression], ***identifier;
Definition of integer variables. An identifier is composed of letters,
numbers and underscores, the starting sign is a letter. It is advisable
to use lowercase letters for variables and uppercase letters for definitions
in accordance with C-conventions (see --> define).
Online initialization of simple variables is allowed as well as the usage of
arrays and pointers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND real
syntax real identifier=expression, identifier[expression], ***identifier;
Definition of real variables. An identifier is composed of letters,
numbers and underscores, the starting sign is a letter. It is advisable
to use lowercase letters for variables and uppercase letters for definitions
in accordance with C-conventions (see --> define).
Online initialization of simple variables is allowed as well as the usage of
arrays and pointers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND char
syntax char identifier=expression, identifier[expression], ***identifier;
Definition of char variables. An identifier is composed of letters,
numbers and underscores, the starting sign is a letter. It is advisable
to use lowercase letters for variables and uppercase letters for definitions
in accordance with C-conventions (see --> define).
Online initialization of simple variables is allowed as well as the usage of
arrays and pointers.
Please take into account that char * is considered as string !
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND echo
COMMAND calculate
syntax echo expression, expression, ...;
calculate expression, expression, ...;
Calculates and echos the values of expressions in the sequence of occurrence.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND r_pdb
Reads a coordinate file in PDB-format. The atoms are automatically added to the
two sets active_at and select_at.
syntax r_pdb(file, flag, checks, number_of_chains, chainidentifiers);
Outside expressions the enclosing parenthesis are optional as well
as all commas. The first comma is obligatory (end of expression !)
if the command name and the file name is followed by something else.
file expression resulting in a string, i.e. char * (e.g. "file")
the file is expected to be located at the directory objdir()
--> see COMMAND objdir, ch_env
flag selection code for PDB-records
* or default: all atom records; if several alternating locations,
then take location A
heavy: only heavy atoms, ignore hydrogens
clean: as heavy, but ignore OXT
octal number: use predefined conditions
#define PDB_ATOM 01 /* read ATOM records */
#define PDB_CHAIN 02 /* read all chains, if not take specified */
#define PDB_ALTIDA 010 /* 1st alternative location */
#define PDB_ALTIDB 020 /* 2nd alternative location */
#define PDB_ALTIDC 040 /* 3rd alternative location */
#define PDB_HETATM 0100 /* read HETATM other than water */
#define PDB_HETHOH 0200 /* read water as one superresidue and molecule */
#define PDB_SKIP_OXT 0400 /* skip OXT during read */
#define PDB_SKIP_H 01000 /* skip hydrogens during read */
checks The allowed code words are: nocheck, _order, _nohyd, _hyd.
"order" forces the reordering of atoms in accordance with PDB-
standards. "nohyd" checks also for the completeness of heavy
atoms in the residue "hyd" controls also the number of
hydrogens. The optional leading underscore allows an incomplete
first or last residue.
Starting with the check-level "nohyd", the chirality of the chiral
atoms of the backbone and in the side chains (of ILE, THR) and the
correctness of labeling (in ARG, VAL, LEU) is investigated. Even
for well refined structures you will find many errors. In the case
of ARG, the atoms are automatically relabelled.
number_of_chains, chain_identifier
Reads only a predefined number of chains (if larger than zero),
specified in the string chain_identifier. Examples for both
fields are 3, "EFG" (only atoms of the three chains E, F, and G
are read). Do not use spaces between the chain-IDs. For chain IDs,
a string is expected as value (constant string is enclosed by "...").
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND w_pdb
Writes a coordinate file in PDB-format, only the atoms of the set select_at are
taken into account.
syntax w_pdb(file, flag);
Outside expressions the enclosing parenthesis are optional as well
as all commas. The first comma is obligatory (end of expression !)
if the command name and the file name is followed by something else.
file expression resulting in a string, i.e. char * (e.g. "file")
The file is expected to be located at the directory workdir(),
the extension ".pdb" is automatically added.
--> see COMMAND workdir, ch_env
flag selection code for residue names:
sup4l use the PDB-standard residue names(3-letter codes),
used as default and may be omitted
0 (=zero), use internal residue names with (sometimes) 4 letters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND w_xyzr
Writes a coordinate file in XYZR-format as used by Connolly, only the atoms
of the set select_at are taken into account.
syntax w_xyzr(file)
Outside expressions the enclosing parenthesis are optional.
file expression resulting in a string, i.e. char * (e.g. "file")
The file is expected to be located at the directory workdir(),
the extension ".xyzr" is automatically added.
--> see COMMAND workdir, ch_env
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND w_msf
Writes a coordinate file in MSF-format as used by Connolly, only the atoms
of the set select_at are taken into account.
syntax w_msf(file, code_word)
Outside expressions the enclosing parenthesis are optional as well
as all commas. The first comma is obligatory (end of expression !)
if the command name and the file name is followed by something else.
file expression resulting in a string, i.e. char * (e.g. "file")
The file is expected to be located at the directory workdir(),
the extension ".msf" is automatically added.
--> see COMMAND workdir, ch_env
code_word
define which atom types should be used in the atom table to be
written:
sfty or atty (the latter is default)
In the first case, the types are obtained from a surface
parameter set. In the second case, the type numbers are given in ac-
cordance with the general internal atom types.
Examples
1) w_msf("best_conformation", atty); is equivalent to
w_msf("best_conformation");
2) w_msf("store_molecule", sfty);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND r_msf
Reads a coordinate file in MSF-format as used by Connolly. The atoms are
automatically added to the two sets active_at and select_at.
!! Before using this command, set the probe radius with solrad !!
syntax r_msf(file, string);
Outside expressions the enclosing parenthesis are optional as well
as all commas. The first comma is obligatory (end of expression !)
if the command name and the file name is followed by something else.
file expression resulting in a string, i.e. char * (e.g. "file")
the file is expected to be located at the directory objdir()
--> see COMMAND objdir, ch_env
string A sequence of letters taken literally and denoting one of the
surface parameter sets (e.g. em86, we92, oons, jrf_) or an
expression yielding a string for a file name located at
objdir. This file is expected to contain the information on
types and radii. Each line for a given atom type should contain
the type number, the atom radius and the specific surface
energy (e.g. " 2 1.6 -112.5 # O" ). Everything after
# is ignored as comment.
format of the MSF-file:
One line contains the information for each atom, the x, y, z coordinates,
the type number (corresponding to the type number in the surface parameter
set, the atom name (leading spaces in the name as in the case of
PDB-names are denoted by _ - underscore), the residue name, and the residue
number.
Examples
1) r_msf("1crn.msf", em86);
2) r_msf("1crn.msf", "sfmcla.sfty");
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND r_xyzr
Reads a coordinate file in XYZR-format as used by Connolly. The atoms are
automatically added to the two sets active_at and select_at.
!! Before using this command, set the probe radius with solrad !!
syntax r_xyzr(file, code);
Outside expressions the enclosing parenthesis are optional as well
as all commas. The first comma is obligatory (end of expression !)
if the command name and the file name is followed by something else.
file expression resulting in a string, i.e. char * (e.g. "file")
the file is expected to be located at the directory objdir()
--> see COMMAND objdir, ch_env
code A sequence of letters taken literally and denoting one of the
surface parameter sets (e.g. em86, we92, oons, jrf_). In this
case the internal R-information of the file will not be taken
into account. This parameter may be absent indicating that the
internal R-information should be used.
format of the XYZR-file:
One line contains the information for each atom, the x, y, z coordinates,
the radius, the atom name (leading spaces in the name as in the case of
PDB-names are denoted by _ - underscore), the residue name, and the residue
number.
Examples
1) r_xyzr("1crn.xyzr"); (is equivalent to: r_xyzr "1crn.xyzr" )
2) r_xyzr("1crn.xyzr", em86);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND asc
syntax asc()
Analytical calculation of the surface of the ensemble of activated atoms.
Surface values per atom are stored in acsfat. Parentheses are optional if
used outside expressions. The command returns the surface area (in sq.
Angstrem) for the set of active atoms (-> active_at).
Surface values per atom are stored in acsfat.
example: 1) > asc; /* information on stdin */
2) > echo 2*asc(); /* value of area is returned to evaluate
expression */
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND nsc_1
COMMAND nsc
COMMAND nsc_t
syntax nsc_1(expression)
(-> number_of_points_per_sphere any number > MIN_DENSIT;
if no number default of 300 points is used )
syntax nsc_t(expression, expression)
Numerical calculation of the surface of the ensemble of activated atoms
by the Shrake & Rupley method (with the double cube lattice method, modi-
fication by Frank Eisenhaber).
The point density is at least as requested in the argument (a tesselation
level t is found so that 10*t**2+2 >= argument).
The most even point distribution is set as default for nsc_1. In the
command nsc_t, the second integer expression codes the way of obtaining
dots (eg. 12 ... default value).
Surface values per atom are stored in acsrat.
The command returns the surface area (in sq. Angstrem) for the set of active
atoms (-> active_at).
example: 1) > nsc_1 600; /* information output on stdin */
2) > echo 2*nsc_1(600); /* value of area is returned to evaluate
expression */
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND nsc_2
syntax nsc_2(expression)
(-> number_of_points_per_sphere)
Numerical calculation of the surface of the ensemble of activated atoms
by the Shrake & Rupley method (with some modification by Pietr Zielenkowicz,
Maxim Totrov and Ruben Abagyan). The point density is at least as requested
in the argument.
Surface values per atom are stored in acsrat.
The command returns the surface area (in sq. Angstrem) for the set of active
atoms (-> active_at).
example: 1) > nsc_2 600; /* information output on stdin */
2) > echo 2*nsc_2(600); /* value of area is returned to evaluate
expression */
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND nsc_3
COMMAND nsc_vol
syntax nsc_vol(expression)
(-> number_of_points_per_sphere)
Numerical calculation of the volume of the ensemble of active atoms via
surface calculation with the double cube modification of the
Shrake & Rupley method.
The point density is at least as requested in the argument.
The command returns the volume (in cubic Angstrem) for the set of active
atoms (-> active_at).
example: 1) > nsc_vol 600; /* information output on stdin */
2) > echo 2*nsc_vol(600); /* value of volume is returned to evaluate
expression */
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND nsc_4
COMMAND nsc_dots
syntax nsc_dots(expression)
(-> number_of_points_per_sphere)
Generation of dot surface. The point coordinates will be written to a
file (the file name will be composed of -> workdir, molecule name and
a date string).
The point density is at least as requested in the argument.
The command returns the area (in sq. Angstrem) for the set of active
atoms (-> active_at).
example: 1) > nsc_dots 600; /* information output on stdin */
2) > echo 2*nsc_dots(600); /* value of area is returned to evaluate
expression */
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sf_statist
syntax sf_statist()
Print the statistics of intersection circles and vertices to protocol.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sf_val
syntax sf_val(asc/nsc, sfey/hydr/full)
Print the surface and surface energy values for selected --> sf_set. The
code asc and nsc distinguishes between analytical and numerical surface
calculation (invoke --> asc or -->nsc_1 before sf_val). The second code
may be omitted. "sfey" is the default value (only overall surface and
energy), "hydr" gives additional information on hydrophobic and hydrophilic
surface (surface with non-negative and negative surface energy for the
given surface parameter set). "full" lists additionally the contributions
of every atom type.
Only the atoms in the set --> select_at are considered.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sfatom
syntax sfatom(asc/nsc)
Print the surface values per atom calculated analytically (asc) or numerically
(nsc).
Only the atoms in the set --> select_at are considered.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND lsat
COMMAND listat
syntax listat()
Print atom nformation.
Only the atoms in the set --> select_at are considered.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND lsre
COMMAND listre
syntax listre()
Print residue information.
Only the atoms in the set --> select_at are considered.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND lsml
COMMAND listml
syntax listml()
Print molecule information.
Only the atoms in the set --> select_at are considered.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sfloop
syntax sfloop(loop_information_file, result_file)
Calculate contact surface properties. contact program developper if interested.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sf_diff
syntax sf_diff(expression)
Check the difference between analytically and numerically calculated surface
values. Consider the real value obtained as result of the expression as upper
threshold for the absolute difference above which each atom is monitored in
the protocol. A difference exceeding twice the real value is considered as
severe deviation and causes a warning.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND bye
COMMAND ciao
COMMAND exit
COMMAND quit
COMMAND stop
syntax bye() ...
Immediately stops the execution of the program. Parentheses are optional
outside expressions.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND history
syntax history(expression)
Print history of commands on screen. If an expression is
given inside parentheses, the line number is changed to the result. The
return value of history is the current line number.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND solrad
syntax solrad(expression)
solrad()
"solrad" returns the current value of the solvent radius. It accepts a new
value if an expression is given. The initial default value of solrad is zero !
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND time
syntax time(expression)
time()
"time" returns the current value of the time setting. If it is equal to one,
the time consumption of expensive operations (e.g. surface calculation) is
measured. It accepts a new value (0 or 1) if an expression is given.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND warning
syntax warning(expression)
warning()
"warning" returns the current value of the warn setting. If it is equal to one,
the warnings are given to the output. Warnings may reflect errors of program-
ming or data input, but also inconsistencies in PDB-files etc.
It accepts a new value (0 or 1) if an expression is given.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND verbose
syntax verbose(expression)
verbose()
"verbose" returns the current value of the verbose setting.
It accepts a new value (0 or 1) if an expression is given.
If it is equal to one, the commands are protocolled in the protocol file
and on screen.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND r_lib
COMMAND w_lib
syntax r_lib()
r_lib(sfty)
r_lib(retp)
r_lib(ps_e)
w_lib()
w_lib(sfty)
w_lib(retp)
w_lib(ps_e)
Read or write (to the protocol file) all libraries or only one of them.
code library
------------------------------------------------------------------------
ps_e periodic system of elements
retp residue topology
sfty surface parameters (atom radii, probe radii and surface energies)
------------------------------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sf_set
syntax sf_set(name of set)
Select surface parameter set by code word (e.g. em86, we92, oons, jrf_).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sf_ey
syntax sf_ey(code, expression)
The command sf_ey is useful to change the energy weights per sq.Angstrem
without changing the radii table. The optional expression should result
in a double-precision floating-point number. If missing, the default
value is 1.0 . This command can only be invoked after sf_set or a successful
execution of r_msf or r_xyzr. A repeated invocation of sf_set clears the
results of sf_ey.
code
----
area all area has the same weight
polar polar atoms (with surface energy weight < 0 are assigned
the expression value with sign "-"), non-polar
atoms get the unchanged value.
Examples:
1)sf_ey(area, 2.0);
2)sf_ey(polar) is equivalent to sf_ey(polar, 1.)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND weight
syntax weight()
Returns the molecular weight (as double) of the set of selected atoms
(-> select_at). As single command outside expressions it communicates
the molecular weight on standard input and in the protocol. This command
works correctly only for atoms read with r_pdb or for MSF/XYZR-files
with full atom description (-> r_msf, r_xyzr with input using the internal
database).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND commdir
syntax commdir()
Funtion returns string with the current value of the command directory
(location of command scripts and the file std.def - standard definitions).
It can be changed by the command --> ch_env.
At the start, the program tries to read an environment variable with the
command name.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND workdir
syntax workdir()
Funtion returns string with the current value of the working directory
(location of result files and protocol).
It can be changed by the command --> ch_env.
At the start, the program tries to read an environment variable with the
command name.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND objdir
syntax objdir()
Funtion returns string with the current value of the object directory
(location of object files, e.g. coordinate tables, pdb-files ...).
It can be changed by the command --> ch_env.
At the start, the program tries to read an environment variable with the
command name.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND libdir
syntax libdir()
Funtion returns string with the current value of the library directory
(location of library files and manual).
It can be changed by the command --> ch_env.
At the start, the program tries to read an environment variable with the
command name.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sfty_lib
syntax sfty_lib()
Funtion returns string with the current value of the name of the surface
parameter library.
It can be changed by the command --> ch_env.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND retp_lib
syntax retp_lib()
Funtion returns string with the current value of the name of the residue
topology library.
It can be changed by the command --> ch_env.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND wk_obj
syntax wk_obj(expression)
wk_obj()
"wk_obj" is an array of 10 strings. The expression may be absent (which is
synonym to zero) or be equal to a natural number between 0 and 9.
Funtion returns string with the current value of wk_obj.
It can be changed by the command --> ch_env.
At the start, the program tries to read an environment variable with the
names wk_obj(=wk_obj0), wk_obj1, wk_obj2, ..., and wk_obj9.
The strings can be used everywhere in expression to produce a string
(e.g. as filename).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND system
COMMAND unix
COMMAND vms
COMMAND vax
syntax system(expression)
The string which should be the result of the expression will be handed to
the shell for execution.
Example system("date");
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND listob
COMMAND delobj
syntax listob()
delobj(expression)
"listob" lists information on all objects currently hold. "delobj" deletes
the object with the integer number obtained as result of the expression.
This may be important if memory has to be freed.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND ch_env
syntax ch_env(item, expression)
The command changes environment values. The expression should yield in a string
which is considered the new value of the item under consideration. The fol-
lowing items are allowed :
(see -->) commdir, workdir, objdir, libdir, retp_lib, sfty_lib,
wk_obj(expression)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND distan
COMMAND plaang
COMMAND dihang
syntax distan(expression, expression)
plaang(expression, expression, expression)
dihang(expression, expression, expression, expression)
Calculate distance, planar and dihedral angle (in degrees) defined by
atom numbers (internal numbering of atoms).
Example echo distan(1,2)+distan(2,3);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND active_at
COMMAND select_at
syntax active_at('field:field: ...');
select_at('field:field: ...');
Formation of subsets of atoms. The parentheses are optional outside expres-
sions,the single quotes (optional) have the only function to suppress alias
sustitution. This is necessary if, e.g., a name of a molecule matches an
alias. The colon of the last field is optional. The first operator (active_at)
selects a subset of all atoms. The second one forms a sub-subset. In the
default case, all three sets are identically.
The field syntax and the delimiter ":" follow mainly the conventions of ICM
(Ruben Abagyan) and INSIGHT (BIOSYM). The description of atoms is generalized
here.
The sets of atoms are ordered. The order is defined by the input or creation
of molecules except cases of automatical reordering (input from PDB-files,
acceptance of standardized order). A reordering of atoms as in the syntax of
INSIGHT is not built in.
Up to three fields without leading specifications denote
molecules:residues:atoms:
The items may be specified by integer numbers or simple integer variables. Also
ranges are allowed, e.g. 1-nat. Sometimes it may be useful to denote a variable
explicitely as such by a leading $, e.g. $nat, to avoid conflicts with names.
In this case, internal numbering is supposed (see --> list*).
It is also possible to use the original ("biochemical") numbering of atoms
and residues. The specifications should be preceded by a @, e.g. the residue
specifications @63A-65 (of 1acx) may also contain insertion codes. In this
case, variables are not allowed. Make sure that in this case of residue
specifications the bordering residues had not been unselected at the
selection levels up to this stage.
The items may also be defined by names. Molecule and residue names are
thought to match the string in the specifier with their first letters.
For example, the name 1aap denotes all chains of this PDB-entry,
1aapA specifies one single molecule (the A-chain). Atoms
are named normally according to PDB-conventions. In this case, the chemical
element should be specified by one uppercase letter and, if necessary, by a
second lowercase letter. E.g. Ca denotes calcium, CA is the alpha-carbon of
amino acids. A star may be used as wildcard, e.g. HH* for ARG denotes
1HH1, 2HH1, 1HH2, 2HH2. To avoid confusion with variable identifiers or alias
definitions, name may be enclosed by double quotes to emphasize the string.
A leading space in the atom name may be denoted by an underscore "_", but
this is optional.
Certain default names are allowed:
"AmAc" - amino acids;
"Arom" - aromatic amino acids F,H,W, and Y;
"Alph" - aliphatic amino acids A,G,I,L, and V;
"Hydr" - hydrogen atoms.
Fields may have a leading specification
o_[numbers] input objects (see numbers of objects with command listob) -
take all atoms of the specified objects
d_[real] distance condition (real value for distance) - take
all atoms with a distance from one of the previously specified
atoms less than a specified value
a_[real] atom accessibility condition (real value for minimal relative
atom accessiblity, if % is following, minimal absolute
atom accessibility otherwise) - take only sufficiently exposed
atoms
r_[real] residue accessibility condition
(the sum of the atom accessibilities of a given residue
should be larger than the real value measured in sq.Angst.)
A percent sign that may follow the real value is currently
ignored.
At the beginning of the field (if no leading specification) or after the
leading specification, the sign ^ denotes "all but" (negation operation).
A single star or an empty field denotes all atoms of the set considered.
Selection fields may be concatenated via || (or) and && (and) operators.
The && operator is of higher preference than ||.
Examples:
1> active_at 'o_1:2:Arom,GLY,CA: || o_2:r_50: && :ALA'
The set consists of atoms with the following properties:
1) C-alpha atoms being in object 1 and molecule 2
in aromatic or glycine residues
or
2) atoms of object 2 in residues with an accessibility of not less than
50 sq. Angstrem and being in alanine residues
2> select_at ^*
empty set of atoms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND fsat
COMMAND nxat
COMMAND n_at
syntax fsat(code);
nxat(code, expression);
n_at(code);
return value
integer number
The code word may have one of the following values : all (all atoms), act
(active atoms), sel (selected atoms). In the case of other code words, the
commands give a warning.
The command *fsat* returns the number of the first atom of the defined set.
In the case of *nxat*, the expression is evaluated, and the resulting integer
is considered of the number of an atom, the function returns the (internal)
number of the next atom. If the set of atoms is exhausted, zero is returned.
The command *n_at* returns the number of atoms in a given set of atoms.
The commands fsat and nxat may be used to cycle through the atoms of
some set, e.g. :
i = fsat(sel);
while (i) {
...
i = nxat(sel, i);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND coat
syntax coat(expression, expression);
return value: double
Returns one component of the coordinates (the type of component is given by
the first expression) of the atom with the number defined by the second
expression, e.g. coat(0,12) is the x-coordinate of atom 12 (internal num-
bering). The components are 0-x, 1-y, 2-z, ...
To get the internal numbering, use the commands listat, select_at, fsat, nxat.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND sfat
syntax sfat(expression);
return value: double
Returns the surface of the atom with the number defined by the
expression, e.g. sfat(12) is the surface of atom 12 (internal
numbering). If previouly the surface was calculated analytically,
this value is returned. Otherwise the numerical value is given,
if it was determined.
To get the internal numbering, use the commands
--> listat, select_at, fsat, nxat.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~