[REVIEW]: VlaPy: A Python package for Eulerian Vlasov-Poisson-Fokker-Planck Simulations

[whedon]

Submitting author: @joglekara (Archis Joglekar)
Repository: https://github.com/joglekara/VlaPy
Version: v0.1.0
Editor: @dpsanders
Reviewer: @TomGoffrey, @StanczakDominik
Archive: 10.5281/zenodo.4026770

Status

Status badge code:

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

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

@TomGoffrey & @StanczakDominik, 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 @dpsanders know.

✨ Please try and complete your review in the next two weeks ✨

Review checklist for @TomGoffrey

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 (@joglekara) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

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 @StanczakDominik

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 (@joglekara) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

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. @TomGoffrey, @StanczakDominik it looks like you're currently assigned to review this paper 🎉.

⭐ 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:

OK DOIs

- 10.1103/PhysRevE.96.043208 is OK
- 10.1088/1361-6587/aab978 is OK
- 10.1103/PhysRev.112.1456 is OK
- 10.1016/0021-9991(73)90131-9 is OK
- 10.1088/0741-3335/41/3A/001 is OK
- 10.1016/S0010-4655(02)00451-4 is OK
- 10.5281/zenodo.1238132 is OK
- 10.1038/nphys3736 is OK
- 10.1038/nphys3744 is OK
- 10.1038/nphys3745 is OK
- 10.1038/s41467-019-08435-3 is OK
- 10.5334/jors.148 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👉 Check article proof 📄 👈

[StanczakDominik]

For the "State of the field: Do the authors describe how this software compares to other commonly-used packages?" checklist item, I think this section should be sufficient:

There are many software libraries that solve the same equation set which are available in academic settings, research laboratories, and industry (e.g., [@Banks2017; @Joglekar2018]), but the community has yet to benefit from a simple-to-read, open-source Python implementation. This lack of capability is currently echoed in conversations within the PlasmaPy [@PlasmaPy] community (PlasmaPy is a collection of open-source plasma physics resources). Our aim with VlaPy is to take a step towards filling this need in the open-source community.

[StanczakDominik]

• "A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?" is being dealt with by Better describe the goal, target audience of the project joglekara/VlaPy#31
• "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", by Contributor instructions joglekara/VlaPy#32
• "Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).", by Updates for the Landau_damping notebook joglekara/VlaPy#21

[TomGoffrey]

My apologies in the delay on this review.

I'm currently stalling at the statement of need and example usage requirements.

Reading the paper it's not clear to me what the primary aim of the software is. Is it intended as a research tool in its own right, an educational tool, or both? I think this could be clarified, and assuming not a purely educational tool some concrete references to example applications using 1D1V Vlasov would ideally be added.

I have a couple of other minor comments at this stage:

• Is the exclusion of sphinx, sphinxcontrib-bibtex and sphinx_rtd_theme from the INSTALL_REQUIREMENTS in setup.py deliberate?
• Personally I would add newline at the end of README.md and CONTRIBUTING.md, as is done in CODE_OF_CONDUCT.md

[joglekara]

Thanks for diving in @TomGoffrey. Comments inline:

My apologies in the delay on this review.

I'm currently stalling at the statement of need and example usage requirements.

Reading the paper it's not clear to me what the primary aim of the software is. Is it intended as a research tool in its own right, an educational tool, or both? I think this could be clarified, and assuming not a purely educational tool some concrete references to example applications using 1D1V Vlasov would ideally be added.

Thanks for the feedback here. The statement of need/applications is hopefully addressed in joglekara/VlaPy#38. Looking forward to your feedback there.

I have a couple of other minor comments at this stage:

• Is the exclusion of sphinx, sphinxcontrib-bibtex and sphinx_rtd_theme from the INSTALL_REQUIREMENTS in setup.py deliberate?

Good point. The main reason sphinx and the related packages are excluded is because we rely on the .read_the_docs.yaml and docs/requirements.txt to do the work. However, that's only configured for hosting on RTD. Do you think it be added to the setup.py for the main package too?

• Personally I would add newline at the end of README.md and CONTRIBUTING.md, as is done in CODE_OF_CONDUCT.md

Thanks for these. The newline suggestions are also included in joglekara/VlaPy#38

[dpsanders]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[dpsanders]

👋 Sorry for the delay.

@joglekara Just wanted to point out that the reference to @Cheng1977 in the paper seems to have the wrong format.

@TomGoffrey Are you happy with the updated statement of need and references and the modifications to the requirements?

@StanczakDominik I see that all of your boxes are checked off, thanks! Have you finished your review?

