MDTransport 1.1.0

A modular, open-source Python tool for computing transport properties from GROMACS and LAMMPS simulations.

MDTransport

MDTransport: Python Tool for Computing Transport Properties from GROMACS and LAMMPS Simulations

MDTransport is a powerful and flexible command-line tool designed to streamline the analysis of transport properties from Molecular Dynamics (MD) simulations. It provides a unified interface for post-processing trajectory data from both GROMACS and LAMMPS.

---

Table of Contents

• Installation Guide
  • Prerequisites
  • Package Managers (Recommended)
  • Build From Source
• Argument Flags
• Commands Usage
  • MSD and Diffusion Analysis
  • Conductivity & Transport Analysis
  • Correlations & Structure

---

Installation Guide

Prerequisites

The following base dependencies are required:

• python >= 3.9
• matplotlib >= 3.6
• pandas >= 2.0
• numpy >= 1.20
• scipy >= 1.10
• tqdm >= 4.60

Optional Dependencies

Depending on the specific engine you wish to use for trajectory parsing, you may need one of the following:

Click to view optional installations (MDAnalysis, Chemfiles, Ovito)

• MDAnalysis (Required for --mda option)

  conda install -c conda-forge mdanalysis

  or

  pip install MDAnalysis

• Chemfiles (Required for --chem option)

  conda install -c conda-forge chemfiles

  or

  pip install chemfiles

• Ovito (Required for --ovito option)

  conda install -c conda-forge ovito

  or

  pip install ovito

Installation via Package Managers

MDTransport is available as a pre-compiled package for Linux, macOS, and Windows.

Via PyPI:

pip install MDTransport

Via Conda-forge:

conda install -c conda-forge mdtransport

Build From Sources

You can install the latest development version directly from GitHub:

git clone https://github.com/ShahResearchGroup/MDTransport.git

cd MDTransport

Using pip

pip install -e .

OR using a Conda environment

conda env create -f environment.yml conda activate mdt_env chmod +x mdt.py

---

Argument Flags

General Analysis Modes

Flag	Description
--gro	Run GROMACS analysis.
--lam	Run LAMMPS analysis.

Trajectory Parsing Modes

Flag	Engine	Description & Example
--pdb	GROMACS	Use PDB file to extract species data.
--exe	GROMACS	Use gmx to extract species data (e.g., --exe gmx or --exe gmx_mpi).
--lamp	LAMMPS	Use lammpstrj file to extract species data.
--com	LAMMPS	Use LAMMPS generated com.txt (e.g., --com /path/to/com.txt).
--chem	Both	Use Chemfiles to extract species data.
--mda	Both	Use MDAnalysis to extract species data.
--ovito	Both	Use Ovito to extract species data.

File & Path Arguments

Flag	Description	Example
--in	Path to MDTransport input file	--in /path/to/input
--itp	Directory containing GROMACS ITP files	--itp /path/to/itp/
--tpr	Path to GROMACS TPR file	--tpr /path/to/file.tpr
--traj	Path to trajectory file	--traj /path/to/file.trr
--data	Path to LAMMPS data file	--data /path/to/data
--lam_in	Path to LAMMPS input file	--lam_in /path/to/input
--gro_path	Path to GROMACS files directory	--gro_path /path/to/gromacs/
--lam_path	Path to LAMMPS files directory	--lam_path /path/to/lammps/

General Parameters

Flag	Description	Example
--temp	Temperature in Kelvin	--temp 298.0
--t_steps	Time steps in ps	--t_steps 2
--n_delta	Time window for time origins shifting in ps	--n_delta 1000
--t_window	Time window for slope calculations in ps	--t_window 1000
--min_window	Minimum time window for diffusivity calculations in ps	--min_window 1000
--n_steps	Snapshots range in frames	--n_steps 0 20000
--fit_method	MSD fitting method for diffusion calculations	--fit_method gls
--msd_fit	Time window (in ps) for MSD fitting: start end	--msd_fit 10000 40000
--steps	Steps for time origin shifting	--steps 20
--dir	Specify directions for msd/diffusion	--dir x y z
--n	Process every N-th frame	--n 5
--dump_frame	LAMMPS trajectory dumping frame	--dump_frame 1000
--n_cores	Number of CPU cores for parallel processing	--n_cores 8
--mp_mode	Multi-processing initialization	--mp_mode fork

Properties Calculations

Flag	Description
--msd	Compute mean squared displacement and diffusion.
--corr	Calculate ion-ion correlations and Einstein conductivity.
--onsg	Calculate Onsager transport coefficients.
--spda	Spatial decomposition of ion-ion correlations.
--en	Calculate Einstein conductivity.
--ne	Calculate Nernst-Einstein conductivity.
--smd	Run Stefan-Maxwell diffusivity analysis.
--pcl	Calculate pair correlation lifetime.
--cage_p	Cage population analysis.
--cage	Calculate cage correlation lifetime.
--veh	Run transport mechanism analysis.
--rdf	Calculate radial distribution functions.
--get_csv	Parse and save trajectories data.

