readme

分子动力学模拟程序

==================================================================
*         The molecular dynamics (MD) program                    *
*               v.4.4 from 18 Nov. 2005                          * 
*                                                                *
*                  A short user guide                            *
*                                                                *
*     by Alexander Lyubartsev, Stockholm University              *
*     e-mail,  [e-mail]                                 *    
==================================================================


1. Preliminary work - writing the force field files.
----------------------------------------------------

   For each molecule type you should have a file describing molecular structure
and parameters of the force field. The file must have extension *.mol  
Examples of .mol files are given in moldb directory.
 
.mol files consist of several parts which are described below.
Lines, beginning with "#" are commentaries and they are ignored by the program.
Other lines contain parameters in free format.

A. Molecular geometry and Lennard-Jones parameters

First line is the number of atoms in the molecule (NSITS).
Then NSITS lines follow, one line per atom. Each line contains 8
parameters. They are: 1) atom name in the program; 2),3) and 4) are
initial X,Y,Z coordinates of the atom in the molecular coord. system,
5) mass in atom units, 6) charge 7) Lennard-Jones parameter sigma
(effective atom diameter) in A, 8) Lennard-Jones parameter epsilon
in kJ/M                                           

B. Reference 

Next line contains number of lines for reference to the force field for
the molecule, followed by lines with the reference itself.

C. Bonds

The first line is number of bonds. Next lines contain parameters for each bond.
They are: 1) type of bond potential. Available values 0 (harmonic bond) and 1
(Morse potential). 2) and 3) parameters are atom numbers which are
linked by the bond. 4) is equilibrium bond length in A 5) Force parameter
in kJ/mol/A**2  (U=F*(R-R0)**2)  6) D parameter of Morse potential
7) RHO parameter of the Morse potential in A**-1    
(Um=D*(1-exp(-Pho(R-R0)))**2)

D. Angles

First line - number of angles.

Next lines - parameters of angles:
1),2) and 3) define atom numbers 
4) is equilibrium angle in degrees
5) is the force constant in kJ/mol/rad**2

E. Dihedral angles. AMBER type of potential, K*(1+cos(M*fi-delta))

Torsional angle fi is 180 for trans-conformation
First line - number of torsions.
Next line - parameters:
1)-4) define atoms 5) is delta in degrees, 6) force constant in kJ/mol
7) is multiple factor M
Multiple torsions are supported.

F. Other parts are optional. 

They begin from the line defining type of extra potential.
Supported types are:

tors1  
tors5 
impropers
hydrogen bonds
special 

tors1 is MM3 potential for dihedral angle 
K1/2*(1+cos(fi))+K2/2*(1-cos(2*fi))+K3/2*(1+cos(3*fi))
parameters 1)-4) define atoms and 5)-7) constants K1,K2,K3 in kJ/M

tors5 is torsion potential of Ryckaert-Bellemans type (for hydrocarbon chains)
Sum_i=1,5 (K_i*cos(fi-180)**i)
fields 5)-9) are parameters for K1,..,K5.

improper:  improper dihedral potential    K*(fi-fi0)**2
field 5) is equilibrium angle in degrees and 6) is the force constant

hydrogen bonds
first line - number of different hydrogen bonds
other lines: 1-st field is atom name (as specified in A part of this file), 
second - number of hydrogen bond type specified in file pathdb/hydro.bonds
The present version of hydro.bond file contains parameters for
hydrogen bonds from the AMBER force field

special 
list, overreading LJ parameters for 1-4 interactions for specified atom 
first line - number of pairs;
other lines: 1-st field defines atom, 2) is new sigma (A) and
3) is epsilon (kJ/M)
(Scaling parameter for 1-4 LJ interactions, specified in the input file,
applies to these interactions also)

Note. For big molecules, the procedure of writing .mol files may be
somewhat automatized by the utility makemol (see moldb/Makemol.doc).
This utility automatically generate lists of angles and torsions from the
bond list and substitute parameters from the force field database.



2. Compile the program
----------------------

Before compiling, you may need to change sizes of working arrays defined
in file dimpar.h. There are several versions of this file creating
executables of different size. The values of parameters depends both
of molecular system you want to simulate and on the computer in hands.

The are several Makefiles for different architectures. Choose the most
suitable and edit it if necessary. Then run "make" which invoke one of 
these Makefiles.

a) sequential execution. These files produce executable "md"

"make default" calls

   Makefile.unknown    - should work for any standard f77 compiler,
                         with exception of accounting cpu time (put your
                         own counter of cpu time in file cpu_dummy.f)

"make risc" calls

   Makefile.risc       - IBM RISC 6000 
                         option "-qarch=pwr2" may be omitted if processor 
                         does not support it

"make linux"

   Makefile.linux      - Linux with g77 fortran (works also
                         with f77/f2c, in this case change line FC = g77
                         to FC = f77, where f77 is shell script calling f2c 
			 in linux < 1.3.99 )
"make pgi"

   Makefile.pgi        - Linux with Portland Group Fortran
   

b) Parallel execution. Note that these makefiles are strongly dependent on how
the MPI library was installed. The name of executable is "mdp"

"make sp2"

   Makefile.sp2        - IBM SP2 with MPI library
                         
