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: @cmarmo
Reviewer 1: @simonom
Reviewer 2: @dbaston
Archive:
Version accepted: 1.4.2
Date accepted (month/day/year): 02/12/2025

---

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.

[cmarmo]

@simonom I took the liberty to highlight the traceback in your previous comment.

I see you are using a miniconda installation, in order to move forward with the review, may I suggest to create a conda/mamba environment with a 3.12 python version?
So we do not need to wait for a 3.13 wheel: the 3.13 wheel build can be a review recommendation though....

Also @dbaston, @simonom , please let me know if the review deadline is realistic.

Thank you! 🙏

[simonom]

@cmarmo, yes, I will continue with a compatible python version, and yes, deadline can be met!

[slayoo]

@simonom

I am struggling with pip install PyPartMC at command line on an Apple M2 Pro (macOS Sonoma).

So far, we have not yet produced binary wheels for Python 3.13, please stay tuned, hope to roll these out in the coming days at least for macOS.

As of PyPartMC v1.3.10 (released earlier today), there are binary wheels on PyPI for Python 3.13 on macOS. Supported OS versions are: macosx-13 (universal binary) and macosx-14 (ARM binary). Hope it helps! Feedback welcome.

Note that Python 3.13 is not fully supported in auxiliary packages used in PyPartMC example notebooks, notably:

• PyMieScatt used in the mie_optical.ipynb example requires installation from GitHub instead of PyPI (pip install git+https://github.com/bsumlin/PyMieScatt.git) to work due to Python 3.13 implying newer SciPy (reported upstream)
• PySDM used in lognorm_ex.ipynb and in terminal_velocities.ipynb uses Numba which requires pre-release version to be compatible with Python 3.13 (pip install numba==0.61.0rc1), but it anyhow fails on ARM CPUs (reported upstream)

[dbaston]

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README.
• Installation instructions: for the development version of the package and any non-standard dependencies in README.

I did not find instructions for installing the development version. After pulling the submodules, running pip install . from the project root successfully installed the package.

• Vignette(s) demonstrating major functionality that runs successfully locally.

I ran the notebooks on Google Colab without issue. It would be helpful to have instructions for running the notebooks locally, as additional dependencies such as open_atmos_jupyter_utils are required. The notebooks would benefit from narrative text explaining the purpose of each notebook, and an explanation of what is being performed in each cell.

• Function Documentation: for all user-facing functions.

While the documentation contains an entry for user-facing functions, it isn't always clear what the expected arguments or return values are. Some argument names are not rendered in the documentation. For example, Scenario.init_env_state lists argument names arg0 and arg1 instead of the names env_state and time that can be found in the sources. In other cases, argument types indicate that JSON is expected but do not describe the expected content of that JSON. Some functions also lack descriptions (e.g., AeroMode.vol_frac, AeroMode.gsd). The markup language used in the docstings is not fully recognized when generating HTML documentation and produces output such as \c name(i) is the name of that species.

• Examples for all user-facing functions.

I did not find examples in the Python API documentation.

• Community guidelines including contribution guidelines in the README or CONTRIBUTING.

It would be helpful to describe how someone can contribute to the documentation. This may be as simple as describing where the docstring text can be found.

• Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a pyproject.toml file or elsewhere.

Included in setup.py file. The project does not have a pyproject.toml.

Readme file requirements
The package meets the readme requirements below:

• Package has a README.md file in the root directory.

The README should include, from top to bottom:

• The package name
• Badges for:
  • Continuous integration and test coverage,
  • Docs building (if you have a documentation website),
  • A repostatus.org badge,
  • Python versions supported,
  • Current package version (on PyPI / Conda).

NOTE: If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the a badge for pyOpenSci peer-review will be provided upon acceptance.)

• Short description of package goals.
• Package installation instructions
• Any additional setup required to use the package (authentication tokens, etc.)

None required.

• Descriptive links to all vignettes. If the package is small, there may only be a need for one vignette which could be placed in the README.md file.
  • Brief demonstration of package usage (as it makes sense - links to vignettes could also suffice here if package description is clear)
