| PLEP | 7 |
|---|---|
| author(s) | Erik T. Everson Tulasi Parashar Stephen Vincena Nicholas A. Murphy |
| contact email | eeverson@ucla.edu |
| date created | 2019-10-27 |
| date last revised | 2021-04-27 |
| type | Standard |
| status | Accepted |
| DOI | 10.5281/zenodo.3774573 |
Contents
- Abstract
- Detailed Description
- Extensible Packages are Exempt
- Implementation
- Issues, Pull Requests, and Branches
- Backward Compatibility
- Decision Rationale
This PLEP defines the top-level structure of PlasmaPy (i.e. plasmapy.<subpackage>). Its intent is to name the top-level sub-packages and define the general scope of each package. Sub-package details are left to be defined in package focused PLEPs, which should NOT conflict with this PLEP. Defining the top-level structure should:
- keep the top-level namespace from getting bloated
- help developers decided where new code should be placed
- help navigate users to the functionality they need
If new code does NOT fall within the current framework after a thorough and exhaustive review, then this PLEP needs to be modified/updated accordingly before any new top-level sub-packages are created.
By defining the top-level sub-package namespace developers are better directed to where code should be added, the PlasmaPy Coordinating Committee can better manage package bloat, and users are better directed to the code they need.
The following sub-packages are outlined in this PLEP, with brief synopses given in the tables below. The details of each package are left to be fully defined by their respective package PLEPs.
| addons | |
|---|---|
| directory: | ./plasmapy/addons/ |
| access: | plasmapy.addons |
| PLEP: | |
| scope: | The addons sub-package is intended to be a plugin location to allow 3rd party users to extend the capabilities of PlasmaPy.PlasmaPy's primary goal is to provide common functionality to the plasma community as a whole and avoids getting too focused on resources/functionality that are specific to a research group, instrument, laboratory, etc. However, we do see the benefit of having this functionality available in the PlasmaPy ecosystem. This addons entry point allows for the PlasmaPy community to develop separate open-source distributions that extend the functionality of plasmapy.Note: Extending PlasmaPy by adding to plasmapy.addons will be covered in a future PLEP. |
| analysis | |
|---|---|
| directory: | ./plasmapy/analysis/ |
| access: | plasmapy.analysis |
| PLEP: | |
| scope: | A sub-package focused on providing analysis techniques that can be applied to data collected from a variety of sources (simulation, experimental, space, etc.). The focus of an analysis routine should be made as broad as possible. When the routine's functionality becomes highly-tailored to its application, then it should be placed into an explicitly appropriate namespace. For example, linear, langmuir, magnetic-flux, etc. analysis tools should be placed in their respective namespaces within plasmapy.analysis. |
| diagnostics | |
|---|---|
| directory: | ./plasmapy/diagnostics/ |
| access: | plasmapy.diagnostics |
| PLEP: | |
| scope: | A sub-package that fully defines the parameters of a "diagnostic." A "diagnostic" is any data collecting instrument ranging from experimental probes, like Langmuir and magnetic flux probes, to analogous synthetic diagnostics for simulations. Tools in this package do not define any analysis routines, but focus on defining probe characteristics/calibrations that can be seamlessly passed to plasmapy.analysis routines.A " Diagnostic" class should fully define its diagnostic characteristics and provide access to its most relevant analysis tools found in plasmapy.analysis. |
| dispersion | |
|---|---|
| directory: | ./plasmapy/dispersion/ |
| access: | plasmapy.dispersion |
| PLEP: | |
| scope: | A sub-package containing tools to work with plasma dispersion relations. This includes, but is not limited to, solving dispersion relations, defining dispersion functions, plotting dispersion relations, etc. |
| formulary | |
|---|---|
| directory: | ./plasmapy/formulary/ |
| access: | plasmapy.formulary |
| PLEP: | |
| scope: | A sub-package that provides mathematical and scientific formulas for calculating physical parameters of various plasmas. This is inspired by, and akin to, the NRL Plasma Formulary. |
| particles | |
|---|---|
| directory: | ./plasmapy/particles/ |
| access: | plasmapy.particles |
| PLEP: | |
| scope: | A sub-package that fully defines the properties of a "particle." A "particle" can come in many forms ranging from a traditional particle (electron, ion, atom, etc.) to more exotic types like dust particles, dimensionless particles for simulations, super-particles for simulations, etc. |
| plasma | |
|---|---|
| directory: | ./plasmapy/plasma/ |
| access: | plasmapy.plasma |
| PLEP: | |
| scope: | A sub-package that fully defines a plasma. This would include the plasma's species constituents and physical parameters (like temperature, boundary conditions, magnetic fields, distribution functions, etc.). Any tools that go into defining a plasma or its environment (e.g. a field solver) should be included in a sub-package within plasmapy.plasma. |
| simulation | |
|---|---|
| directory: | ./plasmapy/simulation/ |
| access: | plasmapy.simulation |
| PLEP: | |
| scope: | A sub-package focused on interfacing with simulations and/or running simulations. If a new feature falls under the scope of the analysis and/or diagnostics sub-packages, then the new feature should be included in one of those sub-packages. For example, a synthetic diagnostic should be included in the plasmapy.diagnostics sub-package. |
| tests | |
|---|---|
| directory: | ./plasmapy/tests/ |
| access: | plasmapy.tests |
| PLEP: | |
| scope: | A collection of tests for top-level modules (i.e. functions and classes defined in top-level .py files).Note: Utilities associated with running and developing tests (e.g. "pytest helpers") should also be included here over plasmapy.utils. |
| transport | |
|---|---|
| directory: | ./plasmapy/transport/ |
| access: | plasmapy.transport |
| PLEP: | |
| scope: | This sub-package will contain functionality for calculating plasma transport coefficients and/or modeling plasma transport. Note: Simulations that focus on calculating transport coefficients should be included in this sub-package and not plasmapy.simulation. |
| utils | |
|---|---|
| directory: | ./plasmapy/utils/ |
| access: | plasmapy.utils |
| PLEP: | |
| scope: | A collection of "utility" functions and classes to help us write (what we try to think of as) clean, readable, and informative code. This collection does not provide any physics tools, instead it is focused on providing package development tools. Note: Utilities focused on running and developing tests should be placed in plasmapy.tests instead. |
Any package separately distributed from plasmapy does not need to go through a PLEP-7 review to add a top-level package to plasmapy. For example, a plasmapy-foo distribution does not require a PLEP-7 review to create the extensible sub-package plasmapy.foo. The reasoning here is (1) this top-level sub-package plasmapy.foo is not distributed with the main plasmapy package and (2) any user is purposefully installing the extensible package plasmapy-foo.
Implementing this PLEP requires creation of new sub-packages and refactoring (renaming and/or moving) of existing modules and sub-packages into the outlined structure.
Implementation of this PLEP was started during the development of plasmapy v0.3.0.
All issues and pull requests were managed under the GitHub project PLEP-0007 Implementation. The key pull requests were:
- PR #692: "plasmapy.formulary - reshuffle"
- PR #742: "Rename plasmapy.atomic to plasmapy.particles"
- PR #728: "Refactor pytest helper functionality"
This PLEP will NOT maintain backward compatibility.
Defining a top-level namespace for plasmapy will (1) prevent namespace pollution, (2) help guide developers on where to place new code, and (3) help navigate users to the functionality they need.