PlasmaPy · rocco8773 · Jan 11, 2022 · May 13, 2021 · May 13, 2021 · May 13, 2021
@@ -0,0 +1,4 @@
+Added a lite-function group to the configuration value
+:confval:``automodapi_custom_groups`` that introduces the
+``__lite_funcs__`` dunder for listing the lite-functions in a module
+(akin to the ``__all__`` dunder).
@@ -0,0 +1,3 @@
+Created decorator `~plasmapy.utils.decorators.lite_func.bind_lite_func`
+for handling the binding of lite-functions and any supporting functions
+to a parent function.
@@ -0,0 +1,7 @@
+Introduced the concept of lite-functions, by creating the lite-function
+`~plasmapy.formulary.parameters.thermal_speed_lite`, which is a simplified
+and `numba` jitted version of `~plasmapy.formulary.parameters.thermal_speed`.
+These functions are intended for computational use and as such have no
+validation of input or output values.
+`~plasmapy.formulary.parameters.thermal_speed_lite` is also bound to
+`~plasmapy.formulary.parameters.thermal_speed` as the ``lite`` attribute.
@@ -0,0 +1,6 @@
+Created function `~plasmapy.formulary.parameters.thermal_speed_coefficients`
+to support `~plasmapy.formulary.parameters.thermal_speed_lite` usage by
+calculating the various thermal speed coefficients.
+`~plasmapy.formulary.parameters.thermal_speed_coefficients` is also bound
+to `~plasmapy.formulary.parameters.thermal_speed` as the ``coefficients``
+attribute.
@@ -0,0 +1,3 @@
+Streamlined `~plasmapy.utils.decorators.helpers.preserve_signature` such that it only
+binds ``__signature__`` to the wrapped function, i.e. it no longer touches
+any other attribute of the wrapped function.
@@ -0,0 +1,3 @@
+Moved all tests associated with calculating the thermal speed from test
+file :file:`plasmapy/formulary/tests/test_parameters.py` to
+:file:`plasmapy/formulary/tests/test_thermal_speed.py`
@@ -49,6 +49,11 @@ div.graphviz {
     white-space: normal;
     line-height: 140%;
 }
+
+/* Reduce top/bottom margin for equations in tables */
+table div.MathJax_Display {
+    margin: 0.5em 0;
+}
 /* -----------------------------------------------------------------------------
  * RTD layout styling additions
  */

@@ -44,7 +44,49 @@
         ),
         "dunder": "__aliases__",
     },
+    "lite-functions": {
+        "title": "Lite-Functions",
+        "description": (
+            """
+            Much of PlasmaPy's functionality incorporates `Astropy units
+            <https://docs.astropy.org/en/stable/units/>`_ for user convenience and
+            to mitigate calculation errors from inappropriate units, but this
+            comes at the sacrifice of speed.  While this penalty is not significant
+            for typical use, it can become substantial during intensive numerical
+            calculations. **Lite-Functions** are introduced for the specific case
+            where speed matters, but **[USER NOTICE]** this comes with the
+            reduction of safeguards so a user needs to know what they are doing!
+            A few things to know about **Lite-Functions**:
+
+            - Lite-functions are a flavor of existing PlasmaPy functionality and
+              are denoted with a trailing ``_lite`` to the name, for example
+              `~plasmapy.formulary.parameters.thermal_speed_lite` is the
+              lite-function associated with
+              `~plasmapy.formulary.parameters.thermal_speed`.
+            - Lite-functions are typically bound to their normal version as the
+              ``lite`` attribute.  For example,
+              `~plasmapy.formulary.parameters.thermal_speed_lite` can be accessed
+              as ``thermal_speed.lite``.
+            - Inputs and outputs to lite-functions are strictly given in SI units.
+            - **UNITS ARE NOT VALIDATED BY THE FUNCTIONS.**  It is solely up to
+              the user to pass in parameters with the correct units.
+            - When possible, lite-functions are decorated with `numba.jit`
+              (or the like) for an additional speed boost.
+            """
+        ),
+        "dunder": "__lite_funcs__",
+    },
 }
+automodapi_group_order = (
+    "modules",
+    "classes",
+    "exceptions",
+    "warnings",
+    "functions",
+    "aliases",
+    "lite-functions",
+    "variables",
+)
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
@@ -90,6 +132,7 @@
         None,
     ),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+    "numba": ("https://numba.readthedocs.io/en/stable/", None),
 }
 
 autoclass_content = "both"

@@ -2,9 +2,9 @@
 The `~plasmapy.formulary` subpackage contains commonly used formulae
 from plasma science.
 """
-# __all__ & __aliases__ will be auto populated below
 __all__ = []
 __aliases__ = []
+__lite_funcs__ = []
 
 from plasmapy.formulary.braginskii import *
 from plasmapy.formulary.collisions import *
@@ -25,7 +25,7 @@
         __all__.append(obj_name)
 __all__.sort()
 
-# auto populate __aliases__
+# auto populate __aliases__ & __lite_funcs__
 for modname in (
     "braginskii",
     "collisions",
@@ -42,10 +42,18 @@
 ):
     try:
         obj = globals()[modname]
+    except KeyError:  # coverage: ignore
+        continue
+
+    try:
         __aliases__.extend(obj.__aliases__)
-    except (KeyError, AttributeError):
+    except AttributeError:
+        pass
+
+    try:
+        __lite_funcs__.extend(obj.__lite_funcs__)
+    except AttributeError:
         pass
-__aliases__.sort()
 
 # cleanup namespace
 del modname, obj, obj_name