Skip to content

Latest commit

 

History

History
386 lines (334 loc) · 22.3 KB

PLEP-0007.rst

File metadata and controls

386 lines (334 loc) · 22.3 KB

PLEP-0007 – Structure of Top-Level Sub-Packages

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

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:

  1. keep the top-level namespace from getting bloated
  2. help developers decided where new code should be placed
  3. 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.

Detailed Description

Why?

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.

Top-Level Sub-Packages

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.

  1. addons
  2. analysis
  3. diagnostics
  4. dispersion
  5. formulary
  6. particles
  7. plasma
  8. simulation
  9. tests
  10. transport
  11. utils
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.

Extensible Packages are Exempt

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.

Implementation

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.

Issues, Pull Requests, and Branches

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"

Backward Compatibility

This PLEP will NOT maintain backward compatibility.

Decision Rationale

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.