Repository: PlasmaPy/PlasmaPy
Pull request #568 (2018-10-15 20:13:08)

Update inertial_length
I fixed an error in the docstring of inertial_length which still used the definition from when it was split into ion_inertial_length and electron_inertial_length.  I took this chance to use `particle_input` and `Particle`, remove the default particle assumption, update tests, and update the description of the physics.

Cross-references: #106, #140, #341, #453 


Patch:
diff --git a/plasmapy/physics/parameters.py b/plasmapy/physics/parameters.py
index 86f78b29..07eb2d33 100644
--- a/plasmapy/physics/parameters.py
+++ b/plasmapy/physics/parameters.py
@@ -1154,28 +1154,28 @@ def Debye_number(T_e: u.K, n_e: u.m**-3):
     return N_D.to(u.dimensionless_unscaled)
 
 
+
 @utils.check_quantity(
     n={'units': u.m ** -3, 'can_be_negative': False}
     )
-def inertial_length(n: u.m**-3, particle='e-'):
-    r"""Calculate the particle inertial length. At this length, the Hall effect
-    becomes important.
+@atomic.particle_input(require='charged')
+def inertial_length(n: u.m**-3, particle: atomic.Particle):
+    r"""
+    Calculate a charged particle's inertial length.
 
     Parameters
     ----------
     n : ~astropy.units.Quantity
-        Particle number density in units convertible to m**-3.
+        Particle number density in units convertible to m ** -3.
 
     particle : str, optional
-        Representation of the particle species (e.g., 'p' for protons, 'D+'
-        for deuterium, or 'He-4 +1' for singly ionized helium-4),
-        which defaults to electrons.  If no charge state information is
-        provided, then the particles are assumed to be singly charged.
+        Representation of the particle species (e.g., 'p+' for protons,
+        'D+' for deuterium, or 'He-4 +1' for singly ionized helium-4).
 
     Returns
     -------
     d : ~astropy.units.Quantity
-        Particles inertial length in meters.
+        The particle's inertial length in meters.
 
     Raises
     ------
@@ -1191,22 +1191,27 @@ def inertial_length(n: u.m**-3, particle='e-'):
     Warns
     -----
     ~astropy.units.UnitsWarning
-        If units are not provided, SI units are assumed
+        If units are not provided and SI units are assumed.
 
     Notes
     -----
-    The particle inertial length is also known as an particle skin depth and is
-    given by:
+    The inertial length of a particle of species :math:`s` is given by
 
     .. math::
-        d = \frac{c}{\omega_{pi}}
+        d = \frac{c}{\omega_{ps}}
+
+    The inertial length is the characteristic length scale for a
+    particle to be accelerated in a plasma.  The Hall effect becomes
+    important on length scales shorter than the ion inertial length.
+
+    The inertial length is also known as the skin depth.
 
     Example
     -------
     >>> from astropy import units as u
-    >>> inertial_length(5*u.m**-3, particle='He+')
+    >>> inertial_length(5 * u.m ** -3, 'He+')
     <Quantity 2.02985802e+08 m>
-    >>> inertial_length(5*u.m**-3)
+    >>> inertial_length(5 * u.m ** -3, 'e-')
     <Quantity 2376534.75601976 m>
 
     """


Test patch:
diff --git a/plasmapy/physics/tests/test_parameters.py b/plasmapy/physics/tests/test_parameters.py
index 63686127..03ca5588 100644
--- a/plasmapy/physics/tests/test_parameters.py
+++ b/plasmapy/physics/tests/test_parameters.py
@@ -809,28 +809,28 @@ def test_inertial_length():
     with pytest.raises(ValueError):
         inertial_length(-5 * u.m ** -3, particle='p')
 
-    with pytest.raises(ValueError):
+    with pytest.raises(InvalidParticleError):
         inertial_length(n_i, particle=-135)
 
     with pytest.warns(u.UnitsWarning):
         inertial_length_no_units = inertial_length(1e19, particle='p')
         assert inertial_length_no_units == inertial_length(1e19 * u.m ** -3, particle='p')
 
-    assert inertial_length(n_e).unit.is_equivalent(u.m)
+    assert inertial_length(n_e, 'e-').unit.is_equivalent(u.m)
 
-    assert np.isclose(inertial_length(1 * u.cm ** -3).cgs.value, 5.31e5, rtol=1e-3)
+    assert np.isclose(inertial_length(1 * u.cm ** -3, 'e-').cgs.value, 5.31e5, rtol=1e-3)
 
     with pytest.warns(u.UnitsWarning):
-        inertial_length(5)
+        inertial_length(5, 'e-')
 
     with pytest.raises(u.UnitConversionError):
-        inertial_length(5 * u.m)
+        inertial_length(5 * u.m, 'e-')
 
     with pytest.raises(ValueError):
-        inertial_length(-5 * u.m ** -3)
+        inertial_length(-5 * u.m ** -3, 'e-')
 
     with pytest.warns(u.UnitsWarning):
-        assert inertial_length(1e19) == inertial_length(1e19 * u.m ** -3)
+        assert inertial_length(1e19, 'e-') == inertial_length(1e19 * u.m ** -3, 'e-')
 
     assert_can_handle_nparray(inertial_length)