Instructor Notes
Discussions at OSSFE 2025
Who develops WarpX? A lot of people from all around the world that work in different fields! WarpX is an open-source project that belongs to the High Performance Software Foundation, which itself is part of the nonprofit Linux Foundation.
What is the difference between a Monte Carlo code and a Particle-In-Cell code? Typically in MC the particles are independent one another, while in PIC they interact through the self-consistent field (collective effect). That being said, MC can and are included in the core PIC loop to simulate, e.g., binary collisions, ionzation, nuclear reactions, QED processes.
Why Conda environments over Python environments? Conda is a system package manager, while
pipis a Python package manager. Withcondayou can install much more than just Python libraries.Can WarpX deal with different species? But of course! One can initialize as many species as desired, with user-define mass and charge. Beware that not all the additional physics modules (ionization, QED, …) may work for arbitrary species!
Does WarpX support mixed kinetic and fluid descriptions? Yes, check out the hybrid solver!
Two-stream instability: exploratory vs. recipe approach
The two-stream instability can be taught in two complementary ways:
Recipe approach (the Two-Stream Instability episode): hand students a prepared input file with blanks to fill in. Good for focusing on parameter selection and physics understanding.
Exploratory approach (the Set Up a Simulation from Scratch episode): start from the WarpX uniform plasma example, browse the repo together, modify it live. Good for teaching the workflow of setting up a new simulation.
The exploratory approach was used in a live session at UCB (April 2026). Key observations from that session:
- Students found it very instructive to start from the “wrong” example and iterate. The first run (2D, 10 timesteps, warm beams) shows nothing – and that’s the point.
- The most common stumbling blocks: too few timesteps, thermal velocity washing out the instability, and running in 2D/3D when 1D suffices.
- A good sequence of iterations: (1) increase timesteps, (2) set
temperature to zero (cold beams),
- switch to 1D, (4) increase resolution and particles per cell.
- Making a video of the phase-space evolution at the end is very rewarding and helps students connect the physics to the numerical experiment.
Introduction to WarpX
Install
Set Up a Simulation from Scratch
A Two-stream Instability
Instructor Note
An ideal gas at standard temperature and pressure (\(T = 300\,\mathrm{K}\), \(p = 1\,\mathrm{atm}\)) has a number density \(n = p/(k_B T) \approx 2.5 \times 10^{25}\,\mathrm{m^{-3}}\). Typical plasma densities span many orders of magnitude depending on the degree of ionization and the environment:
| Example | Density \([\mathrm{m^{-3}}]\) |
|---|---|
| Solar wind | \(\sim 10^{6}\)–\(10^{7}\) |
| Fluorescent lamp | \(\sim 10^{17}\)–\(10^{18}\) |
| Tokamak core | \(\sim 10^{19}\)–\(10^{20}\) |
Any value in a sensible range will work for this exercise.