Setting up DL_POLY_4

full slides of the lectures can be downloaded from


These exercises involve the use of the CCP5 simulation code DL_POLY_4, which has a broad range of applications, that you now have the opportunity to try out for yourself! You will be using DL_POLY_4, you may also use the public domain version, which is called DL_POLY Classic [1] but these notes are not targeting it. This program is available free of charge for academics and researchers from STFC Daresbury Laboratory [2] and is supplied as source code. Those of you who need to develop advanced algorithms, or explore complex systems, but can’t afford the time to develop the molecular dynamics code yourself, may find it a useful starting point.

DL_POLY_4 comes with its own graphical user interface (GUI) written in Java [3]. It is fair to say this is a rather basic GUI, but it does help a great deal when working with DL_POLY_4, as we hope these exercises will show. This session may begin with a short demonstration of how the GUI works if there is time, but if not we have also provided the GUI online manual [4] for you to learn more about using it. Please glance through this to get a feel for how the GUI works, it will pay off in the end!

This guide is for impatients. More information can be found in file that comes with DL_POLY_4. Main support channel is the mailing list, be sure you check the archive before you start. A pdf version of these exercises and all inputs can be downloaded from [5]


To build the code you will need a PC running either a flavour of Linux, Apple MacOSX or MS Windows. If you are running Linux you will probably have all you need, but do make sure you have the cmake, Fortran compiler (e.g. gfortran), MPI library(OpenMPI or MPICH) and, optionally, an up-to-date Java SDK(version 1.7+) installed. Building Windows native binaries is also possible, ask for them. On Windows 10 it is possible to use Windows Linux Subsystem and one can follow the instructions from Linux.


On Windows 10 it is possible to use Windows Linux Subsystem and one can follow the instructions from Linux. For older Windows versions, just use the native windows binary provided in the registration email


Install brew [6] and then install the dependencies. Now you can follow the linux instructions.

[Linux] Compiling and Installing DL_POLY_4

The source code is obtained by registering on the web page of DL_POLY_4 and following the instructions contained in the email you subsequently receive. You now need to unpack the software and compile the executable program. Unpack it as follows and define a helper variable to the newly created directory:

cd $HOME
export DL_POLY=$HOME/dl_poly_4.09

You will observe that the main DL_POLY_4 directory contains several sub-directories:

:~> ls
  1. The bench directory, which contains instructions on how to obtain input files for benchmarking DL_POLY_4

  2. The build directory, which contains the makefiles to build the executable code;

  3. The cmake directory, which contains the cmake build system;

  4. The data directory, which contains information on how to obtain input files for different test cases;

  5. The java directory, which contains the java GUI;

  6. The manual directory, which contains a PDF copy of the user manual;

  7. The public directory, which contains instructions how to obtain helper code contributed by different users;

  8. The source directory, which contains all the source files needed to build DL_POLY_4

  9. The utility directory, which contains a set of source files for programs that can help you to create inputs for or analyze output of DL_POLY_4;

  10. The utils directory, which contains a set of scripts useful for automatic testing.

To compile the software proceed as follows, we assume that gnu compilers [7] and a MPI implementation are available (eg. OpenMPI or MPICH) and properly set up:

Recommended versions of compilers;

  1. gnu forrtran version 6 or above, older versions may or may not work

  2. openmpi version 2 or above for versions beyong 2 there is an workaround, see below.

mkdir build-mpi
cd build-mpi
FFLAGS="-O3" cmake ../
make -j4
cp bin/DLPOLY.Z ../execute/

If the process is successful the code will be build. An executable called DLPOLY.Z will be created and placed in the execute directory. A full film of the process can be seen on youtube [8]

old MPI Library

