PyPartMC

[slayoo]

Submitting Author: Sylwester Arabas (@slayoo)
All current maintainers: (@zdaq12, @jcurtis2, @nriemer, @mwest1066)
Package Name: PyPartMC
One-Line Description of Package: Python interface to PartMC aerosol-dynamics Monte-Carlo simulation package
Repository Link: https://github.com/open-atmos/PyPartMC/
Version submitted: v1.2.0
EIC: @Batalex
Editor: @russbiggs
Reviewer 1: TBD
Reviewer 2: TBD
Archive: TBD
Version accepted: TBD
Date accepted (month/day/year): TBD

---

Code of Conduct & Commitment to Maintain Package

• I agree to abide by [pyOpenSci's Code of Conduct][PyOpenSciCodeOfConduct] during the review process and in maintaining my package after should it be accepted.
• I have read and will commit to package maintenance after the review as per the [pyOpenSci Policies Guidelines][Commitment].

Description

PyPartMC is a Python interface to PartMC, a particle-resolved Monte-Carlo code for atmospheric aerosol simulation. PyPartMC is implemented mostly in C++ (based on the pybind11 framework) with some C and Fortran boilerplate layers. PyPartMC constitutes an API to the PartMC Fortran internals. Besides empowering Python/Jupyter users, PyPartMC can facilitate using PartMC from other environments - see, e.g., Julia and Matlab examples in the project README.

Scope

- [ ] Data retrieval
- [ ] Data extraction
- [ ] Data processing/munging
- [ ] Data deposition
- [ ] Data validation and testing
- [ ] Data visualization
- [ ] Workflow automation
- [ ] Citation management and bibliometrics
- [x] Scientific software wrappers
- [ ] Database interoperability

Domain Specific

n/a

(atmospheric science)

Community Partnerships

n/a

(we host development as a part of the OpenAtmos initiative: https://github.com/open-atmos)

Target audience and scientific applications

Development of PyPartMC has been intended to remove limitations to the use of Fortran-implemented PartMC software. PyPartMC facilitates the dissemination of computational research results by streamlining independent execution of PartMC simulations, which could prove advantageous during peer review process. Additionally, the ability to easily package examples, simple simulations, and results in a web-based notebook allows PyPartMC to support the efforts of many members of the scientific community, including researchers, instructors, and students, with nominal software and hardware requirements.

Other Python packages with relevant feature scope

• PySDM: particle-based Monte-Carlo aerosol-cloud simulation package (differences: PySDM focuses on growth and breakup processes relevant to cloud droplets; PyPartMC focuses on processes relevant to air pollutants and their chemical and physical transformations)
• DustPy: Python package for modelling dust evolution in protoplanetary disks (differences: focus on astrophysical applications vs. atmospheric aerosol)
• PyBox: aerosol simulation model featuring gas and particle chamistry (differences: PyBox focuses on chemical mechanisms; PyPartMC is an interface to PartMC which focuses on physics - e.g., collisions of aerosol particles - while chemical processes are handled with external software, e.g., CAMP or MOSAIC)

Technical checks

For details about the pyOpenSci packaging requirements, see our [packaging guide][PackagingGuide]. Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• uses an [OSI approved license][OsiApprovedLicense].
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions:
  • README file: https://github.com/open-atmos/PyPartMC/blob/main/README.md
  • auto-generated docstring-based docs: https://open-atmos.github.io/PyPartMC/
  • documentation of the wrapped PartMC package: https://lagrange.mechse.illinois.edu/partmc/partmc-2.6.1/doc/html/index.html
• contains a tutorial with examples of its essential functions and uses.
  • Jupyter notebooks with examples: https://github.com/open-atmos/PyPartMC/blob/main/README.md#jupyter-notebooks-with-examples
• has a test suite.
• has continuous integration setup, such as GitHub Actions CircleCI, and/or others.

Publication Options

• Do you wish to automatically submit to the [Journal of Open Source Software][JournalOfOpenSourceSoftware]? If so:

(we have recently published a SoftwareX paper on PyPartMC: https://doi.org/10.1016/j.softx.2023.101613)

Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?

• Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Confirm each of the following by checking the box.

• I have read the author guide.
• I expect to maintain this package for at least 2 years and can help find a replacement for the maintainer (team) if needed.

Please fill out our survey

• Last but not least please fill out our pre-review survey.

[Batalex]

Hey @slayoo, I'm Alex, currently serving as the Editor-in-Chief. I'm sorry it took me so long to get back to you.

PyPartMC seems to be in scope for us. I truly appreciate the care you put into the submission, especially the comparative section. It's very valuable to a profane such as myself when it comes to evaluating submissions.

Please find below the preliminary checks.

Editor-in-Chief checks

Thank you for submitting your package for pyOpenSci review. Below are the basic checks that your package needs to pass to begin our review. If some of these are missing, we will ask you to work on them before the review process begins.

Please check our Python packaging guide for more information on the elements below.

• Installation The package can be installed from a community repository such as PyPI (preferred), and/or a community channel on conda (e.g. conda-forge, bioconda).
  • The package imports properly into a standard Python environment import package.
    The package installation does not install the dependencies
• Fit The package meets criteria for fit and overlap.
• Documentation The package has sufficient online documentation to allow us to evaluate package function and scope without installing the package. This includes:
  • User-facing documentation that overviews how to install and start using the package.
  • Short tutorials that help a user understand how to use the package and what it can do for them.
  • API documentation (documentation for your code's functions, classes, methods and attributes): this includes clearly written docstrings with variables defined using a standard docstring format.
• Core GitHub repository Files
  • README The package has a README.md file with clear explanation of what the package does, instructions on how to install it, and a link to development instructions.
  • Contributing File The package has a CONTRIBUTING.md file that details how to install and contribute to the package.
  • Code of Conduct The package has a CODE_OF_CONDUCT.md file.
  • License The package has an OSI approved license.
    NOTE: We prefer that you have development instructions in your documentation too.
• Issue Submission Documentation All of the information is filled out in the YAML header of the issue (located at the top of the issue template).
• Automated tests Package has a testing suite and is tested via a Continuous Integration service.
• Repository The repository link resolves correctly.
• Package overlap The package doesn't entirely overlap with the functionality of other packages that have already been submitted to pyOpenSci.
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly.
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

• Initial onboarding survey was filled out
  We appreciate each maintainer of the package filling out this survey individually. 🙌
  Thank you authors in advance for setting aside five to ten minutes to do this. It truly helps our organization. 🙌

---

---

Editor comments

I have a few suggestions regarding the documentation:

• Having the links to the binder/collab/etc. is great. Would you consider including those end to end examples in the documentation website? It is a pity that it only has the API reference. I'd like to see more textual content as well, to properly frame the code blocks and fully understand what is going on
• I think it would be great to have a dedicated CONTRIBUTING.md/rst file in the repository with the README's sections about the implementation details and the developers notes.
• We suggest adding a code of conduct document as well. It's always a good idea to set the proper expectations from the start!

[slayoo]

@Batalex, thanks for the feedback!
We've just started addressing the above points with a code-of-conduct PR: open-atmos/PyPartMC#358
I'll report back here after addressing all points

[slayoo]

@Batalex, with the following PRs just merged:

• Create CODE_OF_CONDUCT.md open-atmos/PyPartMC#358
• improve pdoc landing site by rendering the README contents in the index.html. closes #332 open-atmos/PyPartMC#359
• move developer notes into a new CONTRIBUTING.md file open-atmos/PyPartMC#360

the repo and docs are improved following your suggestions:

• https://open-atmos.github.io/PyPartMC
• https://github.com/open-atmos/PyPartMC/tree/main/CODE_OF_CONDUCT.md
• https://github.com/open-atmos/PyPartMC/tree/main/CONTRIBUTING.md

[Batalex]

Thank you, @slayoo, the docs look great!
PyPartMC is a strong submission, I'll get started on finding an editor right now 🫡

[slayoo]

thank you!

[Batalex]

Sorry, I forgot to add something important to my previous message. Since our field of expertise is Python, the significant portion of C++ code in PyPartMC will only be evaluated on the best effort basis (which means that maybe it won't be evaluated). Our focus will be on the Python packaging side of the project.

[cmarmo]

Hello @slayoo, thank you for patience! I'm Chiara, I am following up as Editor in chief.
I am glad to announce that @russbiggs kindly accepted to serve as editor for your submission.
I'll let him introduce himself here and I wish you a happy review process!

[slayoo]

Thank you, @russbiggs and @cmarmo!

[russbiggs]

@slayoo Sorry for the slow start on my part as editor, I am currently seeking reviewers and will update as that progresses.