tranal_base.f:

Information for developers of analysing modules 


1. General.
----------

TRANAL package consists of a number of utilities for analysing atom 
trajectories generated by molecular dynamics programs. Each analyzing 
utility is linked to the main tranal module "tranal_base.f", consisting
of a number of subroutines which are used to retrieve configurations 
from the trajectory. The module is constructed to work mainly with 
MDynaMix molecular dynamics programm, but is able to accept trajectories 
written in some other formats: trajectories written in XMOL format, 
PDB trajectories from GROMACS and NAMD binary trajectories.

It is supposed that in all cases, the atoms and molecules are arranged
in the following way: (the same as in MDynaMix program):

  <molecules of type 1><molecules of type 2>...

in each molecule type:

  <molecule 1><molecules 2>...

in each molecule:

  <atom1> <atom2>...

(the same order must be in all molecules of this type)

Addionally, a term ``site'' is often used. If one chooses one molecule
of each type and set them one after another (in the same order as in the
trajectory), then number of each atom in this sequence would correspond
to the ``site'' number. 

Exchange of data between all subroutines in the tranal_base.f and the 
analyzing utility is organized through COMMON blocks defined in
"tranal.h" file. The meaning of different parameters and arrays of 
"tranal.h" file is described later in the text..

2. Subroutines
--------------

The tranal_base.f module consists of the following subroutines:

     SETTRAJ  - prepare list of trajectories and data structures
     READCONF - reads next configuration
     READMOL  - read information about molecules from .mmol files
     GETCOM   - compute molecular centres of mass
     PBC      - apply periodic boundary conditions

A typical organization of an analyzing utility working with 
tranal_base.f module is the following (see dryrun.f as an example)

<various definitions>

   call SETTRAJ
   <input of parameters>
an infinite loop:
			|    call READCONF(IEND)
                        |    < analysis of configuration>
end of the loop
    < final analysis and output>


SETTRAJ subroutine: 
reads from the input information about trajectories (using
NAMELIST-type of input under $TRAJ name, see the user guide),
reads information about molecules from .mmol files, and  prepares 
data structures for subsequent analysis.

READCONF(IEND) subroutine:
Read one configuration from the trajectory. After next call, read 
the next configuration. When one trajectory file ends, it 
automatically opens the next trajectory file and reads configuration 
from it. It automatically skips configurations coresponding to the 
same time stamp. When it meets the end of the last file, it returns 
value IEND=1, otherwise it returns IEND=0. After each call, it updates
arrays for the atom coordinates and other parameters with the values 
corresponding to the last read configuration.
If ISTEP parameter of the input file is not 1, the subroutine returns only 
each ISTEP-th configuration from the trajectory

READMOL subroutine:
Is used internally in SETTRAJ in order to read information about 
the molecules from .mmol files.

These two subroutines can be optionally called from an analyzing 
utility to perform some common tasks:

GETCOM subroutine:
Is used to compute molecular center-of-masses.

PBC(DX,DY,DZ) subroutine:
Apply periodic boundary conditions to vector (DX,DY,DZ).
It returns (DX,DY,DZ) vector inside rectangular defined by
the current box lengths:  -HBOXH<DX<HBOXL etc where HBOXL is
the half of the box length in X-direction. Note that PBC subroutine works
correctly only if original DX,DY,DZ values are within 3*HBOHL/2 
distance from the origin.


3. Common variables and arrays (file tranal.h):
---------------------------------------------- 
  
By default, all arrays and variables beginning with letters
from I to N are of type integer*4, while all other are of
type real*8.

These variables and arrays are defined after "call SETTRAJ":

NTYPES	- number of types of molecules
NSPEC(I)- number of molecules of type I  (I=1,...,NTYPES) 
NOP	- total number of molecules (sum of NSPEC(I))
NSITS(I)- number of atoms on a molecule of type I (I=1,...,NTYPES)
NSITES  - total number of sites (sum of NSITS(I))
NSTOT	- total number of atoms (sum of NSPEC(I)*NSPEC(I))

MASS(IS)  - mass of site IS  (IS=1,...,NSITES). Type real*8.
CHARGE(IS)- charge of site IS  (IS=1,...,NSITES)
SUMMAS(I) - mass of molecule of type I (I=1,...,NTYPES)

ISADR(I)  - address (shift) of molecular type I in the list of sites
ISADDR(I) - address (shift) of molecular type I in the list of atoms
IADDR(IM) - address (shift) of molecule IM (IM = 1,...,NOP) in the
            list of atoms 

ITYPE(IAT) - molecular type of atom IAT
NSITE(IAT) - site number for atom IAT
NNUM(IAT)  - number of molecule to which atom IAT belongs
ITS(IS)    - molecular type corresponding to site IS
ITM(IM)    - molecular type of moolecule with number IM

These variables and arrays are updated after reading of each new 
configuration:

SX(IAT),SY(IAT),SZ(IAT) - X,Y,Z coordinates for each atom IAT=1,...,NSTOT

OX(IAT),OY(IAT),OZ(IAT) - X,Y,Z coordinates for each atom IAT=1,...,NSTOT
             from the previous configuration

VX(IAT),VY(IAT),VZ(IAT) - X,Y,Z velocities of atoms. If they are 
             not present in the trajectory, they are calculated as the 
             displacement of the atom from the previous configuration 
             divided by the time difference with the previous configuration.
	     The units are Å/fs. 

FULTIM     - time stamp of the current configuration (in ps)
FULTIM1    - time stanp of the previous configuration

BOXL, BOYL, BOZL - box sizes in X,Y,Z directions 
             (if defined in the trajectory)
HBOXL,HBOYL,HBOZL - corresponding half-box sizes
VOL		  - volume

TEMP,PRES,EP - current temperature, pressure and potential energy 
               (MDynaMix trajectories only)



The following arrays acquire values (from the current values of the atom 
coordinates and velocities) after calling GETCOM subroutine:

X(IM),Y(IM),Z(IM) - X,Y,Z coordinates of the center-of-mass of molecule IM
PX(IM),PY(IM),PZ(IM) - X,Y,Z components of the total momentum of molecule IM
WX(IAT),WY(IAT),WZ(IAT) - local X,Y,Z coordinates of atom IAT relative to
			the center-of-mass of the corresponding molecule
QX(IM),QY(IM),QZ(IM) - X,Y,Z components of the angular momentum of molecule IM
Additionally, arrays SX,SY,SZ are updated so that molecular centres of mass 
	      are moved to the principal periodic cell (in MDynaMix 
              trajectory, they are there anyway)


