Codecov Report

Merging #1305 (b9673da) into main (34c717c) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #1305   +/-   ##
=======================================
  Coverage   97.09%   97.09%           
=======================================
  Files          81       81           
  Lines        7679     7679           
=======================================
  Hits         7456     7456           
  Misses        223      223           

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 34c717c...b9673da. Read the comment docs.

Reminders to myself:

• I'll probably be making a bunch of changes to docs/common_links.rst which is a frequently edited file. To start out with I should put all of the newly defined links at the bottom of code_guide.rst, and then move them to docs/common_links.rst later on in order to avoid dreaded merge conflicts of joy and despair.
• It might be helpful to add in here how instead of having a function like def f(): return x, y we can create a namedtuple to use as the output so that we can use output.x and output.y.
• We should also add a discussion on licensing, including: license compatibility, how limitations on licenses of databases that restrict data redistribution are
• We want to balance "concise" and "comprehensive"

• (Briefly) describe the different techniques use to optimize code. (Maybe a different PR, but if so, raise an issue instead.)

How to import functionality from plasmapy.formulary?

1. For end users, they should import directly from plasmapy.formulary (e.g. from plasmapy.formulary import plasma_frequency), because this would lead to more robustness against changing internal pkg structure.
2. For contributors developing code,..
   1. For locations outside plasmapy.formulary functionality can be imported from plasmapy.formulary.
   2. For locations inside plasmapy.formulary, ...
      • Importing from plasmapy.formulary will absolutely cause circular imports, so this option can not be done.
      • Functionality to be directly imported from its sub-module or the sub-module itself should be imported.
      • Importing functionality from a sub-module can still cause circular imports, in that case import the sub-module and dot access the functionality. For example,

        from plasmapy.formulary import frequencies
        
        wp = frequencies.plasmapy_frequency(...)

Add that we can use tools like WebPlotDigitizer to get values from graphs. Was used in #1189.

• Specify the dependency tree for subpackages. utils can't import from anywhere else; particles can import from utils, formulary can import from particles & utils, etc.

• Provide a link to Python packaging tutorial

• Make sure to incorporate the following text, which came from docs/formulary/index.rst:

Notes for developers

Values should be returned as an Astropy |Quantity| in SI units.

If a quantity has several names, then the function name should be the
one that provides the most physical insight into what the quantity
represents. For example, gyrofrequency indicates gyration, while
Larmor frequency indicates that this frequency is somehow related to a
human (or perhaps a cat?) named Larmor. Similarly, using omega_ce
as a function name for this quantity will make the code less readable to
people who are unfamiliar with the notation or use a different symbol.

The docstrings for plasma parameter methods should describe the
physics associated with these quantities in ways that are
understandable to students who are taking their first course in plasma
physics while still being useful to experienced plasma physicists.

• Mention annotations and what they're used for
• Bring up how to use validate_quantities and particle_input

Thinking about this more, it's probably a better idea to break this up into multiple, smaller pull requests.

Closing this in favor of a few separate pull requests (see above). The two main sections that I haven't moved over are on:

• Python standard library
• IDEs

The paragraph on IDEs could perhaps be shortened and put in #1656. Right now I'm not planning on putting the section on the Python standard library anywhere else, but it might be worth thinking about again in shorter form if we add a resources page to the contributor guide.