[REVIEW]: AMReX: a framework for block-structured adaptive mesh refinement

[whedon]

Submitting author: @asalmgren (Ann Almgren)
Repository: https://github.com/AMReX-Codes/amrex
Version: current master branch on github
Editor: @kyleniemeyer
Reviewer: @matthewturk, @RemiLehe , @cmsquared
Archive: 10.5281/zenodo.2754709

Status

Status badge code:

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

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) 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

@matthewturk & @RemiLehe & @cmsquared, 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.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @kyleniemeyer know.

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

Review checklist for @matthewturk

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

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?
• Version: Does the release version given match the GitHub release (current master branch on github)?
• Authorship: Has the submitting author (@asalmgren) 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 function 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @RemiLehe

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

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?
• Version: Does the release version given match the GitHub release (current master branch on github)?
• Authorship: Has the submitting author (@asalmgren) 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 function 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @cmsquared

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

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?
• Version: Does the release version given match the GitHub release (current master branch on github)?
• Authorship: Has the submitting author (@asalmgren) 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 function 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @matthewturk, it looks like you're currently assigned as the reviewer for 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

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[kyleniemeyer]

👋 @asalmgren @matthewturk @RemiLehe @cmsquared

The actual review will take place in this issue; you can find the individual reviewer checklists above. Thanks!

[whedon]

👉 Check article proof 📄 👈

[asalmgren]

Looks good.

…

On Mon, Apr 8, 2019 at 9:51 AM whedon ***@***.***> wrote: 👉 Check article proof 📄 👈 <https://github.com/openjournals/joss-papers/blob/joss.01370/joss.01370/10.21105.joss.01370.pdf> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1370 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AKJPYrBJpsovrMFDtnI3cYmyGF2J_sb-ks5ve3OEgaJpZM4cipG5> .

[cmsquared]

Just to disclose a possible perceived COI: In the last 4 years, I have been on published papers or meeting abstracts with Zhang, Almgren, Beckner, Bell, Friesen, Katz, Nonaka, and Zingale from the author list. Most of this was for work we had done together either on astrophysics or utilizing/writing tools that were based on the predecessor of AMReX: BoxLib. I do not feel this is an actual COI given that I have not worked on AMReX, nor any of the updated modifications to codes that once used BoxLib and now use AMReX.

[cmsquared]

The team has addressed the points outlined in the Issue raised above via a series of commits. I am happy to recommend this article for publication.

[kyleniemeyer]

Thanks @cmsquared!

@RemiLehe @matthewturk just wanted to check in on the status of your reviews

[RemiLehe]

Thanks for the reminder! I'll try to send my review comments today.

[RemiLehe]

I have completed the review ; here are a few comments regarding the checklist itself:

• Regarding possible perceived COI: As mentioned off-line to @kyleniemeyer, I am currently working and collaborating with the AMReX team for the WarpX project. I am not developing the AMReX source code, though.

• Regarding the license: AMReX uses a modified 3-clause BSD license, which has been adapted for UC Berkeley/LBNL. (Open-source software from LBNL usually use this license.) Strictly speaking, it is not in the OSI approved list. (or I missed it)

[matthewturk]

Hi @kyleniemeyer, working on mine now. Apologies, hope to have it done within 24 hours.

[matthewturk]

I have completed my review, and here are my comments:

• LICENSE is not in the repository, but it is in the README.md file and a license.txt file, which seems fine to me.
• I did have to dig around for the tests, but not to the point that I felt even raising an issue was warranted on the original repository.

I recommend this paper be accepted.

[RemiLehe]

The reviewers have addressed my comment (in the issues of the AMReX repository).
I also recommend that the paper be accepted.

[kyleniemeyer]

Thanks for your reviews @matthewturk @RemiLehe @cmsquared !

@asalmgren it looks like the only remaining issue is the license. JOSS requires that software submissions use standard OSI-approved licenses, and it looks like your submission is using a modified version of the BSD 3-clause license.

The editorial board is in agreement that AMReX needs to adopt an (unmodified, standard) OSI-approved license for JOSS to accept it. If possible, this could be as simple as moving to the standard BSD 3-clause license. However, if you need the indemnification protections in your modified license, there is an OSI-approved NASA license that includes such language.

Bruce Wilson (@usethedata) has dealt with some of these issues at ORNL and has volunteered to chat about this if needed. Also, @jedbrown pointed out that AMReX is part of the xSDK collaboration, which states:

