Remove special ReadFlattenSteps Mode, switch to control by writer-sid… (

#4160)

Remove special ReadFlattenSteps Mode, switch to control by writer-side FlattenSteps parameter

bindings/C/adios2/c/adios2_c_engine.cpp

@@ -34,9 +34,6 @@ adios2::Mode adios2_ToMode(const adios2_mode mode, const std::string &hint)
     case adios2_mode_readRandomAccess:
         modeCpp = adios2::Mode::ReadRandomAccess;
         break;
-    case adios2_mode_readFlattenSteps:
-        modeCpp = adios2::Mode::ReadFlattenSteps;
-        break;
     case adios2_mode_deferred:
         modeCpp = adios2::Mode::Deferred;
         break;
@@ -66,9 +63,6 @@ adios2_mode adios2_fromMode(const adios2::Mode mode, const std::string &hint)
     case adios2::Mode::ReadRandomAccess:
         modeC = adios2_mode_readRandomAccess;
         break;
-    case adios2::Mode::ReadFlattenSteps:
-        modeC = adios2_mode_readFlattenSteps;
-        break;
     case adios2::Mode::Deferred:
         modeC = adios2_mode_deferred;
         break;

bindings/C/adios2/c/adios2_c_io.h

@@ -329,8 +329,8 @@ adios2_error adios2_remove_all_attributes(adios2_io *io);
  * MPI Collective function as it calls MPI_Comm_dup
  * @param io engine owner
  * @param name unique engine identifier
- * @param mode adios2_mode_write, adios2_mode_read, adios2_mode_append,
- * adios2_mode_readRandomAccess and adios2_mode_readFlattenSteps
+ * @param mode adios2_mode_write, adios2_mode_read, adios2_mode_append
+ * and adios2_mode_readRandomAccess
  * @return success: handler, failure: NULL
  */
 adios2_engine *adios2_open(adios2_io *io, const char *name, const adios2_mode mode);
@@ -341,8 +341,8 @@ adios2_engine *adios2_open(adios2_io *io, const char *name, const adios2_mode mo
  * MPI Collective function as it calls MPI_Comm_dup
  * @param io engine owner
  * @param name unique engine identifier
- * @param mode adios2_mode_write, adios2_mode_read, adios2_mode_append,
- * adios2_mode_readRandomAccess and adios2_mode_readFlattenSteps
+ * @param mode adios2_mode_write, adios2_mode_read, adios2_mode_append and
+ * adios2_mode_readRandomAccess
  * @param comm communicator other than adios' handler comm. MPI only.
  * @return success: handler, failure: NULL
  */

bindings/C/adios2/c/adios2_c_io.tcc

@@ -36,10 +36,6 @@ adios2::Mode adios2_ToOpenMode(const adios2_mode modeC)
         mode = adios2::Mode::ReadRandomAccess;
         break;
 
-    case adios2_mode_readFlattenSteps:
-        mode = adios2::Mode::ReadFlattenSteps;
-        break;
-
     default:
         break;
     }

bindings/C/adios2/c/adios2_c_types.h

@@ -103,7 +103,6 @@ typedef enum
     adios2_mode_read = 2,
     adios2_mode_append = 3,
     adios2_mode_readRandomAccess = 6,
-    adios2_mode_readFlattenSteps = 7,
 
     adios2_mode_deferred = 4,
     adios2_mode_sync = 5

bindings/CXX11/adios2/cxx11/fstream/ADIOS2fstream.cpp

@@ -89,9 +89,6 @@ adios2::Mode fstream::ToMode(const openmode mode) const noexcept
     case (openmode::in_random_access):
         modeCpp = adios2::Mode::ReadRandomAccess;
         break;
-    case (openmode::in_flatten_steps):
-        modeCpp = adios2::Mode::ReadFlattenSteps;
-        break;
     case (openmode::app):
         modeCpp = adios2::Mode::Append;
         break;

bindings/CXX11/adios2/cxx11/fstream/ADIOS2fstream.h

@@ -48,7 +48,6 @@ class fstream
         out,              //!< write
         in,               //!< read
         in_random_access, //!< read_random_access
-        in_flatten_steps, //!< flatten all input steps to 1
         app               //!< append, not yet supported
     };
 

bindings/Fortran/modules/adios2_parameters_mod.f90

@@ -56,7 +56,6 @@ module adios2_parameters_mod
    integer, parameter :: adios2_mode_read = 2
    integer, parameter :: adios2_mode_append = 3
    integer, parameter :: adios2_mode_readRandomAccess = 6
