FileStream writes BP5; mode-aware append; block-aware Variable::Start()

FileStream now resolves to BP5 on write, chosen by open mode without
querying the filesystem for a version; read and append conform to the
existing file. Fix the file/bp engine to conform to the on-disk version
on append instead of forcing BP5.

Give Variable::Start() the same engine-queried block-selection path as
Count(), so SetBlockSelection reports the block's offset correctly.

Add BP5 read-while-write coverage (StepsInSitu .BP5 variants) and verify
FileStream/BPFile resolve to the expected engine via Engine::Type().

Author: eisenhauer

bindings/CXX/adios2/cxx/Variable.cpp

@@ -150,7 +150,7 @@ namespace adios2
     Dims Variable<T>::Start() const                                                                \
     {                                                                                              \
         helper::CheckForNullptr(m_Variable, "in call to Variable<T>::Start");                      \
-        return m_Variable->m_Start;                                                                \
+        return m_Variable->Start();                                                                \
     }                                                                                              \
                                                                                                    \
     template <>                                                                                    \

bindings/CXX/adios2/cxx/Variable.h

@@ -292,13 +292,20 @@ class Variable
                        const size_t step = adios2::EngineCurrentStep) const;
 
     /**
-     * Inspects current start point
+     * Returns the start offset of the variable's current selection: the box set
+     * by SetSelection, or the selected block's global offset after
+     * SetBlockSelection (queried from the engine; empty for a local-array block,
+     * which has no global offset). For the variable's overall shape use Shape();
+     * to enumerate every block use BlocksInfo().
      * @return start vector
      */
     adios2::Dims Start() const;
 
     /**
-     * Inspects current count from start
+     * Returns the count of the variable's current selection: the box set by
+     * SetSelection, or the selected block's count after SetBlockSelection
+     * (queried from the engine). For the variable's overall shape use Shape();
+     * to enumerate every block use BlocksInfo().
      * @return count vector
      */
     adios2::Dims Count() const;

bindings/CXX/adios2/cxx/VariableNT.cpp

@@ -154,7 +154,21 @@ Dims VariableNT::Shape(const size_t step) const
 Dims VariableNT::Start() const
 {
     helper::CheckForNullptr(m_Variable, "in call to VariableNT::Start");
-    return m_Variable->m_Start;
+    auto type = m_Variable->m_Type;
+#define declare_type(T)                                                                            \
+    if (type == helper::GetDataType<T>())                                                          \
+    {                                                                                              \
+        return reinterpret_cast<core::Variable<T> *>(m_Variable)->Start();                         \
+    }
+    ADIOS2_FOREACH_STDTYPE_1ARG(declare_type)
+#undef declare_type
+    else if (type == DataType::Struct)
+    {
+        return reinterpret_cast<core::VariableStruct *>(m_Variable)->m_Start;
+    }
+    helper::Throw<std::runtime_error>("bindings::CXX", "VariableNT", "Start",
+                                      "invalid data type " + ToString(type));
+    return Dims();
 }
 
 Dims VariableNT::Count() const

bindings/CXX/adios2/cxx/VariableNT.h

@@ -153,13 +153,20 @@ class VariableNT
     adios2::Dims Shape(const size_t step = adios2::EngineCurrentStep) const;
 
     /**
-     * Inspects current start point
+     * Returns the start offset of the variable's current selection: the box set
+     * by SetSelection, or the selected block's global offset after
+     * SetBlockSelection (queried from the engine; empty for a local-array block,
+     * which has no global offset). For the variable's overall shape use Shape();
+     * to enumerate every block use BlocksInfo().
      * @return start vector
      */
     adios2::Dims Start() const;
 
     /**
-     * Inspects current count from start
+     * Returns the count of the variable's current selection: the box set by
+     * SetSelection, or the selected block's count after SetBlockSelection
+     * (queried from the engine). For the variable's overall shape use Shape();
+     * to enumerate every block use BlocksInfo().
      * @return count vector
      */
     adios2::Dims Count() const;

docs/user_guide/source/components/variable.rst

@@ -236,3 +236,29 @@ Limitations of the ADIOS global array concept
    Technically, the content of the individual blocks is kept in the BP format (but not in HDF5 format) and in staging.
    If you really, really want to retrieve all the blocks, you need to handle this array as a Local Array and read the
    blocks one by one.
