Picht

[rolypolytoy]

Submitting Author: (@rolypolytoy)
All current maintainers: (@rolypolytoy)
Package Name: Picht
One-Line Description of Package: Electron and ion optics simulation using the Finite Difference Method (FDM)
Repository Link: https://github.com/rolypolytoy/picht/
Version submitted: v2.1.0
EiC: @coatless
Editor: TBD
Reviewer 1: TBD
Reviewer 2: TBD
Archive:
JOSS DOI: 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 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.

Description

• Include a brief paragraph describing what your package does:
  Simulates electron and ion trajectories using the finite difference method. Exists as an easy, powerful alternative to commercial electrodynamics tools, and stands apart from existing open-source tools by using the finite difference method instead of the boundary element/finite element method, for better support in Dirichlet boundaries (grounded boundary conditions vs infinite). Uses the more physically accurate Lorentz force equation rather than the paraxial ray equation, computes relativistic corrections using the gamma factor, and calculates electron and ion trajectories through electrostatic lenses like cylindrical lenses and unipotential lenses. Example cases demonstrate physically realistic behaviors of electrons inside einzel lenses and through multi-lens systems, where Picht demonstrates simulations of complex focusing and defocusing behaviors, as well as crossovers, spherical aberration, and spot-size demagnification.

Scope

• Please indicate which category or categories.
  Check out our package scope page to learn more about our
  scope. (If you are unsure of which category you fit, we suggest you make a pre-submission inquiry):

  • Data retrieval
  • Data extraction
  • Data processing/munging
  • Data deposition
  • Data validation and testing
  • Data visualization¹
  • Workflow automation
  • Citation management and bibliometrics
  • Scientific software wrappers
  • Database interoperability

Domain Specific

• Geospatial
• Education

Community Partnerships

If your package is associated with an
existing community please check below:

• Astropy:My package adheres to Astropy community standards
• Pangeo: My package adheres to the Pangeo standards listed in the pyOpenSci peer review guidebook

• For all submissions, explain how and why the package falls under the categories you indicated above. In your explanation, please address the following points (briefly, 1-2 sentences for each):

Data Processing/Munging: Picht allows the initialization of custom electrode geometries and then generates electron trajectory data based on this. This allows a physically accurate analysis of the impact of variable geometries and voltages on charged particle beams of different kinds.

Scientific Software Wrappers: The code is modular enough to be used as a more general electrodynamics tool due to the clean nature of how the ODE solver can integrate with other functions, so I thought to put this in here too, since using scipy's ODE solvers for the niche application of numerical electrodynamics is novel enough to add to the scientific community, but derivative enough to require this category.

• Who is the target audience and what are scientific applications of this package?
  Researchers, startups, and students in electrodynamics, electron optics, electron microscopy, or nanofabrication. It can be used to simulate or prototype electrostatic lens systems, scanning electron microscopes using predominantly electrostatic lenses, focused ion beam systems, and some varieties of mass spectrometers. It is also useful as an educational tool in the field of electron optics because of how intuitive the syntax is and how intentionally constrained the features are. Its power is in the large amount of electrical and geometric parameterization it allows, rather than a large amount of prebuilt functions.

