Reading changes: Use snapshot attribute

This means that the snapshot attribute, if present, is used for
accessing iterations inside `series.readIterations()`. Fallback to the
old behavior (linear progression through iterations) if the attribute is
not found.

Author: franzpoeschel

include/openPMD/Iteration.hpp

@@ -29,6 +29,8 @@
 #include "openPMD/ParticleSpecies.hpp"
 #include "openPMD/Streaming.hpp"
 
+#include <deque>
+#include <tuple>
 
 namespace openPMD
 {
@@ -272,15 +274,38 @@ class Iteration : public Attributable
 
 
 
+    struct BeginStepStatus
+    {
+        using AvailableIterations_t =
+            auxiliary::Option< std::deque< uint64_t > >;
+
+        AdvanceStatus stepStatus{};
+        /*
+         * If the iteration attribute `snapshot` is present, the value of that
+         * attribute. Otherwise empty.
+         */
+        AvailableIterations_t iterationsInOpenedStep;
+
+        inline operator AdvanceStatus() const
+        {
+            return stepStatus;
+        }
+        inline
+        operator std::tuple< AdvanceStatus &, AvailableIterations_t & >()
+        {
+            return std::tuple< AdvanceStatus &, AvailableIterations_t & >{
+                stepStatus, iterationsInOpenedStep };
+        }
+    };
+
     /**
      * @brief Begin an IO step on the IO file (or file-like object)
      *        containing this iteration. In case of group-based iteration
      *        layout, this will be the complete Series.
      *
      * @return AdvanceStatus
      */
-    AdvanceStatus
-    beginStep();
+    BeginStepStatus beginStep();
 
     /**
      * @brief End an IO step on the IO file (or file-like object)

include/openPMD/ReadIterations.hpp

@@ -23,6 +23,9 @@
 #include "openPMD/Iteration.hpp"
 #include "openPMD/Series.hpp"
 
+#include <deque>
+#include <iostream>
+
 namespace openPMD
 {
 /**
@@ -54,7 +57,8 @@ class SeriesIterator
     using maybe_series_t = auxiliary::Option< Series >;
 
     maybe_series_t m_series;
-    iteration_index_t m_currentIteration = 0;
+    std::deque< iteration_index_t > m_iterationsInCurrentStep;
+    uint64_t m_currentIteration{};
 
 public:
     //! construct the end() iterator
@@ -71,6 +75,21 @@ class SeriesIterator
     bool operator!=( SeriesIterator const & other ) const;
 
     static SeriesIterator end();
+
+private:
+    inline bool setCurrentIteration()
+    {
+        if( m_iterationsInCurrentStep.empty() )
+        {
+            std::cerr << "[ReadIterations] Encountered a step without "
+                         "iterations. Closing the Series."
+                      << std::endl;
+            *this = end();
+            return false;
+        }
+        m_currentIteration = *m_iterationsInCurrentStep.begin();
+        return true;
+    }
 };
 
 /**

include/openPMD/Series.hpp

@@ -41,6 +41,7 @@
 #   include <mpi.h>
 #endif
 
+#include <deque>
 #include <map>
 #include <set>
 #include <string>
@@ -510,8 +511,11 @@ class Series : public Attributable
      * Note on re-parsing of a Series:
      * If init == false, the parsing process will seek for new
      * Iterations/Records/Record Components etc.
+     * If series.iterations contains the attribute `snapshot`, returns its
+     * value (will only be true in variable-based iteration encoding).
      */
-    void readGorVBased( bool init = true );
+    auxiliary::Option< std::deque< uint64_t > >
+    readGorVBased( bool init = true );
     void readBase();
     std::string iterationFilename( uint64_t i );
 

src/Iteration.cpp

@@ -538,9 +538,9 @@ void Iteration::read_impl( std::string const & groupPath )
     readAttributes( ReadMode::FullyReread );
 }
 
-AdvanceStatus
-Iteration::beginStep()
+auto Iteration::beginStep() -> BeginStepStatus
 {
+    BeginStepStatus res;
     using IE = IterationEncoding;
     auto series = retrieveSeries();
     // Initialize file with this to quiet warnings
@@ -556,11 +556,17 @@ Iteration::beginStep()
             file = &series.get();
             break;
     }
+
     AdvanceStatus status = series.advance(
         AdvanceMode::BEGINSTEP, *file, series.indexOf( *this ), *this );
-    if( status != AdvanceStatus::OK )
+    switch( status )
     {
-        return status;
+    case AdvanceStatus::OVER:
+        res.stepStatus = status;
+        return res;
+    case AdvanceStatus::OK:
+    case AdvanceStatus::RANDOMACCESS:
+        break;
     }
 
     // re-read -> new datasets might be available
@@ -575,12 +581,13 @@ Iteration::beginStep()
         auto newType =
             const_cast< Access * >( &this->IOHandler()->m_frontendAccess );
         *newType = Access::READ_WRITE;
-        series.readGorVBased( false );
+        res.iterationsInOpenedStep = series.readGorVBased( false );
         *newType = oldType;
         series.iterations.written() = previous;
     }
 
-    return status;
+    res.stepStatus = status;
+    return res;
 }
 
 void
@@ -604,6 +611,7 @@ Iteration::endStep()
     // @todo filebased check
     series.advance(
         AdvanceMode::ENDSTEP, *file, series.indexOf( *this ), *this );
+    series.get().m_currentlyActiveIterations.clear();
 }
 
 StepStatus