Add HDF5 option to configure script and add environment variables for configuring HDF5 (#5392)

## Summary

- Resolves #5391
- Adds an `--hdf5` flag to the `configure` script to allow configuring
AMReX with HDF5 support
- Adds two new environment variables:
  - `HDF5_ALIGNMENT_SIZE` which is passed to `H5Pset_alignment()`
  - `HDF5_BLOCK_SIZE` which is passed to `H5Pset_meta_block_size()`

## Additional background

- The two new environment variables mirror how the [other HDF5
configuration
option](https://github.com/AMReX-Codes/amrex/blob/development/Src/Extern/HDF5/AMReX_PlotFileUtilHDF5.cpp#L460-L467)
is currently set.
- ~If we want to move forward with these changes, I will add appropriate
documentation before taking the PR out of draft.~

## Checklist

The proposed changes:
- [ ] ~fix a bug or incorrect behavior in AMReX~
- [x] add new capabilities to AMReX
- [ ] ~changes answers in the test suite to more than roundoff level~
- [ ] ~are likely to significantly affect the results of downstream
AMReX users~
- [x] include documentation in the code and/or rst files, if appropriate

Author: mcmehrtens

Docs/sphinx_documentation/source/IO.rst

@@ -234,6 +234,15 @@ Using compression requires data to be stored in a chunked format. The size of th
 chunks can (and generally should) be configured by changing the ``HDF5_CHUNK_SIZE``
 environment variable, with a default value of 1024 elements provided.
 
+For MPI-enabled builds, two additional file access properties can be tuned via
+environment variables. ``HDF5_ALIGNMENT_SIZE`` (in bytes, default 16 MiB) sets
+both the threshold and alignment passed to ``H5Pset_alignment``: object
+allocations of at least this size are aligned to a multiple of it, while
+smaller allocations are left unpadded. ``HDF5_BLOCK_SIZE`` (in bytes, default
+4 MiB) sets the minimum metadata block allocation size via
+``H5Pset_meta_block_size``, which aggregates small metadata writes to reduce
+I/O overhead on parallel file systems.
+
 HDF5 Asynchronous Output
 ------------------------
 The HDF5 output also comes with its own asynchronous I/O support, which is different

GNUmakefile.in

@@ -51,6 +51,9 @@ endif
 ifeq ($(USE_BITTREE),TRUE)
 	Pdirs += Extern/Bittree
 endif
+ifeq ($(USE_HDF5),TRUE)
+	Pdirs += Extern/HDF5
+endif
 Ppack := $(foreach dir, $(Pdirs), $(AMREX_HOME)/Src/$(dir)/Make.package)
 include $(Ppack)
 

Src/Extern/HDF5/AMReX_PlotFileUtilHDF5.cpp

@@ -117,10 +117,23 @@ static void SetHDF5fapl(hid_t fapl)
     H5Pset_fapl_mpio(fapl, comm, MPI_INFO_NULL);
 
     // Alignment and metadata block size
-    int alignment = 16 * 1024 * 1024;
-    int blocksize =  4 * 1024 * 1024;
+    const char *alignment_env = getenv("HDF5_ALIGNMENT_SIZE");
+    const char *block_env     = getenv("HDF5_BLOCK_SIZE");
+
+    hsize_t alignment = 16 * 1024 * 1024;  // 16 MiB
+    hsize_t block     = 4  * 1024 * 1024;  // 4 MiB
+
+    if (alignment_env != NULL) {
+        alignment = (hsize_t)strtoull(alignment_env, NULL, 10);
+    }
+    if (block_env != NULL) {
+        block = (hsize_t)strtoull(block_env, NULL, 10);
+    }
+
+    // Threshold = alignment value: only allocations >= alignment bytes
+    // get aligned. Avoids padding small allocations up to 16 MiB.
     H5Pset_alignment(fapl, alignment, alignment);
-    H5Pset_meta_block_size(fapl, blocksize);
+    H5Pset_meta_block_size(fapl, block);
 
     // Collective metadata ops
     H5Pset_coll_metadata_write(fapl, true);

Tools/libamrex/configure.py

@@ -132,6 +132,10 @@ def configure(argv):
                         help="Enable Bittree mode [default=no]",
                         choices=["yes","no"],
                         default="no")
+    parser.add_argument("--enable-hdf5",
+                        help="Enable HDF5 output mode [default=no]",
+                        choices=["yes","no"],
+                        default="no")
     args = parser.parse_args()
 
     if args.with_fortran == "no":
@@ -174,6 +178,7 @@ def configure(argv):
     f.write("CUDA_ARCH = " + args.cuda_arch.strip() + "\n")
     f.write("AMREX_NO_PROBINIT = {}\n".format("TRUE" if args.enable_probinit == "no" else "FALSE"))
     f.write("USE_BITTREE = {}\n".format("TRUE" if args.enable_bittree == "yes" else "FALSE"))
+    f.write("USE_HDF5 = {}\n".format("TRUE" if args.enable_hdf5 == "yes" else "FALSE"))
     f.write("\n")
 
     fin = open("GNUmakefile.in","r")