Improve Documentation for Laser-Ion Acceleration from Planar Target

[n01r]

• add PICMI example
• add analysis script
  • slightly updated the one introduced in Histogram 2D #3883 (this one has the prefix analysis but could later be counted as a visualization script and renamed to plot_...)
• add visualization script
• add documentation text
• provide regression test
• update checksum

Phase space for electrons

Phase space for ions

Particle densities

Electromagnetic fields

• TODO replace with higher resolution visualization, once the Perlmutter job has run

[n01r]

Hi @eebasso, I heard from @RTSandberg that you worked some magic to make the labels work for RST's numref.
I don't quite get why I'm still getting WARNING: undefined label: during the compile process.

Could you tell me what in particular you fixed to make this work? 🙂

[eebasso]

@n01r I'm looking at that now. I'll let you know if I figure it out.

[n01r]

Thank you, @eebasso! 🙏

[eebasso]

The :alt: parameter does not specify the caption text, and only appears if the image doesn't load. https://sublime-and-sphinx-guide.readthedocs.io/en/latest/images.html#alt-text

Therefore, you need to repeat the text without the :alt: parameter in order to actually have a caption. Furthermore, make sure that there is an empty new line above the caption text. In this case, it should look like

.. figure:: https://user-images.githubusercontent.com/5416860/295003882-c755fd47-4bb3-4439-9319-c48214cbaafd.png
   :alt: Longitudinal phase space of forward-flying electrons in a 2 degree opening angle.
   :width: 100%

   Longitudinal phase space of forward-flying electrons in a 2 degree opening angle.

.. _fig-tnsa-ps-protons-pinhole:

I don't know why the empty line above the caption text is needed, but that's what I found via testing. As a bonus, this also seemed to fix the "undefined label" error coming from :numref:.

[n01r]

Hi @eebasso, thanks for testing this!

Initially, I did not intend for there to be a caption since the text around is also short and holds all information. 🙂
However, I added it now.

Unfortunately, that does not fix the "undefined label" warnings for me when I build the docs locally (despite the empty line above).

[n01r]

Oh wait! But the CI-built docs now have :numref: working! 🎉

Thanks, @eebasso!

(Now I only need to figure out why locally that does not fix it 🤔)

[ax3l]

Hi @n01r, the CI test seems to fail.

Can you run ./run_tests.sh LaserIonAcc2d Python_LaserIonAcc2d locally and check why?

[n01r]

Hi @ax3l, should be fixed now :)

[n01r]

Hmm, at least locally it passes. But online it does not seem to pass. How do I view Azure pipeline backtraces?

[ax3l]

PICMI issue: position data seems zero in CI

New file for LaserIonAcc2d:
{
  "lev=0": {
    "Bx": 0.0,
    "By": 11411047.898351604,
    "Bz": 0.0,
    "Ex": 2031641076084948.8,
    "Ey": 0.0,
    "Ez": 334777106874158.75,
    "jx": 1.660205025572598e+19,
    "jy": 0.0,
    "jz": 9.545451466990307e+18,
    "rho": 67237998613.860535,
    "rho_electrons": 17449705826002.387,
    "rho_hydrogen": 17441792654743.145
  },
  "electrons": {
    "particle_position_x": 0.0,
    "particle_position_y": 0.0,
    "particle_position_z": 0.0,
    "particle_momentum_x": 3.8463518636930147e-19,
    "particle_momentum_y": 0.0,
    "particle_momentum_z": 1.6287398567676136e-18,
    "particle_weight": 2.647983436428149e+17
  },
  "hydrogen": {
    "particle_origX": 0.007763427734375002,
    "particle_origZ": 0.0351975439453125,
    "particle_position_x": 0.0,
    "particle_position_y": 0.0,
    "particle_position_z": 0.0,
    "particle_momentum_x": 2.2575255298569516e-18,
    "particle_momentum_y": 0.0,
    "particle_momentum_z": 1.0773391029868316e-18,
    "particle_weight": 2.6792730619156992e+17
  }
}

Locally, the data is written in positions:

$ h5ls -r diags/Python_LaserIonAcc2d_plt/openpmd_000100.h5 
/                        Group
/data                    Group
/data/100                Group
/data/100/fields         Group
/data/100/fields/B       Group
/data/100/fields/B/x     Dataset {128, 96}
/data/100/fields/B/y     Dataset {128, 96}
/data/100/fields/B/z     Dataset {128, 96}
/data/100/fields/E       Group
/data/100/fields/E/x     Dataset {128, 96}
/data/100/fields/E/y     Dataset {128, 96}
/data/100/fields/E/z     Dataset {128, 96}
/data/100/fields/j       Group
/data/100/fields/j/x     Dataset {128, 96}
/data/100/fields/j/y     Dataset {128, 96}
/data/100/fields/j/z     Dataset {128, 96}
/data/100/fields/rho     Dataset {128, 96}
/data/100/fields/rho_electrons Dataset {128, 96}
/data/100/fields/rho_hydrogen Dataset {128, 96}
/data/100/particles      Group
/data/100/particles/electrons Group
/data/100/particles/electrons/charge Group
/data/100/particles/electrons/id Dataset {29302}
/data/100/particles/electrons/mass Group
/data/100/particles/electrons/momentum Group
/data/100/particles/electrons/momentum/x Dataset {29302}
/data/100/particles/electrons/momentum/y Dataset {29302}
/data/100/particles/electrons/momentum/z Dataset {29302}
/data/100/particles/electrons/position Group
/data/100/particles/electrons/position/x Dataset {29302}
/data/100/particles/electrons/position/y Group
/data/100/particles/electrons/position/z Dataset {29302}
/data/100/particles/electrons/positionOffset Group
/data/100/particles/electrons/positionOffset/x Group
/data/100/particles/electrons/positionOffset/y Group
/data/100/particles/electrons/positionOffset/z Group
/data/100/particles/electrons/weighting Dataset {29302}

Looks like with PICMI, likely from the SoA update, the particle positions are written as zero though:

[ax3l]

Same problem with non-PICMI (application/executable/inputs file) run...

[ax3l]

The variables and data_lists exclude x and z. Pushing a fix to input files.

[n01r]

Thanks a lot, @ax3l!

[ax3l]

Great work, thank you so much 🚀 ✨