[StanczakDominik]

Oh! Yeah, I bet there's some step here that I should have done to finish it, but forgot - sorry. Getting to it after breakfast.

[dpsanders]

No I don't think you missed a step actually, just wanted to confirm!

[TomGoffrey]

Yes, the statement of need is much clearer now thanks.

Regarding the sphinx requirements discussed above, I'm afraid I don't have a definitive opinion. On one hand my guess would be that not many users would build the docs locally, but on the other hand it's not a big change and it would benefit the users who do want to build for the requirements to be added. That all being said as I don't have a strong opinion I'm happy to leave the decision to you.

Some additional comments:

1. I think the paper itself would benefit from a plot (or two) for the final section. I think you could easily adapt the later plots from the notebook? Obviously with the notebook the user could get the plots that way, but I think my adding it to the paper you make it a stronger stand-alone document.
2. The other tests are mentioned, but it's not obvious how to run them. Obviously it doesn't take much searching through the test directory, but a simple comment along the lines of these tests are demonstrated in tests/test_lb.py would be beneficial. Even better (but I guess more work) would be (e.g.) a plot showing the relaxation to a Maxwellian. Again, sounds basic but in my experience many first time users like to be able to verify they have run the code correctly, and regenerating published plots is an obvious starting point.
3. Is there a reason many of the RTD pages end in '…this page is under development…'? Is there more to do?

It's possible some (all?) of the above is considered beyond the required scope of the article, as I think I could reasonably sign off on the checklist now. @dpsanders could you comment perhaps?

[dpsanders]

Thanks @TomGoffrey! My opinion is that simple modifications to the paper and tests that would make the paper and repo more accessible should definitely be done.

[joglekara]

Thanks @TomGoffrey for the suggestions!

Yes, the statement of need is much clearer now thanks.

Regarding the sphinx requirements discussed above, I'm afraid I don't have a definitive opinion. On one hand my guess would be that not many users would build the docs locally, but on the other hand it's not a big change and it would benefit the users who do want to build for the requirements to be added. That all being said as I don't have a strong opinion I'm happy to leave the decision to you.

Some additional comments:

1. I think the paper itself would benefit from a plot (or two) for the final section. I think you could easily adapt the later plots from the notebook? Obviously with the notebook the user could get the plots that way, but I think my adding it to the paper you make it a stronger stand-alone document.

Agreed! I will implement that.

2. The other tests are mentioned, but it's not obvious how to run them. Obviously it doesn't take much searching through the test directory, but a simple comment along the lines of these tests are demonstrated in tests/test_lb.py would be beneficial. Even better (but I guess more work) would be (e.g.) a plot showing the relaxation to a Maxwellian. Again, sounds basic but in my experience many first time users like to be able to verify they have run the code correctly, and regenerating published plots is an obvious starting point.

Good idea. Implementing this in a Jupyter Notebook seems like the best way forward. Do you agree?

3. Is there a reason many of the RTD pages end in '…this page is under development…'? Is there more to do?

Well, there's always more to do ;). For many of those notes, I was referring to the fact that the the background to some of the finite differencing or kinetic equation derivations is still a work in progress.

Perhaps it is better to clean up any loose ends, trim and close the loop? Or leave the loop open while explicitly stating what is still to be done? @TomGoffrey @StanczakDominik @dpsanders , your thoughts are welcome here.

It's possible some (all?) of the above is considered beyond the required scope of the article, as I think I could reasonably sign off on the checklist now. @dpsanders could you comment perhaps?

[TomGoffrey]

@joglekara I do agree that a notebook would be the best way, looks like you're already working on it. That's great.

I agree, documentation is always WIP, but (and I guess this makes it more your decision than mine) I think the code looks better to (prospective) users if you tie up any loose ends and remove the comments. You can always expand on details later. That's just my opinion though, so as you say if others want to weigh in that would be good.

[joglekara]

I think we might be close...

@dpsanders, @TomGoffrey , @StanczakDominik , any other thoughts or comments to improve this even further?

[TomGoffrey]

@whedon generate pdf

[whedon]

PDF failed to compile for issue #2182 with the following error:

Error producing PDF.
! Missing $ inserted.

$
l.484 where $v_0 = \int

Looks like we failed to compile the PDF

[joglekara]

@whedon commands

[whedon]

Here are some things you can ask me to do:

# List Whedon's capabilities
@whedon commands

# List of editor GitHub usernames
@whedon list editors

# List of reviewers together with programming language preferences and domain expertise
@whedon list reviewers

