add documentation for aborting if adios is used with openpmd and add …

…other BTD input parameters

Docs/source/usage/parameters.rst

@@ -1716,8 +1716,8 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a
     If this is `1`, the last timestep is dumped regardless of ``<diag_name>.period``.
 
 * ``<diag_name>.diag_type`` (`string`)
-    Type of diagnostics. So far, only ``Full`` is supported.
-    example: ``diag1.diag_type = Full``.
+    Type of diagnostics. ``Full`` and ``BackTransformed``
+    example: ``diag1.diag_type = Full`` or ``diag1.diag_type = BackTransformed``
 
 * ``<diag_name>.format`` (`string` optional, default ``plotfile``)
     Flush format. Possible values are:
@@ -1748,6 +1748,7 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a
     ``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.
     When WarpX is compiled with openPMD support, the first available backend in the order given above is taken.
+    Note that when using ``BackTransformed`` diagnostic type, the openpmd format supports only ``h5`` backend for both species and fields, while ``bp`` backend can be used for visualizing fields, but not particles. The code will abort if ``bp`` is selected for particle output.
 
 * ``<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.14.0/usage/concepts.html#iteration-and-series>`__.
@@ -1863,9 +1864,42 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a
     Please see the :ref:`data analysis section <dataanalysis-formats>` for more information.
 
 .. _running-cpp-parameters-diagnostics-btd:
+BackTransformed Diagnostics (with support for Plotfile/OpenPMD output)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``BackTransformed`` diag type are used when running a simulation in a boosted frame, to reconstruct output data to the lab frame. This option can be set using ``<diag_name>.diag_type = BackTransformed``. Additional options for this diagnostic include:
 
-Back-Transformed Diagnostics
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* ``<diag_name>.num_snapshots_lab`` (`integer`)
+    Only used when ``<diag_name>.diag_type`` is ``BackTransformed``.
+    The number of lab-frame snapshots that will be written.
+
+* ``<diag_name>.dt_snapshots_lab`` (`float`, in seconds)
+    Only used when ``<diag_name>.diag_type`` is ``BackTransformed``.
+    The time interval inbetween the lab-frame snapshots (where this
+    time interval is expressed in the laboratory frame).
+
+* ``<diag_name>.dz_snapshots_lab`` (`float`, in meters)
+    Only used when ``<diag_name>.diag_type`` is ``BackTransformed``.
+    Distance between the lab-frame snapshots (expressed in the laboratory
+    frame). ``dt_snapshots_lab`` is then computed by
+    ``dt_snapshots_lab = dz_snapshots_lab/c``. Either `dt_snapshots_lab`
+    or `dz_snapshot_lab` is required.
+
+* ``<diag_name>.buffer_size`` (`integer`)
+    Only used when ``<diag_name>.diag_type`` is ``BackTransformed``.
+    The default size of the back transformed diagnostic buffers used to generate lab-frame
+    data is 256. That is, when the multifab with lab-frame data has 256 z-slices,
+    the data will be flushed out. However, if many lab-frame snapshots are required for
+    diagnostics and visualization, the GPU may run out of memory with many large boxes with
+    a size of 256 in the z-direction. This input parameter can then be used to set a
+    smaller buffer-size, preferably multiples of 8, such that, a large number of
+    lab-frame snapshot data can be generated without running out of gpu memory.
+    The downside to using a small buffer size, is that the I/O time may increase due
+    to frequent flushes of the lab-frame data. The other option is to keep the default
+    value for buffer size and use slices to reduce the memory footprint and maintain
+    optimum I/O performance.
+
+Back-Transformed Diagnostics (customized output)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``BackTransformedDiagnostics`` are used when running a simulation in a boosted frame, to reconstruct output data to the lab frame, and