JOSS Review

[mhlbapat]

Hey folks,
I am reviewing your article and package lammpsio for JOSS.

Overall, the idea behind this package is unique and addresses a real need of the LAMMPS molecular simulation community. I like the convenience it provides to the user in reading/writing LAMMPS data files. The documentation is detailed and accessible via GitHub (thank you @Ladme) and the package is easy to install. This package passes the required JOSS checks.

In order to improve this package and to make sure it reaches a broader audience, the implementation aspect of this package needs a little more work. I have 2 big-picture recommendations and a few minor comments:

1. Add a feature to include force field interactions in the LAMMPS data file: Currently the LAMMPS data file created by this package outputs positions, velocities and topology of the system. Without appropriate force field interactions, the created data file itself is of limited scientific use. It is true that the end-user must choose these interactions specific to their system, but there should be an option to prescribe them in the data file for the user to fully exploit the convenience of working in a Python-based environment.
   To implement this, I encourage you to look into moltemplate. You can implement something as simple as writing out user-prescribed pairwise and bonded interaction parameters to the data file. And ideally (but also optionally): have a feature to create a data file with interactions pulled from classical force fields like OPLSAA or GAFF with the task of atom-typing left to the user and to be able to interface with tools like moltemplate/PACKMOL.

2. Add a tutorial showing construction of a system other than dimers: The tutorials on the documentation page are nice and very helpful for a beginner to get started with writing/reading/analyzing LAMMPS data files. For a broader MD audience, it will be interesting to show construction of a more advanced system that contains bonds, angles, dihedrals and impropers, e.g. a polymer chain in TIP4P water. For this bullet point, the force-field feature in 1. (above) will come in handy, in the sense that a seasoned molecular-simulator -- working with lammpsio -- will save a lot of time in getting from a state of creating initial geometry to simulating dynamics for their system.
   Bonus for the user: showing how lammpsio can create data files with pair interactions generated using relentless or how relentless leverages lammpsio-functionalities would be a plus!

Minor comments:

• The LAMMPS data file created using lammpsio places the "Masses" section after the "Atoms" section. While LAMMPS supports flexible section order, many users and tools expect (and LAMMPS itself outputs) a conventional order with header → Masses → coefficient sections → Atoms/Velocities → topology (Bonds, Angles, …). Moving Masses (and any coeff sections) near the top would make quick sanity checks easier.

• I could not find information on whether lammpsio can read LAMMPS binary restart files. It's okay if not supported in the package, but helpful to state this in the documentation.

• Whether you end up interfacing with moltemplate or not, I encourage you to cite it in your article. It's an open-source tool that is useful in creating LAMMPS data files, with similar use-case as lammpsio.

• I could not discern if lammpsio can be used in combination with multiprocessing or numba modules in python, which would be useful in parsing through multiple frames of a Snapshot of large dump file. If not, then please consider adding this feature.

[clpetix]

Hi @mhlbapat, thank you for taking the time to review our package! We appreciate your helpful feedback! Here are our thoughts and plan for moving forward:

1. Add a feature to include force field interactions in the LAMMPS data file: Currently the LAMMPS data file created by this package outputs positions, velocities and topology of the system. Without appropriate force field interactions, the created data file itself is of limited scientific use. It is true that the end-user must choose these interactions specific to their system, but there should be an option to prescribe them in the data file for the user to fully exploit the convenience of working in a Python-based environment.
   To implement this, I encourage you to look into moltemplate. You can implement something as simple as writing out user-prescribed pairwise and bonded interaction parameters to the data file. And ideally (but also optionally): have a feature to create a data file with interactions pulled from classical force fields like OPLSAA or GAFF with the task of atom-typing left to the user and to be able to interface with tools like moltemplate/PACKMOL.

We agree that force field specification is an important aspect of a LAMMPS simulation workflow! However, we feel that managing force field parameters is outside the current intended scope of lammpsio, which is manipulating particle data. Force field parameters are related to particle data through the particle types, but they are not the particle data itself (positions and topology). For this reason, we also respectfully disagree that a LAMMPS data file is of limited use on its own because the force field parameters can be specified independently in the LAMMPS input script. For example, we routinely use lammpsio to generate different initial configurations in order to sweep parameter spaces, and we feed these configurations through the same LAMMPS script that contains the version-of-record for the force field and protocol.

