DL_MESO Exercises

These exercises involve the use of the CCP5 mesoscopic simulation code DL_MESO. It has two codes - one for Lattice Boltzmann Equation (LBE) and one for Dissipative Particle Dynamics (DPD) - and a broad range of applications, which you now have the opportunity to try out for yourself! You will be using the publicly available version of the code, currently DL_MESO 2.6.

The DL_MESO codes are available from the DL_MESO website and are supplied as source code. Those of you who need to develop advanced algorithms based on LBE or DPD, or explore complex systems, but can't afford the time to develop code from scratch yourself, may find it a useful starting point.

The full software package comes with its own graphical user interface (GUI) which is written in Java. It is fair to say it is a rather basic GUI, but it does help a great deal when working with DL_MESO, as we hope these exercises will show.

This session will begin by (optionally) compiling the GUI and briefly showing how it works. The user manual for DL_MESO includes a chapter on how to use the GUI. Please glance through this to get a feel for how the GUI works: it will pay off in the end! You should pay particular attention to the sections on the system and space settings for LBE and the system and interaction settings for DPD, as these construct the main input files for each code in DL_MESO.

Installation Instructions

System requirements

As DL_MESO is supplied as source code, any machine and/or operating system that can compile the programs should also be able to run them, although plenty of physical memory is recommended to avoid excessive use of hard disk swap space.

To compile the DPD and LBE codes, you will need a Fortran90 compiler and a C++ compiler respectively, e.g. gfortran and g++ from the GNU Compiler Collection (GCC). Various utilities also make use of the same compilers, while decryption of the gzipped tarball package for Unix/Linux or Mac OS X after download (see below) requires a C compiler. If you wish to compile the DPD code natively in Windows, you will also need to install GNU Make to be able to use makefiles: this is normally pre-installed for Unix and Linux distributions as well as Mac OS X.

If you wish to compile parallel versions of the codes for multicore machines, a version of MPI, e.g. OpenMPI, needs to be installed to provide 'compiler wrappers', i.e. commands to compile the codes with MPI. If you are using a centralised computer cluster or supercomputer, MPI-wrapped compilers should already be provided, e.g. CC and ftn on ARCHER: please consult the available documentation for the system or the administrator for information.

The Java GUI requires a Java Runtime Environment (JRE), which is normally already installed on most desktop and laptop computers. If you need to compile the GUI's Java source code, you will also need a Java Development Kit (JDK) for the relevant version of Java, which includes the compiler java.

Download and extract DL_MESO

You must first obtain a copy of the DL_MESO source code from the DL_MESO website. Two options are available:

  1. If you are intending to use DL_MESO for purely academic purposes, you can register for a free academic licence;
  2. If you are intending to use DL_MESO for commercially-funded research, you will need to obtain a commercial licence for an annual fee.

To obtain an academic licence:

  1. Access the DL_MESO website with your browser.
  2. Scroll down until you find the link Registering for the DL_MESO Package and click to select it.
  3. Read the page and, if you so wish, glance through the Licence Agreement; when you are ready, click on the REGISTER NOW link.
  4. Fill out the Registration Form with a valid email address and click REGISTER.
  5. Check your email: you should receive confirmation that you have joined the DL_MESO Mailing List and, more importantly, receive Download Instructions.

To obtain a commercial licence, you will need to email the author of DL_MESO, Michael Seaton, who will grant access to the software in exchange for an annual fee.

In either case, you will receive Download instructions in an email: follow these to download the encrypted software and decrypt it to produce the dl_meso_2.6.tar.gz file, or to download the password-protected dl_meso_2.6.zip file. You now have a copy of the DL_MESO software.

You will now need to unpack the software and compile the executable program. Either copy the dl_meso_2.6.tar.gz file to the location you want to use the software and unpack it with the command:

    tar zxvf dl_meso_2.6.tar.gz

or copy the dl_meso_2.6.zip file to the required directory and uncompress using an unzip command (e.g. unzip dl_meso_2.6.zip) or your operating system's archive manager: you will be prompted to enter the password to unpack the file.

This will create the dl_meso directory, after which you may delete the compressed file to save disc space.

The dl_meso directory contains several sub-directories:

  1. the DEMO directory (which contains the input files and snapshot images for test cases);
  2. the DPD directory (which contains the source for the DPD code, makefiles and utilities for creating input files and processing output files);
  3. the JAVA directory (which contains the source for the DL_MESO Java GUI);
  4. the LBE directory (which contains the source for the LBE code and utilities for creating input files and processing output files);
  5. the MAN directory, which contains a PDF copy of the User Manual; and
  6. the WORK directory, which is the suggested working directory for calculations and contains a Unix/Linux script for running the DL_MESO GUI and a makefile for compiling utilities.

