added examples in boris_push docstring #1556
Conversation
There was a problem hiding this comment.
Thank you for making your first contribution to PlasmaPy! The project's future depends on contributors like you, so we deeply appreciate it! 🌱
To make sure that you get credit for this pull request (PR), please add yourself to the list of contributors in docs/about/credits.rst.
We encourage you to check out our contributor guide, which discusses topics like adding changelog entries. If you'd like to talk with us in real time, the easiest way is via our chat room. We also invite you to stop by our weekly community meeting or office hours.
The bottom of this page includes several checks that are run for every PR. Don't worry if something broke! We break stuff all the time. Eventually we'll want to get checks on this PR to pass before merging it. Clicking on Details next to the check will show the results of the test, including error messages. Please feel free to ask for help if you're having trouble (we do that all the time, as well).
Our testing guide describes these checks in more detail, as well as how to write and run tests. We recommend trying out test-driven development: write tests first, and then write code to make tests pass. Remember to run tests often!
As described in our documentation guide, PlasmaPy's documentation is written in reStructuredText using the numpydoc docstring standard. To see a preview of the documentation from this PR, click on Details next to the docs/readthedocs.org:plasmapy check.
To automagically fix most linter problems, comment on this PR with pre-commit.ci autofix, followed by a git pullto bring the changes home to your own computer.
A code maintainer should come by soon to begin a code review. This step often includes suggestions for fixing bugs, adding tests, or simplifying the implementation. After that you'll have a chance to make changes. If you'd like more time before a code review happens, you can convert this PR to a draft now and mark it as ready for review later.
Finally, we try to be the best community we can be. We have a Code of Conduct to foster a community of care and appreciation.
We thank you once again! ✨
| >>> plt.plot(x,y) | ||
| >>> plt.xlabel('x [m]') | ||
| >>> plt.ylabel('y [m]') | ||
| >>> plt.title(r"Single particle motion without $\vec{E}$ field") | ||
| >>> plt.grid() | ||
| >>> plt.gca().set_aspect('equal') |
There was a problem hiding this comment.
Rather than plotting, which is not going to display in rendered docs at https://docs.plasmapy.org/en/stable/api/plasmapy.simulation.particle_integrators.boris_push.html#plasmapy.simulation.particle_integrators.boris_push and is best kept in jupyter notebooks such as https://docs.plasmapy.org/en/stable/notebooks/ExB_drift.html, perhaps we can instead display a few examples? This chains into something I also just realized...
| >>> y = [] | ||
| >>> | ||
| >>> for _ in range(150): | ||
| >>> boris_push(x = x_0, v = v_0, B=B, E=0, q=1.0, m=1.0, dt=0.01) |
There was a problem hiding this comment.
So I just realized that the boris_push implementation we've got here only modifies the input x, v arrays. This is good for performance but is dreadful for quickly displaying how it works. I think adding an inplace = False keyword argument would be okay both for docs and for future developments here (for example I have a couple ideas on doing this through jax or some such optimizer...), if you'd be up for it!
And then, rather than having an embedded minimal simulation here, I think it'd be better to show how how to use the boris pusher:
- how it returns the x, v arrays in the next time step (the essence of what it does)
- how it modifies the x, v arrays by default (show them before/after)
- how, for B parallel to V, it does nothing;
- what it does for B perpendicular to V;
- how for nonzero E and zero B it reduces to the leapfrog algorithm.
Also, to easily do this from the IPython shell, try the %doctest_mode magic command:
[ins] In [1]: %doctest_mode
Exception reporting mode: Plain
Doctest mode is: ON
>>> 2 + 2
4
There was a problem hiding this comment.
Ok I will work on that and prepare new version in accordance with your suggestions.
|
So, uh, I guess this one issue was a bit under-specified 😅 |
|
pre-commit.ci autofix |
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
Hey, finally circled back to looking into this! I'm sorry for the long delay, a lot has been happening, as you likely well know :) Looks great, I do have one minor suggestion though - changing the default back to the previous one.
If you agree with the proposed changes, we can merge this pretty quickly. It would still need a changelog entry, but besides that, it looks pretty much done.
|
I also think merging the suggestions (or doing anything to the branch, really) and re-triggering CI might get rid of some of the noise from the Documentation test 😅 |
Co-authored-by: Dominik Stańczak <stanczakdominik@gmail.com>
Co-authored-by: Dominik Stańczak <stanczakdominik@gmail.com>
Co-authored-by: Dominik Stańczak <stanczakdominik@gmail.com>
Unfortunately, I continue to get errors related to the documentation :( |
|
Let's see if that fixes things. The doc build seems to have been an unrelated issue fixed elsewhere (that's distributed project development for ya, sorry I missed it! 😅). I also adjusted the doctest values for a few changes where they started differing from what we actually got. |
Codecov Report
@@ Coverage Diff @@
## main #1556 +/- ##
=======================================
Coverage 97.22% 97.22%
=======================================
Files 84 84
Lines 8000 8003 +3
=======================================
+ Hits 7778 7781 +3
Misses 222 222
Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. |
This reverts commit 3ee721a.
The detail on the ``inplace`` keyword seemed different from the docstring description, so I dropped the description from the changelog entry.
docstrings.
pre-commit.ci autofix