Documentation clarity re: "momentum" about warpx HOT 7 CLOSED

@jwestern thanks for bringing this up!

To clarify, the particle diagnostic outputs $\gamma\beta$ where $\beta=v/c$ and $\gamma$ is the usual relativistic factor (so in non-relativistic cases I just multiply the particle diagnostic output by $c$ to get velocities in m/s). The ParticleContainerWrapper actually takes (or gives) $u=\gamma v$ where $v$ is the speed in m/s. And actually WarpX always uses $u=\gamma v$ for particle velocity components, so whenever you see a u in the code it is really $\gamma v$.

Do you have a suggestion for specific documentation sections that could be improved to prevent a future user from having the same difficulty? Would you be willing to open a PR to improve the documentation in this regard?

from warpx.

@roelof-groenewald thanks for the quick reply. Once I'm convinced of what's correct, I can open a PR.

Are you sure about the particle diagnostic output? When I read particle diagnostic data into Python to inspect its values (particles which were created using ParticleContainerWrapper and feeding it $u = \gamma v$), the momentum entries are almost exactly equal to $m \gamma v$. If I instead multiply the particle diagnostic momentum entries by $c$ in m/s as you suggest, the result is off from my expectation by about 18 orders of magnitude.

from warpx.

I should've clarified - are you using plotfile output or openpmd as the output format? The comment I made applies to openpmd output. I'm not sure about the output for plotfile.

Using openpmd output I generally do the following:

from openpmd_viewer import OpenPMDTimeSeries
from scipy import constants

ts_parts = OpenPMDTimeSeries('diags/particles')

ux, uy, uz = ts_parts.get_particle(
    var_list=['ux', 'uy', 'uz'],
    species=<species>, iteration=<it>
)
vx = ux*constants.c
vy = uy*constants.c
vz = uz*constants.c

which gives me expected velocity values in m/s.

from warpx.

I'm using openPMD h5 files, such as openpmd_001000.h5 for example. They are created using

picmi.ParticleDiagnostic(write_dir = f'./diags/test_run',
                                         warpx_file_prefix = 'particle',
                                         period=25,
                                         species=<species_list>,
                                         warpx_openpmd_backend='h5',
                                         warpx_format='openpmd',
                                         data_list=['x', 'y', 'z', 'ux', 'uy', 'uz', 'weighting'])

and then I read it in using h5py like so:

import h5py as h5
from scipy import constants

file = h5.File('openpmd_001000.h5','r')

ux = file['data/1000/particles/electrons/momentum/x'][:]
uy = file['data/1000/particles/electrons/momentum/y'][:]
uz = file['data/1000/particles/electrons/momentum/z'][:]

v = <v> # my expected velocity in m/s
gam = 1./np.sqrt(1-(v/constants.c)**2)

print(ux / constants.m_e / v / gam)

and the result is exactly 1.

from warpx.

Oh, okay I see what is happening. The momentum key in the hdf5 output does store momentum, as you have found. If instead you use the openpmd_viewer API to query u{x/y/z} it will internally convert the momentum to $\gamma \beta$.
Now I also learned something new. Thanks!
So does that clear up your questions as well?

from warpx.

Yes, thanks. I guess it's hard to warn people about the particle diagnostic data when different tools give different results. But one could reasonably expect a user to check the values of what they're reading in.

On the other hand, in my view the documentation for the add_particles method of ParticleContainerWrapper ought not to simply say "momenta," but rather "momenta per unit mass" or "specific momenta" or give the formula $\gamma v$. Should I make a PR for this or is it too trivial?

from warpx.

No, such a change would not be too trivial for a PR since it can definitely help clarify things for other users. I think it would be best to modify the documentation to say the function takes in the "proper velocity".
Thanks for be willing to improve the documentation!

from warpx.