Metadata-Version: 2.4
Name: MDTransport
Version: 1.0.9
Summary: A modular, open-source Python tool for computing transport properties from GROMACS and LAMMPS simulations.
Author-email: "Shah Research Group, Oklahoma State University" <jindal.shah@okstate.edu>
License: GPL-3.0-or-later
Project-URL: Homepage, https://www.shahresearchgroup.org
Project-URL: Source, https://github.com/ShahResearchGroup/MDTransport
Project-URL: Issue Tracker, https://github.com/ShahResearchGroup/MDTransport/issues
Project-URL: Documentation, https://github.com/ShahResearchGroup/MDTransport#readme
Keywords: molecular-dynamics,gromacs,lammps,transport-properties,diffusion,ionic-conductivity,computational-chemistry,materials-science
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.6
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.10
Requires-Dist: tqdm>=4.60
Dynamic: license-file

# MDTransport

[![PyPI version](https://img.shields.io/pypi/v/mdtransport.svg)](https://pypi.org/project/MDTransport/)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/mdtransport.svg)](https://anaconda.org/conda-forge/mdtransport)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

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](#installation-guide)
  - [Prerequisites](#prerequisites)
  - [Package Managers (Recommended)](#installation-via-package-managers)
  - [Build From Source](#build-from-sources)
- [Argument Flags](#argument-flags)
- [Commands Usage](#commands-usage)
  - [MSD and Diffusion Analysis](#1-msd-and-diffusion-analysis)
  - [Conductivity & Transport Analysis](#2-conductivity--transport-analysis)
  - [Correlations & Structure](#3-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:

<details>
<summary><b>Click to view optional installations (MDAnalysis, Chemfiles, Ovito)</b></summary>

* **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

</details>

### 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/akviitm/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:** `[MODE]` in the examples below refers to your chosen file parsing backend:
> * **GROMACS Modes:** `--pdb --traj <pdb file> --itp <itp directory>` OR `--exe <gmx>` OR `--mda` OR `--chem` OR `--ovito` 
> * **LAMMPS Modes:** `--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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --t_steps <time steps> --skip_species <resname> --temp <temperature> --n_steps <start frame> <end frame> --min_window <min. time window>`

**LAMMPS:**

`mdt --lam --ne [MODE] --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 [MODE] --t_steps <time steps> --t_window <time window for slope> --n_steps <start frame> <end frame> --temp <temperature>`

**LAMMPS:**

`mdt --lam --en [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --t_steps <time steps> --temp <temperature> --n_steps <start frame> <end frame> --min_window <min. time window>`

**LAMMPS:**

`mdt --lam --smd [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --t_steps <time steps> --n_steps <start> <end> --steps <time origins>`
`mdt --gro --rdf [MODE] --rdf_mode com com --rdf_pairs resname <res> type <type> <type> resname <res> type <type> <type>`

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

**ATOM-COM RDF:**

# GROMACS
`mdt --gro --rdf [MODE] --rdf_mode atom com --rdf_pairs resname <res> type <type> resname <res> type <type> <type>`

# LAMMPS
`mdt --lam --rdf [MODE] --rdf_mode atom com --rdf_pairs resname <res> type <type> resname <res> type <type> <type>`

**ATOM-ATOM RDF:**

# GROMACS
`mdt --gro --rdf [MODE] --rdf_mode atom atom --rdf_pairs resname <res> type <type> resname <res> type <type>`

# LAMMPS
`mdt --lam --rdf [MODE] --rdf_mode atom atom --rdf_pairs resname <res> type <type> resname <res> type <type>`

#### Cluster Analysis (`--cage_p`)
**GROMACS:**

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

**LAMMPS:**

`mdt --lam --cage_p [MODE] --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 [MODE] --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 [MODE] --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 [MODE] --t_steps <time steps> --n_steps <start frame> <end frame> --steps <time origin steps> --resname <reference species> <target species>`

**LAMMPS:**

`mdt --lam --pcl [MODE] --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>`