"make lin_mpi"

   Makefile.lin_mpi    - Linux with MPI library 
			 Call mpif77 script which must call correct fortran
                         compiler and mpi libraries (not always the case)

"make t3e"             - Cray T3E with MPI

"make intel"           - call Intel Fortran compiler "ifort"


Other makefiles:

  Makefile.DEC       - DEC alpha
  
  Makefile.pgi_mpi   - Portland Group Fortran + MPI library
                       (parallel execution)
		       
  Makefile.ifc       -  old Intel compiler (v.7.0 and older)
		       

3. Prepare the input file
-------------------------
MD.input is a sample input file with extensive commentaries.
Another example is md.in with only short commentaries.
The file is read by the program from the standard input.

Optionally (depending on a parameter in the input file) the program need 
*.inp file containing atom or molecular center-of-mass coordinates.

In the case of parallel execution on linux or Cray computers, the input 
is always taken from file "md.input"


4. Run the program, e.g.:
-------------------------

md < md.in > md.out
                      
in the case of parallel execution on linux - computers or on Cray:

mpirun -np 4 mdp > md.out

where 4 here is the number of available nodes

5. Files
--------

(r) means required, (o) optional
(I)       input     (O) output
<f_name> is the same for all the files in a simulation

   standard input (rI) - file with simulation parameters (example: MD.INPUT)
   standard output (rO) - file with simulation results and final averages
   *.mol (rI) - set of files defining the force field for each molecule type
   <f_name>.inp  (oI) - contains initial atomic or molecular COM coordinates
   <f_name>.dmp  (oIO, binary) - restart file, containing state of the system 
and calculated averages 
   <f_name>.rdf  (oIO,binary) - restart file for radial distribution functions
   <f_name>.tcf  (oIO,binary) - restart file for time corelation functions
   <f_name>.car  (oO) - system configuration in XMOL (xyz) format 
   <f_name>.001,  <f_name>.002, ... (oO, binary or ASCII) - trajectories files



.inp file:  is written in "XMOL" format. Alternatively, only XYZ coordinates
    in 3 columns may be given



6. Tuning
---------

Parameters defining arrays boundaries are defined in dimpar.h file.
They are also define the required memory.  They can be decreased to 
save memory. 

One of the most memory-consuming arrays is list of the atom pairs
within cutoff distance. Its size is defined by parameters NTOT (maximum 
number of atoms) and NBLMX - maximum number of neighbours (within cutoff) 
for each atom. Since list of neigbours is distributed among the available 
nodes, this parameter can be decreased in the case of parallel execution. 

Another "memory consuming" parameters is MAXCF -  set it to 1
if you do not want calculate time correlation functions. 
Much memory may take array with intermediate averages for different
parameters.  Its size is NRQS*LHIST, where NRQS is maximum number 
of calculated different averages and LHIST - max number of time intervals
during which these averages are calculated. It may be really big for large 
macromolecules, because all bond lengths, covalent and torsion angles are
calculated and remembered. Accumulation of these data may be switched off
by specifying parameter no_aver (see files MD.input and Extra_param)

Program check correspondence of array boundaries to the input data and
stop if something is wrong. After correction of dimpar.h file you must
recompile the whole code. 
                    

7. Program structure
--------------------

The program consists of several fortran files, each contains one
or several Fortran units. The files are:


Main.f (Part 1) - the main module
------ 
	This is the main program unit taking care of all what follows. 
	It reads input data, sets up data structure and initial state	
	and then starts MD algorithm.
	It consist of one Fortran unit: program MD

dimpar.h - file defining maximum sizes of working arrays
--------   You must recompile the whole code after changing this file.

prcm.h  - include file
------
	This is the include file containing static dimensioning
	of the working fields and definition of all global parameters.
	Practically all modules depend somehow on it, 
	so you must recompile the sources each time you change this file.

input.f (Part 2) - provides input of data
-------

setup.f (Part 3) - Setup units and data structures 
-------

mdstep.f (Part 4) - integration of the MD trajectory
--------

forces.f (Part 5) - calculation of forces 
--------
	This file contains subroutines responsible for calculations 
	of different forces. Forces are divided into two groups:
	slow and fast forces. This division is essential only if
	double time step algorithm is used. Procedure for updating 
	the lists of neighbours is also in this file 

mpi.f (Part 6a) - collection of MPI calls for parallel execution
-----

mpi_cray.f (Part 6b) - Cray version of MPI calls for parallel execution
-----

scalar.f (Part 6c) - collection of dummy MPI calls for a 
--------             single-processor execution

restart.f (Part 7) - dump/read restart file and some other output
---------
        This file contains subroutines responsible for writing and
        reading restart file, dumping trajectories and other operations
        with input/output files

aver.f (Part 8)  - collecting averages, including RDFs
------

tcf.f (Part 9) - calculation of time correlation functions
-----

service.f (Part 10) - collection of some procedures specific for molecular
---------             dynamics
	
util.f (Part 11) - collection of some other auxiliary procedures
------

cpu_*.f  - different variants to count cpu -time
getcpu.c, getcpucr.c - C-functions to count CPU-time

unused.f - some unused procedures found in previous versions.

Makefile.* -  makefiles for different architectures