[REVIEW]: emg3d: A multigrid solver for 3D electromagnetic diffusion.

[whedon]

Submitting author: @prisae (Dieter Werthmüller)
Repository: https://github.com/empymod/emg3d
Version: v0.7.1
Editor: @jedbrown
Reviewer: @akelbert, @emersodb, @lukeolson
Archive: 10.5281/zenodo.3339421

Status

Status badge code:

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

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

@akelbert & @emersodb & @lukeolson, 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 @jedbrown know.

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

Review checklist for @akelbert

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: v0.7.1
• Authorship: Has the submitting author (@prisae) 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 @emersodb

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: v0.7.1
• Authorship: Has the submitting author (@prisae) 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 @lukeolson

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: v0.7.1
• Authorship: Has the submitting author (@prisae) 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. @akelbert, 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...

[whedon]

👉 Check article proof 📄 👈

[jedbrown]

@akelbert @emersodb @lukeolson 👋 Welcome and thanks for agreeing to review! The comments from @whedon above outline the review process, which takes place in this thread (possibly with issues filed in the emg3d repository). I'll be watching this thread if you have any questions.

[prisae]

Great to see the review started! I repeat a question here that I asked in the original issue (#1431 (comment)): "I saw one typo and some of the reference-bracketing in the compiled version did not turn out as I intended. Is there a way to edit them now or shall I wait for the reviews first?"

[danielskatz]

You can make changes in the paper.md and paper.bib - after you have done so, enter a new comment here containing @whedon generate pdf to rebuild the pdf

[prisae]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[prisae]

I pushed a revised version. The only thing I did was changing things a little to take into account that citations in JOSS seem to always have brackets (). So I avoided having (()), and tried to make sentences that do not have a (citation) in its flow. Nothing change with regards to the context.

[emersodb]

Not a super important issue, but when doing the pip install, the version number installed was emg3d-0.6.1 rather than 0.5.0 as indicated in the version. Should we be forcing an install of 0.5.0 for the review?

[prisae]

Since I submitted the manuscript I worked on it and released v0.6.0 and v0.6.1. I don't know what is the normal procedure in JOSS, if using the most recent version to final publication date or the version when it was submitted. Asking @jedbrown ?

[jedbrown]

It's typical to review the most recent release or maintenance/stable release. When revisions occur as a result of review (also typical) then the final archived version will be tagged post-review (could be v0.6.2, for example). Assuming you would like v0.6.1 to be reviewed, I'll update that now.

[jedbrown]

@whedon set v0.6.1 as version

[whedon]

OK. v0.6.1 is the version.

[emersodb]

A minor issue that I ran into while working through the 1c_3D_triaxial_SimPEG example is that, as I use pip as my python package manager, pymatsolver does not automatically include Pardiso since MKL is not packaged within pip distributions as it is in Anaconda. So I needed to do a pip install MKL before the example could be run using Pardiso

[emersodb]

In the examples repository, it appears that the folder SEG-EAGE/' is missing from the data/ folder. Thus, when I try to run the 2a_SEG-EAGE_3D-Salt-Model.ipynb notebook, it yields that exception

FileNotFoundError: [Errno 2] No such file or directory: './data/SEG-EAGE/SALTF.ZIP'

[prisae]

• Data: Correct, you have to download the data. This is described in the notebook just above the cell that failed.
• pymatsolver: Good input! This is strictly speaking a problem with SimPEG, not with emg3d, but I will add a comment in this regard so the user knows why it is not working.

[prisae]

You can get the data from the SEG-website or via the direct link. The zip-file is ~1.2 GB big. Unzip the archive, and place the file salt_and_overthrust_models/3-D_Salt_Model/VEL_GRIDS/SALT.ZIP (20.0 MB) into ./data/SEG-EAGE/ (or adjust the path in the following cell).

[emersodb]

Ah, apologies on the data-side. I missed that comment in the notebook!

[prisae]

No problem at all.

I just added the following sentence under requirements in the notebook 1c_3D_triaxial_SimPEG.ipynb:
«Note, in order to use the Pardiso-solver pymatsolver has to be installed via conda, not via pip!»
Thanks for pointing that out!

[prisae]

v0.6.2 is out. All these new versions are changes under the hood to improve CPU and RAM usage, nothing changes for the user-facing functionality. I do not expect further new versions until the JOSS review is finished (if it is not taking too long).

[emersodb]

I may have missed this in the examples or elsewhere in the repository, so please correct me if I'm wrong, but I didn't notice if there were any examples exhibiting optimal scaling for the MG solver. It would be beneficial, I think, to add an example showing linear scaling of the solver, even for just a very simple setup. Otherwise, I think the examples do a good job of verifying the algorithm against existing solvers.

[prisae]

That is a good and timely question @emersodb. Since version 0.6.2 (so two days ago) I had a CPU & RAM section in the docs, and a notebook to estimate memory. Given your question I expanded this section and also added a notebook to estimate runtime.

• Docs: https://emg3d.readthedocs.io/en/latest/cpu_and_ram.html
• Notebooks: 4a_RAM-requirements.ipynb and 4b_Runtime.ipynb on https://github.com/empymod/emg3d-examples

Figures

[emersodb]

At this time, I believe that my review is complete and would recommend publication of the emg3d submission.

[prisae]

Thanks for your time, input, and feedback @emersodb

[whedon]

OK. 10.5281/zenodo.3339421 is the archive.

[jedbrown]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Check final proof 👉 openjournals/joss-papers#839

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

@whedon accept deposit=true

[jedbrown]

@openjournals/joss-eics This paper is accepted; over to you.

[prisae]

Thanks @jedbrown , was a pleasure to work with you!

[jedbrown]

Likewise! Thanks for your patient and careful work, and thanks to our reviewers.

[danielskatz]

@prisae - please change "A diffusive problem remains, which resulting system of equations is given in the frequency domain by" to "A diffusive problem remains, which has the resulting system of equations given in the frequency domain by"

"It currently uses mostly" should be "It currently mostly uses" or "It currently primarily uses"

"the multigrid CSEM codes of these publications" should be "the multigrid CSEM codes discussed in these publications"

[prisae]

@danielskatz , does that imply that I'll have to make a new release and mint another Zenodo DOI with it? I am off on vacation right now, I'll do it when I am back on Monday.

[danielskatz]

no, the paper source doesn't need to be in the repo or if it is, it doesn't need to be up to date - we care about the software repo and the pdf of the paper in terms of archiving

[prisae]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[prisae]

I made the corrections @danielskatz

[whedon]

👉 Check article proof 📄 👈

[danielskatz]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Check final proof 👉 openjournals/joss-papers#852

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

@whedon accept deposit=true

[danielskatz]

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

[danielskatz]

Thanks to @akelbert & @emersodb & @lukeolson for reviewing and @jedbrown 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](http://joss.theoj.org/papers/10.21105/joss.01463/status.svg)](https://doi.org/10.21105/joss.01463)

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

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

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