PLEP7: top level package structure

[rocco8773]

This PLEP is focused on:

1. Defining the top-level sub-package namespace for PlasmaPy
2. Defining the general scope of each top-level sub-package

The goal is to:

1. Keep the top-level namespace of PlasmaPy from getting bloated
2. Help guide developers/contributes on where to place their code

---

This PLEP was initially outlined by the PlasmaPy Coordinating Team at the 2019 61st APS-DPP Meeting.

P.S. I will remove the "draft" label when I'm satisfied with the PLEP and ready to merge it.

---

Still need to...

• [X] Start Zenodo upload to reserve DOI (https://doi.org/10.5281/zenodo.3774573)
• [x] Publish to Zenodo
• [x] Update ./README.rst with DOI
• [x] Update PLEP DOI field
• [x] Update PLEP date last revised field with accepted date
• [x] Update PLEP status field with accepted when accepted
• [ ] Update linked PRs under section Issues, Pull Requests, and Branches when PRs are merged (see issue #32, the PLEP will be updated with links once the implementation is complete)

[StanczakDominik]

I went ahead and did a few initial comments, and oh dear, the tables broke them :laughing: The Files Changed view will be a better choice for viewing them.

[namurphy]

While we're doing this...are there things we're missing?

[rocco8773]

I can't think of of anything sub-package related, but we could potentially touch on modules (i.e. .py files) too. I don't really want to do this though, but it is a potential source for package bloat.

[namurphy]

We had a brief discussion on Riot about the possibility of having a plasmapy.transport subpackage once again.

At present, our transport theory formulae are in plasmapy.formulary. There is a lot of transport phenomena that goes beyond formulae, such as detailed modeling of transport in configurations like tokamaks. An example is the detailed modeling that TRANSP does. Such modeling would fall outside the scope of plasmapy.formulary. However, such detailed modeling would probably fall outside of the scope of the core package and would probably need to go in an affiliated package. What would probably be most helpful is talking with plasma researchers who focus on transport theory, and coming up with another PLEP on how to handle it. Since we can amend this PLEP and we want to be cautious about adding unstable packages, we decided to defer the decision.

[namurphy]

Here's a brainstorm of things that could potentially be missing in the subpackage structure. Many of these may fit well into existing subpackages too. Since @rocco8773 purposefully wrote this PLEP to be expandable, we don't need to make any additions now. This too is mostly a note for things to think about in the future.

• orbits or particle_motions: single particle motions, etc. (could fall into simulation and/or analysis)
• configurations and/or devices: descriptions of tokamaks, stellarators, etc. both as experimental devices and for the plasma configuration within (could fall under plasma)
• equilibria: a place for equilibrium solvers, like Grad-Shafranov and whatnot
• turbulence: to shake things up
• phenomena: maybe standard models and descriptions of dynamo, reconnection, particle acceleration
• nonlinear: nonlinear aspects of waves, shocks, instabilities, etc.

[namurphy]

A possibility from looking at SunPy's subpackages: plasmapy.net which contains tools to access online databases and other things over the internet. I don't think we should add it yet, but rather keep it in mind as a possibility for the future.

[rocco8773]

A possibility from looking at SunPy's subpackages: plasmapy.net which contains tools to access online databases and other things over the internet. I don't think we should add it yet, but rather keep it in mind as a possibility for the future.

I do think that would be a useful feature, especially for accessing example data that is not packaged with plasmapy. However, I think a better spot for this would be plasmapy.utils.net.

[namurphy]

I do think that would be a useful feature, especially for accessing example data that is not packaged with plasmapy. However, I think a better spot for this would be plasmapy.utils.net.

My thinking is that if it'll be something primarily used by developers internally within the package, then plasmapy.utils.net would be best. On the other hand, if we create tools that are intended for users, (along the lines of sunpy.net.Fido), then my vote would probably be for plasmapy.net. With all that said, it probably makes the most sense to defer the decision until we have a better plan, and for now just keep track of ideas.