add HDF5 libver option, docs and test (#1056)

* add libver option, docs and test

CHANGELOG.md

@@ -18,6 +18,9 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s
 #### General
 - Updated to BLT v0.5.2
 
+#### Relay
+- When using HDF5 1.10 or newer, default to use libver 1.8 when creating HDF5 files for wider read compatibly. This setting can be controlled via the hdf5 relay option `libver`, accepted values: `default`,`none`,`latest`,`v108`, and `v110`.
+
 ### Fixed
 #### Blueprint
 - Fixed bug with `blueprint::mesh::examples::strided_structured` so it correctly generates a coordset with padding

src/docs/sphinx/relay_io.rst

@@ -294,6 +294,13 @@ It is also the interface used to implement the path-based and handle I/O interfa
 HDF5. This interface provides more control and allows more efficient reuse of I/O handles.
 It is only available in C++.
 
+Relay I/O HDF5 libver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+HDF5 provides a ``libver`` setting to control the data structures and features used.
+When using HDF5 1.10 or newer, relay io will default to use libver 1.8 when creating HDF5 files to provide wider read compatibly. This setting can be controlled via the hdf5 relay option ``libver``, accepted values include: ``default``, ``none``, ``latest``, ``v108``, and ``v110``.
+
+
 Relay I/O HDF5 Interface Examples
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/examples/using-with-cmake/conduit_example.cpp

@@ -17,9 +17,13 @@
 
 int main(int argc, char **argv)
 {
-    std::cout << conduit::about() << std::endl
-              << conduit::relay::about() << std::endl
-              << conduit::blueprint::about() << std::endl;
+    conduit::Node about;
+    conduit::about(about["conduit"]);
+    conduit::relay::about(about["conduit/relay"]);
+    conduit::relay::io::about(about["conduit/relay/io"]);
+    conduit::blueprint::about(about["conduit/blueprint"]);
+
+    std::cout << about.to_yaml() << std::endl;
 }
 
 

src/examples/using-with-make/conduit_example.cpp

@@ -17,9 +17,12 @@
 
 int main(int argc, char **argv)
 {
-    std::cout << conduit::about() << std::endl
-              << conduit::relay::about() << std::endl
-              << conduit::relay::io::about() << std::endl
-              << conduit::blueprint::about() << std::endl;
+    conduit::Node about;
+    conduit::about(about["conduit"]);
+    conduit::relay::about(about["conduit/relay"]);
+    conduit::relay::io::about(about["conduit/relay/io"]);
+    conduit::blueprint::about(about["conduit/blueprint"]);
+
+    std::cout << about.to_yaml() << std::endl;
 }
 

src/libs/relay/conduit_relay_io_hdf5.cpp

@@ -148,12 +148,19 @@ class HDF5Options
     static std::string compression_method;
     static int         compression_level;
 
+    static std::string libver;
+
 public:
 
     //------------------------------------------------------------------------
     static void set(const Node &opts)
     {
 
+        if(opts.has_child("libver"))
+        {
+            libver = opts["libver"].as_string();
+        }
+
         if(opts.has_child("compact_storage"))
         {
             const Node &compact = opts["compact_storage"];
@@ -219,13 +226,30 @@ class HDF5Options
                 }
             }
         }
+
     }
 
     //------------------------------------------------------------------------
     static void about(Node &opts)
     {
         opts.reset();
 
+        // report hdf5_library_version
+        unsigned int major_num=0;
+        unsigned int minor_num=0;
+        unsigned int release_num=0;
+
+        herr_t h5_status = H5get_libversion(&major_num, &minor_num,&release_num);
+
+        CONDUIT_CHECK_HDF5_ERROR(h5_status,
+                                 "Failed to fetch HDF5 library version info ");
+
+        opts["hdf5_library_version"] = conduit_fmt::format("v{0}.{1}.{2}",
+                                                           major_num,
+                                                           minor_num,
+                                                           release_num);
+        opts["libver"] = libver;
+
         if(compact_storage_enabled)
         {
             opts["compact_storage/enabled"] = "true";
@@ -254,6 +278,7 @@ class HDF5Options
         {
             opts["chunking/compression/level"] = compression_level;
         }
+
     }
 };
 
