openPMD: no BP5 Group Based (#5735)

Disallow BP5 with group based encoding, because it creates files that
cannot be read back efficiently.

What works: BP4 f, BP4 g, BP5 f, BP5 v (still experimental, not yet
fully supported in readers), H5 f, H5 g.

References:
- BLAST-ImpactX/impactx#870
- openPMD/openPMD-api#1724
-
openPMD/openPMD-api#1457 (comment)

cc @franzpoeschel

Docs/source/usage/parameters.rst

@@ -2813,14 +2813,14 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a
 
 * ``<diag_name>.openpmd_backend`` (``bp5``, ``bp4``, ``h5`` or ``json``) optional, only used if ``<diag_name>.format = openpmd``
     `I/O backend <https://openpmd-api.readthedocs.io/en/latest/backends/overview.html>`_ for `openPMD <https://www.openPMD.org>`_ data dumps.
-    ``bp`` is the `ADIOS I/O library <https://csmd.ornl.gov/adios>`_, ``h5`` is the `HDF5 format <https://www.hdfgroup.org/solutions/hdf5/>`_, and ``json`` is a `simple text format <https://en.wikipedia.org/wiki/JSON>`_.
-    ``json`` only works with serial/single-rank jobs.
+    ``bp5``/``bp4`` is the `ADIOS I/O library <https://csmd.ornl.gov/adios>`_, ``h5`` is the `HDF5 format <https://www.hdfgroup.org/solutions/hdf5/>`_, and ``json`` is a `simple text format <https://en.wikipedia.org/wiki/JSON>`_.
+    ``json`` is for debugging and only works with serial/single-rank jobs.
     When WarpX is compiled with openPMD support, the first available backend in the order given above is taken.
 
 * ``<diag_name>.openpmd_encoding`` (optional, ``v`` (variable based), ``f`` (file based) or ``g`` (group based) ) only read if ``<diag_name>.format = openpmd``.
      openPMD `file output encoding <https://openpmd-api.readthedocs.io/en/0.16.1/usage/concepts.html#iteration-and-series>`__.
      File based: one file per timestep (slower), group/variable based: one file for all steps (faster)).
-     ``variable based`` is an `experimental feature with ADIOS2 <https://openpmd-api.readthedocs.io/en/0.16.1/backends/adios2.html#experimental-new-adios2-schema>`__ and not supported for back-transformed diagnostics.
+     ``variable based`` is an `experimental feature with ADIOS2 BP5 <https://openpmd-api.readthedocs.io/en/0.16.1/backends/adios2.html#experimental-new-adios2-schema>`__ that will replace ``g``.
      Default: ``f`` (full diagnostics)
 
 * ``<diag_name>.adios2_operator.type`` (``zfp``, ``blosc``) optional,
@@ -2854,7 +2854,7 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a
        <diag_name>.openpmd_backend = bp5
        <diag_name>.adios2_engine.parameters.FlattenSteps = on
 
-* ``<diag_name>.adios2_engine.type`` (``bp4``, ``sst``, ``ssc``, ``dataman``) optional,
+* ``<diag_name>.adios2_engine.type`` (``bp5``, ``bp4``, ``sst``, ``ssc``, ``dataman``) optional,
     `ADIOS2 Engine type <https://openpmd-api.readthedocs.io/en/0.16.1/details/backendconfig.html#adios2>`__ for `openPMD <https://www.openPMD.org>`_ data dumps.
     See full list of engines at `ADIOS2 readthedocs <https://adios2.readthedocs.io/en/latest/engines/engines.html>`__
 

Docs/source/usage/workflows/ml_materials/run_warpx_training.py

@@ -274,7 +274,7 @@ def get_laser(antenna_z, profile_t_peak, fill_in=True):
     data_list=diag_particle_list,
     write_dir="lab_particle_diags",
     warpx_format="openpmd",
-    warpx_openpmd_backend="bp",
+    warpx_openpmd_backend="bp5",
 )
 
 btd_field_diag = picmi.LabFrameFieldDiagnostic(
@@ -287,7 +287,7 @@ def get_laser(antenna_z, profile_t_peak, fill_in=True):
     warpx_upper_bound=[128.0e-6, 0.0e-6, 0.0],
     write_dir="lab_field_diags",
     warpx_format="openpmd",
-    warpx_openpmd_backend="bp",
+    warpx_openpmd_backend="bp5",
 )
 
 field_diag = picmi.FieldDiagnostic(

Source/Diagnostics/FlushFormats/FlushFormatOpenPMD.cpp

@@ -46,6 +46,13 @@ FlushFormatOpenPMD::FlushFormatOpenPMD (const std::string& diag_name)
         encoding = openPMD::IterationEncoding::fileBased;
     }
 
+    // BP5 does not support groupBased (metadata explosion)
+    if ((openpmd_backend == "bp5" || openpmd_backend == "bp") &&
+        (encoding == openPMD::IterationEncoding::groupBased))
+    {
+        throw std::runtime_error("BeamMonitor: groupBased encoding not supported for BP5.");
+    }
+
     std::string diag_type_str;
     pp_diag_name.get("diag_type", diag_type_str);
     if (diag_type_str == "BackTransformed")

Source/Diagnostics/OpenPMDHelpFunction.cpp

@@ -17,9 +17,9 @@ WarpXOpenPMDFileType ()
     std::string openPMDFileType;
 #ifdef WARPX_USE_OPENPMD
 #if openPMD_HAVE_ADIOS2==1
-    openPMDFileType = "bp";
+    openPMDFileType = "bp5";
 #elif openPMD_HAVE_ADIOS1==1
-    openPMDFileType = "bp";
+    openPMDFileType = "bp";  // bp3
 #elif openPMD_HAVE_HDF5==1
     openPMDFileType = "h5";
 #else

Source/Diagnostics/WarpXOpenPMD.H

@@ -82,7 +82,7 @@ public:
   /** Initialize openPMD I/O routines
    *
    * @param ie  iteration encoding from openPMD: "group, file, variable"
-   * @param filetype file backend, e.g. "bp" or "h5"
+   * @param filetype file backend, e.g. "bp5", "bp4", or "h5"
    * @param operator_type openPMD-api backend operator (compressor) for ADIOS2
    * @param operator_parameters openPMD-api backend operator parameters for ADIOS2
    * @param engine_type ADIOS engine for output
@@ -149,7 +149,7 @@ public:
               bool isBTD = false,
               const amrex::Geometry& full_BTD_snapshot=amrex::Geometry() ) const;
 
-  /** Return OpenPMD File type ("bp" or "h5" or "json")*/
+  /** Return OpenPMD File type ("bp5", "bp4", "h5" or "json")*/
   std::string OpenPMDFileType () { return m_OpenPMDFileType; }
 
 private:
@@ -350,7 +350,7 @@ private:
   int m_MPISize = 1;
 
   openPMD::IterationEncoding m_Encoding = openPMD::IterationEncoding::fileBased;
-  std::string m_OpenPMDFileType = "bp"; //! MPI-parallel openPMD backend: bp or h5
+  std::string m_OpenPMDFileType = "bp5"; //! MPI-parallel openPMD backend: bp5, bp4 or h5
   std::string m_OpenPMDoptions = "{}"; //! JSON option string for openPMD::Series constructor
   int m_CurrentStep  = -1;