Use schema-based versioning in ADIOS2 backend (#941)

* Use schema-based versioning in ADIOS2 backend

Also automatically recognize the schema used by a written file

* Only support explicitly listed schema versions

* Update documentation

* Undo unnecessary whitespace changes

* Remove change that is now a PR of its own

See #944

* Rename __is_boolean__ to __openPMD_internal/is_boolean

Only in new layout

Author: franzpoeschel

.github/workflows/unix.yml

@@ -134,7 +134,7 @@ jobs:
         ../share/openPMD/download_samples.sh && chmod u-w samples/git-sample/*.h5
         cmake -S .. -B . -DopenPMD_USE_PYTHON=OFF -DopenPMD_USE_MPI=ON -DopenPMD_USE_HDF5=ON -DopenPMD_USE_ADIOS1=OFF -DopenPMD_USE_ADIOS2=ON -DopenPMD_USE_INVASIVE_TESTS=ON
         cmake --build . --parallel 2
-        export OPENPMD_NEW_ATTRIBUTE_LAYOUT=1
+        export OPENPMD2_ADIOS2_SCHEMA=20210209
         ctest --output-on-failure
 
 # TODO

docs/source/backends/adios2.rst

@@ -51,7 +51,7 @@ environment variable                  default    description
 ``OPENPMD_ADIOS2_HAVE_METADATA_FILE`` ``1``      Online creation of the adios journal file (``1``: yes, ``0``: no).
 ``OPENPMD_ADIOS2_NUM_SUBSTREAMS``     ``0``      Number of files to be created, 0 indicates maximum number possible.
 ``OPENPMD_ADIOS2_ENGINE``             ``File``   `ADIOS2 engine <https://adios2.readthedocs.io/en/latest/engines/engines.html>`_
-``OPENPMD_NEW_ATTRIBUTE_LAYOUT``      ``0``      Experimental: new attribute layout (see below)
+``OPENPMD2_ADIOS2_SCHEMA``            ``0``      ADIOS2 schema version (see below)
 ``OPENPMD_BP_BACKEND``                ``ADIOS2`` Chose preferred ``.bp`` file backend if ``ADIOS1`` and ``ADIOS2`` are available.
 ===================================== ========== ================================================================================
 
@@ -79,8 +79,8 @@ A good number for substreams is usually the number of contributing nodes divided
 For fine-tuning at extreme scale or for exotic systems, please refer to the ADIOS2 manual and talk to your filesystem admins and the ADIOS2 authors.
 Be aware that extreme-scale I/O is a research topic after all.
 
-Experimental new attribute layout
----------------------------------
+Experimental new ADIOS2 schema
+------------------------------
 
 We are experimenting with a breaking change to our layout of openPMD datasets in ADIOS2.
 It is likely that we will in future use ADIOS attributes only for a handful of internal flags.
@@ -96,11 +96,10 @@ We hope that this will bring several advantages:
 
 The new layout may be activated **for experimental purposes** in two ways:
 
-* Via the JSON parameter ``adios2.new_attribute_layout = true``.
-* Via the environment variable ``export OPENPMD_NEW_ATTRIBUTE_LAYOUT=1``.
+* Via the JSON parameter ``adios2.schema = 20210209``.
+* Via the environment variable ``export OPENPMD2_ADIOS2_SCHEMA=20210209``.
 
-The classical and the new layout are absolutely incompatible with one another.
-The ADIOS2 backend will **not** (yet) automatically recognize the layout that has been used by a writer when reading a dataset.
+The ADIOS2 backend will automatically recognize the layout that has been used by a writer when reading a dataset.
 
 Selected References
 -------------------

include/openPMD/IO/ADIOS/ADIOS2IOHandler.hpp

@@ -80,6 +80,26 @@ namespace detail
 } // namespace detail
 
 
+namespace ADIOS2Schema
+{
+    using schema_t = uint64_t;
+    /*
+     * Original ADIOS schema.
+     */
+    constexpr schema_t schema_0000_00_00 = 00000000;
+    /*
+     * This introduces attribute layout via scalar ADIOS variables.
+     */
+    constexpr schema_t schema_2021_02_09 = 20210209;
+
+    enum class SupportedSchema : char
+    {
+        s_0000_00_00,
+        s_2021_02_09
+    };
+}
+using SupportedSchema = ADIOS2Schema::SupportedSchema;
+
 class ADIOS2IOHandlerImpl
 : public AbstractIOHandlerImplCommon< ADIOS2FilePosition >
 {
@@ -203,14 +223,40 @@ class ADIOS2IOHandlerImpl
      * The ADIOS2 engine type, to be passed to adios2::IO::SetEngine
      */
     std::string m_engineType;
+    ADIOS2Schema::schema_t m_schema = ADIOS2Schema::schema_0000_00_00;
 
     enum class AttributeLayout : char
     {
         ByAdiosAttributes,
         ByAdiosVariables
     };
 
-    AttributeLayout m_attributeLayout = AttributeLayout::ByAdiosAttributes;
+    inline SupportedSchema schema() const
+    {
+        switch( m_schema )
+        {
+        case ADIOS2Schema::schema_0000_00_00:
+            return SupportedSchema::s_0000_00_00;
+        case ADIOS2Schema::schema_2021_02_09:
+            return SupportedSchema::s_2021_02_09;
+        default:
+            throw std::runtime_error(
+                "[ADIOS2] Encountered unsupported schema version: " +
+                std::to_string( m_schema ) );
+        }
+    }
+
+    inline AttributeLayout attributeLayout() const
+    {
+        switch( schema() )
+        {
+        case SupportedSchema::s_0000_00_00:
+            return AttributeLayout::ByAdiosAttributes;
+        case SupportedSchema::s_2021_02_09:
+            return AttributeLayout::ByAdiosVariables;
+        }
+        throw std::runtime_error( "Unreachable!" );
+    }
 
     struct ParameterizedOperator
     {
@@ -357,6 +403,11 @@ namespace ADIOS2Defaults
     constexpr const_str str_params = "parameters";
     constexpr const_str str_usesteps = "usesteps";
     constexpr const_str str_usesstepsAttribute = "__openPMD_internal/useSteps";
+    constexpr const_str str_adios2Schema =
+        "__openPMD_internal/openPMD2_adios2_schema";
+    constexpr const_str str_isBooleanOldLayout = "__is_boolean__";
+    constexpr const_str str_isBooleanNewLayout =
+        "__openPMD_internal/is_boolean";
 } // namespace ADIOS2Defaults
 
 namespace detail
@@ -995,8 +1046,6 @@ namespace detail
         detail::DatasetReader const m_readDataset;
         detail::AttributeReader const m_attributeReader;
         PreloadAdiosAttributes preloadAttributes;
-        using AttributeLayout = ADIOS2IOHandlerImpl::AttributeLayout;
-        AttributeLayout m_attributeLayout = AttributeLayout::ByAdiosAttributes;
 
         /*
          * We call an attribute committed if the step during which it was
@@ -1106,6 +1155,7 @@ namespace detail
         invalidateVariablesMap();
 
     private:
+        ADIOS2IOHandlerImpl * m_impl;
         auxiliary::Option< adios2::Engine > m_engine; //! ADIOS engine
         /**
          * The ADIOS2 engine type, to be passed to adios2::IO::SetEngine
@@ -1230,10 +1280,20 @@ namespace detail
          */
         bool finalized = false;
 
+        inline SupportedSchema schema() const
+        {
+            return m_impl->schema();
+        }
+
         void
         configure_IO( ADIOS2IOHandlerImpl & impl );
-    };
 
+        using AttributeLayout = ADIOS2IOHandlerImpl::AttributeLayout;
+        inline AttributeLayout attributeLayout() const
+        {
+            return m_impl->attributeLayout();
+        }
+    };
 
 } // namespace detail
 #endif // openPMD_HAVE_ADIOS2