• Are there other Python packages that accomplish the same thing? If so, how does yours differ?
  There exists a similar package called Traceon (https://github.com/leon-vv/traceon) but it's distinct enough that it supports a different use case. Traceon assumes the user is fluent in meshing, has more support for 3D particle tracing than the axisymmetric view, and has a larger learning curve. Picht uses no approximations but instead uses the Lorentz force equation for guaranteeably accurate physical behavior, uses better boundary conditions, has much simpler dependency management, and is intentionally constrained in scope to enable rapid prototyping and easy syntax. In addition- commercial software packages like ANSYS Maxwell or COMSOL, as well as most open-source electrodynamics software like Traceon use Neumann boundary conditions natively rather than Dirichlet boundary methods- and the differences in boundary effects are distinct enough that this is an important point of clarification. Dirichlet boundary conditions more accurately simulate finite container conditions- where the electrodes are surrounded by metal grounded containers rather than in an infinitely open space or with insulators surrounding.

• If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted:

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. 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.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a tutorial with examples of its essential functions and uses.
• 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? If so:

JOSS Checks

• The package has an obvious research application according to JOSS's definition in their submission requirements. Be aware that completing the pyOpenSci review process does not guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
• The package is not a "minor utility" as defined by JOSS's submission requirements: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
• The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
• The package is deposited in a long-term repository with the DOI:

Note: JOSS accepts our review as theirs. You will NOT need to go through another full review. JOSS will only review your paper.md file. Be sure to link to this pyOpenSci issue when a JOSS issue is opened for your package. Also be sure to tell the JOSS editor that this is a pyOpenSci reviewed package once you reach this step.

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

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.

• 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. This helps us track
  submission and improve our peer review process. We will also ask our reviewers
  and editors to fill this out.

P.S. Have feedback/comments about our review process? Leave a comment here

Editor and Review Templates

The editor template can be found here.

The review template can be found here.

Footnotes

1. Please fill out a pre-submission inquiry before submitting a data visualization package. ↩

[coatless]

Editor in Chief checks

Hi there! 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.
• 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

Hi @rolypolytoy, thanks for submitting the package.

Installation hiccups

I'm running into issues installing it as you're using a newer version of NumPy v2.2.z with numpy.rec; however, there is a downstream dependency of thinc, mendeleev, and numba that are problematic:

thinc 8.3.6 requires numpy<3.0.0,>=2.0.0, but you have numpy 1.26.4 which is incompatible.
mendeleev 1.0.0 requires numpy<2.0,>=1.21; python_version < "3.12", but you have numpy 2.2.5 which is incompatible.
numba 0.60.0 requires numpy<2.1,>=1.22, but you have numpy 2.0.2 which is incompatible.

Test document here:

https://github.com/coatless/pyopensci-eic/blob/main/i242-picht.ipynb

Documentation

The package is missing a user-facing documentation website. Please see our guide here for help on creating docs using sphinx.

https://www.pyopensci.org/python-package-guide/documentation/index.html

Actions

Please address the above points and ping me to restart the EIC checklist once complete.

[rolypolytoy]

Hi @coatless,
I've fixed the issues with v1.1.1 in v1.1.4- I've compiled the release with numpy 1.26.4, and in the dependencies specified the usage of this file. Hopefully this resolves the dependency issues- I've tested it on Google Colab and it seems to be working fine. I did find that after I installed picht on the instance, to restart the session, otherwise it would still act like numpy 2.2.5 was active.

My test document is here:
https://github.com/rolypolytoy/testbed/blob/main/Picht.ipynb

I've also added a user-facing website using Github pages at: https://rolypolytoy.github.io/picht/ using Sphinx. I've kept in the installation instructions and tutorial examples. I've also added much cleaner documentation in the repository, including significantly more comments and docstrings to enable easy modification of the internals by potential contributors or forkers.

Let me know if you find any more bugs or need any more changes to this submission, I'm happy to improve Picht as much as necessary!

[coatless]

@rolypolytoy thanks for the update. I'm still running into version conflicts on Colab. That may be due to some underlying config or test group I'm in.

Running locally, the new versioned packages work:

Regarding the documentation site, there are still a few ways to go. We need the API documentation:

https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html

Alongside a package tutorial that differs from the README.md:

https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/create-package-tutorials.html

[rolypolytoy]

Hi @coatless,
Glad to see the package is working fine. The thinc message came up on my Jupyter notebook too, but it didn't interfere with my package's functioning, and you can safely run it without issues.

As for docstrings- I've added them to my code (https://github.com/rolypolytoy/picht/blob/main/picht/core.py) with better type hints and explanations of what everything does.

I've also added 3 new tutorial examples- to better enable people to create complex lens systems out of the box and avoid common design pitfalls, and I've only added it to the documentation website to provide a proper separation between the README.md and the documentation website, which is more in-depth: https://rolypolytoy.github.io/picht/

Let me know if there are any more changes that need to be made!

[coatless]

@rolypolytoy need docs site to include the API listing and new tutorials.

From our docs, you can see an example of the docstrings being converted to a web API:

https://www.fatiando.org/verde/latest/api/index.html

This requires using an extension:

https://www.pyopensci.org/python-package-guide/documentation/hosting-tools/sphinx-python-package-documentation-tools.html#sphinx-sites-can-be-customized-using-extensions-and-themes

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Lastly, for the new tutorials, you will need to enable Sphinx gallery likely:

https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/create-package-tutorials.html#nbsphinx-tutorials-using-jupyter-notebooks

[rolypolytoy]

@coatless
Ive added API documentation using sphinx autodoc at https://rolypolytoy.github.io/picht/api.html, and added sphinx gallery tutorials (5 total) at https://rolypolytoy.github.io/picht/auto_examples/index.html#.

[rolypolytoy]

@coatless sorry about the ping, just wanted to follow up to see if this fulfils the pre-review requirements

[coatless]

@rolypolytoy It would be good to streamline the navigation bar on the left hand side with a "Getting Started" Section first instead of the API.

https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/get-started.html#four-elements-of-a-good-open-source-documentation-landing-page

You can see the sidebar example structure here:

https://www.fatiando.org/verde/latest/index.html

The reason for these asks is both users and the reviewers will need a solid starting place to understand your package.

[rolypolytoy]

Of course, I'll make sure the website's a lot more intuitively structured and make the function and usability of Picht a lot more clear, I'll get back to you with the changes soon.

[rolypolytoy]

@coatless,
I've made the following changes to the website (https://rolypolytoy.github.io/picht/):
Added a 'Getting Started' section that's first on the sidebar and provides explanatory content, explains the scope of the library and provides additional information (https://rolypolytoy.github.io/picht/gettingstarted.html).

Added a Computational Physics section that explains the formalism of the library to better understand the computational physics concepts it uses (implicitly functions as both an 'About' section and a 'Contributing' section by explaining its internals to make it easier to contribute out-of-the-box). It explains how it solves for the electric field and gives a bit of background about FDM and why we use it: https://rolypolytoy.github.io/picht/physics.html

Manually created API documentation rather than using Sphinx Autodoc, making the API documentation noticeably cleaner: https://rolypolytoy.github.io/picht/api.html

Renamed the Tutorials section to Gallery, but otherwise kept it identical or near-identical: https://rolypolytoy.github.io/picht/auto_examples/index.html

Let me know about any more changes that'll improve Picht's presentation/appeal and any other pre-review steps necessary

[coatless]

@rolypolytoy thanks for the updates. I'll switch this to finding an editor. That might take some cycles given the topic.

[rolypolytoy]

Hi, just commenting here for transparency:
I've added a new update to Picht (v2.1.0) that adds magnetic lenses as an option. It's a minor update, and I've updated the API documentation, docstrings, computational physics section to all reflect the change, added pytest coverage for it as well (all tests passing!) and added a new gallery example for it as well. As any new updates happen and I add new features (because I'm still actively maintaining/developing Picht) CI/CD and documentation will always keep pace.

I have a full changelog at: https://github.com/rolypolytoy/picht/releases