Conversion

The ‘conv’ (conversion) provides tools for the conversion between various physical quantities pertinent to particle physics.

This module includes handling the system properties calculation and conversion such as adiabatic invariant calculations and facilitating unit transformations in radiation belt studies.

Main Features:

Calculation of adiabatic invariants.
Energy and momentum conversion (en2pc, pc2en).
Conversion between Jc and K (Jcmu2K, Kmu2Jc).
Conversion between mu and pc (mural2pc/mu2pc, pcral2mu/pc2mu).
Conversion between mu and energy (mural2en/mu2en, enral2mu/en2mu).
Conversion between L, alpha and K (Lal2K, LK2al).

`Jcmu2K`(Jc, mu)	Calculates adiabatic invariant K.
`Kmu2Jc`(K, mu)	Calculates adiabatic invariant Jc = J*c
`LK2al`(L[, K, B0, xtol])	Calculate the pitch-angle in radians given the L-shell and the adiabatic invariant K.
`Lal2K`(L[, al, B0])	Calculate the adiabatic invariant K, from of L-shell and pitch-angle.
`en2gamma`(en[, mc2])	Calculates the Lorentz factor (γ) from kinetic energy (MeV).
`en2mu`(en, r[, al])	Convert energy in MeV to first adiabatic invariant, mu, in MeV/G.
`en2pc`(en)	Calculates p*c (MeV) from energy (MeV).
`enral2mu`(en, r[, al])	Convert energy in MeV to first adiabatic invariant, mu, in MeV/G.
`mlt2phi`(mlt)	Convert Magnetic Local Time (MLT, hours) to magnetic local time angle \(\phi\) (radians).
`mu2en`(mu, r[, al])	Convert first adiabatic invariant, mu, to energy in MeV
`mu2pc`(mu, r[, al])	Calculate the momentum times the speed of light (pc), in MeV.
`mural2en`(mu, r[, al])	Convert first adiabatic invariant, mu, to energy in MeV
`mural2pc`(mu, r[, al, B0])	Calculate the momentum times the speed of light (pc), in MeV.
`pc2en`(pc)	Calculates energy (MeV) from p*c (MeV).
`pc2mu`(pc, r[, al])	Calculate first adiabatic invariant mu from pc (momentum times the speed of light).
`pcral2mu`(pc, r[, al, B0])	Calculate first adiabatic invariant mu from pc (momentum times the speed of light).
`phi2mlt`(phi)	Convert magnetic local time angle \(\phi\) (radians) to Magnetic Local Time (MLT, hours).

Functions

rbamlib.conv.en2pc(en)

Calculates p*c (MeV) from energy (MeV).

Parameters:: en (float or ndarray) – The energy or an array of energies in MeV.
Returns:: pc – The momentum times the speed of light (p*c) in MeV corresponding to the input energy.
Return type:: ndarray

Notes

\[pc = \sqrt{\left(\frac{energy}{mc^2} + 1\right)^2 - 1} \cdot mc^2\]

where \(mc^2\) (the rest mass energy of an electron) is 0.511 MeV.

rbamlib.conv.pc2en(pc)

Calculates energy (MeV) from p*c (MeV).

Parameters:: pc (float or ndarray) – The momentum times the speed of light (p*c) in MeV, either as a single floating-point number or an ndarray of numbers.
Returns:: en – The energy in MeV corresponding to the given momentum p*c.
Return type:: ndarray

Notes

\[en = \left( \sqrt{1 + \left(\frac{pc}{mc^2}\right)^2} - 1 \right) \cdot mc^2\]

where \(mc^2\) (the rest mass energy of an electron) is 0.511 MeV.

rbamlib.conv.Jcmu2K(Jc, mu)

Calculates adiabatic invariant K.

Calculates the adiabatic invariant K from the second adiabatic invariant Jc and the first adiabatic invariant mu.

Parameters:

Jc (float or ndarray) – The second adiabatic invariant times the speed of light, Jc = J*c, where J is the second adiabatic and c is the speed of light. Units are MeV/G.
mu (float or ndarray) – The first adiabatic invariant mu, in MeV/Gauss

Returns:

The adiabatic invariant K, in units of G^0.5 * R

Return type:

float or ndarray

Notes

\[K = \frac{Jc}{\sqrt{8 \cdot mc^2 \cdot \mu}}\]

where \(mc^2\) (the rest mass energy of an electron) is 0.511 MeV.

rbamlib.conv.Kmu2Jc(K, mu)

Calculates adiabatic invariant Jc = J*c

Calculates the second adiabatic invariant Jc from the adiabatic invariant K and the first adiabatic invariant mu.

Parameters:

K (float or ndarray) – The adiabatic invariant K, in G^0.5 * R.
mu (float or ndarray) – The first adiabatic invariant mu, in MeV/Gauss

Returns:

The second adiabatic invariant times the speed of light, Jc = J*c, where J is the second adiabatic and c is the speed of light. Units are MeV/G.

Return type:

float or ndarray

Notes

\[Jc = K \cdot \sqrt{8 \cdot mc^2 \cdot \mu}\]

where \(mc^2\) (the rest mass energy of an electron) is 0.511 MeV.

