**************************************************************************
**************************************************************************
***** STERIC *****

Hi,
Welcome to steric!

Steric is a program for the calculation of molecular steric parameters. 
Angular calculations include the Tolman cone angle and both numerical and
semi-analytical solid angles, including conformer averages and angular and
radial profiles.  Orthogonal calculations include numerical volumes of
molecules and cavities in crystals, and molecular areas projected onto
planes, as well projected areas of molecular overlap.

**************************************************************************

CONTENTS:

 - OVERVIEW
   - basic summary of the main calculations performed by steric.
 - INSTALLATION
   - Platforms
   - Distribution
   - Installation procedure
   - Other packages required for full functionality
 - RUNNING
   - Running steric
   - Configuring steric
 - AUTHOR INFORMATION
 - DISCLAIMER

**************************************************************************

OVERVIEW

Steric is a program for the calculation of molecular steric parameters
primarily for organometallic chemistry and crystal chemistry.  Two main
types of calculation are performed:

A - Steric effects about a point.  These calculations are seen to be most
useful in organometallic chemistry, where steric effects of ligands about a
metal are of interest, and the chemistry of reactions where steric effects
in groups reacting at points are of interest.

Several 'angular' calculations are performed:
 - Tolman Cone angle.  The algorithm involves itself primarily in
   determining the bonded structure of organometallic molecules, where only
   one ligand is attached to a metal.  The Tolman cone angle is thereafter a
   simple average of the vertex angles of the separate parts of the ligand.
 - total enveloping cone angle is simply the vertex angle of the entire
   ligand.  This will be the same as the Tolman cone angle for ligands with
   identical parts.
 - Solid angle.  This is a far more systematic parameter for describing the
   angular steric size of a ligand than is the cone angle, and refers to the
   angular area around the metal that is occupied by the ligand.  It is not
   dependent on the position of the atom bonded to the metal, or on the
   symmetry of the ligand, and can easily take into account unusual steric
   sizes due to ligands that are not approximately conical in shape. 
   Several approaches to this calculation are available in steric:
   - numerical solid angle.  This is an integration of an angular cone angle
     profile.  It measures the solid angle of the ligand with all internal
     "cavities" and "overhangs" filled in.
   - semi-analytical solid angle including only double overlap.  The ligand
     is viewed as being composed of atoms that only involve themselves in a
     maximum of double overlap.  The total solid angle is calculated as a
     linear combination of single atom and double atom solid angles.
   - semi-analytical solid angle including multiple overlap.  This algorithm
     is an enhancement of the previous one.  All possible orders of atomic
     overlap are taken into account.  The procedures for determining atomic
     angular overlap have been simplified and generalized.  The calculation
     is far more accurate, but also much slower.
 - angle of overlap.  The linear angle by which two atoms overlap can be
   seen as a very rough approximation to their steric congestion.  The solid
   angle of the overlap is, of course, a more reasonable measure of this. 
   The sum of all overlaps in the molecule can give an idea of steric
   angular congestion.  If only non-bonded overlaps are considered, then
   this leads to a measure of molecular congestion.  The two calculations
   available are:
   - linear semi-vertex angle of overlap
   - solid angle of overlap
   The two uses for this are:
   - total congestion
   - non-bonded congestion, or molecular congestion

The radial profiles of all the above parameters can also be calculated to add
another dimension to the steric effect about a point.  This involves the
construction of a sphere about the point of interest.  As the radius of the
sphere is increased from a minimum (normally zero) to a maximum (normally
encompassing all atoms of interest), the data that represent the
intersection of the sphere with the atomic data is used in the steric
calculation.  For example, a solid angle profile of a ligand would give the
solid angle of that slice of the ligand at each radial distance from the
metal, and is a measure of the radial dependence of the ligands angular
steric size.

The conformer energy weighted average steric value of a trajectory of
conformers can also be calculated from biograph and biosym conformer
trajectory files.  Each conformer is read in and has its steric parameter
calculation.  The final average is a weighted average based on the given
conformer energies.  Steric does not calculate these energies itself.

B - Free space effects

