DL_MONTE-user-hub

DL_MONTE-user-hub

User hub for DL_MONTE project, including wiki (see https://gitlab.com/dl_monte/user-hub/wikis/home) and discussion board (via issue tracker).

Welcome to the DL_MONTE wiki!

Here you can find information about the DL_MONTE project, including how to obtain the DL_MONTE program and associated tools, how to contact the DL_MONTE team, and links to documentation, tutorials and examples. See below to find what you are looking for.

Recent news

  • DL_MONTE version 2.07 has been released (5th June 2020)

Contents


About the DL_MONTE project

The aim of the DL_MONTE project is to create open-source software for applying Monte Carlo molecular simulation to a wide range of systems. Our two major codes are:

  • the molecular simulation program DL_MONTE
  • the Python library dlmontepython

Further details of these can be found below.

History and funding sources

DL_MONTE was originally originally developed at Daresbury Laboratory by John Purton for the EPSRC’s Collaborative Computational Project for the Computer Simulation of Condensed Phases (CCP5 : http://www.ccp5.ac.uk ). Bill Smith and Ilian Todorov provided some general purpose routines such as code for geometric transformations of the simulation cell and the module for text parsing. Contributions were also made in this initial phase of development by Stephen Cox (University Colledge London) and Dmytro Antypov (University of Liverpool).

In 2015 a research grant (EP/M011291/1) obtained from the EPSRC’s Software for the Future programme by Nigel Wilding (Physics, University of Bath), Steve Parker (Chemistry, University of Bath) and John Purton (Daresbury Laboratory) funded significant development of DL_MONTE. The joint efforts of Andrey Brukhno (SCD/STFC, Daresbury), Tom Underwood (Physics, University of Bath) and James Grant (Chemistry, University of Bath) resulted in a significant expansion of the methods available in DL_MONTE (too many to list here) and optimisation of the code. During this time a Python toolkit, whose aims were to assist with analysis and automation of DL_MONTE simulations, was instigated by Kevin Stratford (EPCC, University of Edinburgh) as part of an ARCHER-funded embedded CSE project (eCSE11-03).

Further Python tools were later developed from 2018, primarily by Tom Underwood and John Purton, as part of another embedded CSE project (eCSE11-03), and all DL_MONTE-related Python tools were later amalgamated into a single library 'dlmontepython'.

Currently DL_MONTE is maintained by John Purton and Tom Underwood, the latter of whom is supported by the EPSRC grant 'Multiscale tuning of interfaces and surfaces for energy applications' (EP/P007821/1).

Citing/acknowledging DL_MONTE

Please cite the following articles in publications which make use of DL_MONTE:

  • "DL_MONTE: a multipurpose code for Monte Carlo simulation", A. V. Brukhno, J. Grant, T. L. Underwood, K. Stratford, S. C. Parker, J. A. Purton & N. B. Wilding, Molecular Simulation, DOI: 10.1080/08927022.2019.1569760 (2019)
  • "DL_MONTE: a general purpose program for parallel Monte Carlo simulation", J.A. Purton, J.C. Crabtree & S.C. Parker, Molecular Simulation, 39:14-15, 1240-1252 (2013)

If you use only the Python tools it is necessary to only cite the latter of the above two publications.

Contributing to the project

We welcome contribution to the project in any way. Please contact us (see below) if you wish to contribute. Note that there are ways to contribute beyond coding...

We are especially keen for users to contribute to the suite of example simulations; if you have used DL_MONTE to perform any interesting simulations, and you think other users could benefit from seeing your input files, then please get in touch. Or even better, if you have the time, you could even contribute a tutorial.

The main program

The Monte Carlo simulation program DL_MONTE 2 is the key software provided as part of the DL_MONTE project. An overview of the functionality of DL_MONTE 2 can be found on the DL_MONTE CCP5 webpage.

Accessing the program

Releases of DL_MONTE 2 are housed here.

We request that new users register on the DL_MONTE CCP5 webpage. The reason for this is that it enables us to quantify our user base, something which is very helpful for justifying funding for further development DL_MONTE 2.

Access to the development version

The development branch of DL_MONTE 2 is publicly viewable, and is housed here. It is possible for users to download the latest snapshot of the development branch. However we do not recommend you do this without good reason. Firstly, due to the nature of code development, certain snapshots of the development branch may be unstable. Moreover, the size of the development repository is quite large. By contrast the releases are stable, compact, and should be sufficient for most users.

Installing the program

Downloading and extracting the release

The latest version of DL_MONTE is provided as a tar.gz archive here. Below I describe how to install DL_MONTE in unix-like systems (e.g. Mac OS X, Ubuntu). First, move the release archive to the directory where you wish DL_MONTE to be installed, which here is dl_monte.

$ pwd
/home/tom/dl_monte
$ ls
dl_monte_release_v2.07.tar.gz

Then extract the archive using the relevant command, which for my system is tar -zxf.

$ tar -zxf dl_monte_release_v2.07.tar.gz

There should now be a directory, in this case dl_monte_release_v2.07 containing the source code.

$ ls
dl_monte_release_v2.07 dl_monte_release_v2.07.tar.gz

Enter the directory in preparation for compiling the source code.

$ cd dl_monte_release_v2.07

Compiling DL_MONTE - Quick start

There are a number of ways in which DL_MONTE can be compiled. The simplest way is via the build: script. The following command compiles the serial version of DL_MONTE using the Fortran compiler gfortran. (How to compile the parallel/MPI version of DL_MONTE is explained below).

$ ./build: SRL dir gfortran

If this command works correctly then you should see output similar to the following (where ... is an ellipsis).

$ ./build: SRL dir gfortran

//////////////////////////////////////////////////////
//                                                  //
// DL_MONTE-2 building script, version 2.02 (alpha) //
// Author - Dr Andrey Brukhno (DL/STFC), June 2016  //
//                                                  //
//////////////////////////////////////////////////////

Preparing for building with target 'gfortran' from ./Makefile_SRL...

Building serial executable ./bin/DLMONTE-SRL-VDW_dir.X

'./vdw_direct_module.f90' -> './vdw_module.f90'
'./Makefile_SRL' -> './Makefile'

rm -f *.o *.mod
make LD="gfortran -o " \
LDFLAGS=" " \
FC="gfortran -c -cpp -U DEBUG" \
FCFLAGS="-O3 -C" \
EX=DLMONTE-SRL.X BINROOT="./bin" serial
make[1]: Entering directory '/home/tom/dl_monte/dl_monte_release_v2.07'

DL_MONTE_2 compilation in serial mode (Makefile_SRL)

linking to ./SERIAL/mpif.h
gfortran -c -cpp -U DEBUG -O3 -C kinds_f90.f90
gfortran -c -cpp -U DEBUG -O3 -C constants_module.f90
gfortran -c -cpp -U DEBUG -O3 -C mpi_module.f90
gfortran -c -cpp -U DEBUG -O3 -C comms_mpi_module-SRL.f90
gfortran -c -cpp -U DEBUG -O3 -C comms_omp_module.f90
gfortran -c -cpp -U DEBUG -O3 -C error.f90
gfortran -c -cpp -U DEBUG -O3 -C warning.f90
gfortran -c -cpp -U DEBUG -O3 -C parse_module.f90
...
gfortran -c -cpp -U DEBUG -O3 -C traj_convert.f90
gfortran -c -cpp -U DEBUG -O3 -C dl_monte.f90
gfortran -o  ./bin/DLMONTE-SRL.X  kinds_f90.o constants_module.o  mpi_module.o comms_mpi_module-SRL.o comms_omp_module.o error.o warning.o parse_module.o parallel_loop_module.o arrays_module.o bondlist_type.o anglist_type.o atom_type.o nbrlist_type.o dihlist_type.o invlist_type.o coul_type.o lattice_type.o thblist_type.o molecule_type.o control_type.o config_type.o statistics_type.o random_module.o fed_interface_type.o psmc_control_type.o  dcd_format_module.o dihlist_module.o invlist_module.o inversion_module.o bondlist_module.o anglist_module.o nbrlist_module.o atom_module.o molecule_module.o species_module.o bond_module.o metpot_module.o lattice_module.o coul_module.o config_module.o thblist_module.o thbpotential_module.o tersoff_module.o vdw_module.o slit_module.o external_potential_module.o cell_module.o angle_module.o dihedral_module.o field.o psmc_module.o orientation_module.o fed_calculus_module.o fed_order_module.o fed_interface_module.o control_module.o statistics_module.o rep_exchange_module.o mc_moves.o gcmc_moves.o gibbs_moves.o vol_moves.o psmc_moves.o yamldata_module.o montecarlo_module.o traj_convert.o dl_monte.o
make[1]: Leaving directory '/home/tom/dl_monte/dl_monte_release_v2.07'
'./bin/DLMONTE-SRL.X' -> './bin/DLMONTE-SRL-VDW_dir.X'

Moreover a new directory bin will have been created containing the DL_MONTE executable.

$ ls bin
DLMONTE-SRL-VDW_dir.X  DLMONTE-SRL.X

Note that there are two executables. These are identical, and have SRL in their name to reflect that they correspond to the serial version of DL_MONTE.

If the compilation failed then one possibility is that you do not have gfortran installed.

Compiling DL_MONTE - MPI version

The following command compiles the MPI version of DL_MONTE using whatever MPI Fortran compiler is wrapped to the mpif90 command.

$ ./build: PRL dir mpi

The output of this command should look similar to that below.

$ ./build: PRL dir mpi

//////////////////////////////////////////////////////
//                                                  //
// DL_MONTE-2 building script, version 2.02 (alpha) //
// Author - Dr Andrey Brukhno (DL/STFC), June 2016  //
//                                                  //
//////////////////////////////////////////////////////

Preparing for building with target 'mpi' from ./Makefile_PRL...

Building parallel executable ./bin/DLMONTE-PRL-VDW_dir.X 

'./vdw_direct_module.f90' -> './vdw_module.f90'
'./Makefile_PRL' -> './Makefile'

make LD="mpif90 -o " \
LDFLAGS=" " \
FC="mpif90 -c -cpp -U DEBUG" \
FCFLAGS="-O3" \
EX=DLMONTE-PRL.X BINROOT="./bin" parallel
make[1]: Entering directory '/home/tom/dl_monte/dl_monte_release_v2.07'

DL_MONTE_2 compilation in parallel mode (Makefile_PRL)

mpif90 -c -cpp -U DEBUG -O3 kinds_f90.f90
mpif90 -c -cpp -U DEBUG -O3 constants_module.f90
mpif90 -c -cpp -U DEBUG -O3 comms_mpi_module-PRL.f90
mpif90 -c -cpp -U DEBUG -O3 comms_omp_module.f90
mpif90 -c -cpp -U DEBUG -O3 error.f90
mpif90 -c -cpp -U DEBUG -O3 warning.f90
...
mpif90 -c -cpp -U DEBUG -O3 traj_convert.f90
mpif90 -c -cpp -U DEBUG -O3 dl_monte.f90
mpif90 -o  ./bin/DLMONTE-PRL.X  kinds_f90.o constants_module.o  comms_mpi_module-PRL.o comms_omp_module.o error.o warning.o parse_module.o parallel_loop_module.o arrays_module.o bondlist_type.o anglist_type.o atom_type.o nbrlist_type.o dihlist_type.o invlist_type.o coul_type.o lattice_type.o thblist_type.o molecule_type.o control_type.o config_type.o statistics_type.o random_module.o fed_interface_type.o psmc_control_type.o  dcd_format_module.o dihlist_module.o invlist_module.o inversion_module.o bondlist_module.o anglist_module.o nbrlist_module.o atom_module.o molecule_module.o species_module.o bond_module.o metpot_module.o lattice_module.o coul_module.o config_module.o thblist_module.o thbpotential_module.o tersoff_module.o vdw_module.o slit_module.o external_potential_module.o cell_module.o angle_module.o dihedral_module.o field.o psmc_module.o orientation_module.o fed_calculus_module.o fed_order_module.o fed_interface_module.o control_module.o statistics_module.o rep_exchange_module.o mc_moves.o gcmc_moves.o gibbs_moves.o vol_moves.o psmc_moves.o yamldata_module.o montecarlo_module.o traj_convert.o dl_monte.o
make[1]: Leaving directory '/home/tom/dl_monte/dl_monte_release_v2.07'
'./bin/DLMONTE-PRL.X' -> './bin/DLMONTE-PRL-VDW_dir.X'

Moreover a new directory bin will have been created containing the DL_MONTE executable.

$ ls bin
DLMONTE-PRL-VDW_dir.X  DLMONTE-PRL.X

Note that there are two executables. These are identical, and have PRL in their name to reflect that they correspond to the parallel/MPI version of DL_MONTE.

If the compilation failed then one possibility is that you do not have mpif90 installed.

Compiling DL_MONTE - Further details

The build: script employs make to build DL_MONTE. While we believe it is simpler to use the build: script, one could use make to build DL_MONTE in the conventional manner; however note that there are different Makefiles for the serial and parallel versions of DL_MONTE, Makefile_SRL and Makefile_PRL. If one wishes to use make in the conventional manner then one should use either Makefile_SRL or Makefile_PRL. This can be achieved in a number of ways. Firstly, one could copy Makefile_SRL or Makefile_PRL to Makefile, and then run make with the desired target, e.g. make gfortran, make mpi. Alternatively one could specify the desired Makefile using the -f argument to make, e.g. make -f Makefile_SRL gfortran.

build: supports targets other than just gfortran and mpi. For a target TARGET the appropriate command is

$ ./build: SRL dir TARGET

or

$ ./build: PRL dir TARGET

To see which targets are supported for the SRL and PRL arguments please see Makefile_SRL and Makefile_PRL respectively. Note however that many of these were developed for specific machines, and are obsolete. In time we hope to tidy up the Makefiles and improve the process of building DL_MONTE.

Documentation

User manual

Here is the pdf user manual for the latest release of the DL_MONTE main program (v2.06):

DL_MONTE-206_Manual.pdf

Note that the user manual is distributed alongside the source code of DL_MONTE releases.

We have recently started to port the manual online. The latest version of the online manual can be found here. Sorry for any typos -- this manual is currently 'in development'. We hope to improve the state of this manual soon.

Tutorials

Tutorials are currently provided as a website here. The input files and scripts for the tutorials can be downloaded from the public GitLab project DL_MONTE-tutorials-files.

Examples

A suite of example input files for various types of DL_MONTE 2 simulation are provided here. Each example contains a description of the simulation, the input files, and, if applicable, scripts or programs for analysing the output of the simulation. In time we hope to extend the suite of examples, as well as 'promote' many of the examples to tutorials.

Modifying/Hacking the source code

DL_MONTE 2 is open source, and users are free to modify the source code in their own versions of the program as they see fit. Unfortunately, the source code of DL_MONTE is large, and locating the relevant part of it to modify may be difficult. To assist users wishing to 'hack' DL_MONTE 2 we have created a hacking guide, which points users to the key Fortran procedures in the source code.

Here is the latest version of the DL_MONTE 2 Hacking Guide (v2/7/18):

DL_MONTE-2_Hacking_guide_2Jul18.pdf

Python tools

dlmontepython is a Python library containing various tools we have developed pertaining to Monte Carlo molecular simulation (among other things). The library is hosted on the public GitLab project dlmontepython.

Note that this library is still under development. We intend to improve the nature of the documentation as soon as possible.

Obtaining the Python tools

The latest development version of dlmontepython can be obtained from the GitLab project here.

Old releases of Python software we have developed can be found here.

Documentation

Documentation, including examples and tutorials, is included in the dlmontepython library in the root directory of the library.

Miscellaneous software

Further software we have developed is hosted in the GitLab project DL_MONTE-utils. This project contains miscellaneous software - in particular small analysis programs not written in Python - pertaining to DL_MONTE which we have found useful.

Training events

One or more of the DL_MONTE team can usually be found at the CCP5 software training events (which are predominantly held in the UK). See the CCP5 website for details.

Contacting the DL_MONTE team

We welcome dialogue with our users. In particular, please contact us if:

  • You discover a bug in our software.
  • You discover a typo in our documentation.
  • You wish to provide feedback regarding our software or documentation. This includes requests for new functionality, features, software or documentation, or suggestions for improvement of these things.

The preferred way to contact the team is by raising an Issue here in the DL_MONTE user hub. Once the Issue has been raised, a member of the team will address it as soon as possible.

Useful links

  • The DL_MONTE project is supported by CCP5, and the CCP5 DL_MONTE webpage contains more information than presented here regarding functionality in DL_MONTE.

  • DL_MONTE used to be hosted on CCPForge, before it was shut down. The old DL_MONTE-2 CCPForge page, now frozen, contains old releases of DL_MONTE and the htk Python toolkit, as well as an old forum, though I doubt this is of much use to anyone.