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 setup_class(self):
"""initializing parameters for tests"""
self.T_e = 30000 * u.K
self.kappa = 4
self.kappaInvalid = 3 / 2
self.v = 1e5 * u.m / u.s
self.v_drift = 1000000 * u.m / u.s
self.v_drift2 = 0 * u.m / u.s
self.v_drift3 = 1e5 * u.m / u.s
self.start = -5000
self.stop = -self.start
self.dv = 10000 * u.m / u.s
self.v_vect = np.arange(self.start, self.stop,
dtype="float64") * self.dv
self.particle = "e"
self.vTh = kappa_thermal_speed(self.T_e,
kappa=self.kappa,
particle=self.particle)
self.distFuncTrue = 6.637935187755855e-07
def setup_class(self):
"""initializing parameters for tests"""
self.T = 1.0 * u.eV
self.kappa = 4
self.kappaInvalid = 3 / 2
self.particle = "H+"
# get thermal velocity and thermal velocity squared
self.vTh = kappa_thermal_speed(self.T,
kappa=self.kappa,
particle=self.particle)
self.vx = 1e5 * u.m / u.s
self.vy = 1e5 * u.m / u.s
self.vz = 1e5 * u.m / u.s
self.vx_drift = 0 * u.m / u.s
self.vy_drift = 0 * u.m / u.s
self.vz_drift = 0 * u.m / u.s
self.vx_drift2 = 1e5 * u.m / u.s
self.vy_drift2 = 1e5 * u.m / u.s
self.vz_drift2 = 1e5 * u.m / u.s
self.distFuncTrue = 1.1847914288918793e-22
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 units of inverse velocity, normalized so that:
:math:`\iiint_{0}^∞ f(\vec{v}) d\vec{v} = 1`
Raises
------
`TypeError`
If any of the parameters is not a `~astropy.units.Quantity` and
cannot be converted into one.
`~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:`κ` is given by:
.. math::
f = A_κ \left(1 + \frac{(\vec{v} -
\vec{V_{drift}})^2}{κ v_{Th},κ^2}\right)^{-(κ + 1)}
where :math:`v_{Th},κ` is the kappa thermal speed
and :math:`A_κ = \frac{1}{2 π (κ v_{Th},κ^2)^{3/2}}
\frac{Γ(κ + 1)}{Γ(κ - 1/2) Γ(3/2)}` is the
normalization constant.
As :math:`κ → ∞`, the kappa distribution function converges to the
Maxwellian distribution function.
See Also
--------
kappa_velocity_1D
~plasmapy.formulary.speeds.kappa_thermal_speed
Examples
--------
>>> 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_value(SPEED_UNITS)
vy = vy.to_value(SPEED_UNITS)
vz = vz.to_value(SPEED_UNITS)
# Catching case where drift velocities have default values
vx_drift = _v_drift_conversion(vx_drift)
vy_drift = _v_drift_conversion(vy_drift)
vz_drift = _v_drift_conversion(vz_drift)
# convert temperature to kelvin
T = T.to_value(u.K, equivalencies=u.temperature_energy())
if not np.isnan(vTh):
# check units of thermal velocity
vTh = vTh.to_value(SPEED_UNITS)
if np.isnan(vTh):
# get thermal velocity and thermal velocity squared
vTh = kappa_thermal_speed(T << u.K, kappa, particle=particle).to_value(
SPEED_UNITS
)
# 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 << SPEED_DISTRIBUTION_UNITS_3D
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\ :sup:`-1`\ , normalized so that
:math:`\int_{-∞}^{+∞} 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:`κ` is
given by:
.. math::
f = A_κ \left(1 + \frac{(\vec{v} -
\vec{V_{drift}})^2}{κ v_{Th},κ^2}\right)^{-κ}
where :math:`v_{Th},κ` is the kappa thermal speed
and :math:`A_κ = \frac{1}{\sqrt{π} κ^{3/2} v_{Th},κ^2
\frac{Γ(κ + 1)}{Γ(κ - 1/2)}}`
is the normalization constant.
As :math:`κ → ∞`, 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
~plasmapy.formulary.speeds.kappa_thermal_speed
"""
# must have kappa > 3/2 for distribution function to be valid
if kappa <= 3 / 2:
raise ValueError(f"Must have κ > 3/2, instead of {kappa}.")
if units == "units":
# unit checks and conversions
# checking velocity units
v = v.to_value(SPEED_UNITS)
# catching case where drift velocities have default values
v_drift = _v_drift_conversion(v_drift)
# convert temperature to kelvin
T = T.to_value(u.K, equivalencies=u.temperature_energy())
if not np.isnan(vTh):
# check units of thermal velocity
vTh = vTh.to_value(SPEED_UNITS)
if np.isnan(vTh):
# get thermal velocity and thermal velocity squared
vTh = kappa_thermal_speed(T << u.K, kappa, particle=particle).to_value(
SPEED_UNITS
)
# 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 << SPEED_DISTRIBUTION_UNITS_1D
elif units == "unitless":
return distFunc