update the 5min tutorial by pordyna · Pull Request #5715 · ComputationalRadiationPhysics/picongpu

pordyna · 2026-06-19T12:08:32Z

Update the 5min tutorial

Switch from hemera to RoSi
Add some references on how to read openPMD data
Some other minor changes
According to @PrometheusPi the PNG plugin doesn't work with our current setup on RoSi. Since it is a part of the tutorial and the used example one should probably make it work on RoSi. Alternatively remove it from the tutorial and the example. (Not a part of this PR)

@chillenzer, I didn't add any mentions of PICMI since there is no coherent documentation on how to use the newest workflows so far. We need to remember to update this file again when we have PICMI docs ready.

@franzpoeschel if you got some time, could you look over the openPMD part?
@phyprashant since you, you were one of the last people that followed the old tutorial on RoSi, could you have a look if we maybe forgot to add sth useful? You can access the rendered docs by clicking the docs/readthedocs.org:picongpu link in the CI tests below.

* Switch to RoSi * Add info on using openPMD ci: no-compile

finnolec

I added a suggestion to make parallel compiling the standard workflow. Additionally, I think it would be great, if there were minimal code snippet examples with ~5 lines of code on how to use the different openPMD tools to get data from openPMD files with standard PIConGPU name formatting. These could also be linked in the openPMD plugin documentation. In my opinion, these snippets wouldn't need to be explained at all, for this I would forward to the documentation of the different tools.

Co-authored-by: Finn-Ole Carstens <45068748+finnolec@users.noreply.github.com>

PrometheusPi · 2026-06-22T09:45:17Z


-This guide needs **shell access** (probably via :command:`ssh`) and :command:`git`.
+This guide needs **shell access** (probably via :command:`ssh`) and :command:`git` (preinstalled on most systems including RoSi).
+The RoSi shell can also be used from a browser (currently there is no support for Firefox) at `<https://rosi.hzdr.de/>`_ (accessible from the intranet).


I think I used it via Firefox - what does not work?

the shell does not work, jupyter works

franzpoeschel

Thank you for writing this, @pordyna! I have some small comments. If you want me to, I can prepare a PR.

franzpoeschel · 2026-06-29T14:22:55Z

+^^^^^^^
+
+The PNG output is great for having a quick look at the example results, but it is a rather inefficient way of generating and storing your simulation results.
+In general, we write simulation data into ADIOS2 (``.bp``, ``.bp5``, ``.bp4`` extensions) or HDF5 (``.h5``) files with parallel I/O that follow the structure defined by the community openPMD standard.


I would like to either remove .bp or make it more obvious that it is deprecated in favor of the explicit extensions. Makes it far easier to respond to bug reports when I don't always have to make people figure out which BP version they are using.

Also, should we mention that this is an optional dependency? Users might get confused why this is not available in their installation.

both sounds reasonable

franzpoeschel · 2026-06-29T14:25:31Z

+- `openPMD API docs <https://openpmd-api.readthedocs.io/en/latest/>`_ API for reading and writing openPMD output.
+  Powerful tool, its proper use requires some familiarity with the standard itself.
+- `openPMD-viewer <https://github.com/openPMD/openPMD-viewer>`_ Data visualization Python library built on top of the API.
+- `openPMD-scipp <https://github.com/pordyna/openpmd_scipp>`_ Easy visualization of mesh data (fields) using the `plopp <https://scipp.github.io/plopp/>`_ and `scipp <https://github.com/scipp>`_ Python libraries.


Btw, has there been any update on this? This is still open: openPMD/openPMD-api#1716

The codebase diverged slightly again. I will have to just finally spend a day on this and finish it up. Shouldn't be that much work.

franzpoeschel · 2026-06-29T14:27:58Z

+- `openPMD-scipp <https://github.com/pordyna/openpmd_scipp>`_ Easy visualization of mesh data (fields) using the `plopp <https://scipp.github.io/plopp/>`_ and `scipp <https://github.com/scipp>`_ Python libraries.
+- `openPMD pandas support <https://openpmd-api.readthedocs.io/en/latest/analysis/pandas.html>`_ Straightforward solution for working with particle data.
+- `openpmd-ls <https://openpmd-api.readthedocs.io/en/latest/utilities/cli.html#openpmd-ls>`_ Command for getting an overview over the content of an openPMD output via command line.
+- `bpls <https://adios2.readthedocs.io/en/latest/ecosystem/utilities.html#bpls-inspecting-data>`_ Powerful tool for inspecting individual ADIOS2 files via command line.


Do we also need some mention of HDF5 tooling? If yes, I would suggest h5ls, h5dump for cmd line, and https://myhdf5.hdfgroup.org/ (also available as a VS Code plugin) for ease of use.

I don't know if we need to. On some systems hdf5 with openpmd-api can get really slow, like on perlmutter ( in that particular case I think mostly due to noncollective storechunk?) . So hd5 would be probably mostly for people who are already very used to it and this ecosystem anyway. But feel free to add some.

franzpoeschel · 2026-06-29T14:29:30Z

+
+When directly using the openPMD API make sure you make yourself familiar with when you need to call ``series.flush()``.
+See `Flush Chunk <https://openpmd-api.readthedocs.io/en/latest/usage/firstread.html#flush-chunk>`_ and `Deferred Data API Contract <https://openpmd-api.readthedocs.io/en/latest/usage/workflow.html#deferred-data-api-contract>`_ for more details.
+Forgetting it or modifying the data before flush was performed is a common user mistake that can lead to very confusing results.


Btw, WIP for a "give me data immediately" mode
openPMD/openPMD-api#1846

pordyna · 2026-06-30T09:01:20Z

Thank you for writing this, @pordyna! I have some small comments. If you want me to, I can prepare a PR.

Go for it @franzpoeschel ! Maybe once you are at it, can you also link to it on the openPMD plugin page?

franzpoeschel · 2026-07-10T14:58:19Z

Go for it @franzpoeschel ! Maybe once you are at it, can you also link to it on the openPMD plugin page?

Now on #5733
will still add the link

update the 5min tutorial:

2d9e21f

* Switch to RoSi * Add info on using openPMD ci: no-compile

pordyna requested review from PrometheusPi and franzpoeschel June 19, 2026 12:08

pordyna added documentation regarding documentation or wiki discussions CI:no-compile CI is skipping compile/runtime tests but runs PICMI tests labels Jun 19, 2026

finnolec reviewed Jun 19, 2026

View reviewed changes

Comment thread docs/source/tutorials/hemeraIn5min.rst Outdated

Update docs/source/tutorials/hemeraIn5min.rst

4737209

Co-authored-by: Finn-Ole Carstens <45068748+finnolec@users.noreply.github.com>

PrometheusPi approved these changes Jun 22, 2026

View reviewed changes

PrometheusPi merged commit 21ce26e into ComputationalRadiationPhysics:dev Jun 22, 2026
10 checks passed

franzpoeschel reviewed Jun 29, 2026

View reviewed changes

Uh oh!

Conversation

pordyna commented Jun 19, 2026

Update the 5min tutorial

Uh oh!

finnolec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

franzpoeschel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pordyna commented Jun 30, 2026

Uh oh!

franzpoeschel commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants