CCL Home Page
Up Directory CCL moldy.README
Taken from: http://www.earth.ox.ac.uk/~keith/moldy.html on Feb 2, 1997


----------------------         
		#     # ####### #       ######  #     #
		##   ## #     # #       #     #  #   # 
		# # # # #     # #       #     #   # #  
		#  #  # #     # #       #     #    #   
		#     # #     # #       #     #    #   
		#     # #     # #       #     #    #   
		#     # ####### ####### ######     #   

                Copyright Keith Refson January 1990
		All rights reserved


Moldy is a general-purpose molecular dynamics simulation program which
I wrote initially for my own research into aqueous solutions at
mineral surfaces.  However it is sufficiently flexible that it ought
to be useful for a wide range of simulation calculations of atomic,
ionic and molecular systems.

Moldy is available by anonymous file transfer from Oxford.  Connect to
"earth.ox.ac.uk" using "ftp", with an account name of "anonymous" and
your email address as password.  The relevant files are all in the
"/pub" directory and are

* moldy-2.yy.tar.gz   - The Unix distribution (also for MSDOS/Windoze)
* moldy-2.yy.com      - The VMS distribution
* moldy-manual.ps.Z   - The Manual in PostScript form.  Note that
                        the distribution files already contain 
                        the LaTeX source.

Please note that moldy is copyrighted and distributed under the GNU
public license which is designed to encourage its distribution and
modification.  This is to ensure that the source code of moldy and any
improvements made to it by anybody remains available to anyone who
wishes to use it.  If you change or improve Moldy, please tell me 
and if practical and appropriate I will incorporate your modifications
into a future release.  I hope that as time goes on Moldy will become
yet more comprehensive as a result of your input.

I am also keeping a list of email addresses of anyone who uses the
program for notification of updates, bugs and so forth.  Please notify
me if you would like to be added to this list, preferably by email to
Keith.Refson@earth.ox.ac.uk.


Contents of the distribution:

accel.c
algorith.c
alloc.c
ansi.c
auxil.c
beeman.c		These files are the source code for Moldy.
convert.c
dump.c
ewald.c
force.c
input.c
eigens.c
kernel.c
main.c
matrix.c
output.c
quaterns.c
rdf.c
restart.c
startup.c
values.c
xdr.c
parallel.c
   
defs.h
messages.h		'Include' files for above files
structs.h
xdr.h

stddef.h
time.h			replacement ANSI C include files for non-ANSI systems.
stdlib.h
string.h


dumpanal.c
dumpconv.c
dumpext.c		Source code for 'utility' programs.
mdshak.c
mextract.c

getopt.c		Support routine for utility progs.

Makefile		Make file for Moldy.

compile.com		Master compile file for VMS.  Calls all the others.
compile_moldy.com	Compile file for "moldy" itself.
compile_utils.com	Link file for "moldy" itself.       
link_moldy.com		Compile file for utilities.
link_utils.com		Link file for utilities.
defcomm.com		Defines comands - execute from your LOGIN.COM

moldy.tex		LaTeX source for manual
moldy.bbl
fig_*.ps		Encapsulated Postscript versions of figures.
fig_*.tex		LaTeX annotation for figures.
fig_*-eepic.tex		Alternative version of figures in eepic form.


tips2.in
tip4p.in
methane.in
mcy.in
mgclh2o.in		Example system specification files
control.clay
argon.in
quartz-vbst.in

control.mgclh2o
control.tip4p		Example control files
control.water
control.clay
control.argon
control.tips2
control.quartz
control.mgclh2o

water-example.out
argon-example.out	Output from example runs in manual
tips2-example.out
tip4p-example.out
mgclh2o-example.out
quartz-example.out
clay-example.out 

UNPACKING
---------
A. Unix distribution

This distribution of Moldy takes the form of a compressed tar archive.
The archive is unpacked with 
% gunzip moldy.tar (.gz)    or    % uncompress moldy.tar (.Z)
% tar xvf moldy.tar