The xSDK collaboration has a strong preference for packages to use an OSI-approved, permissive open-source license (e.g., MIT or BSD 3-Clause). All new packages will be required to use such a license.

[asalmgren]

Kyle et al -- We understand and are trying to figure out how we can meet the requirement. Is there a way to find out if there are codes currently published in JOSS that have been released from LBNL? Thanks

…

On Wed, May 8, 2019 at 7:50 AM Kyle Niemeyer ***@***.***> wrote: Thanks for your reviews @matthewturk <https://github.com/MatthewTurk> @RemiLehe <https://github.com/RemiLehe> @cmsquared <https://github.com/cmsquared> ! @asalmgren <https://github.com/asalmgren> it looks like the only remaining issue is the license. JOSS requires that software submissions use standard OSI-approved licenses, and it looks like your submission is using a modified version of the BSD 3-clause license. The editorial board is in agreement that AMReX needs to adopt an (unmodified, standard) OSI-approved license for JOSS to accept it. If possible, this could be as simple as moving to the standard BSD 3-clause license. However, if you need the indemnification protections in your modified license, there is an OSI-approved NASA license that includes such language. Bruce Wilson ***@***.*** <https://github.com/usethedata>) has dealt with some of these issues at ORNL and has volunteered to chat about this if needed. Also, @jedbrown <https://github.com/jedbrown> pointed out that AMReX is part of the xSDK collaboration, which states: The xSDK collaboration has a strong preference for packages to use an OSI-approved, permissive open-source license (e.g., MIT or BSD 3-Clause). All new packages will be required to use such a license. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1370 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACRE6YQLCRDNAGDM6BFKI3DPULSBXANCNFSM4HEKSG4Q> .

[jedbrown]

Note that SuperLU_DIST, for example, is standard 3-clause BSD. https://github.com/xiaoyeli/superlu_dist/blob/master/License.txt
JOSS #830 has a normal 3-clause BSD license.

[asalmgren]

We have replaced the license.txt with the modified BSD license by LICENSE containing the standard 3-clause BSD license. For the record however - I think that both JOSS and xSKD should re-consider their policy regarding the modified license -- if you read the text you will notice that it is in fact more "permissive" and in the spirit of open source than the standard 3-clause license, and as such should be acceptable, both in spirit and in reality.

…

On Wed, May 8, 2019 at 9:49 AM Ann Almgren ***@***.***> wrote: Kyle et al -- We understand and are trying to figure out how we can meet the requirement. Is there a way to find out if there are codes currently published in JOSS that have been released from LBNL? Thanks On Wed, May 8, 2019 at 7:50 AM Kyle Niemeyer ***@***.***> wrote: > Thanks for your reviews @matthewturk <https://github.com/MatthewTurk> > @RemiLehe <https://github.com/RemiLehe> @cmsquared > <https://github.com/cmsquared> ! > > @asalmgren <https://github.com/asalmgren> it looks like the only > remaining issue is the license. JOSS requires that software submissions use > standard OSI-approved licenses, and it looks like your submission is using > a modified version of the BSD 3-clause license. > > The editorial board is in agreement that AMReX needs to adopt an > (unmodified, standard) OSI-approved license for JOSS to accept it. If > possible, this could be as simple as moving to the standard BSD 3-clause > license. However, if you need the indemnification protections in your > modified license, there is an OSI-approved NASA license that includes such > language. > > Bruce Wilson ***@***.*** <https://github.com/usethedata>) has dealt > with some of these issues at ORNL and has volunteered to chat about this if > needed. Also, @jedbrown <https://github.com/jedbrown> pointed out that > AMReX is part of the xSDK collaboration, which states: > > The xSDK collaboration has a strong preference for packages to use an > OSI-approved, permissive open-source license (e.g., MIT or BSD 3-Clause). > All new packages will be required to use such a license. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#1370 (comment)>, > or mute the thread > <https://github.com/notifications/unsubscribe-auth/ACRE6YQLCRDNAGDM6BFKI3DPULSBXANCNFSM4HEKSG4Q> > . >

[jedbrown]

