Cleanup and documentation

docs/source/details/backendconfig.rst

@@ -129,10 +129,11 @@ Explanation of the single keys:
 
   * If ``"disk"``, data will be moved to disk on every flush.
   * If ``"buffer"``, then only upon ending an IO step or closing an engine.
+  * If ``new_step``, then a new step will be created. This should be used in combination with the ADIOS2 option ``adios2.engine.parameters.FlattenSteps = "on"``.
 
   This behavior can be overridden on a per-flush basis by specifying this JSON/TOML key as an optional parameter to the ``Series::flush()`` or ``Attributable::seriesFlush()`` methods.
 
-  Additionally, specifying ``"disk_override"`` or ``"buffer_override"`` will take precedence over options specified without the ``_override`` suffix, allowing to invert the normal precedence order.
+  Additionally, specifying ``"disk_override"``, ``"buffer_override"`` or ``"new_step_override"`` will take precedence over options specified without the ``_override`` suffix, allowing to invert the normal precedence order.
   This way, a data producing code can hardcode the preferred flush target per ``flush()`` call, but users can e.g. still entirely deactivate flushing to disk in the ``Series`` constructor by specifying ``preferred_flush_target = buffer_override``.
   This is useful when applying the asynchronous IO capabilities of the BP5 engine.
 * ``adios2.dataset.operators``: This key contains a list of ADIOS2 `operators <https://adios2.readthedocs.io/en/latest/components/components.html#operator>`_, used to enable compression or dataset transformations.

include/openPMD/IO/ADIOS/ADIOS2Auxiliary.hpp

@@ -54,7 +54,8 @@ namespace adios_defs
         Buffer_Override,
         Disk,
         Disk_Override,
-        NewStep
+        NewStep,
+        NewStep_Override
     };
 
     using FlushTarget = adios_defs::FlushTarget;

src/IO/ADIOS/ADIOS2Auxiliary.cpp

@@ -52,11 +52,15 @@ FlushTarget flushTargetFromString(std::string const &str)
     {
         return FlushTarget::NewStep;
     }
+    else if (str == "new_step_override")
+    {
+        return FlushTarget::NewStep_Override;
+    }
     else
     {
         throw error::BackendConfigSchema(
             {"adios2", "engine", adios_defaults::str_flushtarget},
-            "Flush target must be either 'disk' or 'buffer', but "
+            "Flush target must be either 'disk', 'buffer' or 'new_step', but "
             "was " +
                 str + ".");
     }

src/IO/ADIOS/ADIOS2File.cpp

@@ -22,6 +22,7 @@
 #include "openPMD/IO/ADIOS/ADIOS2File.hpp"
 #include "openPMD/Error.hpp"
 #include "openPMD/IO/ADIOS/ADIOS2IOHandler.hpp"
+#include "openPMD/IO/AbstractIOHandler.hpp"
 #include "openPMD/auxiliary/Environment.hpp"
 #include "openPMD/auxiliary/StringManip.hpp"
 
@@ -1067,6 +1068,7 @@ void ADIOS2File::flush_impl(ADIOS2FlushParams flushParams, bool writeLatePuts)
             target = CleanedFlushTarget::Buffer;
             break;
         case FlushTarget::NewStep:
+        case FlushTarget::NewStep_Override:
             target = CleanedFlushTarget::Step;
             break;
         }

src/IO/ADIOS/ADIOS2IOHandler.cpp

@@ -463,6 +463,7 @@ overrideFlushTarget(FlushTarget &inplace, FlushTarget new_val)
             return true;
         case FlushTarget::Buffer_Override:
         case FlushTarget::Disk_Override:
+        case FlushTarget::NewStep_Override:
             return false;
         }
         return true;