Analysis-Specific Parameters

Flag	Description	Example
--species	Define species names and counts for LAMMPS	--species EMI 500 BF4 500
--resname	Define species names	--resname EMI BF
--skip_species	Exclude Resnames from COM generation	--skip_species SOL
--rcut	Cutoff radius for analysis	--rcut 7.6
--rbin	RDF bin size	--rbin 0.2
--ref_species	Reference species for cage correlation	--ref_species EMI
--cage_species	Cage species for cage correlation	--cage_species BF
--ana	Run optional RDFs analysis	--ana
--eh	Enable Einstein-Helfand for TRA and ONSG analysis	--eh
--rdf_mode	Specify the RDF calculation mode	--rdf_mode com com
--rdf_pairs	Specify the RDF pairs	--rdf_pairs resname EMI type HR resname BF type F
--msd_mode	Specify the MSD calculation mode	--msd_mode com
--msd_species	Specify the MSD species	--msd_species type 1-6 type 7-12
--shell	Solvation shell choice for SPDA	--shell first
--species_charges	Override net charges on each species	--species_charges EMI 0.8

---

Commands Usage

Note: [Parser] in the examples below refers to your chosen file parsing backend:

• GROMACS: --pdb --traj <pdb file> --itp <itp directory> OR --exe <gmx> OR --mda OR --chem OR --ovito
• LAMMPS: --lamp OR --com <com file> OR --mda OR --chem OR --ovito

1. MSD and Diffusion Analysis

COM-based MSD for Species

GROMACS:

mdt --gro --msd [Parser] --t_steps <time steps> --skip_species <resname> --dir <x, y, z> --n_steps <start frame> <end frame> --min_window <min. time window>

LAMMPS:

mdt --lam --msd [Parser] --t_steps <time steps> --dir <x, y, z> --n <frame stride> --dump_frame <steps> --min_window <min. time window> --n_steps <start frame> <end frame>

COM-based MSD for Selected Groups

GROMACS:

mdt --gro --msd [Parser] --t_steps <time steps> --min_window <min. time window> --dir <x, y, z> --msd_mode com --msd_species resname <resname> type <atom type> <atom type> --n_steps <start frame> <end frame>

LAMMPS:

mdt --lam --msd [Parser] --dump_frame <steps> --t_steps <time steps> --n <frame stride> --dir <x, y, z> --n_steps <start frame> <end frame> --min_window <min. time window> --msd_mode com --msd_species resname <resname> type 1 2

Atom-based MSD for Selected Atoms

GROMACS:

mdt --gro --msd [Parser] --t_steps <time steps> --min_window <min. time window> --dir <x, y, z> --msd_mode atom --msd_species resname <resname> type <atom type> --n_steps <start frame> <end frame>

LAMMPS:

mdt --lam --msd [Parser] --dump_frame <steps> --t_steps <time steps> --n <frame stride> --dir <x, y, z> --n_steps <start frame> <end frame> --min_window <min. time window> --msd_mode atom --msd_species resname <resname> type <atom type>

---

2. Conductivity & Transport Analysis

Nernst-Einstein Conductivity (--ne)

GROMACS:

mdt --gro --ne [Parser] --t_steps <time steps> --skip_species <resname> --temp <temperature> --n_steps <start frame> <end frame> --min_window <min. time window>

LAMMPS:

mdt --lam --ne [Parser] --t_steps <time steps> --dump_frame <steps> --n <frame stride> --temp <temperature> --n_steps <start frame> <end frame> --min_window <min. time window>

Einstein Conductivity Using Einstein-Helfand (--en)

GROMACS:

mdt --gro --en [Parser] --t_steps <time steps> --t_window <time window for slope> --n_steps <start frame> <end frame> --temp <temperature>

LAMMPS:

mdt --lam --en [Parser] --t_steps <time steps> --dump_frame <steps> --t_window <time window for slope> --n <frame stride> --n_steps <start frame> <end frame> --temp <temperature>

Onsager Transport Coefficients (--onsg)

GROMACS:

mdt --gro --onsg [Parser] --t_steps <time steps> --t_window <time window for slope> --temp <temperature> --n_steps <start frame> <end frame> --n_delta <window>

LAMMPS:

mdt --lam --onsg [Parser] --t_steps <time steps> --dump_frame <steps> --temp <temperature> --n <frame stride> --t_window <time window for slope> --n_steps <start frame> <end frame> --n_delta <window>

Ionic Conductivity Using Stefan-Maxwell Diffusivity (--smd)