+
+Inspecting a Variable's Selection
+---------------------------------
+
+A ``Variable``'s current geometry can be read back through its accessors:
+
+- ``Start()`` and ``Count()`` return the start offset and count of the
+  variable's **current selection**. After ``SetSelection`` they echo the
+  bounding box that was set; after ``SetBlockSelection`` they report the
+  selected block's geometry, queried from the engine (``Start()`` is empty for a
+  Local Array block, which has no global offset).
+- ``Shape()`` returns the variable's global shape, queried from the engine,
+  independent of any selection.
+- ``BlocksInfo()`` and ``AllStepsBlocksInfo()`` enumerate the geometry of
+  **every** block written at a step, for when you need more than the single
+  currently selected block.
+
+.. code-block:: c++
+
+   var.SetBlockSelection(3);
+   adios2::Dims start = var.Start();   // block 3's offset in the global array
+   adios2::Dims count = var.Count();   // block 3's size
+
+``Start()`` and ``Count()`` describe the application's current selection, not
+engine-installed metadata; use ``Shape()`` for the overall shape and
+``BlocksInfo()`` to enumerate all blocks.

source/adios2/core/IO.cpp

@@ -605,14 +605,31 @@ Engine &IO::Open(const std::string &name, const Mode mode, helper::Comm comm, co
         if (engineTypeLC == "filestream")
         {
             // FileStream streams BP4/BP5 file output only (not DAOS, timeseries,
-            // etc.). A not-yet-created stream is normal, so BPVersionLocal returns
-            // '4' for a missing path and the engine waits rather than erroring.
-            char version = '4';
-            if (comm.Rank() == 0)
+            // etc.). The choice is mode-dependent: when writing a new file we
+            // produce the latest streamable format (BP5) and do not query the
+            // filesystem for a version (there is nothing to conform to). When
+            // reading, or appending to, an existing stream we conform to the
+            // file's version. A not-yet-created stream is normal (a reader may
+            // open before the writer creates the file): BPVersionLocal reports
+            // '0' (unknown), and we default to BP5, the format FileStream
+            // writers produce, so the reader matches rather than guessing BP4.
+            if (mode_to_use == Mode::Write)
             {
-                version = helper::BPVersionLocal(name);
+                engineTypeLC = "bp5";
+            }
+            else
+            {
+                char version = '5';
+                if (comm.Rank() == 0)
+                {
+                    char detected = helper::BPVersionLocal(name);
+                    if (detected != '0')
+                    {
+                        version = detected;
+                    }
+                }
+                engineTypeLC = std::string("bp") + comm.BroadcastValue(version);
             }
-            engineTypeLC = std::string("bp") + comm.BroadcastValue(version);
         }
         else if (helper::EndsWith(name, ".h5", false))
         {
@@ -626,8 +643,11 @@ Engine &IO::Open(const std::string &name, const Mode mode, helper::Comm comm, co
         {
             engineTypeLC = "timeseries";
         }
-        else if ((mode_to_use == Mode::Read) || (mode_to_use == Mode::ReadRandomAccess))
+        else if ((mode_to_use == Mode::Read) || (mode_to_use == Mode::ReadRandomAccess) ||
+                 (mode_to_use == Mode::Append))
         {
+            // Read and Append both conform to the on-disk file's version; only a
+            // fresh Write (the final else) chooses the latest format outright.
             auto it = m_Parameters.find("TarInfo");
             if (it != m_Parameters.end())
             {
@@ -676,18 +696,30 @@ Engine &IO::Open(const std::string &name, const Mode mode, helper::Comm comm, co
                 comm.BroadcastVector(selected);
                 if (selected.empty())
                 {
-                    // Built identically on every rank from 'name', so all ranks
-                    // throw together without broadcasting the message.
-                    std::string err = "Cannot determine the engine for reading \"" + name +
-                                      "\": nothing exists at that location.";
-                    if (mode_to_use == Mode::Read)
+                    // Nothing on disk. Appending to a not-yet-created file creates
+                    // it in the latest format; reading is an error.
+                    if (mode_to_use == Mode::Append)
                     {
-                        err += "  If it is a stream that has not been created yet, select "
-                               "the engine explicitly with IO::SetEngine().";
+                        engineTypeLC = "bp5";
                     }
-                    helper::Throw<std::runtime_error>("Core", "IO", "Open", err);
+                    else
+                    {
+                        // Built identically on every rank from 'name', so all ranks
+                        // throw together without broadcasting the message.
+                        std::string err = "Cannot determine the engine for reading \"" + name +
+                                          "\": nothing exists at that location.";
+                        if (mode_to_use == Mode::Read)
+                        {
+                            err += "  If it is a stream that has not been created yet, select "
+                                   "the engine explicitly with IO::SetEngine().";
+                        }
+                        helper::Throw<std::runtime_error>("Core", "IO", "Open", err);
+                    }
+                }
+                else
+                {
+                    engineTypeLC.assign(selected.begin(), selected.end());
                 }
-                engineTypeLC.assign(selected.begin(), selected.end());
             }
         }
         else

source/adios2/core/Variable.cpp

@@ -61,6 +61,12 @@ namespace core
     }                                                                                              \
                                                                                                    \
     template <>                                                                                    \
+    Dims Variable<T>::Start() const                                                                \
+    {                                                                                              \
+        return DoStart();                                                                          \
+    }                                                                                              \
+                                                                                                   \
+    template <>                                                                                    \
     Dims Variable<T>::Count() const                                                                \
     {                                                                                              \
         return DoCount();                                                                          \

source/adios2/core/Variable.h

@@ -104,6 +104,8 @@ class Variable : public VariableBase
 
     T *GetData() const noexcept;
 
+    Dims Start() const;
+
     Dims Count() const;
 
     size_t SelectionSize() const;
@@ -124,6 +126,8 @@ class Variable : public VariableBase
     std::vector<std::vector<typename Variable<T>::BPInfo>> AllStepsBlocksInfo() const;
 
 private:
+    Dims DoStart() const;
+
     Dims DoCount() const;
 
     size_t DoSelectionSize() const;

source/adios2/core/Variable.tcc

@@ -18,6 +18,80 @@ namespace adios2
 namespace core
 {
 
+template <class T>
+Dims Variable<T>::DoStart() const
+{
+    auto lf_Step = [&]() -> size_t {
+        auto itStep = std::next(m_AvailableStepBlockIndexOffsets.begin(), m_StepsStart);
+        if (itStep == m_AvailableStepBlockIndexOffsets.end())
+        {
+            auto it = m_AvailableStepBlockIndexOffsets.rbegin();
+            helper::Throw<std::invalid_argument>(
+                "Core", "Variable", "DoStart",
+                "current relative step start for variable " + m_Name +
+                    " is outside the scope of available steps " + std::to_string(it->first - 1) +
+                    " in call to Start");
+        }
+        return itStep->first - 1;
+    };
+
+    // A block selection reports the selected block's start, queried from the
+    // engine (mirrors DoCount()). For a local-array block this is empty.
+    if (m_Engine != nullptr && m_SelectionType == SelectionType::WriteBlock)
+    {
+        auto MVI = m_Engine->MinBlocksInfo(*this, m_StepsStart);
+        if (MVI)
+        {
+            if (m_BlockID >= MVI->BlocksInfo.size())
+            {
+                helper::Throw<std::invalid_argument>(
+                    "Core", "Variable", "DoStart",
+                    "blockID " + std::to_string(m_BlockID) +
+                        " from SetBlockSelection is out of bounds for available "
+                        "blocks size " +
+                        std::to_string(MVI->BlocksInfo.size()) + " for variable " + m_Name +
+                        " for step " + std::to_string(m_StepsStart) +
+                        ", in call to Variable<T>::Start()");
+            }
+
+            const size_t *StartPtr = (MVI->BlocksInfo)[m_BlockID].Start;
+            // Local values and local-array blocks have no global start offset
+            if (MVI->WasLocalValue || StartPtr == nullptr)
+            {
+                delete MVI;
+                return {};
+            }
+            Dims D;
+            D.resize(MVI->Dims);
+            for (int i = 0; i < MVI->Dims; i++)
+            {
+                D[i] = StartPtr[i];
+            }
+            delete MVI;
+            return D;
+        }
+
+        const size_t step = !m_FirstStreamingStep ? m_Engine->CurrentStep() : lf_Step();
+
+        const std::vector<typename Variable<T>::BPInfo> blocksInfo =
+            m_Engine->BlocksInfo<T>(*this, step);
+
+        if (m_BlockID >= blocksInfo.size())
+        {
+            helper::Throw<std::invalid_argument>(
+                "Core", "Variable", "DoStart",
+                "blockID " + std::to_string(m_BlockID) +
+                    " from SetBlockSelection is out of bounds for available "
+                    "blocks size " +
+                    std::to_string(blocksInfo.size()) + " for variable " + m_Name + " for step " +
+                    std::to_string(step) + ", in call to Variable<T>::Start()");
+        }
+
+        return blocksInfo[m_BlockID].Start;
+    }
+    return m_Start;
+}
+
 template <class T>
 Dims Variable<T>::DoCount() const
 {

source/adios2/helper/adiosSystem.cpp

@@ -171,6 +171,15 @@ bool IsHDF5File(const std::string &name, core::IO &io, helper::Comm &comm,
 
 char BPVersionLocal(const std::string &name) noexcept
 {
+    if (!adios2sys::SystemTools::PathExists(name))
+    {
+        // The dataset directory does not exist (yet). We cannot know which
+        // version a future writer will produce, so report unknown ('0')
+        // rather than guessing BP4. Callers decide how to handle a
+        // not-yet-created stream. Only an existing directory that lacks the
+        // mmd.0 metadata index is genuinely BP4.
+        return '0';
+    }
     const std::string mmdFileName = name + PathSeparator + "mmd.0";
     return adios2sys::SystemTools::PathExists(mmdFileName) ? '5' : '4';
 }