1/ PREPARING TO USE MP_tools

Copy the Examples subdirectory to a convenient place in your working space. Using any of its specific subdirectories as a template, create your own project directory, go there and create inside the ./data subdirectory, something like

mkdir my_project
cd ./my_project
mkdir data

Move the ACCII input (MD dump files and/or trajectory files) of your project into data

mv /volumes/whatever_somewhere/hist_200.txt ./data

or, to avoid manipulating huge data volumes, just make a link and place it into ./data

link /volumes/whats_ever/hist_200.txt ./data/hist_200.txt

A good idea is to give intuitive names to all what follows, eg. BZO200s for a BZO (BaZrO3) short sequence at 200K

mv ./data/hist_200.txt ./data/BZO200s.txt

use the upper and lower case according to your system conventions and to your convenience; on many systems all the MP_tools input specifications will prove case-insensitive.

In your project directory create a <your_project>.par, possibly by editing/duplicating one of the parameter files from the Examples. For convenience, but not obligatorily, use the same filename as above, i.e. BZO200s.par. This file will contain info about your substance and option settings for the MP_tools. The binary snapshot files will automatically use the name of the .par file followed by numbers (if timeseries) in the form of _nxxxx, eg. BZO200s_n0001.dat; for numbers above 9999 the real length is used, i.e. BZO200s_n100001.dat.

Inside the .PAR file the namelist names like &mp_bin, &mp_pdf etc. as well as the names of the variables are in fact FORTRAN identifiers - do not touch them! Each namelist has to be terminated by a slash (/)on the last line. When editing the contents mind to use spaces rather than tabs. Empty lines as well as any text beyond the first exclammation mark on a line is a comment, ignored in input. You cannot add anything to the namelists unless modifying the code itself, on the other hand non-relevant items may be omitted in the .PAR file.

2/ USING MP_tools

Each tool offers a more-or-less intuitive command line dialog (cf. terminal logs in the Examples pages).

A/ Convert the input ASCII file data produced by DL_POLY, LAMMPS, DISCUS etc. into binary form (as a first, obligatory step)
  • MP_DBIN (for DL_POLY data) or MP_LBIN (for LAMMPS, GENERAL data) tools generate the binary direct access files to be used in subsequent work; each of the files will start by a header record containing info from the trajectory-file header and from the .PAR file (atom names, masses, lattice parameters etc.), the binary files will be stored in ./data again; if pertinent, the programs determine real temperature from the kinetic energies of individual velocity components (separately for cores and shells in case of the shell model simulations) and refine corrections to the lattice parameters originally deduced from the supercell dimensions; a detailed output is produced for the first snapshot in the series automatically and can be extended to all of them by setting a switch in the .PAR file

For series of snapshots the binary file names consist of a ‘master’ (a character chain specified in the MP_*BIN dialogue) followed by ‘_n’ and a minimum four-digit number, eg. BZO200_n0001.dat; the other tools will ask later for this information in their input dialogues.

B/ Inspect the contents of the binary data files
  • MP_INSP prints the contents of the header record of a binary data file and displays information on individual atoms identified by their supercell (CELL) or input sequence (BULK) indices.

  • MP_PDF accumulates and plots pair distribution functions (PDF) in direct space by Monte-Carlo sampling; use OpenMP parallelisation if computation speed is of importance; for high accuracy and 100% reproducibility the single process option should be checked

  • MP_DOS calculates and plots the vibrational density of states; atom weights can be chosen between uniform (1.) and neutron (bcoh, read from the .PAR file) with the possibility to mask out any of the atom types

  • MP_SQOM produces total, elastic and inelastic diffuse scattering intensity maps over planes in reciprocal space as well as E(Q) (dispersion-like) cuts with the possibility to save tables of intensities in ASCII format (.TXT) and the graphical output in the .PS or .PNG format; the use of non-uniform fast Fourier transform (NUFFT) to pass from the direct to the reciprocal (momentum) space brings in the FFT-like computing time gain of ≈ NlogN against the N^2 scale for normal FT, which can reach many orders of magnitude for large systems; in addition, the use of OpenMP parallelisation can be activated and is recommended in general (no reproducibility issues to be expected)

3/ EXAMPLES

The examples in the Examples directory cover the two available ASCII data input methods, CELL and BULK, and take as examples data generated by DL_POLY, LAMMPS and FERRODO (phasefield simulation package).

To keep the distribution size reasonable, the data sets extend only over a single or a few snapshots, permitting to test the basic functions of MP_tools: conversion to binary format, inspection of the binary data, plots of total scattering intensities and generation of a PDF. The energy-resolved functionalities calling for sequences of hundreds to thousands snapshots (10-100 Gb) need to be tried in ‘real life’ circumstances (in case of doubt contact the author)

The text files like lammps_cu_48.txt containing terminal session logs, included in each case, give an idea of what could be a brief tutorial session and give also the possibility to cross-check the details of data file structure. The included .PAR files can be used as templates for own projects.