EDITORIAL TASKS

# Compile the paper
@whedon generate pdf

# Compile the paper from alternative branch
@whedon generate pdf from branch custom-branch-name

# Ask Whedon to check the references for missing DOIs
@whedon check references

# Ask Whedon to check repository statistics for the submitted software
@whedon check repository

[joglekara]

@whedon generate pdf from branch paper

[kyleniemeyer]

@whedon generate pdf

[whedon]

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

[joglekara]

I should also note that I added citations to NumPy and SciPy (reminded by and in honor of today's publication in Nature) :)

[kyleniemeyer]

Thanks @joglekara! There were still a few extraneous parentheses left, which I just fixed in joglekara/VlaPy#95

[kyleniemeyer]

@whedon generate pdf

[whedon]

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

[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/PhysRevE.96.043208 is OK
- 10.1063/1.2746779 is OK
- 10.1137/0705041 is OK
- 10.1088/1361-6587/aab978 is OK
- 10.1103/PhysRev.112.1456 is OK
- 10.1016/0021-9991(73)90131-9 is OK
- 10.1088/0741-3335/41/3A/001 is OK
- 10.1016/S0010-4655(02)00451-4 is OK
- 10.5281/zenodo.1238132 is OK
- 10.1038/nphys3736 is OK
- 10.1038/nphys3744 is OK
- 10.1038/nphys3745 is OK
- 10.5334/jors.148 is OK
- 10.1145/3399579.3399867 is OK
- 10.1103/PhysRevLett.102.245002 is OK
- 10.1063/1.4943194 is OK
- 10.1103/PhysRevE.94.053204 is OK
- 10.1103/PhysRevLett.116.145001 is OK
- 10.1063/1.5046194 is OK
- 10.1038/s41467-019-08435-3 is OK
- 10.1016/0021-9991(76)90053-X is OK

MISSING DOIs

- None

INVALID DOIs

- 10.1038/s41586-020-2649-2 is INVALID
- https://doi.org/10.1038/s41592-019-0686-2 is INVALID because of 'https://doi.org/' prefix

[joglekara]

on it!

[whedon]

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

Check final proof 👉 openjournals/joss-papers#1736

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#1736, 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

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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

OK DOIs

- 10.1103/PhysRevE.96.043208 is OK
- 10.1063/1.2746779 is OK
- 10.1137/0705041 is OK
- 10.1088/1361-6587/aab978 is OK
- 10.1103/PhysRev.112.1456 is OK
- 10.1016/0021-9991(73)90131-9 is OK
- 10.1088/0741-3335/41/3A/001 is OK
- 10.1016/S0010-4655(02)00451-4 is OK
- 10.5281/zenodo.1238132 is OK
- 10.1038/nphys3736 is OK
- 10.1038/nphys3744 is OK
- 10.1038/nphys3745 is OK
- 10.5334/jors.148 is OK
- 10.1145/3399579.3399867 is OK
- 10.1103/PhysRevLett.102.245002 is OK
- 10.1063/1.4943194 is OK
- 10.1103/PhysRevE.94.053204 is OK
- 10.1103/PhysRevLett.116.145001 is OK
- 10.1063/1.5046194 is OK
- 10.1038/s41467-019-08435-3 is OK
- 10.1016/0021-9991(76)90053-X is OK
- 10.1038/s41592-019-0686-2 is OK

MISSING DOIs

- None

INVALID DOIs

- 10.1038/s41586-020-2649-2 is INVALID

[whedon]

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

Check final proof 👉 openjournals/joss-papers#1737

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#1737, 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]

@joglekara thanks for fixing that. It looks like the remaining issue is fine—I can confirm that the DOI for the NumPy matches the one given in the article (probably just isn't through the system yet).

[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.02182 joss-papers#1738
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.02182
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 @joglekara on your article's publication in JOSS!

Many thanks to @TomGoffrey and @StanczakDominik for reviewing this submission, and @dpsanders for editing it.

[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.02182/status.svg)](https://doi.org/10.21105/joss.02182)

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

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

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

[dpsanders]

Thanks @kyleniemeyer!

Congratulations @joglekara and reiterating the many thanks to @TomGoffrey and @StanczakDominik for your hard work in reviewing this submission!

[joglekara]

Thanks @kyleniemeyer for pushing it through!

Thanks @dpsanders for shepherding the process and to @dpsanders , @TomGoffrey , and @StanczakDominik for the feedback on the submission. I am really impressed by and happy to be contributing to JOSS.

[StanczakDominik]

Congratulations :)