Add openPMD version 2.0 to supported API versions (#1551)

* Add openPMD 2.0 standard setting

* Fix clang-tidy warning

* Introduce getStandardMaximum(), deprecate getStandard()

* Add warning: openPMD 2.0 still under development

* Remove unnecessary import

include/openPMD/Error.hpp

@@ -109,6 +109,12 @@ namespace error
     public:
         NoSuchAttribute(std::string attributeName);
     };
+
+    class IllegalInOpenPMDStandard : public Error
+    {
+    public:
+        IllegalInOpenPMDStandard(std::string what);
+    };
 } // namespace error
 
 /**

include/openPMD/version.hpp

@@ -37,11 +37,20 @@
  * compile-time)
  * @{
  */
-#define OPENPMD_STANDARD_MAJOR 1
-#define OPENPMD_STANDARD_MINOR 1
+#define OPENPMD_STANDARD_MAJOR 2
+#define OPENPMD_STANDARD_MINOR 0
 #define OPENPMD_STANDARD_PATCH 0
 /** @} */
 
+/** maximum supported version of the openPMD standard (read & write,
+ * compile-time)
+ * @{
+ */
+#define OPENPMD_STANDARD_DEFAULT_MAJOR 1
+#define OPENPMD_STANDARD_DEFAULT_MINOR 1
+#define OPENPMD_STANDARD_DEFAULT_PATCH 0
+/** @} */
+
 /** minimum supported version of the openPMD standard (read, compile-time)
  * @{
  */
@@ -77,7 +86,17 @@ std::string getVersion();
  *
  * @return std::string openPMD standard version (dot separated)
  */
-std::string getStandard();
+[[deprecated(
+    "Deprecated due to unclear semantics. Use one of getStandardMinimum, "
+    "getStandardMaximum() or getStandardDefault instead.")]] std::string
+getStandard();
+
+/** Return the default used version of the openPMD standard (read & write,
+ * run-time)
+ *
+ * @return std::string openPMD standard version (dot separated)
+ */
+std::string getStandardDefault();
 
 /** Return the minimum supported version of the openPMD standard (read,
  * run-time)
@@ -86,6 +105,13 @@ std::string getStandard();
  */
 std::string getStandardMinimum();
 