rbamlib.conv.mural2pc(mu, r, al=1.5707963267948966, B0=<function B0>)

Calculate the momentum times the speed of light (pc), in MeV.

Parameters:

mu (float or ndarray) – First adiabatic invariant, mu, in MeV/G.
r (float or ndarray) – Radial distance, expressed in the planet radii (R).
al (float or ndarray, default=np.pi / 2) – Pitch-angle, in radians. Default is 90 degrees.
B0 (function, default=rbamlib.models.dip.B0) – Function that calculates the magnetic field in Gauss at a given radial distance r. By default, Earth’s dipole field model is used.

Returns:

The momentum times the speed of light, pc = p*c, in MeV.

Return type:

float or ndarray

Notes

\[pc = \frac{\sqrt{2 \cdot \mu \cdot mc^2 \cdot B_0(r)}}{\sin(\alpha)}\]

Where:

\(\mu\) is the magnetic moment
\(mc^2\) is the electron rest mass energy equivalent
\(B_0(r)\) is the magnetic field strength in Gauss at distance r for the specified planet
\(\alpha\) is the pitch-angle

See also

mu2pc: Alias to the mural2pc function.
rbamlib.models.dip.B0: Dipole magnetic field

rbamlib.conv.pcral2mu(pc, r, al=1.5707963267948966, B0=<function B0>)

Calculate first adiabatic invariant mu from pc (momentum times the speed of light).

Parameters:

pc (float or ndarray) – The momentum times the speed of light, pc = p*c, in MeV.
r (float or ndarray) – Radial distance, expressed in the planet radii (R).
al (float or ndarray, default=np.pi / 2) – Pitch-angle, in radians. Default is 90 degrees.
B0 (function, default=rbamlib.models.dip.B0) – Function that calculates the magnetic field in Gauss at a given radial distance r. By default, Earth’s dipole field model is used.

Returns:

First adiabatic invariant, mu, in MeV/G.

Return type:

float or ndarray

Notes

\[\mu = \frac{{pc^2 \cdot \sin^2(\alpha)}}{{2 \cdot mc^2 \cdot B}}\]

Where:

\(pc\) the momentum times the speed of light, pc = p*c,
\(mc^2\) is the electron rest mass energy equivalent
\(B_0(r)\) is the magnetic field strength in Gauss at distance r for the specified planet
\(\alpha\) is the pitch-angle

See also

pc2mu: Alias to the pcral2mu function.
rbamlib.models.dip.B0: Dipole magnetic field

rbamlib.conv.mural2en(mu, r, al=1.5707963267948966, *B0)

Convert first adiabatic invariant, mu, to energy in MeV

Parameters:

mu (float or ndarray) – First adiabatic invariant, mu, in MeV/G.
r (float or ndarray) – Radial distance, expressed in the planet radii (R).
al (float or ndarray, default=np.pi / 2) – Pitch-angle, in radians. Default is 90 degrees.
*B0 (function, optional) – Argument of mural2pc defining function that calculates the magnetic field

Returns:

Energy, in MeV.

Return type:

float or ndarray

Notes

This function is a wrapper of mural2pc and pc2en.

See also

mural2pc: Calculate the momentum times the speed of light (pc), in MeV from mu.
pc2en: Calculates energy (MeV) from p*c (MeV).

rbamlib.conv.enral2mu(en, r, al=1.5707963267948966, *B0)

Convert energy in MeV to first adiabatic invariant, mu, in MeV/G.

Parameters:

en (float or ndarray) – Energy, in MeV.
r (float or ndarray) – Radial distance, expressed in the planet radii (R).
al (float or ndarray, default=np.pi / 2) – Pitch-angle, in radians. Default is 90 degrees.
*B0 (function, optional) – Argument of pcral2mu defining function that calculates the magnetic field

Returns:

First adiabatic invariant, mu, in MeV/G.

Return type:

float or ndarray

Notes

This function is a wrapper of pcral2mu and en2pc.

See also

pcral2mu: Calculate first adiabatic invariant mu from pc.
en2pc: Calculates p*c (MeV) from energy (MeV).

rbamlib.conv.Lal2K(L, al=1.5707963267948966, B0=<function B0>)

Calculate the adiabatic invariant K, from of L-shell and pitch-angle.

Parameters:

L (float or ndarray) – L-shell value
al (float or ndarray) – Pitch-angle, in radians. Default is 90 degrees, which results in K=0.
B0 (function, default=rbamlib.models.dip.B0) – Function that calculates the magnetic field in Gauss at a given L-shell L (or r). By default, Earth’s dipole field model is used.

Returns:

The adiabatic invariant K, in units of G^0.5 * R

Return type:

float or ndarray

Notes

\[K = \frac{Y(\alpha)}{\sin(\alpha)} \cdot L \cdot \sqrt{B_0(L)}\]

where:

\(\alpha\) is the pitch-angle in radians
\(L\) is the L-shell
\(Y(\alpha)\) is a Y-function
\(B_0(L)\) is the magnetic field strength at L-shell L.

See also

rbamlib.models.dip.Y: Y-function
rbamlib.models.dip.B0: Dipole magnetic field

