[REVIEW]: FHI-vibes: Ab initio Vibrational Simulations

[whedon]

Submitting author: @flokno (Florian Knoop)
Repository: https://gitlab.com/vibes-developers/vibes
Version: v1.0.2
Editor: @jgostick
Reviewers: @keipertk, @ajjackson
Archive: 10.5281/zenodo.4300415

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/54c29a971700c09ff80b82f47429a36d"><img src="https://joss.theoj.org/papers/54c29a971700c09ff80b82f47429a36d/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/54c29a971700c09ff80b82f47429a36d/status.svg)](https://joss.theoj.org/papers/54c29a971700c09ff80b82f47429a36d)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@keipertk, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @jgostick know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Review checklist for @keipertk

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@flokno) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

---

Review checklist for @ajjackson

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@flokno) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @keipertk it looks like you're currently assigned to review this paper 🎉.

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1088/1361-648X/aa680e is OK
- 10.1016/j.scriptamat.2015.07.021 is OK
- 10.1103/PhysRevB.91.094306 is OK
- 10.1016/j.cpc.2009.06.022 is OK
- 10.1016/j.cpc.2018.09.020 is OK
- 10.5334/jors.148 is OK
- 10.1109/MCSE.2011.37 is OK
- 10.1002/cpe.3505 is OK
- 10.1038/nmat3568 is OK
- 10.1103/PhysRevLett.78.4063 is OK
- 10.1103/PhysRevLett.118.175901 is OK
- 10.1002/adts.201800184 is OK
- 10.1002/anie.201812112 is OK
- 10.1021/acs.jpcc.5b11115 is OK
- 10.1038/nmat2090 is OK
- 10.1016/j.jeurceramsoc.2007.12.023 is OK
- 10.1103/PhysRevLett.96.115504 is OK
- 10.1103/physrevb.79.064301 is OK
- 10.1557/mrs.2018.208 is OK

MISSING DOIs

- 10.1103/physrevmaterials.4.083809 may be a valid DOI for title: Anharmonicity Measure for Materials
- 10.1038/s41597-020-00638-4 may be a valid DOI for title: AiiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance

INVALID DOIs

- None

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[keipertk]

I was unable to find community guidleines for third parties wishing to contribute to the software, outside of the standard MIT license agreement. Everything else gets a check.

[jgostick]

@keipertk Thanks for this! So fast too! I still haven't even found a second reviewer yet!

[flokno]

@jgostick in case you don't find a second reviewer: I talked to [at]ajjackson at some earlier point and he was interested to review this.

@keipertk thanks for the feedback. Indeed we didn't formally include contribution guidelines, we'll add them.

[jgostick]

Thanks @flokno I will ask them.

Hi @ajjackson, your name has been suggested as a reviewer for this submission by @flokno. I am in need of a second reviewer, so your time would be much appreciated.

[ajjackson]

Hi @jgostick I will be happy to review this.

I have no COI as defined by JOSS policy. In interest of transparency I would state that I met Florian at a workshop last year for ASE developers/users and recommended submitting the code to JOSS based on presentation/discussion at that event. I have not used the code, examined it closely or otherwise been involved in its development.

[jgostick]

That sounds like a fine relationship. The review process is transparent, so if you didn't know each other before, you would afterwards!

[jgostick]

@whedon add @ajjackson as reviewer

[whedon]

OK, @ajjackson is now a reviewer

[flokno]

Hi @keipertk , would you be happy with such a contribution guideline:
https://gitlab.com/vibes-developers/vibes/-/merge_requests/23
?

[keipertk]

Yep that looks great, nice work!

[flokno]

Hi, I was waiting to merge https://gitlab.com/vibes-developers/vibes/-/merge_requests/23 until @ajjackson has made additional comments, any news there?

[ajjackson]

This is a sufficient set of contribution guidelines in my opinion, feel free to merge

[ajjackson]

@jgostick I am not able to click the check boxes in the review - I think I missed the notification to get the required permissions. Can you activate this?

[ajjackson]

Some initial comments on the manuscript:

I think this can be an exciting and useful contribution to the atomistic vibrations ecosystem. I especially welcome that the code interfaces with other active projects rather than reinventing the wheel.