• Link to your documentation website.
• If applicable, how the package compares to other similar packages and/or how it relates to other packages in the scientific ecosystem.

Described in the linked paper.

• Citation information

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole.
Package structure should follow general community best-practices. In general please consider whether:

• Package documentation is clear and easy to find and use.
• The need for the package is clear
• All functions have documentation and associated examples for use
• The package is easy to install

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.

Did not evaluate.

• Performance: Any performance claims of the software been confirmed.

Did not evaluate.

• Automated tests:
  • All tests pass on the reviewer's local machine for the package version submitted by the author. Ideally this should be a tagged version making it easy for reviewers to install.

Did not see instructions for running tests. Tests run successfully using pytest tests.

• Tests cover essential functions of the package and a reasonable range of inputs and conditions.

Did not evaluate. A code coverage report of the C++ binding code would be useful.

• Continuous Integration: Has continuous integration setup (We suggest using Github actions but any CI platform is acceptable for review)
• Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.

PyPartMC uses a custom setup.py instead of the pyproject.toml discussed in the packaging guidelines. Because the project is built using CMake, it may be straightforward to switch to a pyproject.toml and scikit-build-core.

It wasn't clear to me why C++ class methods were implemted as static methods manually taking a reference to self. The pattern is followed consistently, however.

A few notable highlights to look at:
- [X] Package supports modern versions of Python and not [End of life versions](https://endoflife.date/python).

- [X] Code format is standard throughout package and follows PEP 8 guidelines (CI tests for linting pass)

For packages also submitting to JOSS

• The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

• A short summary describing the high-level functionality of the software
• Authors: A list of authors with their affiliations
• A statement of need clearly stating problems the software is designed to solve and its target audience.
• References: With DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 6

---

Review Comments

This package cleanly exposes Fortan code to Python using pybind11. I did not see any serious code quality issues. Tests run smoothly but I was not able to easily determine which code is covered by the tests.

HDF and netCDF being fairly common libraries, I wonder about the potential for runtime issues if the version vendored by PyPartMC differs from a version loaded by another package such as netCDF4 or h5py.

[slayoo]

Thank you @dbaston! Your work is much appreciated and helpful.
We've started working on addressing the feedback and will report back here.

[simonom]

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README.

The authors could be more explicit in the README introduction, such as providing an example of the user you are serving. Actually, the goals stated in the ‘Target audience and scientific applications’ sections of the review page (PyPartMC · Issue #179 · pyOpenSci/software-submission) seem very suitable for this section.

• Installation instructions: for the development version of the package and any non-standard dependencies in README.

The user could benefit from some description around the pip install PyPartMC command to explain that CMake and a fortran compiler are required. This is well detailed in the FAQs, but it makes sense for these dependencies to be stated before the pip install instruction for PyPartMC, including the necessary versions (e.g. python).

• Vignette(s) demonstrating major functionality that runs successfully locally.
• Function Documentation: for all user-facing functions.

The API documentation is very valuable for explaining how a user can set inputs for functions, but the link is somewhat hidden in the Features section of README. I suggest a more obvious presence in README.

• Examples for all user-facing functions.
• Community guidelines including contribution guidelines in the README or CONTRIBUTING.
• Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a pyproject.toml file or elsewhere.

In CITATION.cff is author information in addition to a doi to an associated published paper. In Credits of README is funding information.

Readme file requirements
The package meets the readme requirements below:

• [x ] Package has a README.md file in the root directory.

The README should include, from top to bottom:

• The package name
• Badges for:
  • Continuous integration and test coverage,
  • Docs building (if you have a documentation website),
  • A repostatus.org badge,
  • Python versions supported,
  • Current package version (on PyPI / Conda).

Would be useful to have a repostatus badge.

NOTE: If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the a badge for pyOpenSci peer-review will be provided upon acceptance.)

• Short description of package goals.

The authors could be more explicit in the README introduction, such as providing an example of the user you are serving. Actually, the goals stated in the ‘Target audience and scientific applications’ sections of the review page (PyPartMC · Issue #179 · pyOpenSci/software-submission) seem very suitable for this section.

• Package installation instructions

Because the README does not contain a section titled ‘Installation’ it is really easy to miss the ‘pip install PyPartMC’ command, so recommend making this clearer. Preferably this installations section would also describe the dependencies on Fortran and CMake.

• Any additional setup required to use the package (authentication tokens, etc.)

Not applicable for local install, and additional setup for vignettes is well described

• Descriptive links to all vignettes. If the package is small, there may only be a need for one vignette which could be placed in the README.md file.

I think the vignettes are a real strong point of the repository.

- [x] Brief demonstration of package usage (as it makes sense - links to vignettes could also suffice here if package description is clear)

The python and Julia example are provided. Like with the Short description of package goals (for which I recommend an example of a target user), it would help to have more detail in the ‘Usage examples’ introduction about why a user would be interested in randomly sampling particles from an aerosol size distribution. I think this is particularly important because PyPartMC is aiming to draw in more novice users of PartMC, so these people will potentially be new to PartMC.

• Link to your documentation website.

As stated by me in the Function Documentation: section above, it would be useful to have the link to the API docs more visible than the brief mention in the Features section.

• If applicable, how the package compares to other similar packages and/or how it relates to other packages in the scientific ecosystem.

I think this section needs including in the README, particularly as the package is an interface to another package (PartMC). This section would be an opportunity to really clearly explain what the implications of using this package are over using the PartMC package directly. It would also be good to include in this section the references included in ‘Other Python packages with relevant feature scope’ in the review page (PyPartMC · Issue #179 · pyOpenSci/software-submission)

• Citation information

I think this section needs including in the README, particularly as the package is an interface to another package (PartMC). This section would be an opportunity to really clearly explain what the implications of using this package are over using the PartMC package directly. It would also be good to include in this section the references included in ‘Other Python packages with relevant feature scope’ in the review page (PyPartMC · Issue #179 · pyOpenSci/software-submission)

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole.
Package structure should follow general community best-practices. In general please consider whether:

• Package documentation is clear and easy to find and use.

See notes above on clearer linking to the API Docs in README

• The need for the package is clear

See notes above on clearer linking to the API Docs in README

• All functions have documentation and associated examples for use

The API Docs are impressive, and some examples are also provided

• The package is easy to install

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.
• Performance: Any performance claims of the software been confirmed.
• Automated tests:
  • All tests pass on the reviewer's local machine for the package version submitted by the author. Ideally this should be a tagged version making it easy for reviewers to install.

Some tests need pytest installed, so this should be stated along with other install depenencies

• Tests cover essential functions of the package and a reasonable range of inputs and conditions.
• Continuous Integration: Has continuous integration setup (We suggest using Github actions but any CI platform is acceptable for review)

I can see that CI is setup in the .github/workflows folder, but note that the link in the ‘CI builds’ text in ‘Features’ of README is broken

• Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.
  A few notable highlights to look at:
  • Package supports modern versions of Python and not End of life versions.
  • Code format is standard throughout package and follows PEP 8 guidelines (CI tests for linting pass)

For packages also submitting to JOSS

• The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

• A short summary describing the high-level functionality of the software
• Authors: A list of authors with their affiliations
• A statement of need clearly stating problems the software is designed to solve and its target audience.
• References: With DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 7

---

Review Comments

I've enjoyed reviewing this package, which has been very well put together overall. The comments I have provided I believe cover just minor changes.

[cmarmo]

Hello everybody and happy new year to all of you!
I hope you enjoyed some holiday break, we are now back to business and I wondering if we can set a timeline for the answers to the reviewers.

@slayoo, do you think it will be possible for you to answer the comments and fix the fixable issues by the end of January?
Thank you very much for your work.

[slayoo]

Yes, I confirm we will report back by the end of January. Thank you, @cmarmo.
Thank you, @dbaston and @simonom for the reviews!

[slayoo]

Just confirming we're working towards addressing the feedback from both reviews. A couple of PRs already merged over the last days, including codecov integration (open-atmos/PyPartMC#397), README updates (open-atmos/PyPartMC#396), more narrative in the example notebooks (open-atmos/PyPartMC#398, open-atmos/PyPartMC#383); let me report a point-by-point summary by the end of the weekend, thank you for your patience.

[slayoo]

Here's a point-by-point reply to the comments by @dbaston. Thank you for very helpful feedback!

I did not find instructions for installing the development version. After pulling the submodules, running pip install . from the project root successfully installed the package.

The CONTRIBUTING.md file features a section with a brief info on how to set up a development (debugging) setup: https://github.com/open-atmos/PyPartMC/blob/main/CONTRIBUTING.md#how-to-debug
A new issue was created to track improvements to the CONTRIBUTING.md file: open-atmos/PyPartMC#406

I ran the notebooks on Google Colab without issue. It would be helpful to have instructions for running the notebooks locally, as additional dependencies such as open_atmos_jupyter_utils are required.

This information was previously hidden in the .binder/requirements.txt file (used also in the CI). In open-atmos/PyPartMC#402, we have moved this metadata into setup.py introducing the "examples" installation variant. An indication that pip install PyPartMC[examples] can be used to obtain dependencies for the examples was added to the README.md.

The notebooks would benefit from narrative text explaining the purpose of each notebook, and an explanation of what is being performed in each cell.

PR's open-atmos/PyPartMC#398, open-atmos/PyPartMC#383 and open-atmos/PyPartMC#376 introduced narrative text to three of the examples. There is, clearly, still room for improvement, but we expect that these three examples will also serve as templates for further developments of the descriptive part of PyPartMC example notebooks.

While the documentation contains an entry for user-facing functions, it isn't always clear what the expected arguments or return values are. Some argument names are not rendered in the documentation. For example, Scenario.init_env_state lists argument names arg0 and arg1 instead of the names env_state and time that can be found in the sources. In other cases, argument types indicate that JSON is expected but do not describe the expected content of that JSON. Some functions also lack descriptions (e.g., AeroMode.vol_frac, AeroMode.gsd). The markup language used in the docstings is not fully recognized when generating HTML documentation and produces output such as \c name(i) is the name of that species.
I did not find examples in the Python API documentation.

In short, this is not addressed yet. We have, though, linked the above comments from two outstanding issues relevant to the docs:

• add a check that all docstrings can be found in PartMC fortran code (so that if some text is fixed/removed from PartMC we are notified upon submodule update) + handle Doxygen -> docstring format conversion open-atmos/PyPartMC#31 to somehow automatically check the consistency of PyPartMC docstrings and PartMC doxygen string, so that these become maintainable; an automatic conversion from the Doxygen hypertext syntax to something properly renderable by pdoc should be part of it)
• lack of hyperlinks from type names in docs (since introduction of the _PyPartMC module "hack" for Windows & Python >=3.8); also some function signatures have arg0, arg1 with no types open-atmos/PyPartMC#99 (need to fix hyperlinks for PyPartMC datatypes in the pdoc-generated HTML)

It would be helpful to describe how someone can contribute to the documentation. This may be as simple as describing where the docstring text can be found.

note taken in the CONTRIBUTING.md-enhancements issue: open-atmos/PyPartMC#406

Included in setup.py file. The project does not have a pyproject.toml.

For now, a new issue (with a "help wanted" label) was created: open-atmos/PyPartMC#403

A repostatus.org badge

Added in open-atmos/PyPartMC#396

[ ] All functions have documentation and associated examples for use

To this end, one idea is to introduce a mechanism that will automatically verify if all docstrings in PyPartMC match the Doxygen comments from PartMC Fortran code. It is not entirely doable (perhaps this could be limitted to a subset of the docstring), but a starting point for brainstorming: open-atmos/PyPartMC#31

Did not see instructions for running tests. Tests run successfully using pytest tests.

The CONTRIBUTING.md file has a section hinting how to run the tests: https://github.com/open-atmos/PyPartMC/blob/main/CONTRIBUTING.md#how-to-debug

A code coverage report of the C++ binding code would be useful.

Added in open-atmos/PyPartMC#397
It covers both C++ and Fortran code of the bindings.
Reports and stats available at: https://app.codecov.io/gh/open-atmos/PyPartMC

PyPartMC uses a custom setup.py instead of the pyproject.toml discussed in the packaging guidelines. Because the project is built using CMake, it may be straightforward to switch to a pyproject.toml and scikit-build-core.

Not completed yet, but an issue was created to track progress on it: open-atmos/PyPartMC#403

It wasn't clear to me why C++ class methods were implemted as static methods manually taking a reference to self. The pattern is followed consistently, however.

Noted in the CONTRIBUTING.md0enhancements issue to clarify the above pattern: open-atmos/PyPartMC#406

HDF and netCDF being fairly common libraries, I wonder about the potential for runtime issues if the version vendored by PyPartMC differs from a version loaded by another package such as netCDF4 or h5py.

Earlier in the development, we have noted that SciPy includes parts of SUNDIALS which are also statically linked within PyPartMC. SciPy is used in the examples, so the CI runs include cases where both are loaded (relevant notes: open-atmos/PyPartMC#16). It seems that it is not an issue, but indeed a clarification why would best be added, e.g., to the CONTRIBUTING.md file: note taken in open-atmos/PyPartMC#406

[slayoo]

Here's a point-by-point reply to the comments by @simonom. Thank you for very helpful feedback!

The authors could be more explicit in the README introduction, such as providing an example of the user you are serving. Actually, the goals stated in the ‘Target audience and scientific applications’ sections of the review page (PyPartMC · Issue #179 · pyOpenSci/software-submission) seem very suitable for this section.

Added in open-atmos/PyPartMC#396

The user could benefit from some description around the pip install PyPartMC command to explain that CMake and a fortran compiler are required. This is well detailed in the FAQs, but it makes sense for these dependencies to be stated before the pip install instruction for PyPartMC, including the necessary versions (e.g. python).

The following passage was added early in the README as a part of open-atmos/PyPartMC#396:

Note that, depending on the environment (OS, hardware, Python version), the pip-install invocation may either trigger a download of a pre-compiled binary, or trigger compilation of PyPartMC. In the latter case, a Fortran compiler and some development tools includiong CMake, m4 and perl are required (while all non-Python dependencies are included in the PyPartMC source archive). In both cases, all Python dependencies will be resolved by pip.

The API documentation is very valuable for explaining how a user can set inputs for functions, but the link is somewhat hidden in the Features section of README. I suggest a more obvious presence in README.

A sentence with a link to the docs was added to the second paragraph of the README in open-atmos/PyPartMC#407

Would be useful to have a repostatus badge.

Added in open-atmos/PyPartMC#396

The authors could be more explicit in the README introduction, such as providing an example of the user you are serving. Actually, the goals stated in the ‘Target audience and scientific applications’ sections of the review page (PyPartMC · Issue #179 · pyOpenSci/software-submission) seem very suitable for this section.

ditto - added in open-atmos/PyPartMC#396

Because the README does not contain a section titled ‘Installation’ it is really easy to miss the ‘pip install PyPartMC’ command, so recommend making this clearer. Preferably this installations section would also describe the dependencies on Fortran and CMake.

"Installation" section added in open-atmos/PyPartMC#408

The python and Julia example are provided. Like with the Short description of package goals (for which I recommend an example of a target user), it would help to have more detail in the ‘Usage examples’ introduction about why a user would be interested in randomly sampling particles from an aerosol size distribution. I think this is particularly important because PyPartMC is aiming to draw in more novice users of PartMC, so these people will potentially be new to PartMC.

With the README growing in size, we opt for focusing on explanations of the concepts such as sampling in the examples. To this end, the "urban plume" example was extended with broader narrative commenting on each step of a simulation: open-atmos/PyPartMC#398

As stated by me in the Function Documentation: section above, it would be useful to have the link to the API docs more visible than the brief mention in the Features section.

Addressed in open-atmos/PyPartMC#407

If applicable, how the package compares to other similar packages and/or how it relates to other packages in the scientific ecosystem.
I think this section needs including in the README, particularly as the package is an interface to another package (PartMC). This section would be an opportunity to really clearly explain what the implications of using this package are over using the PartMC package directly. It would also be good to include in this section the references included in ‘Other Python packages with relevant feature scope’ in the review page (PyPartMC · Issue #179 · pyOpenSci/software-submission)

List of other packages with relevant features added in open-atmos/PyPartMC#404

Citation information

Added in open-atmos/PyPartMC#405

Some tests need pytest installed, so this should be stated along with other install depenencies

The CONTRIBUTING.md file is undergoing enhancements (open-atmos/PyPartMC#409) addressing several issues note in the reviews (open-atmos/PyPartMC#406).

I can see that CI is setup in the .github/workflows folder, but note that the link in the ‘CI builds’ text in ‘Features’ of README is broken

Fixed in open-atmos/PyPartMC#410

[slayoo]

@cmarmo, @dbaston, @simonom
Thank you for your valuable feedback and the effort, which we also acknowledged in the Release notes for the just-released PyPartMC v1.4.0: https://github.com/open-atmos/PyPartMC/releases/tag/v1.4.0

[slayoo]

And thanks to all PyPartMC developers who contributed to the recent sprint: @nriemer, @mwest1066, @jcurtis2, @emmacware, @zdaq12, @klee-48 & @Griger5

[cmarmo]

Thank you @slayoo and all the contributors for your work.

@dbaston , @simonom are the maintainer answer acceptable?
If I understand correctly all the comments weren't addressable right now, so issues are still open, but they are acknowledged by the authors who are willing to address them in the future.
Is this kind of approach fine with you?

Please let us know.

As the authors do not plan to submit to JOSS, this is the last step before acceptance.

[simonom]

Thanks, I will review tomorrow morning

[simonom]

@cmarmo, I have looked through the detailed response to referee comments, and conclude the associated updates satisfy the comments. I therefore recommend acceptance as is.

[dbaston]

Yes, I recommend the package be accepted. I especially appreciate the additions to the first notebook and the creation of a code coverage report.

[cmarmo]

🎉 I am very happy to announce then, that PyPartMC has been approved by pyOpenSci!
Thank you @slayoo and co-authors for submitting PyPartMC and many thanks to @simonom and @dbaston for reviewing this package! 😸

Please let me know by commenting in the issue or by e-mail if you are interested in an invite to the pyOpenSci Slack.

Also @slayoo, I am going to announce the approval on our discourse, if you are planning to share your experience with pyOpenSci in a blog post or social posts, please let me know so I can link them to the announcement.

Author Wrap Up Tasks

There are a few things left to do to wrap up this submission:

• Activate Zenodo watching the repo if you haven't already done so.
• Tag and create a release to create a Zenodo version and DOI.
• Add the badge for pyOpenSci peer-review to the README.md of . The badge should be [![pyOpenSci Peer-Reviewed](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/issue-number).
• Please fill out the post-review survey. All maintainers and reviewers should fill this out.

Editor Final Checks

Please complete the final steps to wrap up this review. Editor, please do the following:

• Make sure that the maintainers filled out the post-review survey
• Invite the maintainers to submit a blog post highlighting their package. Feel free to use / adapt language found in this comment to help guide the author.
• Change the status tag of the issue to 6/pyOS-approved6 🚀🚀🚀.
• Invite the package maintainer(s) and both reviewers to slack if they wish to join.

---

If you have any feedback for us about the review process please feel free to share it here. We are always looking to improve our process and documentation in the peer-review-guide.

[slayoo]

thank you, @dbaston, @simonom and @cmarmo

✓pyOpenSci badge just added: open-atmos/PyPartMC#415
✓post-review survey filled in