DL_MESO_DPD utilities

As well as the main DPD code (DL_MESO_DPD), DL_MESO comes with a number of utilities that can be used to help set up DL_MESO_DPD simulations and process the outputs.

The source codes for all of these utilities can be found in the DPD/utility directory of the DL_MESO package: most of these need to be compiled with a Fortran compiler (e.g. gfortran), although two others need to be compiled using a C++ compiler (e.g. g++). All DPD utilities (along with the LBE utilities) can be compiled using the Makefile in the WORK directory with the instructions shown in the DL_MESO Ready, get set, go guide. Each utility can be run with a command-line flag -h, e.g.

./utility.exe -h

to provide details and show the available command-line options.

molecule-generate.cpp

This utility helps to set up a molecular DPD simulation by creating sample configurations for molecules and writing these, bond connectivities and interactions, to a FIELD file. It can devise initial configurations for molecular chains with branches that fit inside cubes, which enable the molecules to be inserted into simulation boxes as part of DL_MESO_DPD’s simulation set up.

The source code for this utility is normally compiled to produce the executable molecule.exe, and can be run with the command:

./molecule.exe

Two command-line options can be invoked:

• -p requests that the molecular data is written to a separate file (molecule) rather than writing it to a new or pre-existing FIELD file
• -s allows users to supply the number and names of all particle species (up to 8 characters each)

If a FIELD file is available, information about the available particle species will be read from it. If this file is not available in the same directory where the utility is run or the command-line option to specify the particle species is not used, the user will be asked to enter this information.

The user will then be asked for the number of molecules to design, as well as the number, types and parameters for all bond, angle and dihedral interactions to be used. The utility will then ask the user a series of questions to specify information for each molecule required to determine the particle positions and connectivity of bonds, angles and dihedrals.

The positions for particles in each molecule will be generated using a constrained random walk algorithm to fit it inside the specified cube, before the information is written to the FIELD file (or alternatively the molecule file if this is requested).

convert-input.cpp

This utility helps users of older versions of DL_MESO_DPD (up to version 2.4) to migrate their input files to the current format so the simulations can be run using the current version of DL_MESO_DPD. It takes up to three input files - CONTROL, FIELD and MOLECULE - and converts them into the newer (DL_POLY-style) format CONTROL and FIELD files.

The source code for this utility is normally compiled (using the Makefile in the DPD/utility directory) to produce the executable convert.exe, and can be run with the command:

./convert.exe

Four command-line options can be invoked:

• -c allows users to specify a non-default name for the old-style CONTROL file
• -f allows users to specify a non-default name for the old-style FIELD file
• -m allows users to specify a non-default name for the old-style MOLECULE file
• -v switches on the verbose option to display all information found in the old input files on the screen or in the standard output

Only the old CONTROL file is essential for this utility, which contains both the simulation controls and interaction data for systems without molecules: the utility will abort with an error message if this file cannot be found.

No user input is required for this utility, which automatically creates a CONTROL and a FIELD file in the newer file formats. If the old-style CONTROL and FIELD files use these names, the original files are renamed as CONTROL.old and FIELD.old respectively. (Since DL_MESO_DPD no longer requires a MOLECULE file, this file does not need to be renamed and will not be replaced.)

export_config.F90

This utility helps users to devise starting configurations for DPD simulations from previous calculations. It reads in an export file containing a configuration at a given timestep and writes that configuration to a CONFIG file, also using the FIELD file to obtain the names of particle species.

The source code for this utility is normally compiled to produce the executable export_config.exe and can be run with the command:

./export_config.exe

Three command-line options can be invoked:

• -k sets the CONFIG file key indicating how much data per particle is to be written to the file (see below)
• -s writes the particle data to the CONFIG file after sorting the particles by particle number
• -u writes the particle data to the CONFIG file without sorting the particles (using the order from the export file)

If the CONFIG file key is not specified in the command-line option, the utility will prompt the user to enter one of the following values:

• 0 for particle positions
• 1 for particle positions and velocities
• 2 for particle positions, velocities and forces

