Repository: PlasmaPy/PlasmaPy

Issue:
Add references in plasmapy.langmuir docstrings
At the moment the `plasmapy.langmuir` docstrings lack references altogether. These need to be added ASAP. A small part of the functions (namely initial fitting parameters and electron temperature-based offset of the exponential region extraction) are empirical. Is that fine?


Discussion:
It's absolutely fine! That needs to be written down and available right there in the docs though.

Resolving patch:
diff --git a/plasmapy/diagnostics/langmuir.py b/plasmapy/diagnostics/langmuir.py
--- a/plasmapy/diagnostics/langmuir.py
+++ b/plasmapy/diagnostics/langmuir.py
@@ -42,10 +42,10 @@ class Characteristic:
 
     Attributes
     ----------
-    bias : Quantity, ndarray
+    bias : `astropy.units.Quantity`, ndarray
         Array of applied probe biases in units convertible to V.
 
-    current : Quantity, ndarray
+    current : `astropy.units.Quantity`, ndarray
         Array of applied probe currents in units convertible to A.
 
     """
@@ -200,59 +200,60 @@ def swept_probe_analysis(probe_characteristic, probe_area, gas,
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The swept probe characteristic that is to be analyzed.
 
-    probe_area : Quantity
+    probe_area : ~astropy.units.Quantity
         The area of the probe exposed to plasma in units convertible to m^2.
 
-    gas : Quantity
+    gas : ~astropy.units.Quantity
         The (mean) mass of the background gas in atomic mass units.
 
-    visualize : bool, Optional
+    visualize : bool, optional
         Can be used to plot the characteristic and the obtained parameters.
         Default is False.
 
-    plot_electron_fit : bool, Optional
+    plot_electron_fit : bool, optional
         If True, the fit of the electron current in the exponential section is
         shown. Default is False.
 
-    plot_EEDF : bool, Optional
+    plot_EEDF : bool, optional
         If True, the EEDF is computed and shown. Default is False.
 
     Returns
     -------
-    A dictionary with the following entries:
 
-    'T_e' : Quantity
+    Results are returned as Dictionary
+
+    "T_e" : `astropy.units.Quantity`
         Best estimate of the electron temperature in units of eV. Contains
         two values if bimaxwellian is True.
 
-    'n_e' : Quantity
+    "n_e" : `astropy.units.Quantity`
         Estimate of the electron density in units of m^-3. See the Notes on
         plasma densities.
 
-    'n_i' : Quantity
+    "n_i" : `astropy.units.Quantity`
         Estimate of the ion density in units of m^-3. See the Notes on
         plasma densities.
 
-    'n_i_OML' : Quantity
+    "n_i_OML" : `astropy.units.Quantity`
         OML-theory estimate of the ion density in units of m^-3. See the Notes
         on plasma densities.
 
-    'V_F' : Quantity
+    "V_F" : `astropy.units.Quantity`
         Estimate of the floating potential in units of V.
 
-    'V_P' : Quantity
+    "V_P" : `astropy.units.Quantity`
         Estimate of the plasma potential in units of V.
 
-    'I_es' : Quantity
+    "I_es" : `astropy.units.Quantity`
         Estimate of the electron saturation current in units of Am^-2.
 
-    'I_is' : Quantity
+    "I_is" : `astropy.units.Quantity`
         Estimate of the ion saturation current in units of Am^-2.
 
-    'hot_fraction' : float
+    "hot_fraction" : float
         Estimate of the total hot (energetic) electron fraction.
 
     Notes
@@ -383,7 +384,7 @@ def get_plasma_potential(probe_characteristic, return_arg=False):
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     return_arg : bool, optional
@@ -393,7 +394,7 @@ def get_plasma_potential(probe_characteristic, return_arg=False):
 
     Returns
     -------
-    V_P : Quantity
+    V_P : ~astropy.units.Quantity
         Estimate of the plasma potential in units convertible to V.
 
     Notes
@@ -427,7 +428,7 @@ def get_floating_potential(probe_characteristic, return_arg=False):
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     return_arg : bool, optional
@@ -437,7 +438,7 @@ def get_floating_potential(probe_characteristic, return_arg=False):
 
     Returns
     -------
-    V_F : Quantity
+    V_F : ~astropy.units.Quantity
         Estimate of the floating potential in units convertible to V.
 
     Notes
@@ -463,12 +464,12 @@ def get_electron_saturation_current(probe_characteristic):
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     Returns
     -------
-    I_es: Quantity
+    I_es: ~astropy.units.Quantity
         Estimate of the electron saturation current in units convertible to A.
 
     Notes
@@ -492,19 +493,19 @@ def get_ion_saturation_current(probe_characteristic):
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     Returns
     -------
-    I_is : Quantity
+    I_is : ~astropy.units.Quantity
         Estimate of the ion saturation current in units convertible to A.
 
     Notes
     -----
-    The method implemented in this function takes the ion saturation current
-    as the smallest probe current in the characteristic. This assumes the bias
-    range in the ion region is sufficiently negative for the ion current to
+    The method implemented in this function assumes the ion saturation current
+    to be the smallest probe current in the characteristic. This assumes the
+    bias range in the ion region is sufficiently negative for the ion current to
     saturate.
 
     """