GROMACS:

mdt --gro --smd [Parser] --t_steps <time steps> --temp <temperature> --n_steps <start frame> <end frame> --min_window <min. time window>

LAMMPS:

mdt --lam --smd [Parser] --t_steps <time steps> --dump_frame <steps> --n <frame stride> --temp <temperature> --n_steps <start frame> <end frame> --min_window <min. time window>

Transport Mechanism of Species (--veh)

GROMACS:

mdt --gro --veh [Parser] --t_steps <time steps> --min_window <min. time window> --rcut <first solvation> --temp <temperature> --steps <time origin steps> --n_steps <start frame> <end frame> --resname <reference species> <target species>

LAMMPS:

mdt --lam --veh [Parser] --t_steps <time steps> --dump_frame <steps> --min_window <min. time window> --n <frame stride> --n_steps <start> <end> --temp <temperature> --rcut <first solvation> --steps <time origin steps> --resname <reference species> <target species>

---

3. Correlations & Structure

Ion-Ion Correlations (--corr)

GROMACS:

mdt --gro --corr [Parser] --t_steps <time steps> --n_delta <window for time origin shifting> --temp <temperature> --n_steps <start frame> <end frame> --t_window <time window for slope>

LAMMPS:

mdt --lam --corr [Parser] --t_steps <time steps> --dump_frame <steps> --n_delta <window for time origin shifting> --n <frame stride> --n_steps <start frame> <end frame> --temp <temperature> --t_window <time window>

Spatial Decomposition Analysis of Ion-Ion Correlations (--spda)

GROMACS:

mdt --gro --spda [Parser] --t_steps <time steps> --n_delta <window for time origin shifting> --temp <temperature> --n_steps <start frame> <end frame> --t_window <time window for slope>

LAMMPS:

mdt --lam --spda [Parser] --t_steps <time steps> --dump_frame <steps> --n_delta <window for time origin shifting> --n <frame stride> --n_steps <start frame> <end frame> --temp <temperature> --t_window <time window>

Radial Distribution Function Calculation (--rdf)

COM-COM RDF:

GROMACS

mdt --gro --rdf [Parser] --t_steps <time steps> --n_steps <start> <end> --steps <time origins> mdt --gro --rdf [Parser] --rdf_mode com com --rdf_pairs resname <res> type <type> <type> resname <res> type <type> <type>

LAMMPS

mdt --lam --rdf [Parser] --n <frame stride> --t_steps <time steps> --n_steps <start> <end> --dump_frame <steps> mdt --lam --rdf [Parser] --rdf_mode com com --rdf_pairs resname <res> type <type> <type> resname <res> type <type> <type>

ATOM-COM RDF:

GROMACS

mdt --gro --rdf [Parser] --rdf_mode atom com --rdf_pairs resname <res> type <type> resname <res> type <type> <type>

LAMMPS

mdt --lam --rdf [Parser] --rdf_mode atom com --rdf_pairs resname <res> type <type> resname <res> type <type> <type>

ATOM-ATOM RDF:

GROMACS

mdt --gro --rdf [Parser] --rdf_mode atom atom --rdf_pairs resname <res> type <type> resname <res> type <type>

LAMMPS

mdt --lam --rdf [Parser] --rdf_mode atom atom --rdf_pairs resname <res> type <type> resname <res> type <type>

Cluster Analysis (--cage_p)

GROMACS:

mdt --gro --cage_p [Parser] --t_steps <time steps> --n_steps <start frame> <end frame> --rcut <first solvation> --resname <reference species> <target species>

LAMMPS:

mdt --lam --cage_p [Parser] --n <frame stride> --dump_frame <steps> --species <resname> <numbers> --rcut <first solvation> --n_steps <start frame> <end frame> --t_steps <time steps> --resname <reference species> <target species>

Cage Correlation Lifetime (--cage)

GROMACS:

mdt --gro --cage [Parser] --ref_species <resname> --cage_species <resname> --n_steps <start frame> <end frame> --t_steps <time steps> --rcut <first solvation> --steps <time origin steps>

LAMMPS:

mdt --lam --cage [Parser] --t_steps <time steps> --dump_frame <steps> --ref_species <resname> --cage_species <resname> --n_steps <start frame> <end frame> --rcut <first solvation> --steps <time origin steps> --n <frame stride>

Pair Correlation Lifetime (--pcl)

GROMACS:

mdt --gro --pcl [Parser] --t_steps <time steps> --n_steps <start frame> <end frame> --steps <time origin steps> --resname <reference species> <target species>

LAMMPS:

mdt --lam --pcl [Parser] --dump_frame <steps> --t_steps <time steps> --species <resname> <numbers> --n <frame stride> --n_steps <start> <end> --steps <time origin steps> --resname <reference species> <target species>