if you get an error like


 Character( Len = MPI_MAX_LIBRARY_VERSION_STRING ), Public :: lib_version = "*"
 Error: Symbol 'mpi_max_library_version_string' at (1) has no IMPLICIT type

 Character( Len = MPI_MAX_LIBRARY_VERSION_STRING ), Public :: lib_version = "*"
 Error: 'lib_version' at (1) must have constant character length in this context
 make[2]: *** [source/CMakeFiles/dlpolycore.dir/comms_module.F90.o] Error 1
 make[2]: *** Waiting for unfinished jobs....
 [  1%] Building Fortran object source/CMakeFiles/dlpolycore.dir/four_body_module.f90.o
 make[1]: *** [source/CMakeFiles/dlpolycore.dir/all] Error 2
 make: *** [all] Error 2

your MPI is too old… you shall try to update as soon as possible. There is an workaround to build the code

mkdir build-mpi
cd build-mpi
FFLAGS="-O3 -DOLDMPI" cmake ../
make -j4
cp bin/DLPOLY.Z ../execute/

Java GUI

The DL_POLY_4 exercises listed in tutorials will be run through the medium of the Java GUI. For this reason it is important to perform the exercises within the DL_POLY_4 directory structure, otherwise the GUI will not operate correctly. Given you have the correct java version build the GUI shall be easy:

cd $DL_POLY/java

To run the DL_POLY GUI you invoke it from within the $DL_POLY/execute directory as follows, a full video of the process on youtube [9]:

cd $DL_POLY/execute
java -jar ../java/GUI.jar &

or simply

cd $DL_POLY/execute
chmod 755 ./gui

The first of these commands puts you in the execute directory, which then becomes the working directory. The second command invokes the java GUI. You may wish to use the linux script command for convenience. In a short while the GUI main window will appear. The online manual explains what the buttons and menus do.

Using the GUI Data Archiver

The GUI Data Archiver allows you to do three things:

  1. Select one of the workshop exercises from the $DL_POLY/data directory and load the required DL_POLY input files into the $DL_POLY/execute directory prior to running the DLPOLY.Z program.

  2. Save the DL_POLY input and output files currently in the $DL_POLY/execute directory into a new sub-directory of the $DL_POLY/data directory. The name of the new directory is chosen by the user.

  3. Fetch the DL_POLY input and output files currently in a user-nominated $DL_POLY/data sub-directory into the $DL_POLY/execute directory.

Note the default directory name for the Save and Fetch options is DEFAULT.

The Fetch and Select options trigger a warning that files already in the $DL_POLY/execute directory may be overwritten. You have the option then to cancel the operation.

The Fetch option may flag up that some files are missing. This is not necessarily harmful. It merely shows the the GUI is aware that some possible files are absent.

Running DL_POLY using the GUI

The Run DL_POLY Panel allows you to set up and execute a DL_POLY simulation. You will find it under the GUI’s Execute menu.

  1. The Run button starts the DLPOLY.Z program running.

  2. There is a text box displaying the text: ./DLPOLY.Z. This is the unix command the GUI runs when the Runbutton is clicked. You may change this command if you have named the DL_POLY program differently.

  3. The Kill button will kill the executing program.

  4. The Status button will tell you if the program is still running.

  5. Always use the Kill button after the run finishes, otherwise the next run will be blocked.

  6. The Control, Field, Config and Table buttons allow you to select the input files for a run. The alternatives must already be in the execute directory and, if chosen, will overwrite any existing CONTROL, FIELD, CONFIG and TABLE files. So do not use this if you already have suitable versions of these files.

  7. The Clear button deletes all input and output files from the execute directory. Use with caution!

  8. The Update button copies the REVOLD and REVIVE files to CONFIG and REVOLD respectively for the next run of the simulation. Note you will still need to modify the CONTROL file by adding a restart directive.

  9. Shutting down the GUI causes it to lose connection with any running program. The program will continue running, but restarting the GUI will not allow you to reconnect with it. Use the unix status command to find out what’s happening in this case.

  10. The GUI has a number of facilites to show the results of your simulation. Please see the GUI online manual for details.

  11. Always delete or move the STATIS file when starting a new simulation with DL_POLY (i.e. when starting again from time step 1). Otherwise the resulting STATIS file will be a concatenation of the previous simulation with the new and the GUI will not be able to read it. The same applies to the HISTORY file!