If not otherwise specified, the utility will also write the particle data to the CONFIG file without sorting the particles first. If no FIELD file is available, the utility will close with an error message.

It should be noted that the particles are only likely to be in a randomised order if the export file was written during a parallel DL_MESO_DPD run. If DL_MESO_DPD had been run in serial, the particles will automatically be in numerical order regardless of which writing option is selected.

export_image_vtf.F90 and export_image_xml.F90

These utilities enable users to visualise a DPD simulation at the point when a export restart file was created. They read in the export file containing a configuration at a given timestep and write that configuration into a format that can be opened with graphical visualisation software, also using the FIELD file to find the names and other properties of particle species.

The source codes for these utilities are normally compiled to produce the executables export_image_vtf.exe and export_image_xml.exe. They can be run with the following commands:

./export_image_vtf.exe
./export_image_xml.exe

The optional command-line option -s can be used with export_image_vtf.exe to sort the particles in numerical order: this is carried out automatically by export_image_xml.exe. If no FIELD file is available, the utility will close with an error message.

No user intervention is required for the utilities to produce either an export.vtf file that can be opened in VMD or an export.xml file (in GALAMOST format) to open in OVITO.

history_config.F90

This utility helps users to devise starting configurations for DPD simulations from previous calculations. It reads in a HISTORY file containing a series of configurations and writes one of those configurations (as selected by the user) to a CONFIG file.

The source code for this utility is normally compiled to produce the executable history_config.exe and can be run with the command:

./history_config.exe

Five command-line options can be invoked:

• -k sets the CONFIG file key indicating how much data per particle is to be written to the file
• -f allows users to select the number of the trajectory frame from the HISTORY file to write to the CONFIG file
• -l requests the last available trajectory frame in the HISTORY file is written to the CONFIG file
• -s writes the particle data to the CONFIG file after sorting the particles by particle number
• -u writes the particle data to the CONFIG file without sorting the particles (using the order given in the HISTORY file for the required frame)

It should be noted that the available CONFIG file keys are limited based on the content of the HISTORY file. If no command-line option is given or the CONFIG file key and/or frame number are out of range for the HISTORY file, the utility will ask the user to enter the required CONFIG file key (if more than particle positions are available) and the trajectory frame number (if the last one is not already requested). By default the utility will also not sort the particles by number when writing to the CONFIG file.

traject_vtf.F90 and traject_selected_vtf.F90

These utilities help user visualise DPD simulations by reading in HISTORY files and writing out at least one VTF file that can be opened in VMD.

The source codes for these utilities are normally compiled to produce the executables traject_vtf.exe and trajects_vtf.exe. They can be run with the following commands:

./traject_vtf.exe
./trajects_vtf.exe

Three command-line options can be invoked by both utilities:

• -s writes the particle data to the VTF file(s) after sorting the particles by particle number
• -u writes the particle data to the VTF file(s) without sorting the particles (using the ordering given in the HISTORY file)
• -sc requests separate structure and coordinate files (traject.vsf and traject.vcf)

while traject_vtf.exe can also use -b to request separate files for bonded and unbonded particles. (If the -sc option is also invoked, this also applies for separate bonded and unbonded particle files.)

No user input is required for traject_vtf.exe, which by default will produce a single VTF file with both structure (bond connectivity) and coordinates (traject.vtf) that can be read natively by VMD without first sorting the particles by number. trajects_vtf.exe will ask the user to select which particles are to be written to the VTF file(s) (based on numbers or species/molecule types) as well as which trajectory frames should be used.

traject_xml.F90 and traject_selected_xml.F90

These utilities help user visualise DPD simulations by reading in HISTORY files and writing out a series of GALAMOST-formatted XML files that can be opened in OVITO.

The source codes for these utilities are normally compiled to produce the executables traject_xml.exe and trajects_xml.exe. They can be run with the following commands:

./traject_xml.exe
./trajects_xml.exe