2. Add a tutorial showing construction of a system other than dimers: The tutorials on the documentation page are nice and very helpful for a beginner to get started with writing/reading/analyzing LAMMPS data files. For a broader MD audience, it will be interesting to show construction of a more advanced system that contains bonds, angles, dihedrals and impropers, e.g. a polymer chain in TIP4P water. For this bullet point, the force-field feature in 1. (above) will come in handy, in the sense that a seasoned molecular-simulator -- working with lammpsio -- will save a lot of time in getting from a state of creating initial geometry to simulating dynamics for their system.

We agree that including a tutorial demonstrating a more complex system would help users better understand ways to use lammpsio. We will add a tutorial that constructs an initial configuration of an ethanol-water mixture, which will highlight angles and dihedrals as well interfacing with packmol.

Bonus for the user: showing how lammpsio can create data files with pair interactions generated using relentless or how relentless leverages lammpsio-functionalities would be a plus!

relentless uses lammpsio to convert files in the background without explicit user involvement, so it is unfortunately not possible to show this in a tutorial.

Minor comments:

• The LAMMPS data file created using lammpsio places the "Masses" section after the "Atoms" section. While LAMMPS supports flexible section order, many users and tools expect (and LAMMPS itself outputs) a conventional order with header → Masses → coefficient sections → Atoms/Velocities → topology (Bonds, Angles, …). Moving Masses (and any coeff sections) near the top would make quick sanity checks easier.

No problem, we will move the Masses section to come after the header section for consistency with LAMMPS.

• I could not find information on whether lammpsio can read LAMMPS binary restart files. It's okay if not supported in the package, but helpful to state this in the documentation.

Reading LAMMPS binary files is not currently supported. The home page of the documentation states lammpsio can read and write data and dump files, and these are the only formats included in the File formats section of the API documentation. Please note that there are several file formats LAMMPS can write, in addition to restart files, that lammpsio cannot currently read. To make it easier to maintain our documentation somewhat independently of LAMMPS development, we prefer to explicitly document only the formats lammpsio does support. We have, however, noted that supporting additional file formats is an area of future work in the manuscript.

• Whether you end up interfacing with moltemplate or not, I encourage you to cite it in your article. It's an open-source tool that is useful in creating LAMMPS data files, with similar use-case as lammpsio.

We agree and will include a citation to moltemplate as a related tool!

• I could not discern if lammpsio can be used in combination with multiprocessing or numba modules in python, which would be useful in parsing through multiple frames of a Snapshot of large dump file. If not, then please consider adding this feature.

Snapshots are read from the DumpFile using an iterator, so we believe it should be possible to multiprocess snapshots. Further, the particle data in the Snapshot is stored in NumPy arrays, so we believe the data in a snapshot should be compatible with numba if desired. We will test to confirm this and, if successful, include a short example demonstrating these capabilities.

[clpetix]

These are the tasks required to complete the requested work:

• Add a tutorial showing ethanol-water system.
  • @clpetix assigned this task.
  • PR Add tutorial for initializing an ethanol-water.  #97
• Move the Masses section to come after the header section for consistency with LAMMPS.
  • @clpetix assigned this task.
  • PR [JOSS] Reorder DataFile.  #96
• Update paper to mention binary restart files and moltemplate.
  • @mphoward assigned this task.
  • Completed in bdce48e
• Add tutorial showing how to speed things up with numba and multiprocessing.
  • @mayukh33 assigned this task.
  • PR Numba tutorial #95

[mhlbapat]

Thank you @clpetix for your thoughtful and precise responses! I am glad I was of some help. Looking forward to the ethanol-water system and numba tutorials!

[clpetix]

Hi @mhlbapat, we've updated the manuscript and code as outlined above.

Thank you for your helpful suggestions! They made for some really nice additions to the package! Please have a look and let us know what you think.

[mhlbapat]

Looks good to me. I like the ethanol+water and numba tutorials. Can you please also update them in your documentation page? As far as the JOSS review is concerned, I would consider this issue to be closed.

[mphoward]

Thanks! They should already be linked into the docs if you check the latest build:

https://lammpsio.readthedocs.io/en/latest/tutorials.html

They will become part of the default stable docs on the next tagged release.