diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml new file mode 100644 index 00000000..9dae1d0c --- /dev/null +++ b/.github/workflows/draft-pdf.yml @@ -0,0 +1,36 @@ +on: + push: + # Action will run when any changes to these paths are pushed or pr'ed to master + branches: [ joss ] + paths: + - paper/** + - .github/workflows/draft-pdf.yml + pull_request: + branches: [ joss ] + paths: + - paper/** + - .github/workflows/draft-pdf.yml + # Allows workflow to be manually triggered + workflow_dispatch: + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: paper/paper.md + - name: Upload + uses: actions/upload-artifact@v1 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: paper/paper.pdf diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 00000000..b6b6f0d3 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,259 @@ + +@article{radonpy_2022, + title = {{RadonPy}: automated physical property calculation using all-atom classical molecular dynamics simulations for polymer informatics}, + volume = {8}, + issn = {2057-3960}, + url = {https://www.nature.com/articles/s41524-022-00906-4}, + doi = {10.1038/s41524-022-00906-4}, + shorttitle = {{RadonPy}}, + pages = {222}, + number = {1}, + journaltitle = {npj Computational Materials}, + shortjournal = {npj Comput Mater}, + author = {Hayashi, Yoshihiro and Shiomi, Junichiro and Morikawa, Junko and Yoshida, Ryo}, + urldate = {2023-09-26}, + date = {2022-11-08}, + langid = {english}, +} + +@article{TRUE_2020, + title = {Towards molecular simulations that are transparent, reproducible, usable by others, and extensible ({TRUE})}, + volume = {118}, + issn = {0026-8976, 1362-3028}, + url = {https://www.tandfonline.com/doi/full/10.1080/00268976.2020.1742938}, + doi = {10.1080/00268976.2020.1742938}, + pages = {e1742938}, + number = {9}, + journaltitle = {Molecular Physics}, + shortjournal = {Molecular Physics}, + author = {Thompson, Matthew W. and Gilmer, Justin B. and Matsumoto, Ray A. and Quach, Co D. and Shamaprasad, Parashara and Yang, Alexander H. and Iacovella, Christopher R. and {McCabe}, Clare and Cummings, Peter T.}, + urldate = {2023-09-27}, + date = {2020-06-01}, + langid = {english}, +} + +@article{biosimspace_2019, + title = {{BioSimSpace}: An interoperable Python framework for biomolecular simulation}, + volume = {4}, + issn = {2475-9066}, + url = {https://joss.theoj.org/papers/10.21105/joss.01831}, + doi = {10.21105/joss.01831}, + shorttitle = {{BioSimSpace}}, + pages = {1831}, + number = {43}, + journaltitle = {Journal of Open Source Software}, + shortjournal = {{JOSS}}, + author = {Hedges, Lester and Mey, Antonia and Laughton, Charles and Gervasio, Francesco and Mulholland, Adrian and Woods, Christopher and Michel, Julien}, + urldate = {2023-09-27}, + date = {2019-11-22}, + langid = {english}, +} + +@article{shirts_statistically_2008, + title = {Statistically optimal analysis of samples from multiple equilibrium states}, + volume = {129}, + issn = {0021-9606, 1089-7690}, + url = {https://pubs.aip.org/jcp/article/129/12/124105/957527/Statistically-optimal-analysis-of-samples-from}, + doi = {10.1063/1.2978177}, + pages = {124105}, + number = {12}, + journaltitle = {The Journal of Chemical Physics}, + author = {Shirts, Michael R. and Chodera, John D.}, + urldate = {2023-10-02}, + date = {2008-09-28}, + langid = {english}, +} + +@article{chodera_2007, + title = {Use of the Weighted Histogram Analysis Method for the Analysis of Simulated and Parallel Tempering Simulations}, + volume = {3}, + issn = {1549-9618, 1549-9626}, + url = {https://pubs.acs.org/doi/10.1021/ct0502864}, + doi = {10.1021/ct0502864}, + pages = {26--41}, + number = {1}, + journaltitle = {Journal of Chemical Theory and Computation}, + shortjournal = {J. Chem. Theory Comput.}, + author = {Chodera, John D. and Swope, William C. and Pitera, Jed W. and Seok, Chaok and Dill, Ken A.}, + urldate = {2023-10-02}, + date = {2007-01-01}, + langid = {english}, +} + +@misc{hoomd_2019, + title = {{HOOMD}-blue: A Python package for high-performance molecular dynamics and hard particle Monte Carlo simulations}, + url = {http://arxiv.org/abs/1308.5587}, + shorttitle = {{HOOMD}-blue}, + number = {{arXiv}:1308.5587}, + publisher = {{arXiv}}, + author = {Anderson, Joshua A. and Glaser, Jens and Glotzer, Sharon C.}, + urldate = {2023-10-03}, + date = {2019-10-18}, + langid = {english}, + eprinttype = {arxiv}, + eprint = {1308.5587 [physics]}, + keywords = {Physics - Computational Physics}, +} + +@article{polyply_2022, + title = {Polyply; a python suite for facilitating simulations of macromolecules and nanomaterials}, + volume = {13}, + issn = {2041-1723}, + url = {https://www.nature.com/articles/s41467-021-27627-4}, + doi = {10.1038/s41467-021-27627-4}, + pages = {68}, + number = {1}, + journaltitle = {Nature Communications}, + shortjournal = {Nat Commun}, + author = {Grünewald, Fabian and Alessandri, Riccardo and Kroon, Peter C. and Monticelli, Luca and Souza, Paulo C. T. and Marrink, Siewert J.}, + urldate = {2023-10-03}, + date = {2022-01-10}, + langid = {english}, +} +@article{eastman2017openmm, + title={OpenMM 7: Rapid development of high performance algorithms for molecular dynamics}, + author={Eastman, Peter and Swails, Jason and Chodera, John D and McGibbon, Robert T and Zhao, Yutong and Beauchamp, Kyle A and Wang, Lee-Ping and Simmonett, Andrew C and Harrigan, Matthew P and Stern, Chaya D and others}, + journal={PLoS computational biology}, + volume={13}, + number={7}, + pages={e1005659}, + year={2017}, + publisher={Public Library of Science San Francisco, CA USA} +} + +@article{Santana-Bonilla_2023, + title = {Modular Software for Generating and Modeling Diverse Polymer Databases}, + volume = {63}, + issn = {1549-9596, 1549-960X}, + url = {https://pubs.acs.org/doi/10.1021/acs.jcim.3c00081}, + doi = {10.1021/acs.jcim.3c00081}, + pages = {3761--3771}, + number = {12}, + journaltitle = {Journal of Chemical Information and Modeling}, + shortjournal = {J. Chem. Inf. Model.}, + author = {Santana-Bonilla, Alejandro and López-Ríos De Castro, Raquel and Sun, Peike and Ziolek, Robert M. and Lorenz, Christian D.}, + urldate = {2023-10-03}, + date = {2023-06-26}, + langid = {english}, +} +@article{martin2018pyprism, + title={pyPRISM: a computational tool for liquid-state theory calculations of macromolecular materials}, + author={Martin, Tyler B and Gartner III, Thomas E and Jones, Ronald L and Snyder, Chad R and Jayaraman, Arthi}, + journal={Macromolecules}, + volume={51}, + number={8}, + pages={2906--2922}, + year={2018}, + publisher={ACS Publications} +} + +@Inbook{Klein2016mBuild, + author = "Klein, Christoph and Sallai, János and Jones, Trevor J. and Iacovella, Christopher R. and McCabe, Clare and Cummings, Peter T.", + editor = "Snurr, Randall Q and Adjiman, Claire S. and Kofke, David A.", + title = "A Hierarchical, Component Based Approach to Screening Properties of Soft Matter", + bookTitle = "Foundations of Molecular Modeling and Simulation: Select Papers from FOMMS 2015", + year = "2016", + publisher = "Springer Singapore", + address = "Singapore", + pages = "79--92", + isbn = "978-981-10-1128-3", + doi = "10.1007/978-981-10-1128-3_5", + url = "https://doi.org/10.1007/978-981-10-1128-3_5" +} + +@article{lammps_2022, + title = {{LAMMPS} - a flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales}, + volume = {271}, + issn = {00104655}, + url = {https://linkinghub.elsevier.com/retrieve/pii/S0010465521002836}, + doi = {10.1016/j.cpc.2021.108171}, + pages = {108171}, + journaltitle = {Computer Physics Communications}, + shortjournal = {Computer Physics Communications}, + author = {Thompson, Aidan P. and Aktulga, H. Metin and Berger, Richard and Bolintineanu, Dan S. and Brown, W. Michael and Crozier, Paul S. and In 'T Veld, Pieter J. and Kohlmeyer, Axel and Moore, Stan G. and Nguyen, Trung Dac and Shan, Ray and Stevens, Mark J. and Tranchida, Julien and Trott, Christian and Plimpton, Steven J.}, + urldate = {2023-10-05}, + date = {2022-02}, + langid = {english}, +} + +@software{gmso, + author = {mosdef-hub, Vanderbilt University}, + title = {{GMSO: General Molecular Simulation Object}}, + url = {https://gmso.mosdef.org/en/stable/}, + version = {0.11.2}, + year = {2023}, + publisher = {GitHub}, +} + +@software{parmed, + author = {Swails, Jason and Hernandez, Carlos and Mobley, David L. and Nguyen, Hai and Wang, Lee-Ping and Janowski, Pawel}, + title = {{ParmED: Cross-program parameter and topology file editor and molecular mechanical simulator engine}}, + url = {https://github.com/ParmEd/ParmEd}, + version = {4.1.0}, + year = {2014}, + publisher = {GitHub}, +} +@article{aggarwal_molecular_2020, + title = {Molecular dynamics studies on the strength and ductility of symmetric thermally welded joints}, + issn = {0965-0393, 1361-651X}, + url = {https://iopscience.iop.org/article/10.1088/1361-651X/ab6a44}, + doi = {10.1088/1361-651X/ab6a44}, + journaltitle = {Modelling and Simulation in Materials Science and Engineering}, + shortjournal = {Modelling Simul. Mater. Sci. Eng.}, + author = {Aggarwal, Ishu and Paul, Saptarshi and Sinha, Nishant K and Basu, Sumit}, + urldate = {2023-08-09}, + date = {2020-01-10}, + langid = {english}, +} + +@article{bukowski_load-bearing_2021, + title = {Load-bearing entanglements in polymer glasses}, + volume = {7}, + issn = {2375-2548}, + url = {https://www.science.org/doi/10.1126/sciadv.abg9763}, + doi = {10.1126/sciadv.abg9763}, + pages = {eabg9763}, + number = {38}, + journaltitle = {Science Advances}, + shortjournal = {Sci. Adv.}, + author = {Bukowski, Cynthia and Zhang, Tianren and Riggleman, Robert A. and Crosby, Alfred J.}, + urldate = {2023-10-06}, + date = {2021-09-17}, + langid = {english}, +} + +@article{fan_wetting_1995, + title = {Wetting of crystalline polymer surfaces: A molecular dynamics simulation}, + volume = {103}, + issn = {0021-9606, 1089-7690}, + url = {https://pubs.aip.org/jcp/article/103/20/9053/179676/Wetting-of-crystalline-polymer-surfaces-A}, + doi = {10.1063/1.470016}, + shorttitle = {Wetting of crystalline polymer surfaces}, + abstract = {Molecular dynamics has been used to study the wetting of model polymer surfaces, the crystal surfaces of polyethylene ({PE}), poly(tetrafluoroethylene) ({PTFE}), and poly(ethylene terephthalate) ({PET}) by water and methylene iodide. In the simulation a liquid droplet is placed on a model surface and constant temperature, rigid body molecular dynamics is carried out while the model surface is kept fixed. A generally defined microscopic contact angle between a liquid droplet and a solid surface is quantitatively calculated from the volume of the droplet and the interfacial area between the droplet and the surface. The simulation results agree with the trend in experimental data for both water and methylene iodide. The shape of the droplets on the surface is analyzed and no obvious anisotropy of the droplets is seen in the surface plane, even though the crystal surfaces are highly oriented. The surface free energies of the model polymer surfaces are estimated from their contact angles with the two different liquid droplets.}, + pages = {9053--9061}, + number = {20}, + journaltitle = {The Journal of Chemical Physics}, + author = {Fan, Cun Feng and Caǧin, Tahir}, + urldate = {2023-10-06}, + date = {1995-11-22}, + langid = {english}, + file = {Accepted Version:/home/marjan/Zotero/storage/X8LJLYKB/Fan and Caǧin - 1995 - Wetting of crystalline polymer surfaces A molecul.pdf:application/pdf}, +} + +@article{bamane_wetting_2021, + title = {Wetting Simulations of High-Performance Polymer Resins on Carbon Surfaces as a Function of Temperature Using Molecular Dynamics}, + volume = {13}, + issn = {2073-4360}, + url = {https://www.mdpi.com/2073-4360/13/13/2162}, + doi = {10.3390/polym13132162}, + abstract = {Resin/reinforcement wetting is a key parameter in the manufacturing of carbon nanotube ({CNT})-based composite materials. Determining the contact angle between combinations of liquid resin and reinforcement surfaces is a common method for quantifying wettability. As experimental measurement of contact angle can be difficult when screening multiple high-performance resins with {CNT} materials such as {CNT} bundles or yarns, computational approaches are necessary to facilitate {CNT} composite material design. A molecular dynamics simulation method is developed to predict the contact angle of high-performance polymer resins on {CNT} surfaces dominated by aromatic carbon, aliphatic carbon, or a mixture thereof (amorphous carbon). Several resin systems are simulated and compared. The results indicate that the monomer chain length, chemical groups on the monomer, and simulation temperature have a significant impact on the predicted contact angle values on the {CNT} surface. Difunctional epoxy and cyanate ester resins show the overall highest levels of wettability, regardless of the aromatic/aliphatic nature of the {CNT} material surface. Tetrafunctional epoxy demonstrates excellent wettability on aliphatic-dominated surfaces at elevated temperatures. Bismaleimide and benzoxazine resins show intermediate levels of wetting, while typical molecular weights of polyether ether ketone demonstrate poor wetting on the {CNT} surfaces.}, + pages = {2162}, + number = {13}, + journaltitle = {Polymers}, + shortjournal = {Polymers}, + author = {Bamane, Swapnil S. and Gaikwad, Prashik S. and Radue, Matthew S. and Gowtham, S. and Odegard, Gregory M.}, + urldate = {2023-10-06}, + date = {2021-06-30}, + langid = {english}, + file = {Bamane et al. - 2021 - Wetting Simulations of High-Performance Polymer Re.pdf:/home/marjan/Zotero/storage/JPFTYNU9/Bamane et al. - 2021 - Wetting Simulations of High-Performance Polymer Re.pdf:application/pdf}, +} diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 00000000..1cdac499 --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,162 @@ +--- +title: 'FlowerMD: Flexible Library of Organic Workflows and Extensible Recipes for Molecular Dynamics' +tags: + - molecular simulation + - materials science + - molecular dynamics + - polymers + - HOOMD-blue +authors: + - name: Chris Jones + orcid: 0000-0002-6196-5274 + equal-contrib: true + affiliation: 1 + - name: Marjan Albooyeh + orcid: 0009-0001-9565-3076 + equal-contrib: true + affiliation: 1 + - name: Rainier Barrett + orcid: 0000-0002-5728-9074 + equal-contrib: false + affiliation: 1 + - name: Eric Jankowski + orcid: 0000-0002-3267-1410 + corresponding: true + affiliation: 1 +affiliations: + - name: Boise State University, Boise, ID, USA + index: 1 +date: 01 January 2001 +bibliography: paper.bib +--- +# Summary +`flowerMD` is a package for reproducibly performing multi-stage HOOMD-blue [@hoomd_2019] +simulation workflows. It enables the programmatic specification of tasks including +definition of molecular structures, forcefield definition and application and chaining +together simulation stages (e.g., shrinking, equilibration, simulating a sequence +of ensembles, tensile testing, etc.) through an extensible set of Python classes. +The modular design supports a library of workflows for organic +macrmolecular and polymer simulations. Tutorials are provided to demonstrate +package features and flexibility. + + +# Statement of need + +High-level programmatic specifications of molecular simulation workflows are +needed for two reasons. First, they provide the information necessary for a +simulation study to be reproduced, and second, they help lower the cognitive +load associated with learning and performing simulations in general. +Reproducible simulations benefit the research community by enabling studies +to be validated and extended. +Lowering the cognitive load of performing molecular simulations helps +computational researchers of all levels of expertise reason about the logic +of a simulation study. This is particularly important for researchers new to +the discipline becuase developing the tools needed to perform experiments often +involves: (a) gaining new software development skills and knowledge, and +(b) repeating work that others have already performed. + + +Recent advances in open-source tools have made the programmatic specification of +molecular simulation components easier than ever +[@hoomd_2019; @lammps_2022; @eastman2017openmm; @Klein2016mBuild; @gmso; @parmed; +@Santana-Bonilla_2023; @polyply_2022; @biosimspace_2019; @martin2018pyprism]. +Individually, each of these tools lower the cognitive load of one aspect of an +overall workflow such as representing molecules, building initial structures, +parameterizing and applying a forcefield, and running simulations. +However, stitching these pieces together to create a complete workflow presents +a need that we address in the present work. + +The computational researcher who follows best practices for accurate, +accessible and reproducible results may create a programmatic layer over these +individual software packages (i.e. wrapper) that serves to consolidate and +automate a complete workflow. However, these efforts often use a bespoke approach +where the entire workflow design is tailored toward the specific question or +project. Design choices might include the materials studied, the model used +(e.g. atomistic or coarse-grained), the source of the forcefield in the model, and +the simulation protocols followed. As a result, this wrapper is likely unusable +for the next project where one of the aforementioned choices changes, and the +process of designing a workflow must begin again from scratch. + +Software packages such as Radonpy [@radonpy_2022] exist that provide an automated +workflow for building molecules and bulk structures to calculating physical +properties of polymers. However, these tools may not be suitable for modeling complex +experimental processes that extend beyond measuring material properties, such as +simulating fusion welding of polymer interfaces +[@aggarwal_molecular_2020; @bukowski_load-bearing_2021] and surface wetting +[@fan_wetting_1995; @bamane_wetting_2021]. + +`flowerMD` is a Python package that consolidates and automates +end-to-end workflows for modeling such engineering processes with a focus on organic +molecules. Following the principals of Transparent, Reproducible, Usable by others, +and Extensible (TRUE) [@TRUE_2020] software design, the modular design of `flowerMD` +facilitates building and running workflows for specific materials science research +applications, while reducing the cognitive load and programming demands on the user's part. + +# Building Blocks +`flowerMD` is extensible. Modular base classes serve as building blocks that lay the +foundation for constructing workflow recipes designed for specific applications. +The resultant recipes are agnostic to choices such as chemistry, model resolution +(e.g. atomistic vs. coarse grained) and forcefield selection. +This is accomplished via three base classes: + +• The `Molecule` class utilizes the mBuild [@Klein2016mBuild] and GMSO [@gmso] packages to initialize chemical +structures from a variety of input formats. This class provides methods +for building polymers and copolymer structures, and supports a straightforward +coarse-graining process by leveraging SMARTS matching. + +• The `System` class serves as an intermediary between molecular initialization +and simulation setup. This class builds the initial configuration and +applies a chosen forcefield that defines particle interactions. + +• The `Simulation` class adds a layer on top of the HOOMD-blue simulation object, +adding additional methods and features to simplify the process of starting and +resuming a HOOMD-blue simulation. + +Additionally, `flowerMD` offers a library pre-defined subclasses of these base classes +including common polymers, forcefields, and bulk system initialization algorithms. + +# Recipes +`flowerMD` offers the following two ready-to-go recipes to illustrate how the design creates +potential for expanding the library of open-source and version-controlled workflows. The example code included in this repository demonstrates how the modularity of `flowerMD` +allows use and re-use of workflows, using pre-built "recipe steps" (subclasses) included in +the repository: +`flowerMD.modules.welding.SlabSimulation`, `flowerMD.modules.welding.Interface`, `flowerMD.modules.welding.WeldSimulation`, +and `flowerMD.library.simulations.Tensile`. + +We can use these four blocks to build the following recipe: +1. `SlabSimulation` creates two "slabs" of e.g. polyethylene +2. `Interface` joins two resultant slabs at an interface +3. `WeldSimulation` simulates thermal welding at this interface, and +4. `Tensile` simulates a tensile test of the resultant weld to create a stress/strain curve. + +Note that each of these steps can be run independently, and each simulation +type is agnostic to system and force field selection, enabling easy iteration with different +materials, force fields, etc. without replicating the workflow code itself. One example might be that we could instead run `SlabSimulation` on two different bulk polymers, then reuse the rest of the recipe unchanged. We could also iterate over new weld temperatures pending results of `Tensile` runs, etc. + +This flexibility and ease of iteration is the core design principle of flowerMD, and enables +both new and experienced researchers to more quickly begin the process of scientific inquiry +via molecular dynamics simulations. +We encourage molecular simulation practitioners of all levels of expertise to file issues +and submit pull requests to extend `flowerMD`'s utility. + +# Availability +`flowerMD` is freely available under the GNU General Public License (version 3) +on [github](https://github.com/cmelab/flowerMD). For installation instructions, +and Python API documentation +please visit the [documentation](https://flowermd.readthedocs.io/en/latest/). +For examples of how to use `flowerMD`, +please visit the [tutorials](https://github.com/cmelab/flowerMD/tree/main/tutorials) + +# Acknowledgements +This research was partially supported by the National Aeronautics and Space +Administration (NASA) under the University Leadership Initiative program; +grant number 80NSSC20M0165. +This material is based upon work supported by the National Science Foundation +under Grant Numbers: 1653954, 1835593, and 2118217. +No sponsor had any involvement in the development of `flowerMD`. + +# Conflict of Interest Statement +The authors declare the absence of any conflicts of interest: No author has any financial, +personal, professional, or other relationship that affect our objectivity toward this work. + +# References