No command-line options are available for both utilities, since the particle must be sorted by number for the file format. No user input is required for traject_xml.exe, which will write a series of XML files (one per trajectory frame) each with the particle positions (and velocities if available) for the trajectory frame and bond connectivity data. trajects_xml.exe will ask the user to select which particles are to be written to the XML files (based on numbers or species/molecule types) as well as which trajectory frames should be used.

local.F90

This utility takes the available trajectory frames in a HISTORY file, divides the simulation volume into cuboidal cells and calculates local properties (e.g. densities, velocities) for all cells that can be visualised and analysed.

The source code for this utility is normally compiled to produce the executable local.exe and run with the following command:

./local.exe

Seven command-line options can be invoked:

• -nx, -ny and -nz set the number of cells in each dimension (\(x\)-, \(y\)- and \(z\)-dimensions)
• -sf and -sl select the first and last trajectory frames from the HISTORY file to be used
• -tf sets the frequency of trajectory frames to use
• -av suppresses the writing of results for all individual frames and only produces time-averaged results

If the command-line options for the numbers of cells are not invoked, the user will be prompted to enter this information before proceeding. By default, all trajectory frames will be used and the results for each frame as well as time-averaged values will be written to files.

The results are written to Legacy VTK files - local_*.vtk for each frame, averages.vtk for time-averaged values - that can be opened, visualised and analysed using Paraview. The data included in each file will depend upon the available particle data in the HISTORY file: particle densities and numbers for each species are always written, while velocities and temperatures (including partial temperatures for Cartesian directions) will be included if particle velocities are available, as will pressure tensors if forces on particles are known.

isosurfaces.F90

This utility helps users identify and visualise mesophases in DPD simulations. For each trajectory frame in the HISTORY file, it assigns Gaussian functions with centres at particle positions for a selected species to a grid to create a density map. The density map is then used to calculate the second moment of the isosurface normal distributions, whose eigenvalues can be used as order parameters to determine the structure formed by the particles.

The source code for this utility is normally compiled to produce the executable isosurfaces.exe and run with the following command:

./isosurfaces.exe

Six command-line options can be invoked:

• -b selects the particle species used to create density maps
• -p sets the spacing between grid points
• -s sets the size (standard deviation) of Gaussian functions applied for each particle
• -sf and -sl select the first and last trajectory frames from the HISTORY file to be used
• -tf sets the frequency of trajectory frames to use

Default values for the grid spacing and Gaussian standard deviation are used if not specified in the command-line options, and all trajectory frames will be used if not otherwise specified. If the particle species is not selected at the command-line, the user will be prompted to enter it.

The utility will generate a Legacy VTK file (density_*.vtk) for each trajectory frame with the density map, which can be plotted using Paraview. The same density map is used to calculate the three eigenvalues of the second moment of isosurface normals, \(\mu_1\), \(\mu_2\) and \(\mu_3\), which are both printed to the screen or standard output and written to a text file moment with columns for time and the three values that can be read by plotting software (e.g. Gnuplot).

radius.F90

This utility calculates end-to-end distances and radii of gyration for all molecules at each trajectory frame in a HISTORY file, recording averages for each molecule type per frame and calculating time-averaged distributions of end-to-end distances for each molecule type at the end.

The source code for this utility is normally compiled to produce the executable radius.exe and run with the following command:

./radius.exe

Five command-line options can be invoked:

• -c sets the maximum end-to-end distance for the time-averaged distributions
• -d sets the histogram spacing for the time-averaged end-to-end distance distributions
• -sf and -sl select the first and last trajectory frames from the HISTORY file to be used
• -tf sets the frequency of trajectory frames to use

If no molecules are included in the HISTORY file, the utility will stop with an error message. No user input is otherwise required, as the utility will use default values for the maximum distance, histogram spacing and trajectory frame selection (i.e. all frames) if the command-line options are not specified.

The end-to-end distances and radii of gyration for all molecules are calculated from the particle positions given in each frame of the HISTORY file and averaged for all molecules of each type. Files named radius_* are written for each molecule type with columns for these quantities, and a single MOLDIST file is produced at the end with time-averaged distributions of end-to-end distances for all molecule types. All files can be read by plotting software (e.g. Gnuplot) and used for later analysis.