-   integer, parameter :: adios2_mode_readFlattenSteps = 7
 
    integer, parameter :: adios2_mode_deferred = 4
    integer, parameter :: adios2_mode_sync = 5

bindings/Python/py11glue.cpp

@@ -98,7 +98,6 @@ PYBIND11_MODULE(ADIOS2_PYTHON_MODULE_NAME, m)
         .value("Write", adios2::Mode::Write)
         .value("Read", adios2::Mode::Read)
         .value("ReadRandomAccess", adios2::Mode::ReadRandomAccess)
-        .value("ReadFlattenSteps", adios2::Mode::ReadFlattenSteps)
         .value("Append", adios2::Mode::Append)
         .value("Deferred", adios2::Mode::Deferred)
         .value("Sync", adios2::Mode::Sync)

docs/user_guide/source/components/anatomy.rst

@@ -169,13 +169,3 @@ mode.  Also newer file Engines like BP5 to not allow
     |--> ADIOS goes out of scope or adios2_finalize()
     
 
-In addition to the two read modes discussed above, ADIOS has another
-input mode named `adios2::Mode::ReadFlattenSteps`. This is a highly
-specialized mode built that is unlikely to be of general utility, but
-we describe it for completeness.  In `ReadFlattenSteps` mode, ADIOS
-loads all the metadata in the file upon Open (just like
-`ReadRandomAccess` mode, but everything that was written appears that
-it was output on the same step, regardless of how many steps actually
-appear in the file.  This affects the operation of many reader-side
-ADIOS functions, including Steps(), BlocksInfo(), Get(), etc.
-

docs/user_guide/source/components/io.rst

@@ -196,7 +196,7 @@ A particular ``Engine`` type is set to the current ``IO`` component with the ``I
 Engine polymorphism is handled internally by the ``IO`` class, which allows subclassing future derived ``Engine`` types without changing the basic API.
 
 ``Engine`` objects are created in various modes.
-The available modes are ``adios2::Mode::Read``, ``adios2::Mode::ReadRandomAccess``, ``adios2::Mode::ReadFlattenSteps``, ``adios2::Mode::Write``, ``adios2::Mode::Append``, ``adios2::Mode::Sync``, ``adios2::Mode::Deferred``, and ``adios2::Mode::Undefined``.
+The available modes are ``adios2::Mode::Read``, ``adios2::Mode::ReadRandomAccess``, ``adios2::Mode::Write``, ``adios2::Mode::Append``, ``adios2::Mode::Sync``, ``adios2::Mode::Deferred``, and ``adios2::Mode::Undefined``.
 
 
 .. code-block:: c++

docs/user_guide/source/engines/bp5.rst

@@ -130,6 +130,14 @@ This engine allows the user to fine tune the buffering operations through the fo
 
    #. **Threads**: Read side: Specify how many threads one process can use to speed up reading. The default value is *0*, to let the engine estimate the number of threads based on how many processes are running on the compute node and how many hardware threads are available on the compute node but it will use maximum 16 threads. Value *1* forces the engine to read everything within the main thread of the process. Other values specify the exact number of threads the engine can use. Although multithreaded reading works in a single *Get(adios2::Mode::Sync)* call if the read selection spans multiple data blocks in the file, the best parallelization is achieved by using deferred mode and reading everything in *PerformGets()/EndStep()*.   
 
+   #. **FlattenSteps**: This is a writer-side parameter specifies that the
+      reader should interpret multiple writer-created timesteps as a
+      single timestep, essentially flattening all Put()s into a single step.
+
+   #. **IgnoreFlattenSteps**: This is a reader-side parameter that
+      tells the reader to ignore any FlattenSteps parameter supplied
+      to the writer.
+
 ============================== ===================== ===========================================================
  **Key**                       **Value Format**      **Default** and Examples
 ============================== ===================== ===========================================================
@@ -156,6 +164,8 @@ This engine allows the user to fine tune the buffering operations through the fo
  StatsLevel                     integer, 0 or 1       **1**, 0
  MaxOpenFilesAtOnce             integer >= 0          **UINT_MAX**, 1024, 1
  Threads                        integer >= 0          **0**, 1, 32
+ FlattenSteps                   boolean               **off**, on, true, false
+ IgnoreFlattenSteps             boolean               **off**, on, true, false
 ============================== ===================== ===========================================================
 
 

source/adios2/common/ADIOSTypes.h

@@ -80,7 +80,6 @@ enum class Mode
     Read,
     Append,
     ReadRandomAccess, // reader random access mode
-    ReadFlattenSteps, // reader flatten steps to one
     // launch execution modes
     Sync,
     Deferred

source/adios2/core/Engine.cpp

@@ -135,8 +135,7 @@ void Engine::Put(VariableStruct &variable, const void *data, const Mode launch)
 
 void Engine::Get(VariableStruct &variable, void *data, const Mode launch)
 {
-    CommonChecks(variable, data, {Mode::Read, Mode::ReadRandomAccess, Mode::ReadFlattenSteps},
-                 "in call to Get");
+    CommonChecks(variable, data, {Mode::Read, Mode::ReadRandomAccess}, "in call to Get");
 
     switch (launch)
     {

source/adios2/core/Engine.tcc

@@ -87,8 +87,7 @@ void Engine::Put(const std::string &variableName, const T &datum, const Mode /*l
 template <class T>
 void Engine::Get(Variable<T> &variable, T *data, const Mode launch)
 {
-    CommonChecks(variable, data, {Mode::Read, Mode::ReadRandomAccess, Mode::ReadFlattenSteps},
-                 "in call to Get");
+    CommonChecks(variable, data, {Mode::Read, Mode::ReadRandomAccess}, "in call to Get");
 
     switch (launch)
     {

source/adios2/core/IO.cpp

@@ -150,14 +150,6 @@ const std::unordered_map<std::string, bool> ReadRandomAccess_Supported = {
     {"campaign", true},
 };
 
-const std::unordered_map<std::string, bool> ReadFlattenSteps_Supported = {
-    {"bp3", false},     {"bp4", false},        {"bp5", true},      {"dataman", false},
-    {"ssc", false},     {"mhs", false},        {"sst", false},     {"daos", false},
-    {"effis", false},   {"dataspaces", false}, {"hdf5", false},    {"skeleton", false},
-    {"inline", false},  {"null", true},        {"nullcore", true}, {"plugin", false},
-    {"campaign", true},
-};
-
 // Synchronize access to the factory in case one thread is
 // looking up while another registers additional entries.
 std::mutex FactoryMutex;
@@ -568,8 +560,7 @@ Engine &IO::Open(const std::string &name, const Mode mode, helper::Comm comm)
         {
             engineTypeLC = "campaign";
         }
-        else if ((mode_to_use == Mode::Read) || (mode_to_use == Mode::ReadRandomAccess) ||
-                 (mode_to_use == Mode::ReadFlattenSteps))
+        else if ((mode_to_use == Mode::Read) || (mode_to_use == Mode::ReadRandomAccess))
         {
             if (adios2sys::SystemTools::FileIsDirectory(name))
             {
@@ -677,26 +668,10 @@ Engine &IO::Open(const std::string &name, const Mode mode, helper::Comm comm)
         }
     }
 
-    if (mode_to_use == Mode::ReadFlattenSteps)
-    {
-        // older engines don't know about ReadFlattenSteps Mode, throw an exception
-        auto it = ReadFlattenSteps_Supported.find(engineTypeLC);
-        if (it != ReadFlattenSteps_Supported.end())
-        {
-            if (!it->second)
-            {
-                helper::Throw<std::runtime_error>("Core", "IO", "Open",
-                                                  "Engine " + engineTypeLC +
-                                                      " doesn't support ReadFlattenSteps mode");
-            }
-        }
-    }
-
     auto f = FactoryLookup(engineTypeLC);
     if (f != Factory.end())
     {
-        if ((mode_to_use == Mode::Read) || (mode_to_use == Mode::ReadRandomAccess) ||
-            (mode_to_use == Mode::ReadFlattenSteps))
+        if ((mode_to_use == Mode::Read) || (mode_to_use == Mode::ReadRandomAccess))
         {
             engine = f->second.MakeReader(*this, name, mode_to_use, std::move(comm));
         }

source/adios2/core/Stream.cpp

@@ -23,8 +23,7 @@ Stream::Stream(const std::string &name, const Mode mode, helper::Comm comm,
 : m_ADIOS(std::make_shared<ADIOS>(std::move(comm), hostLanguage)), m_IO(&m_ADIOS->DeclareIO(name)),
   m_Name(name), m_Mode(mode), m_EngineType(engineType)
 {
-    if ((mode == adios2::Mode::Read) || (mode == adios2::Mode::ReadRandomAccess) ||
-        (mode == adios2::Mode::ReadFlattenSteps))
+    if ((mode == adios2::Mode::Read) || (mode == adios2::Mode::ReadRandomAccess))
     {
         CheckOpen();
     }
@@ -42,8 +41,7 @@ Stream::Stream(const std::string &name, const Mode mode, helper::Comm comm,
 : m_ADIOS(std::make_shared<ADIOS>(configFile, std::move(comm), hostLanguage)),
   m_IO(&m_ADIOS->DeclareIO(ioInConfigFile)), m_Name(name), m_Mode(mode)
 {
-    if ((mode == adios2::Mode::Read) || (mode == adios2::Mode::ReadRandomAccess) ||
-        (mode == adios2::Mode::ReadFlattenSteps))
+    if ((mode == adios2::Mode::Read) || (mode == adios2::Mode::ReadRandomAccess))
     {
         CheckOpen();
     }

source/adios2/engine/bp5/BP5Engine.h

@@ -56,15 +56,33 @@ class BP5Engine
 
     format::BufferSTL m_MetadataIndex;
 
-    /** Positions of flags in Index Table Header that Reader uses */
-    static constexpr size_t m_IndexHeaderSize = 64;
-    static constexpr size_t m_EndianFlagPosition = 36;
-    static constexpr size_t m_BPVersionPosition = 37;
-    static constexpr size_t m_BPMinorVersionPosition = 38;
-    static constexpr size_t m_ActiveFlagPosition = 39;
-    static constexpr size_t m_ColumnMajorFlagPosition = 40;
-    static constexpr size_t m_VersionTagPosition = 0;
-    static constexpr size_t m_VersionTagLength = 32;
+    /** Positions of flags in Index Table Header that Reader uses - MUST BE 64 bytes total */
+    struct BP5IndexTableHeader
+    {
+        char VersionTag[32];
+        uint8_t adiosMajorVersion;
+        uint8_t adiosMinorVersion;
+        uint8_t adiosPatchVersion;
+        uint8_t unused1;        // init to zero
+        uint8_t isLittleEndian; // boolean
+        uint8_t bpVersion;      // 5 here
+        uint8_t bpMinorVersion;
+        uint8_t activeFlag;
+        char columnMajor;     // y or n
+        uint8_t flattenSteps; // writer requests all steps flattened to one on read
+        char unused2[22];     // init to zero
+    };
+    static constexpr size_t m_IndexHeaderSize = sizeof(BP5IndexTableHeader);
+    static constexpr size_t m_EndianFlagPosition = offsetof(BP5IndexTableHeader, isLittleEndian);
+    static constexpr size_t m_BPVersionPosition = offsetof(BP5IndexTableHeader, bpVersion);
+    static constexpr size_t m_BPMinorVersionPosition =
+        offsetof(BP5IndexTableHeader, bpMinorVersion);
+    static constexpr size_t m_ActiveFlagPosition = offsetof(BP5IndexTableHeader, activeFlag);
+    static constexpr size_t m_ColumnMajorFlagPosition = offsetof(BP5IndexTableHeader, columnMajor);
+    static constexpr size_t m_FlattenStepsPosition = offsetof(BP5IndexTableHeader, flattenSteps);
+    static constexpr size_t m_VersionTagPosition = offsetof(BP5IndexTableHeader, VersionTag);
+    static constexpr size_t m_VersionTagLength = sizeof(BP5IndexTableHeader().VersionTag);
+    static constexpr size_t m_HeaderTailPadding = sizeof(BP5IndexTableHeader().unused2);
 
     static constexpr uint8_t m_BP5MinorVersion = 2;
 
@@ -154,6 +172,8 @@ class BP5Engine
     MACRO(StatsBlockSize, SizeBytes, size_t, DefaultStatsBlockSize)                                \
     MACRO(Threads, UInt, unsigned int, 0)                                                          \
     MACRO(UseOneTimeAttributes, Bool, bool, true)                                                  \
+    MACRO(FlattenSteps, Bool, bool, false)                                                         \
+    MACRO(IgnoreFlattenSteps, Bool, bool, false)                                                   \
     MACRO(RemoteDataPath, String, std::string, "")                                                 \
     MACRO(MaxOpenFilesAtOnce, UInt, unsigned int, UINT_MAX)
 

source/adios2/engine/bp5/BP5Reader.cpp

@@ -72,7 +72,7 @@ void BP5Reader::InstallMetadataForTimestep(size_t Step)
         size_t ThisMDSize =
             helper::ReadValue<uint64_t>(m_Metadata.Data(), Position, m_Minifooter.IsLittleEndian);
         char *ThisMD = m_Metadata.Data() + MDPosition;
-        if ((m_OpenMode == Mode::ReadRandomAccess) || (m_OpenMode == Mode::ReadFlattenSteps))
+        if ((m_OpenMode == Mode::ReadRandomAccess) || (m_FlattenSteps))
         {
             m_BP5Deserializer->InstallMetaData(ThisMD, ThisMDSize, WriterRank, Step);
         }
@@ -475,14 +475,12 @@ void BP5Reader::PerformLocalGets()
 // PRIVATE
 void BP5Reader::Init()
 {
-    if ((m_OpenMode != Mode::Read) && (m_OpenMode != Mode::ReadRandomAccess) &&
-        (m_OpenMode != Mode::ReadFlattenSteps))
+    if ((m_OpenMode != Mode::Read) && (m_OpenMode != Mode::ReadRandomAccess))
     {
-        helper::Throw<std::invalid_argument>(
-            "Engine", "BP5Reader", "Init",
-            "BPFileReader only supports OpenMode::Read, "
-            "OpenMode::ReadRandomAccess, or OpenMode::ReadFlattenSteps from" +
-                m_Name);
+        helper::Throw<std::invalid_argument>("Engine", "BP5Reader", "Init",
+                                             "BPFileReader only supports OpenMode::Read or "
+                                             "OpenMode::ReadRandomAccess from" +
+                                                 m_Name);
     }
 
     // if IO was involved in reading before this flag may be true now
@@ -521,7 +519,7 @@ void BP5Reader::InitParameters()
     ParseParams(m_IO, m_Parameters);
     if (m_Parameters.OpenTimeoutSecs < 0.0f)
     {
-        if ((m_OpenMode == Mode::ReadRandomAccess) || (m_OpenMode == Mode::ReadFlattenSteps))
+        if (m_OpenMode == Mode::ReadRandomAccess)
         {
             m_Parameters.OpenTimeoutSecs = 0.0f;
         }
@@ -809,9 +807,9 @@ void BP5Reader::UpdateBuffer(const TimePoint &timeoutInstant, const Seconds &pol
         // create the serializer object
         if (!m_BP5Deserializer)
         {
-            m_BP5Deserializer = new format::BP5Deserializer(m_WriterIsRowMajor, m_ReaderIsRowMajor,
-                                                            (m_OpenMode != Mode::Read),
-                                                            (m_OpenMode == Mode::ReadFlattenSteps));
+            m_BP5Deserializer =
+                new format::BP5Deserializer(m_WriterIsRowMajor, m_ReaderIsRowMajor,
+                                            (m_OpenMode != Mode::Read), (m_FlattenSteps));
             m_BP5Deserializer->m_Engine = this;
         }
     }
@@ -908,7 +906,7 @@ void BP5Reader::UpdateBuffer(const TimePoint &timeoutInstant, const Seconds &pol
 
         m_Comm.Bcast(m_Metadata.Data(), inputSize, 0);
 
-        if ((m_OpenMode == Mode::ReadRandomAccess) || (m_OpenMode == Mode::ReadFlattenSteps))
+        if ((m_OpenMode == Mode::ReadRandomAccess) || m_FlattenSteps)
         {
             for (size_t Step = 0; Step < m_MetadataIndexTable.size(); Step++)
             {
@@ -985,6 +983,15 @@ size_t BP5Reader::ParseMetadataIndex(format::BufferSTL &bufferSTL, const size_t
         const uint8_t val =
             helper::ReadValue<uint8_t>(buffer, position, m_Minifooter.IsLittleEndian);
         m_WriterIsRowMajor = val == 'n';
+
+        position = m_FlattenStepsPosition;
+        const uint8_t flatten_val =
+            helper::ReadValue<uint8_t>(buffer, position, m_Minifooter.IsLittleEndian);
+        m_FlattenSteps = (flatten_val != 0);
+
+        if (m_Parameters.IgnoreFlattenSteps)
+            m_FlattenSteps = false;
+
         // move position to first row
         position = m_IndexHeaderSize;
     }
@@ -1253,7 +1260,7 @@ void BP5Reader::DoGetStructDeferred(VariableStruct &variable, void *data)
 void BP5Reader::DoClose(const int transportIndex)
 {
     PERFSTUBS_SCOPED_TIMER("BP5Reader::Close");
-    if ((m_OpenMode == Mode::ReadRandomAccess) || (m_OpenMode == Mode::ReadFlattenSteps))
+    if (m_OpenMode == Mode::ReadRandomAccess)
     {
         PerformGets();
     }
@@ -1316,7 +1323,7 @@ void BP5Reader::FlushProfiler()
 
 size_t BP5Reader::DoSteps() const
 {
-    if (m_OpenMode == Mode::ReadFlattenSteps)
+    if (m_FlattenSteps)
         return 1;
     else
         return m_StepsCount;