def mass_density(density,
particle: Optional[str] = None,
z_mean: Optional[numbers.Real] = None) -> u.kg / u.m**3:
"""Utility function to merge two possible inputs for particle charge.
Parameters
----------
density : ~astropy.units.Quantity
Either a particle density (number of particles per unit volume, in units
of 1/m^3) or a mass density (in units of kg/m^3 or equivalent).
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.
z_mean : float
An optional float describing the average ionization of a particle
species.
Raises
------
ValueError
If the `density` has units incovertible to either a particle density
or a mass density, or if you pass in a number density without a particle.
Returns
-------
~astropy.units.Quantity
The mass density calculated from all the provided sources of information.
Examples
-------
>>> from astropy import units as u
>>> mass_density(1 * u.m ** -3,'p')
<Quantity 1.67353284e-27 kg / m3>
>>> mass_density(4 * u.m ** -3,'D+')
<Quantity 1.33779786e-26 kg / m3>
"""
if density.unit.is_equivalent(u.kg / u.m**3):
rho = density
elif density.unit.is_equivalent(u.m**-3):
if particle:
m_i = atomic.particle_mass(particle)
Z = _grab_charge(particle, z_mean)
rho = density * m_i + Z * density * m_e
else:
raise ValueError(
f"If passing a number density, you must pass a"
f"particle (not {particle}) to calculate the mass density!")
else:
raise ValueError(f"mass_density accepts either particle (m**-3)"
" or mass (kg * m**-3) density, not {density.unit}!")
return rho
def __init__(self, T_e, n_e, Z=None, particle='p'):
"""
Initialize plasma paramters.
The most basic description is composition (ion), temperature,
density, and ionization.
"""
self.T_e = T_e
self.n_e = n_e
self.particle = particle
self.Z = grab_charge(particle, Z)
# extract mass from particle
self.ionMass = particle_mass(self.particle)
def plasma_frequency(n: u.m**-3, particle='e-', z_mean=None):
r"""Calculate the particle plasma frequency.
Parameters
----------
n : ~astropy.units.Quantity
Particle number density in units convertible to per cubic meter
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.
z_mean : ~astropy.units.Quantity, optional
The average ionization (arithmetic mean) for a plasma where the
a macroscopic description is valid. If this quantity is not
given then the atomic charge state (`int`) of the ion
is used. This is effectively an average plasma frequency for the
plasma where multiple charge states are present.
Returns
-------
omega_p : ~astropy.units.Quantity
The particle plasma frequency in radians per second.
Raises
------
TypeError
If n_i is not a `~astropy.units.Quantity` or particle is not of
an appropriate type.
UnitConversionError
If `n_i` is not in correct units
ValueError
If `n_i` contains invalid values or particle cannot be used to
identify an particle or isotope.
Warns
-----
~astropy.units.UnitsWarning
If units are not provided, SI units are assumed
Notes
-----
The particle plasma frequency is
.. math::
\omega_{pi} = Z e \sqrt{\frac{n_i}{\epsilon_0 m_i}}
At present, astropy.units does not allow direct conversions from
radians/second for angular frequency to 1/second or Hz for
frequency. The dimensionless_angles equivalency allows that
conversion, but does not account for the factor of 2*pi. The
alternatives are to convert to cycle/second or to do the
conversion manually, as shown in the examples.
Example
-------
>>> from astropy import units as u
>>> plasma_frequency(1e19*u.m**-3, particle='p')
<Quantity 4.16329453e+09 rad / s>
>>> plasma_frequency(1e19*u.m**-3, particle='D+')
<Quantity 2.94462452e+09 rad / s>
>>> plasma_frequency(1e19*u.m**-3)
<Quantity 1.78398636e+11 rad / s>
"""
try:
m = atomic.particle_mass(particle)
if z_mean is None:
# warnings.warn("No z_mean given, defaulting to atomic charge",
# PhysicsWarning)
try:
Z = atomic.integer_charge(particle)
except Exception:
Z = 1
else:
# using user provided average ionization
Z = z_mean
Z = np.abs(Z)
# TODO REPLACE WITH Z = np.abs(_grab_charge(particle, z_mean)), some bugs atm
except Exception:
raise ValueError(f"Invalid particle, {particle}, in "
"plasma_frequency.")
omega_p = u.rad * Z * e * np.sqrt(n / (eps0 * m))
return omega_p.si
def gyrofrequency(B: u.T, particle='e-', signed=False, Z=None):
r"""Calculate the particle gyrofrequency in units of radians per second.
Parameters
----------
B : ~astropy.units.Quantity
The magnetic field magnitude in units convertible to tesla.
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.
signed : bool, optional
The gyrofrequency can be defined as signed (negative for electron,
positive for ion). Default is `False` (unsigned, i.e. always
positive).
Z : float or ~astropy.units.Quantity, optional
The average ionization (arithmetic mean) for a plasma where the
a macroscopic description is valid. If this quantity is not
given then the atomic charge state (integer) of the ion
is used. This is effectively an average gyrofrequency for the
plasma where multiple charge states are present, and should
not be interpreted as the gyrofrequency for any single particle.
If not provided, it defaults to the integer charge of the `particle`.
Returns
-------
omega_c : ~astropy.units.Quantity
The particle gyrofrequency in units of radians per second
Raises
------
TypeError
If the magnetic field is not a `Quantity` or particle is not of an
appropriate type
ValueError
If the magnetic field contains invalid values or particle cannot be
used to identify an particle or isotope
Warns
-----
~astropy.units.UnitsWarning
If units are not provided, SI units are assumed
Notes
-----
The particle gyrofrequency is the angular frequency of particle gyration
around magnetic field lines and is given by:
.. math::
\omega_{ci} = \frac{Z e B}{m_i}
The particle gyrofrequency is also known as the particle cyclotron
frequency or the particle Larmor frequency.
The recommended way to convert from angular frequency to frequency
is to use an equivalency between cycles per second and Hertz, as
Astropy's `dimensionles_angles` equivalency does not account for
the factor of 2*pi needed during this conversion. The
`dimensionless_angles` equivalency is appropriate when dividing a
velocity by an angular frequency to get a length scale.
Examples
--------
>>> from astropy import units as u
>>> gyrofrequency(0.1*u.T)
<Quantity 1.75882002e+10 rad / s>
>>> gyrofrequency(0.1*u.T, signed=True)
<Quantity -1.75882002e+10 rad / s>
>>> gyrofrequency(0.01*u.T, 'p')
<Quantity 957883.32241481 rad / s>
>>> gyrofrequency(0.01*u.T, 'p', signed=True)
<Quantity 957883.32241481 rad / s>
>>> gyrofrequency(0.01*u.T, particle='T+')
<Quantity 319964.54975911 rad / s>
>>> omega_ce = gyrofrequency(0.1*u.T)
>>> print(omega_ce)
17588200236.02124 rad / s
>>> f_ce = omega_ce.to(u.Hz, equivalencies=[(u.cy/u.s, u.Hz)])
>>> print(f_ce)
2799249007.6528206 Hz
"""
m_i = atomic.particle_mass(particle)
Z = _grab_charge(particle, Z)
if not signed:
Z = abs(Z)
omega_ci = u.rad * (Z * e * np.abs(B) / m_i).to(1 / u.s)
return omega_ci
def thermal_speed(T,
particle: atomic.Particle = "e-",
method="most_probable",
mass=np.nan * u.kg):
r"""
Return the most probable speed for a particle within a Maxwellian
distribution.
Parameters
----------
T : ~astropy.units.Quantity
The particle temperature in either kelvin or energy per particle
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.
method : str, optional
Method to be used for calculating the thermal speed. Options are
`'most_probable'` (default), `'rms'`, and `'mean_magnitude'`.
mass : ~astropy.units.Quantity
The particle's mass override. Defaults to NaN and if so, doesn't do
anything, but if set, overrides mass acquired from `particle`. Useful
with relative velocities of particles.
Returns
-------
V : ~astropy.units.Quantity
particle thermal speed
Raises
------
TypeError
The particle temperature is not a ~astropy.units.Quantity
~astropy.units.UnitConversionError
If the particle temperature is not in units of temperature or
energy per particle
ValueError
The particle temperature is invalid or particle cannot be used to
identify an isotope or particle
Warns
-----
RelativityWarning
If the ion sound speed exceeds 5% of the speed of light, or
~astropy.units.UnitsWarning
If units are not provided, SI units are assumed.
Notes
-----
The particle thermal speed is given by:
.. math::
V_{th,i} = \sqrt{\frac{2 k_B T_i}{m_i}}
This function yields the most probable speed within a distribution
function. However, the definition of thermal velocity varies by
the square root of two depending on whether or not this velocity
absorbs that factor in the expression for a Maxwellian
distribution. In particular, the expression given in the NRL
Plasma Formulary [1] is a square root of two smaller than the
result from this function.
Examples
--------
>>> from astropy import units as u
>>> thermal_speed(5*u.eV, 'p')
<Quantity 30949.69018286 m / s>
>>> thermal_speed(1e6*u.K, particle='p')
<Quantity 128486.55193256 m / s>
>>> thermal_speed(5*u.eV)
<Quantity 1326205.12123959 m / s>
>>> thermal_speed(1e6*u.K)
<Quantity 5505693.98842538 m / s>
>>> thermal_speed(1e6*u.K, method="rms")
<Quantity 6743070.47577549 m / s>
>>> thermal_speed(1e6*u.K, method="mean_magnitude")
<Quantity 6212510.3969422 m / s>
"""
T = T.to(u.K, equivalencies=u.temperature_energy())
m = mass if np.isfinite(mass) else atomic.particle_mass(particle)
# different methods, as per https://en.wikipedia.org/wiki/Thermal_velocity
if method == "most_probable":
V = (np.sqrt(2 * k_B * T / m)).to(u.m / u.s)
elif method == "rms":
V = (np.sqrt(3 * k_B * T / m)).to(u.m / u.s)
elif method == "mean_magnitude":
V = (np.sqrt(8 * k_B * T / (m * np.pi))).to(u.m / u.s)
else:
raise ValueError("Method {method} not supported in thermal_speed")
return V
def ion_sound_speed(T_e, T_i, gamma_e=1, gamma_i=3, ion='p+', z_mean=None):
r"""
Return the ion sound speed for an electron-ion plasma.
Parameters
----------
T_e : ~astropy.units.Quantity
Electron temperature in units of temperature or energy per
particle. If this is not given, then the electron temperature
is assumed to be zero.
T_i : ~astropy.units.Quantity
Ion temperature in units of temperature or energy per
particle. If this is not given, then the ion temperature is
assumed to be zero.
gamma_e : float or int
The adiabatic index for electrons, which defaults to 1. This
value assumes that the electrons are able to equalize their
temperature rapidly enough that the electrons are effectively
isothermal.
gamma_i : float or int
The adiabatic index for ions, which defaults to 3. This value
assumes that ion motion has only one degree of freedom, namely
along magnetic field lines.
ion : str, optional
Representation of the ion species (e.g., `'p'` for protons,
`'D+'` for deuterium, or 'He-4 +1' for singly ionized
helium-4), which defaults to protons. If no charge state
information is provided, then the ions are assumed to be
singly charged.
z_mean : ~astropy.units.Quantity, optional
The average ionization (arithmetic mean) for a plasma where the
a macroscopic description is valid. If this quantity is not
given then the atomic charge state (integer) of the ion
is used. This is effectively an average ion sound speed for the
plasma where multiple charge states are present.
Returns
-------
V_S : ~astropy.units.Quantity
The ion sound speed in units of meters per second.
Raises
------
TypeError
If any of the arguments are not entered as keyword arguments
or are of an incorrect type.
ValueError
If the ion mass, adiabatic index, or temperature are invalid.
~plasmapy.utils.PhysicsError
If an adiabatic index is less than one.
~astropy.units.UnitConversionError
If the temperature is in incorrect units.
Warns
-----
RelativityWarning
If the ion sound speed exceeds 5% of the speed of light.
~astropy.units.UnitsWarning
If units are not provided, SI units are assumed.
Notes
-----
The ion sound speed :math:`V_S` is approximately given by
.. math::
V_S = \sqrt{\frac{\gamma_e Z k_B T_e + \gamma_i k_B T_i}{m_i}}
where :math:`\gamma_e` and :math:`\gamma_i` are the electron and
ion adiabatic indices, :math:`k_B` is the Boltzmann constant,
:math:`T_e` and :math:`T_i` are the electron and ion temperatures,
:math:`Z` is the charge state of the ion, and :math:`m_i` is the
ion mass.
This function assumes that the product of the wavenumber and the
Debye length is small. In this limit, the ion sound speed is not
dispersive. In other words, it is frequency independent.
When the electron temperature is much greater than the ion
temperature, the ion sound velocity reduces to
:math:`\sqrt{\gamma_e k_B T_e / m_i}`. Ion acoustic waves can
therefore occur even when the ion temperature is zero.
Example
-------
>>> from astropy import units as u
>>> ion_sound_speed(T_e=5e6*u.K, T_i=0*u.K, ion='p', gamma_e=1, gamma_i=3)
<Quantity 203155.0764042 m / s>
>>> ion_sound_speed(T_e=5e6*u.K, T_i=0*u.K)
<Quantity 203155.0764042 m / s>
>>> ion_sound_speed(T_e=500*u.eV, T_i=200*u.eV, ion='D+')
<Quantity 229586.01860212 m / s>
"""
m_i = atomic.particle_mass(ion)
Z = _grab_charge(ion, z_mean)
for gamma, particles in zip([gamma_e, gamma_i], ["electrons", "ions"]):
if not isinstance(gamma, (numbers.Real, numbers.Integral)):
raise TypeError(
f"The adiabatic index gamma for {particles} must be "
"a float or int")
if gamma < 1:
raise utils.PhysicsError(
f"The adiabatic index for {particles} must be between "
"one and infinity")
T_i = T_i.to(u.K, equivalencies=u.temperature_energy())
T_e = T_e.to(u.K, equivalencies=u.temperature_energy())
try:
V_S_squared = (gamma_e * Z * k_B * T_e + gamma_i * k_B * T_i) / m_i
V_S = np.sqrt(V_S_squared).to(u.m / u.s)
except Exception:
raise ValueError("Unable to find ion sound speed.")
return V_S
def deBroglie_wavelength(V, particle):
r"""
Calculates the de Broglie wavelength.
Parameters
----------
V : ~astropy.units.Quantity
Particle velocity in units convertible to meters per second.
particle : str or ~astropy.units.Quantity
Representation of the particle species (e.g., `'e'`, `'p'`, `'D+'`,
or `'He-4 1+'`, or the particle mass in units convertible to
kilograms.
Returns
-------
lambda_dB : ~astropy.units.Quantity
The de Broglie wavelength in units of meters.
Raises
------
TypeError
The velocity is not a `~astropy.units.Quantity` and cannot be
converted into a ~astropy.units.Quantity.
~astropy.units.UnitConversionError
If the velocity is not in appropriate units.
~plasmapy.utils.RelativityError
If the magnitude of `V` is faster than the speed of light.
Warns
-----
~astropy.units.UnitsWarning
If units are not provided, SI units are assumed
Notes
-----
The de Broglie wavelength is given by
.. math::
\lambda_{dB} = \frac{h}{p} = \frac{h}{\gamma m V}
where :math:`h` is the Planck constant, :math:`p` is the
relativistic momentum of the particle, :math:`gamma` is the
Lorentz factor, :math:`m` is the particle's mass, and :math:`V` is the
particle's velocity.
Examples
--------
>>> from astropy import units as u
>>> velocity = 1.4e7 * u.m / u.s
>>> deBroglie_wavelength(velocity, 'e')
<Quantity 5.18997095e-11 m>
>>> deBroglie_wavelength(V = 0 * u.m / u.s, particle = 'D+')
<Quantity inf m>
"""
V = np.abs(V)
if np.any(V >= c):
raise utils.RelativityError(
"Velocity input in deBroglie_wavelength cannot "
"be greater than or equal to the speed of "
"light.")
if not isinstance(particle, u.Quantity):
try:
# TODO: Replace with more general routine!
m = atomic.particle_mass(particle)
except Exception:
raise ValueError("Unable to find particle mass.")
else:
try:
m = particle.to(u.kg)
except Exception:
raise u.UnitConversionError("The second argument for deBroglie"
" wavelength must be either a "
"representation of a particle or a"
" Quantity with units of mass.")
if V.size > 1:
lambda_dBr = np.ones(V.shape) * np.inf * u.m
indices = V.value != 0
lambda_dBr[indices] = h / (m * V[indices] * Lorentz_factor(V[indices]))
else:
if V == 0 * u.m / u.s:
lambda_dBr = np.inf * u.m
else:
lambda_dBr = h / (Lorentz_factor(V) * m * V)
return lambda_dBr.to(u.m)
def ion_sound_speed(T_e: u.K,
T_i: u.K,
n_e: u.m ** -3 = None,
k: u.m ** -1 = None,
gamma_e=1,
gamma_i=3,
ion='p+',
z_mean=None) -> u.m / u.s:
r"""
Return the ion sound speed for an electron-ion plasma.
Parameters
----------
T_e : ~astropy.units.Quantity
Electron temperature in units of temperature or energy per
particle. If this is not given, then the electron temperature
is assumed to be zero.
T_i : ~astropy.units.Quantity
Ion temperature in units of temperature or energy per
particle. If this is not given, then the ion temperature is
assumed to be zero.
n_e : ~astropy.units.Quantity
Electron number density. If this is not given, then ion_sound_speed
will be approximated in the non-dispersive limit
(:math:`k^2 \lambda_{D}^2` will be assumed zero). If n_e is given,
a value for k must also be given.
k : ~astropy.units.Quantity
Wavenumber (in units of inverse length, e.g. per meter). If this
is not given, then ion_sound_speed will be approximated in the
non-dispersive limit (:math:`k^2 \lambda_{D}^2` will be assumed zero).
If k is given, a value for n_e must also be given.
gamma_e : float or int
The adiabatic index for electrons, which defaults to 1. This
value assumes that the electrons are able to equalize their
temperature rapidly enough that the electrons are effectively
isothermal.
gamma_i : float or int
The adiabatic index for ions, which defaults to 3. This value
assumes that ion motion has only one degree of freedom, namely
along magnetic field lines.
ion : str, optional
Representation of the ion species (e.g., `'p'` for protons,
`'D+'` for deuterium, or 'He-4 +1' for singly ionized
helium-4), which defaults to protons. If no charge state
information is provided, then the ions are assumed to be
singly charged.
z_mean : ~astropy.units.Quantity, optional
The average ionization (arithmetic mean) for a plasma where the
a macroscopic description is valid. If this quantity is not
given then the atomic charge state (integer) of the ion
is used. This is effectively an average ion sound speed for the
plasma where multiple charge states are present.
Returns
-------
V_S : ~astropy.units.Quantity
The ion sound speed in units of meters per second.
Raises
------
TypeError
If any of the arguments are not entered as keyword arguments
or are of an incorrect type.
ValueError
If the ion mass, adiabatic index, or temperature are invalid.
~plasmapy.utils.PhysicsError
If an adiabatic index is less than one.
~astropy.units.UnitConversionError
If the temperature, electron number density, or wavenumber
is in incorrect units.
Warns
-----
RelativityWarning
If the ion sound speed exceeds 5% of the speed of light.
~astropy.units.UnitsWarning
If units are not provided, SI units are assumed.
PhysicsWarning
If only one of (k, n_e) is given, the non-dispersive limit
is assumed.
Notes
-----
The ion sound speed :math:`V_S` is given by
.. math::
V_S = \sqrt{\frac{\gamma_e Z k_B T_e + \gamma_i k_B T_i}{m_i (1 + k^2 \lambda_{D}^2)}}
where :math:`\gamma_e` and :math:`\gamma_i` are the electron and
ion adiabatic indices, :math:`k_B` is the Boltzmann constant,
:math:`T_e` and :math:`T_i` are the electron and ion temperatures,
:math:`Z` is the charge state of the ion, :math:`m_i` is the
ion mass, :math:`\lambda_{D}` is the Debye length, and :math:`k` is the
wavenumber.
In the non-dispersive limit (:math:`k^2 \lambda_{D}^2` is small) the
equation for :math:`V_S` is approximated (the denominator reduces
to :math:`m_i`).
When the electron temperature is much greater than the ion
temperature, the ion sound velocity reduces to
:math:`\sqrt{\gamma_e k_B T_e / m_i}`. Ion acoustic waves can
therefore occur even when the ion temperature is zero.
Example
-------
>>> from astropy import units as u
>>> n = 5e19*u.m**-3
>>> k_1 = 3e1*u.m**-1
>>> k_2 = 3e7*u.m**-1
>>> ion_sound_speed(T_e=5e6*u.K, T_i=0*u.K, ion='p', gamma_e=1, gamma_i=3)
<Quantity 203155... m / s>
>>> ion_sound_speed(T_e=5e6*u.K, T_i=0*u.K, n_e=n, k=k_1, ion='p', gamma_e=1, gamma_i=3)
<Quantity 203155... m / s>
>>> ion_sound_speed(T_e=5e6*u.K, T_i=0*u.K, n_e=n, k=k_2, ion='p', gamma_e=1, gamma_i=3)
<Quantity 310.31... m / s>
>>> ion_sound_speed(T_e=5e6*u.K, T_i=0*u.K, n_e=n, k=k_1)
<Quantity 203155... m / s>
>>> ion_sound_speed(T_e=500*u.eV, T_i=200*u.eV, n_e=n, k=k_1, ion='D+')
<Quantity 229585... m / s>
"""
m_i = atomic.particle_mass(ion)
Z = _grab_charge(ion, z_mean)
for gamma, particles in zip([gamma_e, gamma_i], ["electrons", "ions"]):
if not isinstance(gamma, (numbers.Real, numbers.Integral)):
raise TypeError(f"The adiabatic index gamma for {particles} must be "
"a float or int")
if gamma < 1:
raise PhysicsError(f"The adiabatic index for {particles} must be between "
f"one and infinity")
# Assume non-dispersive limit if values for n_e (or k) are not specified
klD2 = 0.0
if (n_e is None) ^ (k is None):
warnings.warn("The non-dispersive limit has been assumed for "
"this calculation. To prevent this, values must "
"be specified for both n_e and k.", PhysicsWarning)
elif n_e is not None and k is not None:
lambda_D = Debye_length(T_e, n_e)
klD2 = (k * lambda_D) ** 2
try:
V_S_squared = (gamma_e * Z * k_B * T_e + gamma_i * k_B * T_i) / (m_i * (1 + klD2))
V_S = np.sqrt(V_S_squared).to(u.m / u.s)
except Exception:
raise ValueError("Unable to find ion sound speed.")
return V_S
