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.

WPIT (Wave-Particle Interactions Toolset) is a Python-based library and simulation environment for studying how energetic charged particles in the radiation belts interact with plasma waves such as whistler-mode chorus and electromagnetic ion cyclotron (EMIC) waves. It provides four modular components covering magnetospheric environment modelling, cold and warm plasma wave properties, gyro-averaged equations of motion for test-particle simulations, and Landau damping calculations — all usable interactively via Jupyter Notebooks or importable as a Python library.

Quickstart

Run your first wave-particle interaction simulation in minutes

Installation

Set up WPIT and its dependencies

Concepts

Understand the physics and architecture behind WPIT

API Reference

Explore every module, function signature, and parameter

​
What WPIT Does

WPIT provides a unified set of routines that cover the full chain of a wave-particle interaction simulation:

Environment Model

Geomagnetic dipole field, plasma densities, characteristic frequencies, loss cone, and particle orbital parameters

Wave Properties

Refractive index, dispersion relations, Stix parameters, resonance angles, and wave amplitude models

WPI Equations of Motion

Gyro-averaged equations of motion for whistler–electron, EMIC–ion, and parallel EMIC interactions, including nonlinearity metrics

Landau Damping

Spatial damping rate along a ray path for multiple particle distribution functions

​
Getting Started

1

Clone the repository

git clone https://github.com/stourgai/WPIT.git
cd WPIT
2

Install dependencies

pip install -r requirements.txt
3

Import WPIT in Python or Jupyter

import WPIT.Environment_mod as env
import WPIT.WaveProperties_mod as wave
import WPIT.WPI_mod.whistler_electron_mod as wpi
import WPIT.LandauDamp_mod as ld
4

Run your first calculation

import numpy as np
import WPIT.Environment_mod as env

# Dipole field strength at L=5, equator
L = 5.0
lamda = 0.0  # magnetic latitude in radians
B = env.Bmag_dipole(L, lamda)
print(f"B at L={L}, equator: {B:.3e} T")

# Electron cyclotron frequency
wce = env.omega_cyclotron(B, env.const.qe, env.const.me)
print(f"Electron cyclotron frequency: {wce/(2*np.pi):.1f} Hz")

​
Modules at a Glance

ModulePurpose
Environment_modDipole field, densities, frequencies, particle kinematics
WaveProperties_modDispersion, refractive index, wave amplitudes, resonance
WPI_modEquations of motion for whistler, EMIC, and parallel EMIC interactions
LandauDamp_modLandau damping rates, distribution functions, ray path utilities
WPIT is distributed under the Creative Commons Attribution (CC BY) license. When using WPIT in research, please cite: Tourgaidis, S., & Sarris, T. Wave-Particle Interactions Toolset (WPIT): a Python-based toolset to model wave-particle interactions in the magnetosphere. Frontiers in Astronomy and Space Sciences, 295.

Build docs developers (and LLMs) love

Get started for freeTalk to us