Skip to content

Home

Jump to bottom Edit New page
KM Tu edited this page Apr 2, 2018 · 131 revisions

Overview

Decond calculates the decomposed transport quantity of fluid by decomposing the Green-Kubo formula as described in J. Chem. Phys. 141, 044126 (2014). The data for calculating the time correlation functions in the formula are provided by the molecular dynamics simulations (MD).

Decond package consists of two parts:

  1. A Fortran program (decond) that reads in an MD trajectory and outputs the decomposed correlation data.
  2. A Python script (dec) that reads in the decomposed correlation and outputs the analysis results.

In addition, several Python scripts that demonstrate how to read and plot the analysis results are included in the python/plot/ directory. Users can create their own plotting scripts based on these examples.

Throughout the wiki, "decond" will refer to the Fortran binary decond, while "Decond" will refer to the whole Decond project including decond and dec.

Installing

Download the package

If one knows Git, one can simply run git clone to clone the whole repository to the directory where Decond is to be installed. Let's call the directory <Decond>.

git clone https://github.com/decond/decond.git <Decond>

Or, if Git is not an option, one can download Decond from https://github.com/decond/decond/releases and extract the files to <Decond>. For example,

wget https://github.com/decond/decond/archive/v0.4.3.tar.gz
tar -zxvf v0.4.3
mv decond-0.4.3/* <Decond>/

Note that <Decond> should be replaced with the real directory path that the user chose, such as $HOME/decond.

Compile the Fortran binary decond

One can skip compiling decond if only dec is needed. On a personal computer, for example, one usually does not run decond but may want to analyze the data with dec.

  1. Prepare the dependent libraries

  2. Manually edit the file <Decond>/fortran/Makefile to suit your environment (Details...) and compile with make

    cd <Decond>/fortran
make

    decond should then be ready to use in the <Decond>/bin directory.

Prepare Python environment for dec

  1. The easiest way is to download and install Anaconda Python Distribution. (Remember to download the Python 3+ version.) Alternatively, one can install Python 3, SciPy, and h5py on one's own. Not an easy task, though.

  2. Set the environment variable PYTHONPATH=<Decond>/python:$PYTHONPATH so that Decond Python package is searchable in Python. To make it set automatically in the future, add the following line to ~/.bashrc:

    export PYTHONPATH=<Decond>/python:$PYTHONPATH

  3. To use dec more conveniently, one can set dec in the PATH by adding the following line to ~/.bashrc:

    export PATH=<Decond>/bin:$PATH

    Then dec can simply be run by

    dec -h

    -h means to show the help message of dec, which is used simply for testing purposes here

    Alternatively, without setting the PATH, one should run dec by its full path

    <Decond>/bin/dec -h

    or if Python 3 is not in the PATH,

    <path/to/python3> <Decond>/bin/dec -h

Using

Prepare MD files

Before running decond, one needs to prepare the necessary MD files for input. Currently, decond supports the trajectory files of .trr format and any XYZ-compatible trajectory (.xyz).

  • Trajectory
    decond reads GROMACS .trr file for both positions and velocities. So don't forget to set both nstxout and nstvout when generating trajectories. Please refer to Refs. [1] and [2] for the details of MD procedures.

  • Log file (optional) decond reads .log file just for the system temperature, which will be recorded in the output for dec to calculate the transport quantity. Optionally, one can choose to input the temperature value manually.

  • Topology (optional for monoatomic ionic systems)
    decond reads the topology file for the ion charges and for calculating the center of mass of each ion molecule. If the ionic system only consists of monoatomic ions (e.g. NaCl), one can choose not to use the topology file and manually specify the charges and indexes of ions, instead.

    If the topology file is "self-content" (without using any #include directive), it can be fed to decond directly. Otherwise, users have to preprocess the topology file with cpp, first. For example:

    cpp topology.top topology.cpp.top

    It is because decond only reads the given topology file stupidly without following any #include directive. Since it does no harm to preprocess an already "self-content" topology, it may be wise to run cpp first for all topology files anyhow.

    cpp stands for C Preprocessor

Run decond

When the input MD files are ready, one can start to run decond. decond reads in the MD files and outputs the decomposed correlation data.

  1. Input
    Please read Using decond for details about the input options of decond.

  2. Output

    • The default output filename of decond is corr.c5, which can be changed via the -o <filename> option. Please read Correlation data file (corr.c5) for details about the format of corr.c5.

    • decond also prints information to standard output for users to validate their input data and to estimate the program running time. Please read decond standard output for details.

Analyze with dec

corr.c5 contains the decomposed correlation data, which have to be processed by dec to give the decomposed physical quantity of interest. The default output name for the resulting processed file is decond.d5. Please read Processed correlation data file (decond.d5) for the data format of decond.d5.

One has to use dec with the five subcommands: new, add, fit, window, and report. Except report, all the other commands essentially read in corr.c5 and/or decond.d5 files and then output new decond.d5 file. Please read Using dec for the usage of each command, or click any of the commands below:

  • dec new: create a new decond file (decond.d5) from corr.c5 data
  • dec add: add more corr.c5 data based on an existing decond.d5
  • dec fit: change fitting ranges based on an existing decond.d5
  • dec window: change binning window based on an existing decond.d5
  • dec report: show an overall report of decond.d5 to the standard output

Visualize results

The data in decond.d5 can be visualized in several ways.

  1. Since decond.d5 is just an HDF5 file, users can read and manipulate the HDF5 data through any HDF5 tools or programming interfaces (C, C++, Fortran, Java, or Python ... etc.) they like. Thus plot the data with any tool that the users are familiar with.

  2. If the users are not familiar with HDF5 format, they can choose to use the plotting Python scripts that are included in Decond. Please read Using plotting scripts for details.

Tutorial

Developing

Program structure

Citing

Please cite Decond with the following publications:
[1] J. Chem. Phys. 141, 044126 (2014)
[2] J. Chem. Phys. 141, 244507 (2014)

Add a custom footer
Add a custom sidebar
Clone this wiki locally