rbamlib.conv.LK2al(L, K=0, B0=<function B0>, xtol=1e-09)

Calculate the pitch-angle in radians given the L-shell and the adiabatic invariant K.

This function uses numerical methods to find the pitch angle where the calculated function based on the dipole field properties matches K.

Parameters:

L (float or ndarray) – L-shell value at which the pitch-angle is to be calculated.
K (float or ndarray, default K=0) – Adiabatic invariant K, in units of G^0.5 * R. Should be the same shape as L if an array is provided. At default K=0 pitch angle is 90 degrees.
B0 (function, default=rbamlib.models.dip.B0) – Function that calculates the magnetic field in Gauss at a given L-shell, or r. By default, Earth’s dipole field model is used.
xtol (float, default=1e-9) – Tolerance for the numerical root finder.

Returns:

Pitch angle in radians.

Return type:

ndarray

Notes

The pitch-angle \(\alpha\) is calculated by solving the equation:

\[\frac{Y(\alpha)}{\sin(\alpha)} = \frac{K}{R \sqrt{B_0(L)}}\]

where:

\(Y(\alpha)\) is a Y-function specific to the dipole field,
\(B_0(L)\) is the dipole magnetic field strength at L-shell L (or r).

The function uses the fsolve method from SciPy to numerically solve for \(\alpha\) at each value of L. The initial guess is set near \(\frac{\pi}{4}\) and uses a tight tolerance to ensure accurate results. The shape of the output array matches the input array L or K.

rbamlib.conv.en2gamma(en, mc2=0.51099895)

Calculates the Lorentz factor (γ) from kinetic energy (MeV).

Parameters:

en (float or ndarray) – The kinetic energy or an array of kinetic energies in MeV.
mc2 (float, optional) – The rest mass energy (\(mc^2\)) in MeV. Default is provided for electrons (typically 0.511 MeV).

Returns:

gamma – The Lorentz factor corresponding to the input kinetic energy.

Return type:

float or ndarray

Notes

The total energy of a particle is given by

\[E = \gamma m c^2\]

where the Lorentz factor is

\[\gamma = \frac{E}{mc^2} = \frac{en}{mc^2} + 1\]

Here, en is the kinetic energy.

rbamlib.conv.phi2mlt(phi)

Convert magnetic local time angle \(\phi\) (radians) to Magnetic Local Time (MLT, hours).

Parameters:: phi (float or ndarray) – Magnetic local time angle \(\Phi\) in radians. Can be any real value; the mapping is periodic with \(2\pi\).
Returns:: Magnetic Local Time (MLT) in hours.
Return type:: float or ndarray

Notes

\(\phi = 0\) → MLT = 12 h (noon)
\(\phi = \pi/2\) → MLT = 18 h (dusk)
\(\phi = \pi\) → MLT = 0 h (midnight)
\(\phi = 3\pi/2\) → MLT = 6 h (dawn)

\[{\rm MLT} = \left( \frac{12\,\Phi}{\pi} + 12 \right) \bmod 24.\]

Examples

>>> import numpy as np
>>> phi2mlt(0.0)                     # φ = 0 -> MLT = 12 h (noon)
12.0
>>> phi2mlt(np.pi)                   # φ = π -> MLT = 24 ≡ 0 h (midnight)
0.0
>>> phi2mlt(3*np.pi/2)                # φ = 3π/2 -> MLT = 18 h
18.0

rbamlib.conv.mlt2phi(mlt)

Convert Magnetic Local Time (MLT, hours) to magnetic local time angle \(\phi\) (radians).

Parameters:: mlt (float or ndarray) – Magnetic Local Time in hours.
Returns:: Magnetic local time angle \(\phi\) in radians.
Return type:: float or ndarray

Notes

MLT = 12 h → \(\phi = 0\) (noon)
MLT = 18 h → \(\phi = \pi/2\) (dusk)
MLT = 0 h → \(\phi = \pi\) (midnight)
MLT = 6 h → \(\phi = 3\pi/2\) (dawn)

\[\phi = \left( \mathrm{MLT} \bmod 24 - 12 \right)\frac{\pi}{12}\]

Examples

>>> mlt2phi(12.0)  # noon
0.0
>>> mlt2phi(0.0)   # midnight
3.141592653589793

Aliases

rbamlib.conv.mu2pc(mu, r, al=1.5707963267948966, *B0)

Calculate the momentum times the speed of light (pc), in MeV.

See also

mural2pc: Alias of the mural2pc function.

rbamlib.conv.pc2mu(pc, r, al=1.5707963267948966, *B0)

Calculate first adiabatic invariant mu from pc (momentum times the speed of light).

See also

pcral2mu: Alias of the pcral2mu function.

rbamlib.conv.mu2en(mu, r, al=1.5707963267948966, *B0)

Convert first adiabatic invariant, mu, to energy in MeV

See also

mural2en: Alias of the mural2en function.

rbamlib.conv.en2mu(en, r, al=1.5707963267948966, *B0)

Convert energy in MeV to first adiabatic invariant, mu, in MeV/G.

See also

enral2mu: Alias of the enral2mu function.