Compile and run DL_MESO GUI

A pre-compiled Java archive (JAR) file containing the DL_MESO GUI is available in the dl_meso/JAVA directory, but depending on the system and version of Java in use you may need to compile it yourself. To compile the GUI, go to the dl_meso/JAVA directory and invoke the following commands:

    javac *.java
    jar -cfm GUI.jar manifest.mf *.class

To run the DL_MESO GUI, go to the dl_meso/WORK directory and start up the GUI as follows:

    java -jar ../java/GUI.jar

or use the script rungui in the same directory to invoke that command. In a short while the GUI main window will appear. Chapter 2 in the DL_MESO User Manual explains what the buttons and menus do. The DL_MESO exercises listed below can be run through the medium of the Java GUI. It is important to adhere to the DL_MESO directory structure, otherwise the GUI will not operate correctly.

Compile DL_MESO codes

The LBE and DPD codes can be compiled either by using command-line operations or by using the DL_MESO GUI. If you do not intend to change either of the codes, this only needs to be carried out once on the machine you wish to run DL_MESO.

To compile either code using the GUI, select the method using the top button and then either the 'Compile LBE Code' or 'Compile DPD Code' button in the side panel. For the LBE code, use the pull-down boxes to select the C++ compiler and version of the code (serial or parallel) you wish to use, then click 'COMPILE' to start compilation. The DPD code requires the construction of a makefile prior to compilation: select the Fortran90 compiler and code version you wish to use, click 'Create Makefile' to construct the makefile and then click 'COMPILE'. In both cases, an executable file will be created in the dl_meso/WORK directory.

Alternatively, it is possible to compile both codes manually. To compile the LBE code proceed as follows:

To manually compile the DPD code proceed as follows:

You will also need to compile the supplied utilities to create some input files and process outputs. While in the dl_meso/WORK directory, type

     make -f Makefile-utils

to compile the utilities for both LBE and DPD codes. You may wish to check the makefile prior to use to ensure it uses the correct Fortran90 (FC=) and C++ (CC=) compilers. Most of the utilities can be invoked via the GUI, but all of them can be launched from the command line. Full details of the utilities available and how to use them can be found in Appendix B of the user manual.

Running DL_MESO codes

Once they have been compiled, the LBE and DPD codes in DL_MESO can be launched using the GUI by selecting 'Run LBE Program' or 'Run DPD Program' and following the instructions. Alternatively, to run the serial version of one of the codes at the command line (for example, the LBE code), type:

    ./lbe.exe

if running in Unix, Linux or Mac OS X, or type:

    lbe.exe

if running in Windows. To launch the parallel version of a code, you must use either mpirun or mpiexec to specify the number of processors as well as the name of the executable, e.g.

    mpirun -np 4 ./dpd.exe

to run the parallel DPD code on 4 processors. (The exact command will depend upon the available MPI implementation.) A runscript may be required for centralised clusters or supercomputers with job queuing systems: consult the system documentation or ask the system administrator for more details.

If you want to run the OpenMP versions of the code, you will need to set the environment variable OMP_NUM_THREADS, e.g.

    export OMP_NUM_THREADS=4

before running the code as above, either at the command-line or in the runscript.

In all cases, the relevant input files for the DPD or LBE simulation must be included in the directory where the code is launched.

Visualisation software

DL_MESO and its utility can make use of two visualisation software packages: VMD for displaying trajectory data from DPD simulations, and Paraview for visualising grid-based data mainly from LBE simulations. Both are open-source and free to use for non-commercial purposes.

Exercises

You may now start on the exercises.

The following 10 exercises have been constructed for the tutorial and are intended to give experience of using DL_MESO in 'typical' applications: the first five use the LBE code, while the last five use the DPD code. Most exercises make use of the test cases that can be found in the dl_meso/DEMO directory. The exercises are not of equal difficulty or computing requirements. Exercises 3, 7 and 9, in particular, may require not yield useful results in a short time frame without some imaginative intervention by the student or access to multiple processor cores.

LBE exercises

DPD exercises

All of these exercises require you to perform actual simulations with DL_MESO. As these may take some time, while you wait you are encouraged to take a look at the theories behind LBE and DPD and how some of the other features of the DL_MESO GUI work.

If you want more information about the DL_MESO code, please see the DL_MESO User Manual.

Do not worry if you do not have time to complete any of the exercises during the workshop! You can always continue with them after you leave. If you want to, once you feel confident in using the package, you can try out the other test cases not covered in these exercises.