Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/stourgai/WPIT/llms.txt

Use this file to discover all available pages before exploring further.

The magnetic field functions in Environment_mod implement an idealized Earth-centered magnetic dipole model. This approximation is standard in inner-magnetosphere wave-particle interaction studies and provides analytically tractable expressions for field strength, field-line geometry, and the gradient of B — quantities that drive particle mirroring and bounce motion. All functions assume a geocentric dipole with an equatorial surface field of B0=31,200 nTB_0 = 31{,}200\ \text{nT}. 
import WPIT.Environment_mod as env

# Evaluate the dipole field at L=4, magnetic latitude = 20°
import numpy as np
B = env.Bmag_dipole(4.0, np.radians(20.0))
print(f"B = {B:.3e} T")

​
Bmag_dipole

Calculates the magnitude of Earth’s geomagnetic dipole field at a given L-shell and magnetic latitude. The dipole field magnitude follows: B=B0L31+3sin⁡2λcos⁡6λB = \frac{B_0}{L^3} \frac{\sqrt{1 + 3\sin^2\lambda}}{\cos^6\lambda} where B0=31,200 nTB_0 = 31{,}200\ \text{nT} is the equatorial surface field, LL is the L-shell, and λ\lambda is the magnetic latitude. Reference: Parks, G. K. (1991). Physics of Space Plasmas: An Introduction, 1st ed. Addison-Wesley, p. 54.

​
Parameters

​
L_arg
float
required
L-shell value (dimensionless). Represents the equatorial crossing distance of the field line in units of Earth radii. Typical inner-magnetosphere range: 1.5 – 8.
​
lamda_arg
float
required
Magnetic latitude in radians. The equator corresponds to lamda_arg = 0. Valid range: −π/2-\pi/2 to π/2\pi/2.

​
Returns

​
Bmag
float
Geomagnetic dipole field magnitude in Tesla (T).

​
Example

import numpy as np
import WPIT.Environment_mod as env

# Equatorial field at L = 4
B_eq = env.Bmag_dipole(4.0, 0.0)
print(f"Equatorial B at L=4: {B_eq:.3e} T")
# Equatorial B at L=4: 1.225e-08 T

# Field at L = 4, latitude = 30°
B_30 = env.Bmag_dipole(4.0, np.radians(30.0))
print(f"B at L=4, λ=30°: {B_30:.3e} T")

# Profile along a field line
latitudes = np.linspace(0, np.radians(50), 100)
B_profile = env.Bmag_dipole(4.0, latitudes)
lamda_arg must be in radians, not degrees. Use numpy.radians() to convert. The formula becomes singular as λ→±90°\lambda \to \pm 90° (at the magnetic poles); avoid evaluating near the poles.

​
dB_ds

Calculates the gradient of the magnetic field strength with respect to arc length along the magnetic field line, ∂B/∂s\partial B / \partial s. This quantity appears directly in the mirror force on a charged particle and is needed for bounce motion calculations. The gradient is given by: ∂B∂s=3BLRE⋅sin⁡λ1+3sin⁡2λ(11+3sin⁡2λ+2cos⁡2λ)\frac{\partial B}{\partial s} = \frac{3B}{L R_E} \cdot \frac{\sin\lambda}{\sqrt{1+3\sin^2\lambda}} \left(\frac{1}{1+3\sin^2\lambda} + \frac{2}{\cos^2\lambda}\right) where RER_E is Earth’s mean radius.

​
Parameters

​
B_arg
float
required
Dipole magnetic field strength at the point of interest, in Tesla (T). Typically obtained from Bmag_dipole(L_arg, lamda_arg).
​
lamda_arg
float
required
Magnetic latitude in radians. Must match the latitude at which B_arg was evaluated.
​
L_arg
float
required
L-shell value (dimensionless).

​
Returns

​
dB_ds_arg
float
Gradient of the geomagnetic field along the field line in T/m (Tesla per metre). The sign is positive for increasing B (towards the mirror points) and zero at the equator where λ=0\lambda = 0.

​
Example

import numpy as np
import WPIT.Environment_mod as env

L = 4.0
lamda = np.radians(20.0)   # 20° magnetic latitude

# First compute the field magnitude
B = env.Bmag_dipole(L, lamda)

# Then compute the gradient
dBds = env.dB_ds(B, lamda, L)
print(f"dB/ds = {dBds:.4e} T/m")

# Gradient profile along the field line (equator to 50°)
latitudes = np.linspace(0, np.radians(50), 200)
B_vals = env.Bmag_dipole(L, latitudes)
dBds_vals = env.dB_ds(B_vals, latitudes, L)
At the magnetic equator (lamda_arg = 0) the gradient is exactly zero by symmetry — the equator is the field minimum and the particle bounce point occurs away from the equator for non-zero pitch angles. B_arg and lamda_arg must refer to the same point on the field line.

​
Lshell

Computes the L-shell (McIlwain L parameter) of a point given its geocentric distance and magnetic latitude. The L-shell is defined as the equatorial crossing distance of the dipole field line passing through the point, measured in units of Earth radii. The relation is: L=rREcos⁡2λL = \frac{r}{R_E \cos^2\lambda} where rr is the geocentric distance in metres and RER_E is Earth’s mean radius. Reference: Tao, X., et al. (2012). “Effects of amplitude modulation on nonlinear interactions between electrons and chorus waves.” Geophysical Research Letters, 39(6).

​
Parameters

​
r_arg
float
required
Geocentric distance in metres (m). This is the distance from Earth’s centre to the point of interest. For reference, Earth’s surface corresponds to r ≈ 6.378 × 10⁶ m (i.e., env.const.Re). The function divides by const.Re internally so the input must be in metres.
​
lat_arg
float
required
Magnetic latitude in radians. The parameter is named lat_arg internally (the docstring labels it lamda_arg).

​
Returns

​
L_tmp
float
L-shell value (dimensionless). Equal to the equatorial crossing distance of the field line in units of Earth radii.

​
Example

import numpy as np
import WPIT.Environment_mod as env

Re = env.const.Re   # 6378137 m

# L-shell at 3 Earth radii geocentric distance, equator
r = 3.0 * Re
L = env.Lshell(r, 0.0)
print(f"L = {L:.2f}")   # L = 3.00

# L-shell at 4 Re geocentric distance, latitude = 20°
r2 = 4.0 * Re
lat = np.radians(20.0)
L2 = env.Lshell(r2, lat)
print(f"L = {L2:.3f}")  # L ≈ 4.530

# Convert a field-line coordinate (r, λ) to L-shell
r_km = 25000e3           # 25,000 km geocentric distance
lat_rad = np.radians(15.0)
L_val = env.Lshell(r_km, lat_rad)
r_arg is in metres, not kilometres. Multiply kilometre values by 1000 before passing to this function. The result is the standard dipole McIlwain L parameter, valid only under the magnetic dipole approximation.

Build docs developers (and LLMs) love

Get started for freeTalk to us