Implement NIST STAR Data

[JaydenR2305]

Implements the ability to calculate stopping power for alpha particles and protons in a specified material using the NIST ASTAR and PSTAR databases, respectively. The data for this pull request can be found here

Resolves #2517

[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)

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!

[JaydenR2305]

@namurphy I wasn't quite sure where to put this function.. Where do you think it should go?

[JaydenR2305]

Just to ensure that the pulled hdf5 file has accurate data, here is data I pulled directly from the PSTAR website (blue) plotted with data from the hdf5 file (orange). This particular plot is for the total stopping power of hydrogen

[JaydenR2305]

@pheuer Do you know what's causing these ReadTimeout errors??

[pheuer]

@pheuer Do you know what's causing these ReadTimeout errors??

Hm, does the test pass locally? The file/url it is trying to reach is definitely valid?

One thing you might want to do to limit test time/number of API queries is to use an unvalidated downloader in the tests (except for maybe one, that confirms the file is accessible). See example of how I did that here:

PlasmaPy/tests/utils/data/test_downloader.py

Line 11 in 534b8e9

def in_ci() -> bool:

But, that shouldn't explain the read timeout, since even in the unvalidated mode downloader still has to download from the raw github URL...

[JaydenR2305]

One thing you might want to do to limit test time/number of API queries is to use an unvalidated downloader in the tests (except for maybe one, that confirms the file is accessible).

Does this mean we would take a Downloader instance as an optional parameter for stopping_power ?

[pheuer]

Does this mean we would take a Downloader instance as an optional parameter for stopping_power ?

Or you could add a switch inside stopping_power that automatically uses the unvalidated downloader if CI is detected?

It might be best practice to just say that any function that internally uses Downloader should allow an instance to be passed as an optional argument, just for this kind of thing, though?

[JaydenR2305]

@pheuer What are your thoughts on implicitly setting the API token if it is detected that the code is being run in a CI environment? That is, if an API key is not explicitly passed during instantiation then os.environ["GH_TOKEN"] would be used.

This way we don't need to complicate things by introducing optional keywords for Downloader objects and remembering that we have to pass one in every time we write tests involving the downloader

[pheuer]

@pheuer What are your thoughts on implicitly setting the API token if it is detected that the code is being run in a CI environment? That is, if an API key is not explicitly passed during instantiation then os.environ["GH_TOKEN"] would be used.

This way we don't need to complicate things by introducing optional keywords for Downloader objects and remembering that we have to pass one in every time we write tests involving the downloader

Hm, that's a good idea for now! It's not exactly equivalent to unvalidated (still makes queries to find the file I think) but that's ok.

Make sure you include a comment in the test explaining what you're doing.

[codecov]

Codecov Report

Attention: Patch coverage is 94.44444% with 2 lines in your changes are missing coverage. Please review.

Project coverage is 95.21%. Comparing base (534b8e9) to head (2455f67).
Report is 4 commits behind head on main.

❗ Current head 2455f67 differs from pull request most recent head bef6384

Please upload reports for the commit bef6384 to get more accurate results.

Files	Patch %	Lines
src/plasmapy/particles/atomic.py	93.75%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2555      +/-   ##
==========================================
- Coverage   95.25%   95.21%   -0.04%     
==========================================
  Files         104      104              
  Lines        9435     9435              
  Branches     2159     2167       +8     
==========================================
- Hits         8987     8984       -3     
- Misses        272      273       +1     
- Partials      176      178       +2     

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

[JaydenR2305]

How should I add coverage for these lines?

PlasmaPy/src/plasmapy/particles/atomic.py

Lines 1238 to 1241 in fe4ed92

	return (
	baseline_energies_data * u.MeV,
	relevant_stopping_data * u.MeV * u.cm**2 / u.g,
	)

The returned result can have some ~100 entries.

[JaydenR2305]

also why does this have partial coverage? It looks like the code under the elseif statement is being executed fine?

https://app.codecov.io/gh/PlasmaPy/PlasmaPy/pull/2555/blob/src/plasmapy/particles/atomic.py#L595

[pheuer]

How should I add coverage for these lines?

PlasmaPy/src/plasmapy/particles/atomic.py

Lines 1238 to 1241 in fe4ed92

	return (
	baseline_energies_data * u.MeV,
	relevant_stopping_data * u.MeV * u.cm**2 / u.g,
	)

The returned result can have some ~100 entries.

It looks like this isn't being hit just because all the test cases supply energies? You could include one separate test that doesn't supply an energies vector, then just confirm that you get the tuple out?

also why does this have partial coverage? It looks like the code under the elseif statement is being executed fine?

https://app.codecov.io/gh/PlasmaPy/PlasmaPy/pull/2555/blob/src/plasmapy/particles/atomic.py#L595

I've no idea about this, weird...

[pheuer]

These two branches aren't getting hit: I would add one more test/test case that asks for the electronic and then the nuclear stopping power

[JaydenR2305]

any ideas on this?
https://github.com/PlasmaPy/PlasmaPy/actions/runs/9291692287/job/25570832682#step:6:118

[JaydenR2305]

pre-commit.ci autofix

[pheuer]

Looks good!