+/** Return the minimum supported version of the openPMD standard (read,
+ * run-time)
+ *
+ * @return std::string minimum openPMD standard version (dot separated)
+ */
+std::string getStandardMaximum();
+
 /** Return the feature variants of the openPMD-api library (run-time)
  *
  * @return std::map< std::string, bool > with variants such as backends

src/Error.cpp

@@ -122,6 +122,12 @@ namespace error
         , description(std::move(description_in))
     {}
 
+    IllegalInOpenPMDStandard::IllegalInOpenPMDStandard(std::string what_in)
+        : Error(
+              "Operation leads to illegal use of the openPMD standard:\n" +
+              std::move(what_in))
+    {}
+
     void throwReadError(
         AffectedObject affectedObject,
         Reason reason,

src/Series.cpp

@@ -139,6 +139,11 @@ std::string Series::openPMD() const
 
 Series &Series::setOpenPMD(std::string const &o)
 {
+    if (o >= "2.0")
+    {
+        std::cerr << "[Warning] openPMD 2.0 is still under development."
+                  << std::endl;
+    }
     setAttribute("openPMD", o);
     return *this;
 }
@@ -162,9 +167,10 @@ std::string Series::basePath() const
 Series &Series::setBasePath(std::string const &bp)
 {
     std::string version = openPMD();
-    if (version == "1.0.0" || version == "1.0.1" || version == "1.1.0")
+    if (version == "1.0.0" || version == "1.0.1" || version == "1.1.0" ||
+        version == "2.0.0")
         throw std::runtime_error(
-            "Custom basePath not allowed in openPMD <=1.1.0");
+            "Custom basePath not allowed in openPMD <=2.0");
 
     setAttribute("basePath", bp);
     return *this;
@@ -1222,7 +1228,7 @@ void Series::initDefaults(IterationEncoding ie, bool initAll)
         }
     }
     if (!containsAttribute("openPMD"))
-        setOpenPMD(getStandard());
+        setOpenPMD(getStandardDefault());
     /*
      * In Append mode, only init the rest of the defaults after checking that
      * the file does not yet exist to avoid overriding more than needed.
@@ -1828,7 +1834,8 @@ void Series::readOneIterationFileBased(std::string const &filePath)
 
     Parameter<Operation::OPEN_PATH> pOpen;
     std::string version = openPMD();
-    if (version == "1.0.0" || version == "1.0.1" || version == "1.1.0")
+    if (version == "1.0.0" || version == "1.0.1" || version == "1.1.0" ||
+        version == "2.0.0")
         pOpen.path = auxiliary::replace_first(basePath(), "/%T/", "");
     else
         throw error::ReadError(
@@ -1980,7 +1987,8 @@ creating new iterations.
 
     Parameter<Operation::OPEN_PATH> pOpen;
     std::string version = openPMD();
-    if (version == "1.0.0" || version == "1.0.1" || version == "1.1.0")
+    if (version == "1.0.0" || version == "1.0.1" || version == "1.1.0" ||
+        version == "2.0.0")
         pOpen.path = auxiliary::replace_first(basePath(), "/%T/", "");
     else
         throw error::ReadError(

src/binding/python/Error.cpp

@@ -22,6 +22,8 @@ void init_Error(py::module &m)
     py::register_exception<error::Internal>(m, "ErrorInternal", baseError);
     py::register_exception<error::NoSuchAttribute>(
         m, "ErrorNoSuchAttribute", baseError);
+    py::register_exception<error::IllegalInOpenPMDStandard>(
+        m, "ErrorIllegalInOpenPMDStandard", baseError);
 
 #ifndef NDEBUG
     m.def("test_throw", [](std::string description) {

src/version.cpp

@@ -34,10 +34,16 @@ std::string openPMD::getVersion()
 }
 
 std::string openPMD::getStandard()
+{
+    return getStandardMaximum();
+}
+
+std::string openPMD::getStandardDefault()
 {
     std::stringstream standard;
-    standard << OPENPMD_STANDARD_MAJOR << "." << OPENPMD_STANDARD_MINOR << "."
-             << OPENPMD_STANDARD_PATCH;
+    standard << OPENPMD_STANDARD_DEFAULT_MAJOR << "."
+             << OPENPMD_STANDARD_DEFAULT_MINOR << "."
+             << OPENPMD_STANDARD_DEFAULT_PATCH;
     return standard.str();
 }
 
@@ -49,3 +55,11 @@ std::string openPMD::getStandardMinimum()
                 << OPENPMD_STANDARD_MIN_PATCH;
     return standardMin.str();
 }
+
+std::string openPMD::getStandardMaximum()
+{
+    std::stringstream standard;
+    standard << OPENPMD_STANDARD_MAJOR << "." << OPENPMD_STANDARD_MINOR << "."
+             << OPENPMD_STANDARD_PATCH;
+    return standard.str();
+}

test/CoreTest.cpp

@@ -1,6 +1,4 @@
 // expose private and protected members for invasive testing
-#include "openPMD/Datatype.hpp"
-#include "openPMD/Error.hpp"
 #if openPMD_USE_INVASIVE_TESTS
 #define OPENPMD_private public:
 #define OPENPMD_protected public:
@@ -36,8 +34,11 @@ TEST_CASE("versions_test", "[core]")
     auto const is_dot = [](char const c) { return c == '.'; };
     REQUIRE(2u == std::count_if(apiVersion.begin(), apiVersion.end(), is_dot));
 
-    auto const standard = getStandard();
-    REQUIRE(standard == "1.1.0");
+    auto const standardDefault = getStandardDefault();
+    REQUIRE(standardDefault == "1.1.0");
+
+    auto const standard = getStandardMaximum();
+    REQUIRE(standard == "2.0.0");
 
     auto const standardMin = getStandardMinimum();
     REQUIRE(standardMin == "1.0.0");

test/SerialIOTest.cpp

@@ -912,6 +912,7 @@ inline void constant_scalar(std::string const &file_ending)
         // constant scalar
         Series s =
             Series("../samples/constant_scalar." + file_ending, Access::CREATE);
+        s.setOpenPMD("2.0.0");
         auto rho = s.iterations[1].meshes["rho"][MeshRecordComponent::SCALAR];
         REQUIRE(s.iterations[1].meshes["rho"].scalar());
         rho.resetDataset(Dataset(Datatype::CHAR, {1, 2, 3}));