B. VMS 

The VMS version of Moldy comes as a DCL archive, moldy.com. To unpack:
$ @moldy
This creates all the files needed in the current directory.

Alternatively, versions of "uncompress" and "tar" are available for
VMS, though they are not standard.  If you have them then you can
unpack the "moldy.tar.Z" archive (suitably renamed) in the same way.

COMPILING
---------

Here are some brief notes.  There are more detailed instructions in the 
manual.

A. UNIX

Stage 1.
You ought to be able to type "make moldy utilities" on just about any
flavour of unix and build a working version.  However if you want to
get the best performance you will have to work a bit harder with
compiler options.  You may also find that the compile fails for
obscure reasons.  Don't worry, some compile options will probably sort
that out too.

Stage 2.  
Edit "Makefile", choose a suitable set of compiler options for your
machine and uncomment them. Moldy has been test compiled on most
modern workstations as well as vector super and minisuper-computers,
so you only have to select the preset options.

Stage 3.  
This section describes how to "hand-tune" compiler options.
If you get this far you have probably got a different machine or
compiler system from any of the tested ones.  Moldy recognises a
number of C preprocessor macros which adjust its expectations of the
compiler and operating system.  These are best defined using the
"-DMACRO-NAME" option of most unix C compilers.

MACRO		Purpose
-----           -------
	The following two macros are used to select the ANSI C
	"stdarg" mechanism. Default is older "varargs" mechanism. 

__STDC__	Automatically defined by ANSI compilers in strict mode.
ANSI		Alternative for ANSI compiler in non-strict mode which
		does not define __STDC__.

ANSI_LIBS	Set this if your libraries and header files conform
		to those expected in the ANSI 89 Standard.  Otherwise
		extra replacement routines and header files to
		remedy the deficiencies of older systems are included.

		Set this if at all possible.  Only in an ANSI
		environment can you be sure that all needed headers and
		library routines will be present.  The alternative is
		a kludge which works most of the time on most machines.

		This is automatically set in "defs.h" for some
		machines/compilers vhich are known to have ANSI libraries.

USE_XDR		Turn on support for the portable binary dump and
		restart files using the XDR mechanism.  This is the
		only area where Moldy departs substantially from the
		ANSI C standard so it is optional.  Nevertheless it
		is so massively useful that it is on by default.

		As this is not part of the standard it may not compile
		correctly on some systems if the compiler is in
		"strict ANSI" mode.  Use the default  or the "relaxed"
		or "extended" ansi mode often provided. 

		You may well need to add a library to the link using
		the LDFLAGS variable in the Makefile.  For
		example, solaris 2 on Suns needs the "-lnsl"
		option and SGI's need the "-lsun" option.

		You may also need to define some other macro to get
		the headers correctly included viz:

_ALL_SOURCE 	(IBM RS6000)
_HPUX_SOURCE	(HPUX)
		These are needed to enable stuff needed for the XDR
		routines and headers on IBM and HP machines.  
		N.B. These are actually set automatically in the Moldy
		header "defs.h" However other systems may require something
		similar .

SPMD		Compile for SPMD (Single Program Multiple Data) parallel
		execution.  You must also specify one of the macros
		BSP, MPI or TCGMSG to select a message-passing library
		and have the appropriate include paths and libraries
		defined in the Makefile.

BSP/MPI/TCGMSG/SHMEM   (parallel.c only)
		These select the parallel interface library.  Portable
		implementations of the first three are available for
		most parallel architectures, and MPI should be available
		on most true parallel machines.  

MPPMANY		(Ewald.c only) Selects parallelization of some of the
		trig initialization code for the reciprocal-space sum.
		This is a loser on all but the highest-bandwidth
		parallel machines.  It increases run time on the IBM SP2.
		However it DOES give a speedup on the T3D when used in
		conjunction with the SHMEM or BSP library interface.

B. VMS (VAX/VMS and OpenVMS/AXP)

Just execute the "compile.com" DCL command file which will build Moldy
and the utilities.  All the required macros are set in "defs.h".  It
also executes the command file "defcomm.com" which defines the command
symbols to execute the programs.  It is a good idea to execute this
file from your LOGIN.COM to make them available every time you log in.

N.B. Depending on how your VMS system is set up you may need to take
additional steps to link moldy with the C runtime library.  Consult
your local documentation or systems staff.  If the C library isn't linked
by default the command

   $ assign sys$library:vaxcrtl lnk$library
   
before the executing the compile command file

   $ @compile

may well do the trick.


	RUNNING
	-------

Try it out by typing

	moldy control.water

to do a 10 timestep simulation of water.

PRINTING THE MANUAL
-------------------

The LaTeX source, "moldy.tex" and bibliography file, "moldy.bbl"
are supplied. If you have LaTeX, "latex moldy" a couple of times
to get the cross-references correct and print the dvi file using
dvips or dvi2ps, or whatever dvi output you normally use.

There is a "moldy.dvi" target in the make file so just "make
moldy.dvi" ought to do the trick.

PARALLEL VERSION
----------------

A.  Distributed Memory
    ------------------

    To build this version you must have one of the three supported
    message-passing libraries installed on the target system.  These
    are the Oxford BSP library, MPI (the new standardised
    message-passing library interface) and TCGMSG (the Theoretical
    Chamistry message-passing system).  Then define the macro PARLIBC
    in the Makefile to contain the "include" path for the library
    header files, and the preprocessor symbols SPMD and one of MPI,
    BSP and TCGMSG.  The macro PARLIBL should be defined to link with
    the appropriate libraries.

    For the Cray T3D, there is also an interface to the SHMEM libraries
    which provides the very fastest interprocessor communication.  This
    may be used in conjunction with the MPPMANY option in Ewald.c.

    To find out how to set up a parallel run, consult the documentation
    for your parallel system, as this varies.  

    The parallel performance increses with system size as the amount
    of work in the force and ewald sum loops increases as a proportion
    of the total work and with respect to the communication overhead.
    A speedup of nearly 7 on an 8-processor IBM SP1 has been
    demonstrated for the run "control.big", and in general the larger
    the system the better the parallel performance.  

    The parallel interface is contained within a single file
    "parallel.c" and versions for other MP libraries should be
    relatively easy to add with a few hours of programming effort.

    Alternative Ewald:
    ------------------

    There is an alternative version of Ewald.c which uses W. Smith's
    RIL paralellization strategy in ewald-RIL.c.  This uses far less
    memory but at the cost of doing parallel communication in the
    inner loops.  This works reasonably on parallel machines
    with very short latencies such as the Cray T3D, but on lesser
    beasts it serializes the whole code!

B.  Shared memory.
    -------------
    The sources contain separate versions of ewald.c and force.c with
    the appropriate code and compiler directives for compilation on
    certain shared-memory parallel machines including Stardent Titan,
    Convex and Cray architectures.  To use, you must REPLACE ewald.c
    and force.c with the file ewald_parallel.c and force_parallel.c
    respecively.  You must also define the preprocessor symbol
    PARALLEL during the compilation (eg with the compiler option
    -DPARALLEL).

    The code reads the environment to decide how many processors
    to execute on.  The name of the env variable is usually the
    same one as the manufacturers use for the same purpose
    NCPUS for the CRAY and THREADS on everything else.  Use
    the SETENV command (for c-chell) or the bourne-shell equivalent
    to before starting a run.

    Note. The Stardent Titan version does not work as shipped because
    the system supplied version of "malloc" can not be safely called
    from a parallel program.  Contact the author for a "thread-safe"
    version which can.
Modified: Sun Feb 2 17:00:00 1997 GMT
Page accessed 5130 times since Sat Apr 17 21:59:05 1999 GMT