@asalmgren Although the intent may be to ensure inbound=outbound (see "Inbound=Outbound Is All You Need"), it applies to those who may make modifications in a fork (not just contributors to upstream) or as a component of a different project, and thus may require one-off legal consult for potential users as well as possible conflict with more restrictive licenses such as GPL. IMO, clarity regarding inbound=outbound (e.g., Developer's Certification of Origin) belongs in contributing documentation and not in a license. I'm not aware of any OSI approved licenses with such terms.

[arfon]

We have replaced the license.txt with the modified BSD license by LICENSE
containing the standard 3-clause BSD license.

Many thanks @asalmgren.

For the record however - I think that both JOSS and xSKD should re-consider
their policy regarding the modified license -- if you read the text you
will notice that it is in fact more "permissive" and in the spirit of open
source than the standard 3-clause license, and as such should be
acceptable, both in spirit and in reality.

The challenge here is that with the modification, without consulting a lawyer, we don't know what this license is. Any modification to an existing open source license effectively creates a new license, hence defeating the purpose of having a shared set of common licenses where the terms are understood from a legal perspective.

If you and your colleagues strongly believe in this modified license, then I'd encourage you to petition the Open Source Initiative with this modified license. If a project uses a license in this list then JOSS can accept a submission using that license.

[asalmgren]

Arfon et al, Thank you for the discussion. We'll look into petitioning OSI to accept this modification. In the meantime, however, I'm glad that the new AMReX license (standard 3-clause BSD) is acceptable. Thanks, Ann

…

On Wed, May 8, 2019 at 12:24 PM Arfon Smith ***@***.***> wrote: We have replaced the license.txt with the modified BSD license by LICENSE containing the standard 3-clause BSD license. Many thanks @asalmgren <https://github.com/asalmgren>. For the record however - I think that both JOSS and xSKD should re-consider their policy regarding the modified license -- if you read the text you will notice that it is in fact more "permissive" and in the spirit of open source than the standard 3-clause license, and as such should be acceptable, both in spirit and in reality. The challenge here is that with the modification, without consulting a lawyer, we don't know *what* this license is. Any modification to an existing license is effectively a new license, hence defeating the purpose of having a shared set of common licenses where the terms are understood from a legal perspective. If you and your colleagues strongly believe in this modified license, then I'd encourage you to petition the Open Source Initiative with this modified license. If a project uses a license in this list <https://opensource.org/licenses/alphabetical> then JOSS can accept a submission. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1370 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACRE6YVCMCS3B56SD6MLTZTPUMSITANCNFSM4HEKSG4Q> .

[kyleniemeyer]

Thanks @asalmgren!

[kyleniemeyer]

@whedon generate pdf

[WeiqunZhang]

One of the references has a valid but incorrect DOI. I will fix it.

[WeiqunZhang]

DOI 10.1137/0915008 appeared in two different references. This has been fixed in AMReX repo. I have also manually clicked and checked the DOI links in generated pdf file.

[kyleniemeyer]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[kyleniemeyer]

Thanks @WeiqunZhang and @asalmgren! Looks good to move forward now.

[kyleniemeyer]

@whedon set 10.5281/zenodo.2754709 as archive

[whedon]

OK. 10.5281/zenodo.2754709 is the archive.

[kyleniemeyer]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

OK DOIs

- 10.1088/1742-6596/1031/1/012024 is OK
- 10.1016/0021-9991(84)90073-1 is OK
- 10.1016/0021-9991(89)90035-1 is OK
- 10.1137/0915008 is OK
- 10.1006/jcph.1998.5890 is OK
- 10.1080/00102209808915770 is OK
- 10.1088/1364-7830/4/4/309 is OK
- 10.1137/15M102616X is OK
- 10.1145/1089014.1089020 is OK
- 10.1016/B978-012387582-2/50038-1 is OK
- 10.1088/0067-0049/192/1/9 is OK
- 10.1137/1.9780898719505 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

Check final proof 👉 openjournals/joss-papers#685

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

🚨🚨🚨 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.01370 joss-papers#686
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.01370
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]

Hey @arfon, looks like the paper PDF isn't showing up at http://joss.theoj.org/papers/10.21105/joss.01370 even though the PDF was generated fine at https://github.com/openjournals/joss-papers/blob/49965f4a1df4246a547c458c1f29feada6b6aa8e/joss.01370/10.21105.joss.01370.pdf

Any ideas? Just wait a bit longer?

[arfon]

Any ideas? Just wait a bit longer?

Sometimes GitHub pages can take a couple of minutes to build. I can see the paper fine now at https://doi.org/10.21105/joss.01370 👍

[kyleniemeyer]

Works for me too now, thanks!

Congrats @asalmgren et al. on your paper being published in JOSS! Thanks to @matthewturk, @RemiLehe , and @cmsquared for reviewing!

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

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

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

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: http://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.salsalabs.org/donate-to-joss