def test_invalid_kappa(self):
"""
Checks if function raises error when kappa <= 3/2 is passed as an
argument.
"""
with pytest.raises(ValueError):
kappa_thermal_speed(self.T_e, self.kappaInvalid, particle=self.particle)
return
def test_invalid_method(self):
"""
Checks if function raises error when invalid method is passed as an
argument.
"""
with pytest.raises(ValueError):
kappa_thermal_speed(
self.T_e, self.kappa, particle=self.particle, method="invalid"
)
return
def test_mean1(self):
"""
Tests if expected value is returned for a set of regular inputs.
"""
known1 = kappa_thermal_speed(self.T_e,
self.kappa,
particle=self.particle,
method="mean_magnitude")
errStr = (f"Kappa thermal velocity should be {self.mean1True} "
f"and not {known1.si.value}.")
assert np.isclose(known1.value, self.mean1True, rtol=1e-8,
atol=0.0), errStr
return
def kappa_velocity_3D(
vx,
vy,
vz,
T,
kappa,
particle="e",
vx_drift=0,
vy_drift=0,
vz_drift=0,
vTh=np.nan,
units="units",
):
r"""
Return the probability density function for finding a particle with
velocity components `v_x`, `v_y`, and `v_z`in m/s in a suprathermal
plasma of temperature `T` and parameter 'kappa' which follows the
3D Kappa distribution function. This function assumes Cartesian
coordinates.
Parameters
----------
vx: ~astropy.units.Quantity
The velocity in x-direction units convertible to m/s.
vy: ~astropy.units.Quantity
The velocity in y-direction units convertible to m/s.
vz: ~astropy.units.Quantity
The velocity in z-direction units convertible to m/s.
T: ~astropy.units.Quantity
The temperature, preferably in Kelvin.
kappa: ~astropy.units.Quantity
The kappa parameter is a dimensionless number which sets the slope
of the energy spectrum of suprathermal particles forming the tail
of the Kappa velocity distribution function. Kappa must be greater
than :math:`3/2`.
particle: str, optional
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.
vx_drift: ~astropy.units.Quantity, optional
The drift velocity in x-direction units convertible to m/s.
vy_drift: ~astropy.units.Quantity, optional
The drift velocity in y-direction units convertible to m/s.
vz_drift: ~astropy.units.Quantity, optional
The drift velocity in z-direction units convertible to m/s.
vTh: ~astropy.units.Quantity, optional
Thermal velocity (most probable) in m/s. This is used for
optimization purposes to avoid re-calculating `vTh`, for example
when integrating over velocity-space.
units: str, optional
Selects whether to run function with units and unit checks (when
equal to "units") or to run as unitless (when equal to "unitless").
The unitless version is substantially faster for intensive
computations.
Returns
-------
f : ~astropy.units.Quantity
Probability density in Velocity^-1, normalized so that:
:math:`\iiint_{0}^{\infty} f(\vec{v}) d\vec{v} = 1`
Raises
------
TypeError
The parameter arguments are not Quantities and
cannot be converted into Quantities.
~astropy.units.UnitConversionError
If the parameters is not in appropriate units.
ValueError
If the temperature is negative, or the particle mass or charge state
cannot be found.
Notes
-----
In three dimensions, the Kappa velocity distribution function describing
the distribution of particles with speed :math:`v` in a plasma with
temperature :math:`T` and suprathermal parameter :math:`\kappa` is given by:
.. math::
f = A_\kappa \left(1 + \frac{(\vec{v} -
\vec{V_{drift}})^2}{\kappa v_{Th},\kappa^2}\right)^{-(\kappa + 1)}
where :math:`v_{Th},\kappa` is the kappa thermal speed
and :math:`A_\kappa = \frac{1}{2 \pi (\kappa v_{Th},\kappa^2)^{3/2}}
\frac{\Gamma(\kappa + 1)}{\Gamma(\kappa - 1/2) \Gamma(3/2)}` is the
normalization constant.
As :math:`\kappa` approaches infinity, the kappa distribution function
converges to the Maxwellian distribution function.
See also
--------
kappa_velocity_1D
kappa_thermal_speed
Example
-------
>>> from astropy import units as u
>>> v=1 * u.m / u.s
>>> kappa_velocity_3D(vx=v,
... vy=v,
... vz=v,
... T=30000 * u.K,
... kappa=4,
... particle='e',
... vx_drift=0 * u.m / u.s,
... vy_drift=0 * u.m / u.s,
... vz_drift=0 * u.m / u.s)
<Quantity 3.7833...e-19 s3 / m3>
"""
# must have kappa > 3/2 for distribution function to be valid
if kappa <= 3 / 2:
raise ValueError(f"Must have kappa > 3/2, instead of {kappa}.")
if units == "units":
# unit checks and conversions
# checking velocity units
vx = vx.to(u.m / u.s)
vy = vy.to(u.m / u.s)
vz = vz.to(u.m / u.s)
# Catching case where drift velocities have default values, they
# need to be assigned units
vx_drift = _v_drift_units(vx_drift)
vy_drift = _v_drift_units(vy_drift)
vz_drift = _v_drift_units(vz_drift)
# convert temperature to Kelvins
T = T.to(u.K, equivalencies=u.temperature_energy())
if np.isnan(vTh):
# get thermal velocity and thermal velocity squared
vTh = parameters.kappa_thermal_speed(T, kappa, particle=particle)
elif not np.isnan(vTh):
# check units of thermal velocity
vTh = vTh.to(u.m / u.s)
elif np.isnan(vTh) and units == "unitless":
# assuming unitless temperature is in Kelvins
vTh = parameters.kappa_thermal_speed(T * u.K, kappa,
particle=particle).si.value
# getting square of thermal velocity
vThSq = vTh**2
# Get square of relative particle velocity
vSq = (vx - vx_drift)**2 + (vy - vy_drift)**2 + (vz - vz_drift)**2
# calculating distribution function
expTerm = (1 + vSq / (kappa * vThSq))**(-(kappa + 1))
coeff1 = 1 / (2 * np.pi * (kappa * vThSq)**(3 / 2))
coeff2 = gamma(kappa + 1) / (gamma(kappa - 1 / 2) * gamma(3 / 2))
distFunc = coeff1 * coeff2 * expTerm
if units == "units":
return distFunc.to((u.s / u.m)**3)
elif units == "unitless":
return distFunc
def kappa_velocity_1D(v,
T,
kappa,
particle="e",
v_drift=0,
vTh=np.nan,
units="units"):
r"""
Return the probability density at the velocity `v` in m/s
to find a particle `particle` in a plasma of temperature `T`
following the Kappa distribution function in 1D. The slope of the
tail of the Kappa distribution function is set by 'kappa', which
must be greater than :math:`1/2`.
Parameters
----------
v: ~astropy.units.Quantity
The velocity in units convertible to m/s.
T: ~astropy.units.Quantity
The temperature in Kelvin.
kappa: ~astropy.units.Quantity
The kappa parameter is a dimensionless number which sets the slope
of the energy spectrum of suprathermal particles forming the tail
of the Kappa velocity distribution function. Kappa must be greater
than :math:`3/2`.
particle: str, optional
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.
v_drift: ~astropy.units.Quantity, optional
The drift velocity in units convertible to m/s.
vTh: ~astropy.units.Quantity, optional
Thermal velocity (most probable) in m/s. This is used for
optimization purposes to avoid re-calculating `vTh`, for example
when integrating over velocity-space.
units: str, optional
Selects whether to run function with units and unit checks (when
equal to "units") or to run as unitless (when equal to "unitless").
The unitless version is substantially faster for intensive
computations.
Returns
-------
f : ~astropy.units.Quantity
Probability density in Velocity^-1, normalized so that
:math:`\int_{-\infty}^{+\infty} f(v) dv = 1`.
Raises
------
TypeError
A parameter argument is not a `~astropy.units.Quantity` and
cannot be converted into a `~astropy.units.Quantity`.
~astropy.units.UnitConversionError
If the parameters is not in appropriate units.
ValueError
If the temperature is negative, or the particle mass or charge state
cannot be found.
Notes
-----
In one dimension, the Kappa velocity distribution function describing
the distribution of particles with speed :math:`v` in a plasma with
temperature :math:`T` and suprathermal parameter :math:`\kappa` is
given by:
.. math::
f = A_\kappa \left(1 + \frac{(\vec{v} -
\vec{V_{drift}})^2}{\kappa v_{Th},\kappa^2}\right)^{-\kappa}
where :math:`v_{Th},\kappa` is the kappa thermal speed
and :math:`A_\kappa = \frac{1}{\sqrt{\pi} \kappa^{3/2} v_{Th},\kappa^2
\frac{\Gamma(\kappa + 1)}{\Gamma(\kappa - 1/2)}}`
is the normalization constant.
As :math:`\kappa` approaches infinity, the kappa distribution function
converges to the Maxwellian distribution function.
Examples
--------
>>> from astropy import units as u
>>> v=1 * u.m / u.s
>>> kappa_velocity_1D(v=v, T=30000*u.K, kappa=4, particle='e', v_drift=0 * u.m / u.s)
<Quantity 6.75549...e-07 s / m>
See Also
--------
kappa_velocity_3D
kappa_thermal_speed
"""
# must have kappa > 3/2 for distribution function to be valid
if kappa <= 3 / 2:
raise ValueError(f"Must have kappa > 3/2, instead of {kappa}.")
if units == "units":
# unit checks and conversions
# checking velocity units
v = v.to(u.m / u.s)
# catching case where drift velocities have default values, they
# need to be assigned units
if v_drift == 0:
if not isinstance(v_drift, astropy.units.quantity.Quantity):
v_drift = v_drift * u.m / u.s
# checking units of drift velocities
v_drift = v_drift.to(u.m / u.s)
# convert temperature to Kelvins
T = T.to(u.K, equivalencies=u.temperature_energy())
if np.isnan(vTh):
# get thermal velocity and thermal velocity squared
vTh = parameters.kappa_thermal_speed(T, kappa, particle=particle)
elif not np.isnan(vTh):
# check units of thermal velocity
vTh = vTh.to(u.m / u.s)
elif np.isnan(vTh) and units == "unitless":
# assuming unitless temperature is in Kelvins
vTh = (parameters.kappa_thermal_speed(T * u.K,
kappa,
particle=particle)).si.value
# Get thermal velocity squared and accounting for 1D instead of 3D
vThSq = vTh**2
# Get square of relative particle velocity
vSq = (v - v_drift)**2
# calculating distribution function
expTerm = (1 + vSq / (kappa * vThSq))**(-kappa)
coeff1 = 1 / (np.sqrt(np.pi) * kappa**(3 / 2) * vTh)
coeff2 = gamma(kappa + 1) / (gamma(kappa - 1 / 2))
distFunc = coeff1 * coeff2 * expTerm
if units == "units":
return distFunc.to(u.s / u.m)
elif units == "unitless":
return distFunc
def time_kappa_thermal_speed(self):
kappa_thermal_speed(5 * u.eV, 4, 'p', 'mean_magnitude')