dipole.F90

This utility calculates total dipole moments for each molecule type based on trajectory frames in a HISTORY file, their autocorrelation functions and (optionally) Fourier transforms, which can be used to analyse the charge polarisability of a DPD simulation.

The source code for this utility is normally compiled to produce the executable dipole.exe and run with the following command:

./dipole.exe

Six command-line options can be invoked:

• -n sets the number of bins to calculate dipole autocorrelation functions (DAFs)
• -fft requests calculation of Fourier transforms of the DAFs
• -fc sets the number of histogram bins for Fourier-transformed DAF calculations
• -sf and -sl select the first and last trajectory frames from the HISTORY file to be used
• -tf sets the frequency of trajectory frames to use

No user input is otherwise required, as the utility will use default values for the number of bins and trajectory frame selection (i.e. all frames) and not calculate Fourier transforms if the command-line options are not specified.

The averaged dipole moments for each molecule type are given in dipole_* files, tabulating time and the Cartesian components of the moments. The DAFs for all molecule types are given in a DIPOLEDAT file, tabulating the autocorrelation functions for each type, while their Fourier transforms are supplied in a DIPOLEFFT file (if requested).

rdf.F90 and rdfmol.F90

These utilities calculate radial distribution functions (RDFs) for all pairs of species or molecule types using available trajectory frames in a HISTORY file.

The source codes for these utilities are normally compiled to produce the executables rdf.exe and rdfmol.exe, both of which can be compiled with OpenMP to speed up calculations. They can be run with the following commands:

./rdf.exe
./rdfmol.exe

Seven command-line options can be invoked:

• -c sets the maximum distance between pairs of particles for the RDFs
• -d sets the histogram spacing for RDF calculations
• -fft requests calculation of Fourier transforms of the RDFs (structure factors)
• -fc sets the number of histogram bins for Fourier-transformed RDF (structure factor) calculations
• -sf and -sl select the first and last trajectory frames from the HISTORY file to be used
• -tf sets the frequency of trajectory frames to use

The rdf.exe utility calculates the radial distribution functions for all pairs of particle species as well as between all possible particle pairs, writing the results in an RDFDAT file that can be opened by graphing software for visualisation and analysis. If requested, the Fourier transforms of the RDFs are supplied in an RDFFFT file. The rdfmol.exe utility does the same but with pairs of molecule types instead of species, writing the results to an RDFMOLDAT file and their transforms (if requested) to an RDFMOLFFT file.

widom_insertion.F90

This utility calculates excess chemical potentials by means of Widom insertion, using the trajectory frames in a HISTORY file to provide configurations for randomised trial insertions.

The source code for this utility is normally compiled to produce the executable widom.exe and can be compiled with OpenMP to speed up calculations. It can be run with the following command:

./widom.exe

Eight command-line options can be invoked:

• -p or -m allow the user to specify the particle or molecule to be used in trial insertions
• -rm uses the configuration of a randomly chosen molecule in each trajectory frame for trial insertions instead of the configuration specified in the FIELD file
• -n sets the number of trial insertions per trajectory frame
• -sf and -sl select the first and last trajectory frames from the HISTORY file to be used
• -r sets the random number generator seed
• -v switches on the verbose option to print instantaneous and block-averaged chemical potentials for each trajectory frame to the screen or standard output

The CONTROL and FIELD files used for the original DL_MESO_DPD simulation need to be supplied to provide interaction data, which are used to calculate contributions to the excess chemical potential from trial insertions. If these files are not available, the utility will close with an error message.

If the command-line options are not specified, the user will be prompted to select the bead type (species) or molecule type to use for insertions as well as the number of trial insertions per frame. A file called CHEMPOT_* ending with the name of the particle species or molecule type is created with the instantaneous and time-averaged excess chemical potentials and their standard deviations. The random number generator state is also written to a RNDSEED file that can be used for subsequent runs of the utility.

^ GO TO TOP ^