From 7df7e08a1661cd0c423d34e4f7750d77ae4a7771 Mon Sep 17 00:00:00 2001
From: Matthew Mehrtens <12023414+mcmehrtens@users.noreply.github.com>
Date: Mon, 27 Apr 2026 16:22:31 -0500
Subject: [PATCH 1/2] Add HDF5 option to configure script and add environment
 variables for HDF5 options

---
 GNUmakefile.in                             |  3 +++
 Src/Extern/HDF5/AMReX_PlotFileUtilHDF5.cpp | 19 ++++++++++++++++---
 Tools/libamrex/configure.py                |  5 +++++
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/GNUmakefile.in b/GNUmakefile.in
index 67c789d97ca..1a234281535 100644
--- a/GNUmakefile.in
+++ b/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)
 
diff --git a/Src/Extern/HDF5/AMReX_PlotFileUtilHDF5.cpp b/Src/Extern/HDF5/AMReX_PlotFileUtilHDF5.cpp
index 4eb335d918d..5113791c004 100644
--- a/Src/Extern/HDF5/AMReX_PlotFileUtilHDF5.cpp
+++ b/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);
diff --git a/Tools/libamrex/configure.py b/Tools/libamrex/configure.py
index 873b575fe4f..3bf4c77f2d0 100755
--- a/Tools/libamrex/configure.py
+++ b/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")

From 07ab2ff02ce21478c96e20e4429b400a00c6b9f0 Mon Sep 17 00:00:00 2001
From: Matthew Mehrtens <12023414+mcmehrtens@users.noreply.github.com>
Date: Tue, 5 May 2026 12:29:13 -0500
Subject: [PATCH 2/2] Add documentation for new HDF5 environment variables

---
 Docs/sphinx_documentation/source/IO.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Docs/sphinx_documentation/source/IO.rst b/Docs/sphinx_documentation/source/IO.rst
index 8dc4b56a12a..5e8dc6e9a82 100644
--- a/Docs/sphinx_documentation/source/IO.rst
+++ b/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