@@ -269,6 +294,7 @@ int         HDF5Options::chunk_threshold    = 2000000; // 2 mb
 std::string HDF5Options::compression_method = "gzip";
 int         HDF5Options::compression_level  = 5;
 
+std::string HDF5Options::libver             = "default";
 
 //-----------------------------------------------------------------------------
 void
@@ -2942,9 +2968,53 @@ create_hdf5_file_access_plist()
     if(major_num == 1 && minor_num >= 8)
     {
 #if H5_VERSION_GE(1, 10, 2)
-        h5_status = H5Pset_libver_bounds(h5_fa_props, H5F_LIBVER_V18, H5F_LIBVER_V18);
+        if(HDF5Options::libver == "default" ||
+           HDF5Options::libver == "v108")
+        {
+            h5_status = H5Pset_libver_bounds(h5_fa_props, H5F_LIBVER_V18, H5F_LIBVER_V18);
+        }
+        else if(HDF5Options::libver == "v1110")
+        {
+            h5_status = H5Pset_libver_bounds(h5_fa_props, H5F_LIBVER_V18, H5F_LIBVER_V110);
+        }
+        else if(HDF5Options::libver == "latest")
+        {
+            h5_status = H5Pset_libver_bounds(h5_fa_props, H5F_LIBVER_V18, H5F_LIBVER_LATEST);
+        }
+        else if( HDF5Options::libver == "none" )
+        {
+            // no op
+        }
+        else
+        {
+            // unknown or unsupported libver
+            CONDUIT_ERROR("HDF5 libver option: '"
+                          << HDF5Options::libver 
+                          << "' is unknown or unsupported with HDF5 v"
+                          << major_num << "." << major_num << "." << release_num
+                          );
+        }
 #else
-        h5_status = H5Pset_libver_bounds(h5_fa_props, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST);
+        // for 1.8, we map def, v108, and latest to H5F_LIBVER_LATEST
+        if(HDF5Options::libver == "default" ||
+           HDF5Options::libver == "v108" ||
+           HDF5Options::libver == "latest")
+        {
+            h5_status = H5Pset_libver_bounds(h5_fa_props, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST);
+        }
+        else if( HDF5Options::libver == "none" )
+        {
+            // no op
+        }
+        else
+        {
+            // unknown or unsupported libver
+            CONDUIT_ERROR("HDF5 libver option: '"
+                          << HDF5Options::libver 
+                          << "' is unknown or unsupported with HDF5 v"
+                          << major_num << "." << major_num << "." << release_num
+                          );
+        }
 #endif
 
         CONDUIT_CHECK_HDF5_ERROR(h5_status,

src/tests/blueprint/CMakeLists.txt

@@ -64,7 +64,6 @@ endif()
 
 set(BLUEPRINT_MPI_TESTS_RANKS_2
     t_blueprint_mpi_smoke
-
     t_blueprint_mpi_mesh_query
     t_blueprint_mpi_mesh_transform
     t_blueprint_mpi_mesh_verify)

src/tests/relay/CMakeLists.txt

@@ -10,6 +10,7 @@
 # conduit relay Unit Tests
 ################################
 set(RELAY_TESTS t_relay_smoke
+                t_relay_io_smoke
                 t_relay_io_basic
                 t_relay_io_file_sizes
                 t_relay_io_handle
@@ -22,7 +23,8 @@ set(RELAY_TESTS t_relay_smoke
 set(RELAY_WEBSERVER_TESTS  t_relay_node_viewer
                            t_relay_websocket)
 
-set(RELAY_MPI_TESTS      t_relay_mpi_smoke t_relay_mpi_test)
+set(RELAY_MPI_TESTS      t_relay_mpi_smoke
+                         t_relay_mpi_test)
 set(RELAY_SILO_TESTS     t_relay_io_silo)
 
 set(RELAY_HDF5_TESTS t_relay_io_hdf5
@@ -32,6 +34,7 @@ set(RELAY_HDF5_TESTS t_relay_io_hdf5
                      t_relay_io_hdf5_ident_report)
 
 
+set(RELAY_MPI_IO_TESTS t_relay_io_mpi_smoke)
 set(RELAY_ADIOS_TESTS t_relay_io_adios)
 set(RELAY_MPI_ADIOS_TESTS t_relay_mpi_io_adios)
 set(RELAY_ZFP_TESTS t_relay_zfp)
@@ -118,6 +121,14 @@ if(MPI_FOUND)
                          DEPENDS_ON conduit conduit_relay_mpi
                          FOLDER tests/relay)
     endforeach()
+    message(STATUS "MPI enabled: Adding conduit_relay_mpi_io unit tests")
+    foreach(TEST ${RELAY_MPI_IO_TESTS})
+        add_cpp_mpi_test(TEST ${TEST}
+                         NUM_MPI_TASKS 2
+                         DEPENDS_ON conduit conduit_relay_mpi_io
+                         FOLDER tests/relay)
+    endforeach()
+
 else()
     message(STATUS "MPI disabled: Skipping conduit_relay_mpi tests")
 endif()

src/tests/relay/t_relay_io_hdf5.cpp

@@ -1400,6 +1400,32 @@ TEST(conduit_relay_io_hdf5, conduit_hdf5_save_generic_options)
 
 
 
+//-----------------------------------------------------------------------------
+TEST(conduit_relay_io_hdf5, conduit_hdf5_save_libver)
+{
+
+    Node n, opts;
+
+    n["data"] = 3.1415;
+
+    opts["libver"]  = "badvalue";
+
+    std::string tout = "tout_hdf5_save_libver_test.hdf5";
+
+    conduit::relay::io::hdf5_set_options(opts);
+
+    utils::remove_path_if_exists(tout);
+    // bad libver
+    EXPECT_THROW(io::save(n,tout, "hdf5"),Error);
+
+    // better libver
+    opts["libver"]  = "v108";
+    conduit::relay::io::hdf5_set_options(opts);
+    io::save(n,tout, "hdf5");
+
+    EXPECT_TRUE(utils::is_file(tout));
+}
+
 //-----------------------------------------------------------------------------
 TEST(conduit_relay_io_hdf5, conduit_hdf5_group_list_children)
 {

src/tests/relay/t_relay_io_mpi_smoke.cpp

@@ -0,0 +1,36 @@
+// Copyright (c) Lawrence Livermore National Security, LLC and other Conduit
+// Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+// other details. No copyright assignment is required to contribute to Conduit.
+
+//-----------------------------------------------------------------------------
+///
+/// file: t_relay_io_mpi_smoke.cpp
+///
+//-----------------------------------------------------------------------------
+
+#include "conduit_relay_mpi_io.hpp"
+#include <iostream>
+#include "gtest/gtest.h"
+
+using namespace conduit;
+using namespace conduit::relay;
+
+//-----------------------------------------------------------------------------
+TEST(conduit_mpi_smoke, about)
+{
+    std::cout << conduit::relay::mpi::io::about(MPI_COMM_WORLD) << std::endl;
+}
+
+//-----------------------------------------------------------------------------
+int main(int argc, char* argv[])
+{
+    int result = 0;
+
+    ::testing::InitGoogleTest(&argc, argv);
+    MPI_Init(&argc, &argv);
+    result = RUN_ALL_TESTS();
+    MPI_Finalize();
+
+    return result;
+}
+

src/tests/relay/t_relay_io_smoke.cpp

@@ -0,0 +1,20 @@
+// Copyright (c) Lawrence Livermore National Security, LLC and other Conduit
+// Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+// other details. No copyright assignment is required to contribute to Conduit.
+
+//-----------------------------------------------------------------------------
+///
+/// file: t_relay_io_smoke.cpp
+///
+//-----------------------------------------------------------------------------
+
+#include "conduit_relay.hpp"
+#include <iostream>
+#include "gtest/gtest.h"
+
+using namespace conduit;
+
+TEST(conduit_relay_io_smoke, about)
+{
+    std::cout << relay::io::about() << std::endl;
+}