Add documentation

docs/source/details/mpi.rst

@@ -47,6 +47,12 @@ Functionality                Behavior           Description
 .. [4] We usually open iterations delayed on first access. This first access is usually the ``flush()`` call after a ``storeChunk``/``loadChunk`` operation. If the first access is non-collective, an explicit, collective ``Iteration::open()`` can be used to have the files already open.
        Alternatively, iterations might be accessed for the first time by immediate operations such as ``::availableChunks()``.
 
+.. warning::
+
+  The openPMD-api will by default flush only those Iterations which are dirty, i.e. have been written to.
+  This is somewhat unfortunate in parallel setups since only the dirty status of the current MPI rank can be considered.
+  As a workaround, use ``Attributable::seriesFlush()`` on an Iteration (or an object contained within an Iteration) to force flush that Iteration regardless of its dirty status.
+
 .. tip::
 
    Just because an operation is independent does not mean it is allowed to be inconsistent.

include/openPMD/backend/Attributable.hpp

@@ -246,6 +246,8 @@ class Attributable
      * of parents. This method will walk up the parent list until it reaches
      * an object that has no parent, which is the Series object, and flush()-es
      * it.
+     * If the Attributable is an Iteration or any object contained in an
+     * Iteration, that Iteration will be flushed regardless of its dirty status.
      *
      * @param backendConfig Further backend-specific instructions on how to
      *                      implement this flush call.