Two calculations can currently be performed:
 - Volumes.  Several steric volumes of interest can be calculated using both
   Monet Cargo and Fixed grid approaches (ie. fully numerical):
   - free unit cell volume (volume of the unit cell - Z*molecular volume)
   - molecular volume
   - cavity volume.  The difficulty here is in deciding exactly what a
     cavity is and where it is.  The approach used here applies only to
     cavities which do not deviate too much from spherical in rough shape.
     The volume of a sphere is calculated with those parts due to molecular
     intrusion into the sphere extracted.  There are two ways to determine
     the radius of the sphere to be used:
     - using predefined maximum cavity radius (only useful for comparisons
       of similar cavity types).  Not expected to yield absolute cavity
       sizes, since the volume is dependent on the choice of radius.
     - using radial profile of angular steric parameter to determine cavity
       radius.  If the solid angle calculation is used, this can be seen as
       a way to calculate an absolute steric size for cavities that are near
       spherical in shape (ie. not channels).
 - Projected areas (using a fully analytical algorithm

C - Graphics

Currently steric does not perform any graphics operations itself.  Instead
all graphs plotted are done so by writing the data of interest to a file and
then calling the public domain program 'gnuplot' to plot the data in a
separate window.  Certain extra scripts are available to also make use of
LaTeX for fancier final graph output.

**************************************************************************


INSTALLATION


Platforms
---------

Steric has been written entirely in ANSI C on the Linus UNIX platform, and
includes a few scripts written for the UNIX Bourne Shell ( /bin/sh ).  It
has been compiled successfully on the following platforms:
 - i386 Linux 1.2.8
 - IBM RS6000 AIX 3
 - SGI IRIX 4.0
 - SGI IRIX 5.2
 - MSDOS 6.2 using the 32-bit DJGPP compiler (port of GNU gcc)
Compilation on other unix platforms should involve only modification of
the Makefile.

Although the 'Makefile' as it is worked under IRIX 4.0, the configuration 
of the #ifdef statements did not work under IRIX 5.2, and so a simpler
'Makefile.sgi' has been provided as an alternative.  If this does not work,
the shell script 'makeit' can also be used to make steric without the use
of the make facility at all.

The MSDOS port of steric has not been fully tested, but appears to run
almost exactly like the unix version.  See the file readme.dos for details.

Distribution
------------

The current source can be ftp'd from ftp://hobbes.gh.wits.ac.za/pub/steric/
The latest version at the time of writing was 1.11
The distribution is archived with tar, and compressed with either the GNU
utility 'gzip' (available from most major ftp sites) or the old compression
program 'compress':
  steric_1.11.tar.gz
  steric_1.11.tar.Z

The MSDOS port is available as ster1_11.zip and includes a binary only
distribution.  The source used to compile this distribution is based on
the unix version 1.11, with very few modifications, so any enthusiast can
easy repeat it if they have the djgpp compiler.  Future releases of the
source will come with a makefile for dos/djgpp as well.

Installation Procedure
----------------------

Read readme.dos for MSDOS installation.  All unix installations should
follow the following procedure.

In order to install you need and tar and either gzip or compress.  Tar and
compress should be available under all UNIX systems.  Gzip is available
from GNU, and can be found on most major ftp sites.

To uncompress the package type:

 'gunzip steric_1.11.tar.gz'
or:
 'uncompress steric_1.11.tar.Z'

To dearchive type:

 'tar xvf steric_1.11.tar'

The directory ./steric/ will be made and will include all necessary files.
If you are running under the Linux operating system on i386, i486 or i586
hardware, or compatibles, the non-ELF executable binary "steric" can be run
immediately, otherwise you will need to recompile steric.

Go to the new directory:

 'cd steric'

Edit the Makefile to suite your system.
Note also the variable STERICHOME.  This defines where steric will expect to
find its default files (steric.hlp steric.err, steric.grp steric.ini
steric.par and steric.TeX).  This information is compiled directly into
steric.  If you use the precompiled version, then steric will use the
default value STERICHOME="/usr/local/steric".

To compile to program, type:

 'make'

To install the program, type:

 'make install'

If there are any errors with the Makefile, try:

 make -f Makefile.sgi

As a last resort the script 'makeit' can be used, but will probably require
modifications for your system.

If there are any problems with compiling the code itself that cannot easily
be fixed, please contact the programmer (see below).


Other Packages Required for Full Functionality
----------------------------------------------

In order for steric to plot graphs you will need the public domain program
'gnuplot' installed.  Certain graphics can be enhanced using LaTeX, and some
of the shell scripts provided with steric contain the relevant commands, but
LaTeX is not required for normal operation.
Under MSDOS the lack of multitasking is likely to upset steric's
communication with GNUPlot while running, but plots can still be plotted
afterwards using any available graphics package.

**************************************************************************


RUNNING


Running Steric
--------------

Steric is run simply by typing the program name followed by an optional list
of filenames.  The filenames can refer to data files containing atomic data,
or steric command files containing normal steric commands, or steric atomic
radius parameter files.  File types are autodetected according to content. 
The steric command files and the steric parameter files are identified by
having the lines "#steric" and "#sterpar" as their first lines repectively. 
The files 'steric.ini' and 'steric.par' are command and parameter files that
are read by steric automatically on startup.

The program expects to find the following files in the current directory, or
the directory described by the compilation variable STERICHOME:
 steric.par    - list of atomic radii
 steric.hlp    - help on using the program
 steric.grp    - group definitions
 steric.err    - error messages
 steric.ini    - optional, modifiable initialization commands

Steric does plot it's radial profiles, and other data to files, but doesn't
have it's own graphics algorithms, and instead calls the public domain
program 'gnuplot' to plot the graphs.  If you would rather use another
graphics package, modify the source in stergrap.c.

As a test try the example input file test.bgf
This file does not have an origin defining atom (type DUO) so one needs to be
defined (obviously the metal atom).  Look inside the command file test.inp
for example commands.  The command file can be run as "steric test.inp".
Steric can read a wide range of Cartesian and fractional coordinate data
files.

Use the help facility!  It contains a lot of information.

For example: "help file load" will list all the different file types that
steric can interpret.  "help" on its own will give the first level of
commands.


Configuring Steric
------------------

Although not much has been done to facilitate the configuration of steric in
an automatic way, it is very configurable during running.  See "help change"
and "help change settings" for the major options.  The automatically
run command file 'steric.ini' can also contain commands to make these
changes, but be careful, because the number of options required by "change
settings" is dependent on the version of steric being run. This means that
the steric.ini file will most probably not be portable to different versions
if it contains that command.

If STERICHOME was set in the Makefile, but any of the default files
(steric.par, seteric.hlp, steric.err, steric.ini, steric.grp) exist in the
current directory as well, they will be read instead of the ones in
STERICHOME.
For example, you may wish to install steric in /usr/local/steric, and
therefore set STERICHOME=/usr/local/steric, but also want to customize
'steric.ini' for a particular use.  Simply copy 'steric.ini' to the working
directory and edit it there.  Only 'steric.hlp' and 'steric.err' are not
expected to be used this way, but you can if you really want to.

**************************************************************************

AUTHOR INFORMATION

If you have any other questions, please contact the programmer:

Brian Craig Taverner

tel:   +27-11-716-2290
fax:   +27-11-716-3826
email: craig@hobbes.gh.wits.ac.za
www:   http://www.gh.wits.ac.za/craig

Structural Chemistry
University of the Witwatersrand
Private Bag 3
WITS 2050
South Africa

12/8/'95

**************************************************************************

DISCLAIMER

Steric Copyright 1994,1995 Craig Taverner, et al.  All rights reserved.

Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose is hereby granted without fee, provided 
that any distributed or published results include a reference to the above
author/programmer and to any previously published papers regarding relevant
calculations, and also that any distribution of the program or its source
includes both the copyright notice, this permission notice, and the
following disclaimer.

BRIAN CRAIG TAVERNER, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM 
ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL BRIAN
CRAIG TAVERNER, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY 
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER 
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF 
CONTRACT, NEGLIGENCE OR OTHER TORTUOUS ACTION, ARISING OUT OF OR IN 
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

*************************************************************************

Date: 29th December 1995

*************************************************************************
*************************************************************************
*************************************************************************