@@ -541,21 +542,21 @@ def get_ion_density_LM(ion_saturation_current, T_e,
 
     Parameters
     ----------
-    ion_saturation_current : Quantity
+    ion_saturation_current : ~astropy.units.Quantity
         The ion saturation current in units convertible to A.
 
-    T_e : Quantity
+    T_e : ~astropy.units.Quantity
         The electron temperature in units convertible to eV.
 
-    probe_area : Quantity
+    probe_area : ~astropy.units.Quantity
         The area of the probe exposed to plasma in units convertible to m^2.
 
-    gas : Quantity
+    gas : ~astropy.units.Quantity
         The (mean) mass of the background gas in atomic mass units.
 
     Returns
     -------
-    n_i : Quantity
+    n_i : ~astropy.units.Quantity
         Estimate of the ion density in units convertible to m^-3.
 
     Notes
@@ -565,6 +566,11 @@ def get_ion_density_LM(ion_saturation_current, T_e,
     probe is equal to the Bohm loss. The acoustic Bohm velocity is obtained
     from the electron temperature and the ion mass.
 
+    The ion saturation current is given by
+
+    .. math::
+        I_{is} = 0.6 e A_p n_i \sqrt{\frac{T_e}{m_i}}.
+
     """
 
     # Calculate the acoustic (Bohm) velocity
@@ -597,24 +603,29 @@ def get_electron_density_LM(electron_saturation_current, T_e,
 
     Parameters
     ----------
-    electron_saturation_current : Quantity
+    electron_saturation_current : ~astropy.units.Quantity
         The electron saturation current in units convertible to A.
 
-    T_e : Quantity
+    T_e : ~astropy.units.Quantity
         The electron temperature in units convertible to eV.
 
-    probe_area : Quantity
+    probe_area : ~astropy.units.Quantity
         The area of the probe exposed to plasma in units convertible to m^2.
 
     Returns
     -------
-    n_e : Quantity
+    n_e : ~astropy.units.Quantity
         Estimate of the electron density in units convertible to m^-3.
 
     Notes
     -----
     The method implemented in this function obtains the electron density from
-    the electron saturation current density, assuming a low plasma density.
+    the electron saturation current density, assuming a low plasma density. The
+    electron saturation current is given by
+
+    .. math::
+        I_{es} = \frac{1}{4} e n_e A_p \sqrt{\frac{8 T_e}{\pi m_e}}.
+
     Please note that the electron saturation current density is a hard
     parameter to acquire and it is usually better to measure the ion density,
     which should be identical to the electron density in quasineutral plasmas.
@@ -636,21 +647,21 @@ def extract_exponential_section(probe_characteristic, T_e=None,
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
-    T_e : Quantity, optional
+    T_e : ~astropy.units.Quantity, optional
         If given, the electron temperature can improve the accuracy of the
         bounds of the exponential region.
 
-    ion_current : Characteristic, optional
+    ion_current : ~plasmapy.diagnostics.langmuir.Characteristic, optional
         If given, the ion current will be subtracted from the probe
         characteristic to yield a better estimate of the electron current in
         the exponential region.
 
     Returns
     -------
-    exponential_section : Characteristic
+    exponential_section : ~plasmapy.diagnostics.langmuir.Characteristic
         The exponential electron current growth section.
 
     Notes
@@ -695,12 +706,12 @@ def extract_ion_section(probe_characteristic):
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     Returns
     -------
-    ion_section : Characteristic
+    ion_section : ~plasmapy.diagnostics.langmuir.Characteristic
         The exponential electron current growth section.
 
     Notes
@@ -728,7 +739,7 @@ def get_electron_temperature(exponential_section, bimaxwellian=False,
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     bimaxwellian : bool, optional
@@ -748,16 +759,26 @@ def get_electron_temperature(exponential_section, bimaxwellian=False,
 
     Returns
     -------
-    T_e : Quantity, (ndarray)
+    T_e : ~astropy.units.Quantity, (ndarray)
         The estimated electron temperature in eV. In case of a bi-Maxwellian
         plasma an array containing two Quantities is returned.
 
     Notes
     -----
-    The exponential section of the probe characteristic should be a straight
-    line if the plasma electrons are fully Maxwellian, or exhibit a knee in a
+    In the electron growth region of the probe characteristic the electron
+    current grows exponentially with bias voltage:
+
+    .. math::
+        I_e = I_{es} \textrm{exp} \left(
+        -\frac{e\left(V_P - V \right)}{T_e} \right).
+
+    In log space the current in this region should be a straight line if the
+    plasma electrons are fully Maxwellian, or exhibit a knee in a
     bi-Maxwellian case. The slope is inversely proportional to the
-    temperature of the respective electron population.
+    temperature of the respective electron population:
+
+    .. math::
+        \textrm{log} \left(I_e \right ) \propto \frac{1}{T_e}.
 
     """
 
@@ -867,7 +888,7 @@ def extrapolate_electron_current(probe_characteristic, fit,
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     fit : ndarray
@@ -883,7 +904,7 @@ def extrapolate_electron_current(probe_characteristic, fit,
 
     Returns
     -------
-    electron_current : Characteristic
+    electron_current : ~plasmapy.diagnostics.langmuir.Characteristic
         The extrapolated electron current characteristic.
 
     Notes
@@ -933,7 +954,7 @@ def reduce_bimaxwellian_temperature(T_e, hot_fraction):
 
     Parameters
     ----------
-    T_e : Quantity, ndarray
+    T_e : ~astropy.units.Quantity, ndarray
         The bi-Maxwellian temperatures in eV. If a single temperature is
         provided, this is returned.
 
@@ -943,14 +964,17 @@ def reduce_bimaxwellian_temperature(T_e, hot_fraction):
 
     Returns
     -------
-    T_e : Quantity
+    T_e : ~astropy.units.Quantity
         The reduced (mean) temperature in units of eV.
 
     Notes
     -----
     This function aids methods that take a single electron temperature in
     situations where the electron population is bi-Maxwellian. The reduced
-    temperature is obtained as the weighted mean.
+    temperature is obtained as the weighted mean:
+
+    .. math::
+        T_{e,red} = T_c \left( 1 - f_h \right) + T_h f_h
 
     """
 
@@ -979,13 +1003,13 @@ def get_ion_density_OML(probe_characteristic, probe_area, gas,
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The swept probe characteristic that is to be analyzed.
 
-    probe_area : Quantity
+    probe_area : ~astropy.units.Quantity
         The area of the probe exposed to plasma in units convertible to m^2.
 
-    gas : Quantity
+    gas : ~astropy.units.Quantity
         The (mean) mass of the background gas in atomic mass units.
 
     visualize : bool, optional
@@ -997,19 +1021,24 @@ def get_ion_density_OML(probe_characteristic, probe_area, gas,
 
     Returns
     -------
-    n_i_OML : Quantity
+    n_i_OML : ~astropy.units.Quantity
         Estimated ion density in m^-3.
 
     Notes
     -----
     The method implemented in this function holds for cylindrical probes in a
-    cold ion plasma, ie. T_i = 0 eV. With OML theory an expression is found
+    cold ion plasma, ie. :math:T_i=0` eV. With OML theory an expression is found
     for the ion current as function of probe bias independent of the electron
-    temperature:
+    temperature [mott-smith.langmuir-1926]_:
 
     .. math::
-        I = A_p n e \frac{\sqrt{2}}{\pi} \left( \frac{|eV_b|}{m_i}
-        \right)^{1/2}
+        I_i \xrightarrow[T_i = 0]{} A_p n_i e \frac{\sqrt{2}}{\pi}
+        \sqrt{\frac{e \left( V_F - V \right)}{m_i}}
+
+    References
+    ----------
+    .. [mott-smith.langmuir-1926] H. M. Mott-Smith, I. Langmuir,
+        Phys. Rev. 28, 727-763 (Oct. 1926)
 
     """
 
@@ -1052,7 +1081,7 @@ def extrapolate_ion_current_OML(probe_characteristic, fit,
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The probe characteristic that is being analyzed.
 
     fit : ndarray
@@ -1064,7 +1093,7 @@ def extrapolate_ion_current_OML(probe_characteristic, fit,
 
     Returns
     -------
-    ion_section : Characteristic
+    ion_section : ~plasmapy.diagnostics.langmuir.Characteristic
         The exponential electron current growth section.
 
     Notes
@@ -1103,7 +1132,7 @@ def get_EEDF(probe_characteristic, visualize=False):
 
     Parameters
     ----------
-    probe_characteristic : Characteristic
+    probe_characteristic : ~plasmapy.diagnostics.langmuir.Characteristic
         The swept probe characteristic that is to be analyzed.
 
     visualize : bool, optional
@@ -1112,7 +1141,7 @@ def get_EEDF(probe_characteristic, visualize=False):
 
     Returns
     -------
-    energy : Quantity, ndarray
+    energy : `astropy.units.Quantity`, ndarray
         Array of potentials in V.
 
     probability : float, ndarray
@@ -1121,10 +1150,22 @@ def get_EEDF(probe_characteristic, visualize=False):
 
     Notes
     -----
-    The Druyvesteyn method requires the second derivative of the probe I-V
-    characteristic, which inherently amplifies noise and measurement errors.
-    Therefore it is advisable to smooth the I-V prior to the use of this
-    function.
+    The Druyvesteyn method requires the second derivative of the probe
+    I-V characteristic, which inherently amplifies noise and
+    measurement errors. Therefore it is advisable to smooth the I-V
+    prior to the use of this function.
+
+    The Druyvesteyn analysis results in the following equation
+    [druyvesteyn-1930]_:
+
+    .. math::
+        N_e \left( \epsilon \right) =
+        \frac{2}{A_pe^2} \sqrt{\frac{2 m \epsilon}{e}}
+        \frac{\textrm{d}^2 I}{\textrm{d} V^2}
+
+    References
+    ----------
+    .. [druyvesteyn-1930] Druyvesteyn, M.J. Z. Physik (1930) 64: 781
 
     """
 
@@ -1151,16 +1192,18 @@ def get_EEDF(probe_characteristic, visualize=False):
 
     # Division by the Druyvesteyn factor. Since the result will be normalized
     # all constant values are irrelevant.
-    probability = dIdV2[_filter] / energy.to(u.eV).value
+    probability = dIdV2[_filter] * np.sqrt(energy.to(u.eV).value)
 
     # Integration of the EEDF for the purpose of normalization.
-    integral = np.trapz(probability, x=energy.to(u.eV).value)
-    probability = np.abs(probability / integral)
+    integral = np.abs(np.trapz(probability, x=energy.to(u.eV).value))
+    probability = probability / integral
 
     if visualize:  # coveralls: ignore
         with quantity_support():
             plt.figure()
             plt.semilogy(energy, probability, c='k')
-            plt.title("EEDF")
+            plt.title("Electron Energy Distribution Function")
+            plt.xlabel("Energy (eV)")
+            plt.ylabel("Probability")
 
     return energy, probability


Test patch: