Improve consistency of particle definitions (PlasmaPy#2495)

* particle="e" → particle="e-" and "p" → "p+" * Add search and replace for consistent symbols * Consistentify particle symbols * Consistentify particle symbols * Consistentify particle symbols * Consistentify particle symbols * Consistentify particle symbols * Update pre-commit hooks * Consistentify particle symbols * Consistentify particle symbols
MKastek · Feb 5, 2024 · d8b6e2d · d8b6e2d
1 parent 2b51278
commit d8b6e2d
Show file tree

Hide file tree

Showing 21 changed files with 113 additions and 102 deletions.
diff --git a/.pre-commit-search-and-replace.yaml b/.pre-commit-search-and-replace.yaml
@@ -42,3 +42,15 @@
 
 - search: 'MacOS'
   replacement: 'macOS'
+
+- search: 'particle="e"'
+  replacement: 'particle="e-"'
+  description: Use canonical symbol for electron
+
+- search: 'particle="p"'
+  replacement: 'particle="p+"'
+  description: Use canonical symbol for proton
+
+- search: 'ion="p"'
+  replacement: 'ion="p+"'
+  description: Use canonical symbol for proton
diff --git a/plasmapy/diagnostics/charged_particle_radiography/tests/test_synthetic_radiography.py b/plasmapy/diagnostics/charged_particle_radiography/tests/test_synthetic_radiography.py
@@ -413,7 +413,7 @@ def test_create_particles() -> None:
     )
 
     # Test specifying particle
-    sim.create_particles(1e3, 15 * u.MeV, particle="e", random_seed=42)
+    sim.create_particles(1e3, 15 * u.MeV, particle="e-", random_seed=42)
 
 
 @pytest.mark.slow()

diff --git a/plasmapy/dispersion/analytical/mhd_waves_.py b/plasmapy/dispersion/analytical/mhd_waves_.py
@@ -326,7 +326,7 @@ class AlfvenWave(AbstractMHDWave):
         convertible to kg m\ :sup:`-3`\ .
 
     ion : |particle-like|
-        Representation of the ion species (e.g., ``'p'`` for protons,
+        Representation of the ion species (e.g., ``'p+'`` for protons,
         ``'D+'`` for deuterium, ``'He-4 +1'`` for singly ionized
         helium-4, etc.). If no charge state information is provided,
         then the ions are assumed to be singly ionized.
@@ -544,7 +544,7 @@ class FastMagnetosonicWave(AbstractMHDWave):
         convertible to kg m\ :sup:`-3`\ .
 
     ion : |particle-like|
-        Representation of the ion species (e.g., ``'p'`` for protons,
+        Representation of the ion species (e.g., ``'p+'`` for protons,
         ``'D+'`` for deuterium, ``'He-4 +1'`` for singly ionized
         helium-4, etc.). If no charge state information is provided,
         then the ions are assumed to be singly ionized.
@@ -794,7 +794,7 @@ class SlowMagnetosonicWave(AbstractMHDWave):
         to m\ :sup:`-3` or the total mass density :math:`ρ` in units
         convertible to kg m\ :sup:`-3`\ .
     ion : |particle-like|
-        Representation of the ion species (e.g., ``'p'`` for protons,
+        Representation of the ion species (e.g., ``'p+'`` for protons,
         ``'D+'`` for deuterium, ``'He-4 +1'`` for singly ionized
         helium-4, etc.). If no charge state information is provided,
         then the ions are assumed to be singly ionized.
@@ -1045,7 +1045,7 @@ def mhd_waves(*args, **kwargs):
         convertible to kg m\ :sup:`-3`\ .
 
     ion : |particle-like|
-        Representation of the ion species (e.g., ``'p'`` for protons,
+        Representation of the ion species (e.g., ``'p+'`` for protons,
         ``'D+'`` for deuterium, ``'He-4 +1'`` for singly ionized
         helium-4, etc.). If no charge state information is provided,
         then the ions are assumed to be singly ionized.

diff --git a/plasmapy/formulary/braginskii.py b/plasmapy/formulary/braginskii.py
@@ -182,7 +182,7 @@ class ClassicalTransport:
 
     ion : `str`
         Representation of the ion species (e.g., ``'p'`` for protons,
-        ``'e'`` for electrons, ``'D+'`` for deuterium, or ``'He-4 +1'``
+        ``'e-'`` for electrons, ``'D+'`` for deuterium, or ``'He-4 +1'``
         for singly ionized helium-4). If no charge state information is
         provided, then the particles are assumed to be singly charged.
 
@@ -368,7 +368,7 @@ def __init__(  # noqa: PLR0912, PLR0915
             raise ValueError("Z is not allowed to be negative!")  # TODO: remove?
 
         # decide on the particle string for the electrons
-        self.e_particle = "e"
+        self.e_particle = "e-"
         self.ion = ion
 
         # save other arguments

diff --git a/plasmapy/formulary/collisions/tests/test_frequencies.py b/plasmapy/formulary/collisions/tests/test_frequencies.py
@@ -807,7 +807,7 @@ def setup_class(cls) -> None:
         """Initializing parameters for tests"""
         cls.T_arr = np.array([1, 2]) * u.eV
         cls.n_arr = np.array([1e20, 2e20]) * u.cm**-3
-        cls.ion = "p"
+        cls.ion = "p+"
         cls.coulomb_log = 10
 
     # TODO: array coulomb log
@@ -826,7 +826,7 @@ def setup_class(cls) -> None:
         """Initializing parameters for tests"""
         cls.T_arr = np.array([1, 2]) * u.eV
         cls.n_arr = np.array([1e20, 2e20]) * u.cm**-3
-        cls.ion = "p"
+        cls.ion = "p+"
         cls.coulomb_log = 10
 
     # TODO: array coulomb log

diff --git a/plasmapy/formulary/densities.py b/plasmapy/formulary/densities.py
@@ -97,7 +97,7 @@ def mass_density(
     particle : `~plasmapy.particles.particle_class.Particle`
         The particle for which the mass density is being calculated for.  Must
         be a `~plasmapy.particles.particle_class.Particle` or a value convertible to
-        a `~plasmapy.particles.particle_class.Particle` (e.g., ``'p'`` for protons,
+        a `~plasmapy.particles.particle_class.Particle` (e.g., ``'p+'`` for protons,
         ``'D+'`` for deuterium, or ``'He-4 +1'`` for singly ionized helium-4).
 
     z_ratio : `int`, `float`, optional
@@ -133,7 +133,7 @@ def mass_density(
     Examples
     --------
     >>> import astropy.units as u
-    >>> mass_density(1 * u.m**-3, "p")
+    >>> mass_density(1 * u.m**-3, "p+")
     <Quantity 1.67262...e-27 kg / m3>
     >>> mass_density(4 * u.m**-3, "D+")
     <Quantity 1.33743...e-26 kg / m3>

diff --git a/plasmapy/formulary/dielectric.py b/plasmapy/formulary/dielectric.py
@@ -51,7 +51,7 @@ def cold_plasma_permittivity_SDP(
 
     species : `list` of `str`
         List of the plasma particle species,
-        e.g.: ``['e', 'D+']`` or ``['e', 'D+', 'He+']``.
+        e.g.: ``['e-', 'D+']`` or ``['e-', 'D+', 'He+']``.
 
     n : `list` of `~astropy.units.Quantity`
         `list` of species density in units convertible to per cubic meter
@@ -102,7 +102,7 @@ def cold_plasma_permittivity_SDP(
     >>> import astropy.units as u
     >>> from numpy import pi
     >>> B = 2*u.T
-    >>> species = ['e', 'D+']
+    >>> species = ['e-', 'D+']
     >>> n = [1e18*u.m**-3, 1e18*u.m**-3]
     >>> omega = 3.7e9*(2*pi)*(u.rad/u.s)
     >>> permittivity = S, D, P = cold_plasma_permittivity_SDP(B, species, n, omega)
@@ -146,8 +146,8 @@ def cold_plasma_permittivity_LRP(
         Magnetic field magnitude in units convertible to tesla.
 
     species : `list` of `str`
-        The plasma particle species (e.g.: ``['e', 'D+']`` or
-        ``['e', 'D+', 'He+']``.
+        The plasma particle species (e.g.: ``['e-', 'D+']`` or
+        ``['e-', 'D+', 'He+']``.
 
     n : `list` of `~astropy.units.Quantity`
         `list` of species density in units convertible to per cubic meter.
@@ -192,7 +192,7 @@ def cold_plasma_permittivity_LRP(
     >>> import astropy.units as u
     >>> from numpy import pi
     >>> B = 2 * u.T
-    >>> species = ["e", "D+"]
+    >>> species = ["e-", "D+"]
     >>> n = [1e18 * u.m**-3, 1e18 * u.m**-3]
     >>> omega = 3.7e9 * (2 * pi) * (u.rad / u.s)
     >>> L, R, P = permittivity = cold_plasma_permittivity_LRP(B, species, n, omega)

diff --git a/plasmapy/formulary/dimensionless.py b/plasmapy/formulary/dimensionless.py
@@ -157,7 +157,7 @@ def Hall_parameter(
 
     particle : `~plasmapy.particles.particle_class.Particle`
         The particle species for which the Hall parameter is calculated
-        for.  Representation of the particle species (e.g., ``'p'`` for
+        for.  Representation of the particle species (e.g., ``'p+'`` for
         protons, ``'D+'`` for deuterium, or ``'He-4 +1'`` for singly
         ionized helium-4).  If no charge state information is provided,
         then the particles are assumed to be singly charged.
@@ -484,7 +484,7 @@ def Lundquist_number(
         The conductivity of the plasma.
 
     ion : `~plasmapy.particles.particle_class.Particle`, optional
-        Representation of the ion species (e.g., ``'p'`` for protons, ``'D+'`` for
+        Representation of the ion species (e.g., ``'p+'`` for protons, ``'D+'`` for
         deuterium, ``'He-4 +1'`` for singly ionized helium-4, etc.). If no charge
         state information is provided, then the ions are assumed to be singly
         ionized. If the density is an ion number density, then this parameter
@@ -562,7 +562,7 @@ def Lundquist_number(
     >>> sigma = 10**-7 * u.S / u.m
     >>> Lundquist_number(L, B, rho, sigma)
     <Quantity 0.866538...>
-    >>> Lundquist_number(L, B, n, sigma, ion="p")
+    >>> Lundquist_number(L, B, n, sigma, ion="p+")
     <Quantity 0.866538...>
     >>> Lundquist_number(L, B, n, sigma, ion="He +2")
     <Quantity 0.434819...>

diff --git a/plasmapy/formulary/distribution.py b/plasmapy/formulary/distribution.py
@@ -39,7 +39,7 @@ def _v_drift_conversion(v_drift):
 def Maxwellian_1D(
     v,
     T,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     v_drift=0,
     vTh=np.nan,
     units="units",
@@ -64,7 +64,7 @@ def Maxwellian_1D(
         The temperature in kelvin.
 
     particle : `str`, optional
-        Representation of the particle species(e.g., ``'p'`` for protons,
+        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.
 
@@ -123,7 +123,7 @@ def Maxwellian_1D(
     --------
     >>> import astropy.units as u
     >>> v = 1 * u.m / u.s
-    >>> Maxwellian_1D(v=v, T=30000 * u.K, particle="e", v_drift=0 * u.m / u.s)
+    >>> Maxwellian_1D(v=v, T=30000 * u.K, particle="e-", v_drift=0 * u.m / u.s)
     <Quantity 5.9163...e-07 s / m>
     """
 
@@ -166,7 +166,7 @@ def Maxwellian_velocity_2D(
     vx,
     vy,
     T,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     vx_drift=0,
     vy_drift=0,
     vTh=np.nan,
@@ -196,7 +196,7 @@ def Maxwellian_velocity_2D(
         The temperature, preferably in kelvin.
 
     particle : `str`, optional
-        Representation of the particle species [e.g., ``'p'`` for protons,
+        Representation of the particle species [e.g., ``'p+'`` for protons,
         ``'D+'`` for deuterium, or ``'He-4 +1'`` for :math:`He_4^{+1}`
         (singly ionized helium-4)], which defaults to electrons.
 
@@ -267,7 +267,7 @@ def Maxwellian_velocity_2D(
     ...     vx=v,
     ...     vy=v,
     ...     T=30000 * u.K,
-    ...     particle="e",
+    ...     particle="e-",
     ...     vx_drift=0 * u.m / u.s,
     ...     vy_drift=0 * u.m / u.s,
     ... )
@@ -317,7 +317,7 @@ def Maxwellian_velocity_3D(
     vy,
     vz,
     T,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     vx_drift=0,
     vy_drift=0,
     vz_drift=0,
@@ -351,7 +351,7 @@ def Maxwellian_velocity_3D(
         The temperature, preferably in kelvin.
 
     particle : `str`, optional
-        Representation of the particle species (e.g., ``'p'`` for protons,
+        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.
 
@@ -426,7 +426,7 @@ def Maxwellian_velocity_3D(
     ...     vy=v,
     ...     vz=v,
     ...     T=30000 * u.K,
-    ...     particle="e",
+    ...     particle="e-",
     ...     vx_drift=0 * u.m / u.s,
     ...     vy_drift=0 * u.m / u.s,
     ...     vz_drift=0 * u.m / u.s,
@@ -476,7 +476,7 @@ def Maxwellian_velocity_3D(
 def Maxwellian_speed_1D(
     v,
     T,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     v_drift=0,
     vTh=np.nan,
     units="units",
@@ -501,7 +501,7 @@ def Maxwellian_speed_1D(
         The temperature, preferably in kelvin.
 
     particle : `str`, optional
-        Representation of the particle species [e.g., ``'p'`` for protons, ``'D+'``
+        Representation of the particle species [e.g., ``'p+'`` for protons, ``'D+'``
         for deuterium, or ``'He-4 +1'`` for :math:`He_4^{+1}`
         (singly ionized helium-4)], which defaults to electrons.
 
@@ -560,7 +560,7 @@ def Maxwellian_speed_1D(
     --------
     >>> import astropy.units as u
     >>> v = 1 * u.m / u.s
-    >>> Maxwellian_speed_1D(v=v, T=30000 * u.K, particle="e", v_drift=0 * u.m / u.s)
+    >>> Maxwellian_speed_1D(v=v, T=30000 * u.K, particle="e-", v_drift=0 * u.m / u.s)
     <Quantity 1.1832...e-06 s / m>
 
     """
@@ -603,7 +603,7 @@ def Maxwellian_speed_1D(
 def Maxwellian_speed_2D(
     v,
     T,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     v_drift=0,
     vTh=np.nan,
     units="units",
@@ -629,7 +629,7 @@ def Maxwellian_speed_2D(
         The temperature, preferably in kelvin.
 
     particle: |particle-like|, optional
-        Representation of the particle species(e.g., ``'p'`` for protons,
+        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.
 
@@ -692,7 +692,7 @@ def Maxwellian_speed_2D(
     --------
     >>> import astropy.units as u
     >>> v = 1 * u.m / u.s
-    >>> Maxwellian_speed_2D(v=v, T=30000 * u.K, particle="e", v_drift=0 * u.m / u.s)
+    >>> Maxwellian_speed_2D(v=v, T=30000 * u.K, particle="e-", v_drift=0 * u.m / u.s)
     <Quantity 2.199...e-12 s / m>
 
     """
@@ -738,7 +738,7 @@ def Maxwellian_speed_2D(
 def Maxwellian_speed_3D(
     v,
     T,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     v_drift=0,
     vTh=np.nan,
     units="units",
@@ -764,9 +764,9 @@ def Maxwellian_speed_3D(
         The temperature, preferably in kelvin.
 
     particle : `str`, optional
-        Representation of the particle species(e.g., ``'p'`` for protons, ``'D+'``
+        Representation of the particle species(e.g., ``'p+'`` for protons, ``'D+'``
         for deuterium, or ``'He-4 +1'`` for :math:`He_4^{+1}`
-        (singly ionized helium-4)), which defaults to electrons.
+        (singly ionized helium-4), which defaults to electrons.
 
     v_drift : `~astropy.units.Quantity`
         The drift speed in units convertible to m/s.
@@ -827,7 +827,7 @@ def Maxwellian_speed_3D(
     --------
     >>> import astropy.units as u
     >>> v = 1 * u.m / u.s
-    >>> Maxwellian_speed_3D(v=v, T=30000 * u.K, particle="e", v_drift=0 * u.m / u.s)
+    >>> Maxwellian_speed_3D(v=v, T=30000 * u.K, particle="e-", v_drift=0 * u.m / u.s)
     <Quantity 2.60235...e-18 s / m>
     """
     if v_drift != 0:
@@ -873,7 +873,7 @@ def kappa_velocity_1D(
     v,
     T,
     kappa,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     v_drift=0,
     vTh=np.nan,
     units="units",
@@ -974,7 +974,7 @@ def kappa_velocity_1D(
     ...     v=v,
     ...     T=30000 * u.K,
     ...     kappa=4,
-    ...     particle="e",
+    ...     particle="e-",
     ...     v_drift=0 * u.m / u.s,
     ... )
     <Quantity 6.75549...e-07 s / m>
@@ -1030,7 +1030,7 @@ def kappa_velocity_3D(
     vz,
     T,
     kappa,
-    particle: ParticleLike = "e",
+    particle: ParticleLike = "e-",
     vx_drift=0,
     vy_drift=0,
     vz_drift=0,
@@ -1068,7 +1068,7 @@ def kappa_velocity_3D(
         than :math:`3/2`.
 
     particle : `str`, optional
-        Representation of the particle species(e.g., 'p' for protons, 'D+'
+        Representation of the particle species(e.g., 'p+' for protons, 'D+'
         for deuterium, or 'He-4 +1' for :math:`He_4^{+1}` : singly ionized
         helium-4)), which defaults to electrons.
 
@@ -1151,7 +1151,7 @@ def kappa_velocity_3D(
     ...     vz=v,
     ...     T=30000 * u.K,
     ...     kappa=4,
-    ...     particle="e",
+    ...     particle="e-",
     ...     vx_drift=0 * u.m / u.s,
     ...     vy_drift=0 * u.m / u.s,
     ...     vz_drift=0 * u.m / u.s,