Taken on Feb 4, 1998, The latest versions are available at: ftp://ftp.earth.ox.ac.uk/pub/moldy-2.12g.tar.gz ftp://ftp.earth.ox.ac.uk/pub/moldy-2.12g.com ftp://ftp.earth.ox.ac.uk/pub/moldy-2.12g.zip ftp://ftp.earth.ox.ac.uk/pub/moldy-manual.ps.gz ftp://ftp.earth.ox.ac.uk/pub/moldy-manual.pdf a pointer to the Oxford WWW page http://www.earth.ox.ac.uk/~keith/moldy.html ---------------------- # # ####### # ###### # # ## ## # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # ####### ####### ###### # 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. Thank you Keith Refson -- ------------------------------------------------------------------------------ Email: Keith.Refson@ | Tel: +44 1865 272026 | Dr Keith Refson, | earth.ox.ac.uk | Fax: +44 1865 272072 | Dept of Earth Sciences | | Parks Road, Oxford OX1 3PR, UK| ------------------------------------------------------------------------------