Phase Space¶
This plugin creates a 2D phase space image for a user-given spatial and momentum coordinate.
External Dependencies¶
The plugin is available as soon as the libSplash and HDF5 libraries are compiled in.
.cfg file¶
Example for y-pz phase space for the electron species (.cfg
file macro):
# Calculate a 2D phase space
# - momentum range in m_e c
TGB_ePSypz="--e_phaseSpace.period 10 --e_phaseSpace.filter all --e_phaseSpace.space y --e_phaseSpace.momentum pz --e_phaseSpace.min -1.0 --e_phaseSpace.max 1.0"
The distinct options are (assuming a species e
for electrons):
Option | Usage Unit | |
---|---|---|
--e_phaseSpace.period <N> |
calculate each N steps | none |
--e_phaseSpace.filter |
Use filtered particles. Available filters are set up in particleFilters.param. | none |
--e_phaseSpace.space <x/y/z> |
spatial coordinate of the 2D phase space | none |
--e_phaseSpace.momentum <px/py/pz> |
momentum coordinate of the 2D phase space | none |
--e_phaseSpace.min <ValL> |
minimum of the momentum range | \(m_\mathrm{species} c\) |
--e_phaseSpace.max <ValR> |
maximum of the momentum range | \(m_\mathrm{species} c\) |
Memory Complexity¶
Accelerator¶
locally, a counter matrix of the size local-cells of space
direction times 1024
(for momentum bins) is permanently allocated.
Host¶
negligible.
Output¶
The 2D histograms are stored in .hdf5
files in the simOutput/phaseSpace/
directory.
A file is created per species, phasespace selection and time step.
Values are given as charge density per phase space bin.
In order to scale to a simpler charge of particles per \(\mathrm{d}r_i\) and \(\mathrm{d}p_i\) -bin multiply by the cell volume dV
.
Analysis Tools¶
Data Reader¶
You can quickly load and interact with the data in Python with:
from picongpu.plugins.data import PhaseSpaceData
import numpy as np
# load data
ps_data = PhaseSpaceData('/home/axel/runs/lwfa_001')
ps, meta = ps_data.get(species='e', species_filter='all', ps='ypy', iteration=2000)
# unit conversion from SI
mu = 1.e6 # meters to microns
e_mc_r = 1. / (9.109e-31 * 2.9979e8) # electrons: kg * m / s to beta * gamma
Q_dr_dp = np.abs(e_ps) * e_ps_meta.dV # C s kg^-1 m^-2
extent = e_ps_meta.extent * [mu, mu, e_mc_r, e_mc_r] # spatial: microns, momentum: beta*gamma
Note that the spatial extent of the output over time might change when running a moving window simulation.
Matplotlib Visualizer¶
You can quickly plot the data in Python with:
from picongpu.plugins.plot_mpl import PhaseSpaceMPL
import matplotlib.pyplot as plt
# create a figure and axes
fig, ax = plt.subplots(1, 1)
# create the visualizer
ps_vis = PhaseSpaceMPL('path/to/run_dir', ax)
# plot
ps_vis.visualize(iteration=200, species='e')
plt.show()
The visualizer can also be used from the command line by writing
python phase_space_visualizer.py
with the following command line options
Options | Value |
---|---|
-p | Path and filename to the run directory of a simulation. |
-i | An iteration number |
-s (optional, defaults to ‘e’) | Particle species abbreviation (e.g. ‘e’ for electrons) |
-f (optional, defaults to ‘all’) | Species filter string |
-m (optional, defaults to ‘ypy’) | Momentum string to specify the phase space |
Out-of-Range Behavior¶
Particles that are not in the range of <ValL>
/<ValR>
get automatically mapped to the lowest/highest bin respectively.
Take care about that when setting your range and during analysis of the results.
Known Limitations¶
- only one range per selected space-momentum-pair possible right now (naming collisions)
- charge deposition uses the counter shape for now (would need one more write to neighbours to get it correct to the shape)
- the user has to define the momentum range in advance
- the resolution is fixed to
1024 bins
in momentum and the number of cells in the selected spatial dimension - this plugin does not yet use openPMD markup.
References¶
The internal algorithm is explained in pull request #347 and in [Huebl2014].
[Huebl2014] | A. Huebl. Injection Control for Electrons in Laser-Driven Plasma Wakes on the Femtosecond Time Scale, chapter 3.2, Diploma Thesis at TU Dresden & Helmholtz-Zentrum Dresden - Rossendorf for the German Degree “Diplom-Physiker” (2014), https://doi.org/10.5281/zenodo.15924 |