The paper makes a reasonable survey of related tools, putting FHI-vibes in context. It does seem unfair to omit any mention of the MIT-licensed TDEP code which does firmly sit at the interface between lattice dynamics and MD. I don't think TDEP undermines the scholarly effort or community need for this work; the statement of need already clearly argues that the wide scope and integrated features set FHI-vibes apart from existing codes.

I am confused about the relationship between the statement of need and the actual existing feature set of FHI-vibes. The SoN gives several examples of methods that might be accessed using an integrated LD/MD toolkit: efficient MD initialisation; harmonic analysis of MD trajectories; anharmonicity analysis (Knoop et al); ab initio GK (Carbogno et al).
Of these, it is not clear from the manuscript which of these is implemented as a workflow in FHI-vibes, and which are aspirational examples of things that a user might build on top of FHI-vibes. From the documentation, I can find information about MD initialisation and anharmonicity analysis but not the other two techniques. I see green_kubo and harmonic_analysis modules in the source code so presumably these are WIP?

I will have a crack at the tutorials next.

[flokno]

Hi Adam, thanks for the initial comments!

The paper makes a reasonable survey of related tools, putting FHI-vibes in context. It does seem unfair to omit any mention of the MIT-licensed TDEP code which does firmly sit at the interface between lattice dynamics and MD. I don't think TDEP undermines the scholarly effort or community need for this work; the statement of need already clearly argues that the wide scope and integrated features set FHI-vibes apart from existing codes.

Of course we are aware of TDEP (and actually big fans of it), and we actually support dumping MD trajectories to TDEP input files, although this is kind of a hidden feature. However, since TDEP is essentially unrelated to our officially supported features (run calculations and in particular MD, compute finite-differences harmonic forceconstants, postprocessing like anharmonicity quantification) and it is outside of the python environment, I omitted it in the survey.

I am confused about the relationship between the statement of need and the actual existing feature set of FHI-vibes. The SoN gives several examples of methods that might be accessed using an integrated LD/MD toolkit: efficient MD initialisation; harmonic analysis of MD trajectories; anharmonicity analysis (Knoop et al); ab initio GK (Carbogno et al).
Of these, it is not clear from the manuscript which of these is implemented as a workflow in FHI-vibes, and which are aspirational examples of things that a user might build on top of FHI-vibes. From the documentation, I can find information about MD initialisation and anharmonicity analysis but not the other two techniques. I see green_kubo and harmonic_analysis modules in the source code so presumably these are WIP?

Yes, Green Kubo and more sophisticated harmonic analysis are WIP. These things should be finalized sometime next year. We plan a separate release (vibes 1.1.?) when GK is ready. Our plan with the paper was to write it such that it covers the envisaged scope of FHI-vibes and not just the features available in 1.0. It is stated in the paper that the officially supported features are listed in the docs/the webpage. If you wish to disentangle this more clearly in the paper, we can do so. I could for example write sth. like "In the initial release, FHI-vibes supports XYZ. We plan to add features A and B in upcoming releases. The currently supported list of features and a use guide etc. are available at vibes....de". Would you prefer that?

I will have a crack at the tutorials next.

Looking forward to that, thanks again for the good comments.

[jgostick]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

👋 @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/joss-papers#1948

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#1948, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1103/PhysRevMaterials.4.083809 is OK
- 10.1088/1361-648X/aa680e is OK
- 10.1016/j.scriptamat.2015.07.021 is OK
- 10.1103/PhysRevB.91.094306 is OK
- 10.1016/j.cpc.2009.06.022 is OK
- 10.1016/j.cpc.2018.09.020 is OK
- 10.5334/jors.148 is OK
- 10.1109/MCSE.2011.37 is OK
- 10.1002/cpe.3505 is OK
- 10.1038/nmat3568 is OK
- 10.1103/PhysRevLett.78.4063 is OK
- 10.1103/PhysRevLett.118.175901 is OK
- 10.1002/adts.201800184 is OK
- 10.1002/anie.201812112 is OK
- 10.1021/acs.jpcc.5b11115 is OK
- 10.1038/nmat2090 is OK
- 10.1016/j.jeurceramsoc.2007.12.023 is OK
- 10.1103/PhysRevLett.96.115504 is OK
- 10.1103/physrevb.79.064301 is OK
- 10.1557/mrs.2018.208 is OK
- 10.1038/s41597-020-00638-4 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[flokno]

@jgostick this looks good to me, although I cannot make a qualified statement about the xml file.

[jgostick]

An editor-in-chief is notified by whedon and will drop in here shortly to make the final approval.

[kyleniemeyer]

Hi @flokno, I'm the EIC on duty this week, doing some final checks of your submission. In the paper, I noticed a few references missing DOIs: Giannozzi 2009, Kresse 1996. Could you check on that, and update the paper if so? There's no need to archive the repository again after that, since JOSS archives the paper (only changes to the software would require that).

[flokno]

@whedon check references

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1103/PhysRevMaterials.4.083809 is OK
- 10.1088/1361-648X/aa680e is OK
- 10.1016/j.scriptamat.2015.07.021 is OK
- 10.1103/PhysRevB.91.094306 is OK
- 10.1016/j.cpc.2009.06.022 is OK
- 10.1016/j.cpc.2018.09.020 is OK
- 10.5334/jors.148 is OK
- 10.1109/MCSE.2011.37 is OK
- 10.1002/cpe.3505 is OK
- 10.1088/0953-8984/21/39/395502 is OK
- 10.1103/PhysRevB.54.11169 is OK
- 10.1038/nmat3568 is OK
- 10.1103/PhysRevLett.78.4063 is OK
- 10.1103/PhysRevLett.118.175901 is OK
- 10.1002/adts.201800184 is OK
- 10.1002/anie.201812112 is OK
- 10.1021/acs.jpcc.5b11115 is OK
- 10.1038/nmat2090 is OK
- 10.1016/j.jeurceramsoc.2007.12.023 is OK
- 10.1103/PhysRevLett.96.115504 is OK
- 10.1103/physrevb.79.064301 is OK
- 10.1557/mrs.2018.208 is OK
- 10.1038/s41597-020-00638-4 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[flokno]

Hi @kyleniemeyer thanks for pointing this out, seems I was relying on whedon too much.

I added the two dois and apparently this worked, no complaints from our robo friend.

[kyleniemeyer]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1103/PhysRevMaterials.4.083809 is OK
- 10.1088/1361-648X/aa680e is OK
- 10.1016/j.scriptamat.2015.07.021 is OK
- 10.1103/PhysRevB.91.094306 is OK
- 10.1016/j.cpc.2009.06.022 is OK
- 10.1016/j.cpc.2018.09.020 is OK
- 10.5334/jors.148 is OK
- 10.1109/MCSE.2011.37 is OK
- 10.1002/cpe.3505 is OK
- 10.1088/0953-8984/21/39/395502 is OK
- 10.1103/PhysRevB.54.11169 is OK
- 10.1038/nmat3568 is OK
- 10.1103/PhysRevLett.78.4063 is OK
- 10.1103/PhysRevLett.118.175901 is OK
- 10.1002/adts.201800184 is OK
- 10.1002/anie.201812112 is OK
- 10.1021/acs.jpcc.5b11115 is OK
- 10.1038/nmat2090 is OK
- 10.1016/j.jeurceramsoc.2007.12.023 is OK
- 10.1103/PhysRevLett.96.115504 is OK
- 10.1103/physrevb.79.064301 is OK
- 10.1557/mrs.2018.208 is OK
- 10.1038/s41597-020-00638-4 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👋 @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/joss-papers#1951

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#1951, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[kyleniemeyer]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.02671 joss-papers#1952
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.02671
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

[kyleniemeyer]

Congrats @flokno on your article's publication in JOSS!

Many thanks to @keipertk and @ajjackson for reviewing this, and @jgostick for editing.

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.02671/status.svg)](https://doi.org/10.21105/joss.02671)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.02671">
  <img src="https://joss.theoj.org/papers/10.21105/joss.02671/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.02671/status.svg
   :target: https://doi.org/10.21105/joss.02671

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

[flokno]

Thank you very much @ajjackson , @keipertk , @jgostick , @kyleniemeyer , and @whedon !