Skip to content

Latest commit

 

History

History
117 lines (98 loc) · 6.6 KB

README.md

File metadata and controls

117 lines (98 loc) · 6.6 KB
Raw

htp_md

htp_md is the analysis module in a suite of tools (UI) that streamlines the process of analyzing, storing, visualizing, and predicting properties based on raw trajectory data, in support of research by polymers program at Massachusetts Institute of Technology and the Toyota Research Institute.

htp_md extracts the following properties from raw trajectory data:

  • SMILES (input metadata)
  • Simulation length (input metadata)
  • Ionic Conductivity
  • Diffusion Coefficient (ions and polymer chains)
  • Molality
  • Transference Number
  • Structure (CIF)
  • Mean Squared Displacement (MSD) time series of ions

Getting Started

Dependencies

Dependencies are found in requirements.txt. This is for reference only; the dependencies will be installed automatically as part of the installation process.

Installation

  1. Clone the repo and install
git clone git@github.com:TRI-AMDD/htp_md.git
  1. Install htpmd. As of now python's setuptools use of easy_install has problems installing subpackages of torch, such as torch_sparse. Hence, the installation is a pip install followed by a regular setup.py install
pip install -e .
python setup.py install
  1. To run optional unit tests to ensure that installation is successful, install tests dependencies and run pytest:
pip install -e .[tests]
python -m pytest

Test Data

We package some data which can be used for testing purposes. This data can be found in ./test_data/, including several datasets:

  • nacl_water: a trajectory of a 1m aqueous NaCl electrolyte at 350 K. The system is composed of 222 water molecules and 20 ion pairs. The trajectory is 2 ns long, with 201 snapshots. The interatomic potential used is the SPC/E model for water, with standard Joung-Cheatham parameters for the ions. All parameters are reported in 10.1021/jp902584c.
  • 9-0-246295613-0: a small fraction from a trajectory of polymer electrolytes with LiTFSI at 353 K. The trajectory is 14 ps long, with 7 snapsshots. The interatomic potential used is PCFF+, with the charge distribution of TFSI- adjusted. Details for the simualtion can be found in 10.1038/s41467-022-30994-1.
  • 9-0-413610210-0: a small fraction from a trajectory of polymer electrolytes with LiTFSI at 353 K. The trajectory is 14 ps long, with 8 snapsshots. The interatomic potential used is PCFF+, with the charge distribution of TFSI- adjusted. Details for the simualtion can be found in 10.1038/s41467-022-30994-1.

Example protocol for relaxation/equilibration

We have included an example LAMMPS input file in the example_for_relaxation_equilibration folder for relaxing and equilibrating the polymer systems that should be performed before the production run simulation step. The goal of relaxation and equilibration simulation is to achieve a more favorable energy-minimized state and a density close to the theoretical density, which helps to obtain more accurate computed ion transport properties during the production run step. Other files, including an example polymer data file, meta.json, and a submit file, are included in this folder, and users can use these files as a guide. The example data file in this folder has been generated by MedeA Software with the PCFF+ interatomic potential. In addition, the LAMMPS input file for the production run simulations is available in the test_data folder as well as https://www.htpmd.matr.io/.

Using htpmd

To analyze trajectory data using the htpmd api:

import htpmd
results = htpmd.analyze('test_data/9-0-246295613-0')
print(results.keys())

To use htpmd as an installed command line utility, run:

htpmd <action> [-d <dir_path>]

External software used in HTPMD

The dump module from the pizza.py toolkit ((https://github.com/lammps/pizza) has been added to the code and used to compute the ion cluster population matrix.

""" Pizza.py toolkit, www.cs.sandia.gov/~sjplimp/pizza.html Steve Plimpton, sjplimp@sandia.gov, Sandia National Laboratories

Copyright (2005) Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain rights in this software. This software is distributed under the GNU General Public License. """

Please note that some modifications were applied to the dump tool in Pizza toolkit to run in Python 3.

How to contribute

User contributions for new analysis functions and data are greatly appreciated.

Contributing a new analysis function

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

When contributing a new function, please follow the template. Each Pull Request for a new function should contain the following:

  • function.py, following template guidelines
  • test_function.py, following template guidelines
  • Test data and expected outcome

Contributing a new trajectory

Contact the HTP team at Toyota Research Institute (em-htp@tri.global) with your name, affiliation, and a description of your data. Any contributed data should be reproducible and are required to include the following:

  • Metadata.json, which contains the description of the system, such as SMILES string for monomer and polymer, force field used, material group (polymer), temperature, time step, and cation and anion information (name and atom type), as well as polymer information (range of atom types)
  • relaxed.lmp, which contains the starting configuration for LAMMPS production run, in the LAMMPS data file format (https://docs.lammps.org/2001/data_format.html)
  • in.lmp, which contains input information for running LAMMPS, in the LAMMPS input script format (https://docs.lammps.org/Commands_input.html)

Authors

Toyota Research Institute

  • Ha-Kyung Kwon
  • Daniel Schweigert
  • Arash Khajeh

Massachusetts Institute of Technology

  • Tian Xie
  • Arthur France-Lanord
  • Emily Crabb
  • Sheng Gong

How to Cite

If you use htp_md, please cite the following:

@article{xie2022cloud,
  title={A cloud platform for automating and sharing analysis of raw simulation data from high throughput polymer molecular dynamics simulations},
  author={Xie, Tian and Kwon, Ha-Kyung and Schweigert, Daniel and Gong, Sheng and France-Lanord, Arthur and Khajeh, Arash and Crabb, Emily and Puzon, Michael and Fajardo, Chris and Powelson, Will and others},
  journal={arXiv preprint arXiv:2208.01692},
  year={2022}
}