Issue 2673: Rename binding_energy to remove ambiguity, add electron_binding_energy

[chasepd]

Description

Adds requested feature from #2673.

• Renames binding_energy to nuclear_binding_energy, but leaves binding_energy as a pointer to nuclear_binding_energy for backwards compatibility with a warning that it is deprecated and will be removed in a future release.
• Adds electron_binding_energy, defined as the sum of ionization_energy for all charge states above the given ionization.

Motivation and context

See #2673. With the addition of ionization energy data, calculating electron_binding_data becomes fairly easy. However, this causes binding_energy to be ambiguous/confusing, and is renamed to nuclear_binding_energy for clarity and greater specificity.

Related issues

Resolves #2673.

[github-actions]

Thank you for submitting a pull request (PR) to PlasmaPy! ✨ The future of the project depends on contributors like you, so we deeply appreciate it! 🌱

Our contributor guide has information on:

• Getting ready to contribute and the code contribution workflow
• Using astropy.units and plasmapy.particles
• Coding tips and guidelines
• Writing documentation (in reStructuredText with numpydoc style docstrings).
• Writing tests using pytest
• Adding a changelog entry (needed except for minor changes)

Important

PlasmaPy recently switched to an src layout. The source code previously in plasmapy/ is now in src/plasmapy/. Tests are now in tests/. If you have previously done an editable installation, it will likely need to be re-done (i.e., with pip install -e .[tests,docs] in the top-level directory of the repository). The former plasmapy/ directory will need to be deleted manually in old clones because git does not track directories.

The bottom of this page shows several checks that are run for every PR. Don't worry if something broke! We break stuff all the time. 😺 Click on "Details" to learn why a check didn't pass. Please also feel free to ask for help. We do that all the time as well. 🌸 You can find us in our chat room or weekly community meeting & office hours. Here are some tips:

• Try fixing CI / Python 3.12 test failures first.
• Most pre-commit.ci - pr failures can be automagically fixed by commenting pre-commit.ci autofix below, followed by a git pull to bring the changes back to your computer. Please also see our pre-commit troubleshooting guide.
• If pre-commit.ci - pr says that a function is too long or complex, try breaking up that function into multiple short functions that each do one thing. See also these tips on writing clean scientific software.
• If the CI / Documentation check ends with a cryptic error message, check out our documentation troubleshooting guide.
• For a documentation preview, click on Details next to docs/readthedocs.org:plasmapy.

If this PR is marked as ready for review, someone should stop by to provide a code review and offer suggestions soon. ✅ If you don't get a review within a few days, please feel free to send us a reminder.

Please also use SI units within PlasmaPy, except when there is strong justification otherwise or in some examples.

We thank you once again!

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.24%. Comparing base (24d83fb) to head (4822922).

❗ Current head 4822922 differs from pull request most recent head 027f164. Consider uploading reports for the commit 027f164 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2693      +/-   ##
==========================================
+ Coverage   94.90%   95.24%   +0.34%     
==========================================
  Files         104      104              
  Lines        9435     9468      +33     
  Branches     2159     2171      +12     
==========================================
+ Hits         8954     9018      +64     
+ Misses        299      273      -26     
+ Partials      182      177       -5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[chasepd]

@pheuer - here's a new PR from a fresh branch!

[pheuer]

@pheuer - here's a new PR from a fresh branch!

Thank you!!! Here's a couple comments:

1. Can you make it work for isotopes, similar to the ionization_energy property? E.g.

Particle("C +3").electron_binding_energy == Particle("C-12+3").electron_binding_energy
>True

Right now the isotope just raises an exception. Again, should work for everything above hydrogen, but return separate values for the hydrogen isotopes since the ionization energies are measurably different there.

2. I think you might be adding one too few ionization energies onto the list?

Particle("C +3").electron_binding_energy.to(u.eV) 
> 882.08 eV 

But according to the NIST database, that's the ionization energy of C+4, and C+3 should be 946.57 eV. Binding energy being the energy required to free every electron the ion has. This is a little confusing, so maybe you could clarify conceptually a bit in the docstring?

Otherwise this looks great to me, thanks again for doing this!