Repository: PlasmaPy/PlasmaPy

Issue:
Return namedtuples in dielectric.py functions
There are a few functions in [`plasmapy/physics/dielectric.py`](https://github.com/PlasmaPy/PlasmaPy/blob/1511167bfb7631b0b54d1e4919d0adaf001c59aa/plasmapy/physics/dielectric.py) that return three values, e.g.
```Python
def cold_plasma_permittivity_SDP(B, species, n, omega):
    ...
    return S, D, P
```
It would probably be helpful if we could return these as `collections.namedtuple` objects (or perhaps a new class) since that would group the values together in a convenient object.  If it is returned as a `namedtuple`, then it should preserve existing behavior when doing: 
```Python
>>> S, D, P = cold_plasma_permittivity_SDP(B, species, n, omega)
```
Thanks!
-Nick




Discussion:

Resolving patch:
diff --git a/plasmapy/physics/dielectric.py b/plasmapy/physics/dielectric.py
--- a/plasmapy/physics/dielectric.py
+++ b/plasmapy/physics/dielectric.py
@@ -5,8 +5,8 @@
 from plasmapy import utils
 from plasmapy.physics import parameters
 from plasmapy.constants import (pi, m_e, c, mu0, e, eps0)
-import scipy.special as spec
 from plasmapy.mathematics import plasma_dispersion_func_deriv
+from collections import namedtuple
 
 r"""
 Values should be returned as a `~astropy.units.Quantity` in SI units.
@@ -16,6 +16,8 @@
            'cold_plasma_permittivity_LRP',
            'permittivity_1D_Maxwellian']
 
+StixTensorElements = namedtuple("StixTensorElements", ["sum", "difference", "plasma"], )
+RotatingTensorElements = namedtuple("RotatingTensorElements", ["left", "right", "plasma"], )
 
 @utils.check_quantity(
     B={'units': u.T, 'can_be_negative': False},
@@ -47,13 +49,13 @@ def cold_plasma_permittivity_SDP(B, species, n, omega):
 
     Returns
     -------
-    S : ~astropy.units.Quantity
+    sum : ~astropy.units.Quantity
         S ("Sum") dielectric tensor element.
 
-    D : ~astropy.units.Quantity
+    difference : ~astropy.units.Quantity
         D ("Difference") dielectric tensor element.
 
-    P : ~astropy.units.Quantity
+    plasma : ~astropy.units.Quantity
         P ("Plasma") dielectric tensor element.
 
     Notes
@@ -94,9 +96,11 @@ def cold_plasma_permittivity_SDP(B, species, n, omega):
     >>> species = ['e', 'D+']
     >>> n = [1e18*u.m**-3, 1e18*u.m**-3]
     >>> omega = 3.7e9*(2*pi)*(u.rad/u.s)
-    >>> S, D, P = cold_plasma_permittivity_SDP(B, species, n, omega)
+    >>> permittivity = S, D, P = cold_plasma_permittivity_SDP(B, species, n, omega)
     >>> S
     <Quantity 1.02422902>
+    >>> permittivity.sum   # namedtuple-style access
+    <Quantity 1.02422902>
     >>> D
     <Quantity 0.39089352>
     >>> P
@@ -111,7 +115,7 @@ def cold_plasma_permittivity_SDP(B, species, n, omega):
         S += - omega_p ** 2 / (omega ** 2 - omega_c ** 2)
         D += omega_c / omega * omega_p ** 2 / (omega ** 2 - omega_c ** 2)
         P += - omega_p ** 2 / omega ** 2
-    return S, D, P
+    return StixTensorElements(S, D, P)
 
 
 @utils.check_quantity(
@@ -146,13 +150,13 @@ def cold_plasma_permittivity_LRP(B: u.T, species, n, omega: u.rad / u.s):
 
     Returns
     -------
-    L : ~astropy.units.Quantity
+    left : ~astropy.units.Quantity
         L ("Left") Left-handed circularly polarization tensor element.
 
-    R : ~astropy.units.Quantity
+    right : ~astropy.units.Quantity
         R ("Right") Right-handed circularly polarization tensor element.
 
-    P : ~astropy.units.Quantity
+    plasma : ~astropy.units.Quantity
         P ("Plasma") dielectric tensor element.
 
     Notes
@@ -187,9 +191,11 @@ def cold_plasma_permittivity_LRP(B: u.T, species, n, omega: u.rad / u.s):
     >>> species = ['e', 'D+']
     >>> n = [1e18*u.m**-3, 1e18*u.m**-3]
     >>> omega = 3.7e9*(2*pi)*(u.rad/u.s)
-    >>> L, R, P = cold_plasma_permittivity_LRP(B, species, n, omega)
+    >>> L, R, P = permittivity = cold_plasma_permittivity_LRP(B, species, n, omega)
     >>> L
     <Quantity 0.63333549>
+    >>> permittivity.left    # namedtuple-style access
+    <Quantity 0.63333549>
     >>> R
     <Quantity 1.41512254>
     >>> P
@@ -204,7 +210,7 @@ def cold_plasma_permittivity_LRP(B: u.T, species, n, omega: u.rad / u.s):
         L += - omega_p ** 2 / (omega * (omega - omega_c))
         R += - omega_p ** 2 / (omega * (omega + omega_c))
         P += - omega_p ** 2 / omega ** 2
-    return L, R, P
+    return RotatingTensorElements(L, R, P)
 
 
 @u.quantity_input(omega=u.rad / u.s,


Test patch:
diff --git a/plasmapy/physics/tests/test_dielectric.py b/plasmapy/physics/tests/test_dielectric.py
--- a/plasmapy/physics/tests/test_dielectric.py
+++ b/plasmapy/physics/tests/test_dielectric.py
@@ -6,7 +6,9 @@
 
 from ..dielectric import (cold_plasma_permittivity_LRP,
                           cold_plasma_permittivity_SDP,
-                          permittivity_1D_Maxwellian)
+                          permittivity_1D_Maxwellian,
+                          RotatingTensorElements,
+                          StixTensorElements)
 
 from ..parameters import (plasma_frequency,
                           gyrofrequency,
@@ -46,12 +48,23 @@ def test_proton_electron_plasma(self):
         P_analytical = 1 - (omega_pe ** 2 + omega_pp ** 2) / omega ** 2
 
         species = ['e', 'p']
-        S, D, P = cold_plasma_permittivity_SDP(B, species, n, omega)
+        S, D, P = tuple_result = cold_plasma_permittivity_SDP(B, species, n, omega)
+
+        assert tuple_result.sum is S
+        assert tuple_result.difference is D
+        assert tuple_result.plasma is P
+        assert isinstance(tuple_result, StixTensorElements)
 
         assert np.isclose(S, S_analytical)
         assert np.isclose(D, D_analytical)
         assert np.isclose(P, P_analytical)
 
+        L, R, P = rotating_tuple_result = cold_plasma_permittivity_LRP(B, species, n, omega)
+        assert rotating_tuple_result.left is L
+        assert rotating_tuple_result.right is R
+        assert rotating_tuple_result.plasma is P
+        assert isinstance(rotating_tuple_result, RotatingTensorElements)
+
     def test_three_species(self):
         """
         Test with three species (2 ions): D plasma with 5%H minority fraction
@@ -79,6 +92,14 @@ def test_SD_to_LR_relationships(self):
         assert np.isclose(S, (R + L) / 2)
         assert np.isclose(D, (R - L) / 2)
 
+    def test_numpy_array_workflow(self):
+        """as per @jhillairet at https://github.com/PlasmaPy/PlasmaPy/issues/539#issuecomment-425337810 """
+        ns = np.logspace(17, 19, 50)/u.m**3
+        B0 = 4*u.T
+        omega_RF = 2*np.pi*50e6*(u.rad/u.s)
+
+        S, D, P = cold_plasma_permittivity_SDP(B=B0, species=['e', 'D+'], n=[ns, ns], omega=omega_RF)
+        assert S.shape == D.shape == P.shape == (50,)
 
 class Test_permittivity_1D_Maxwellian:
     @classmethod