Reduce memory footprints for 1D compression, improve domain decomposition, and add data compatibility mode

CMakeLists.txt

@@ -47,6 +47,8 @@ option(MGARD_ENABLE_UNSTRUCTURED "Enable experimental unstructured mesh support.
 
 option(MGARD_ENABLE_TIMING "Enable timing." OFF)
 
+option(MGARD_ENABLE_DATA_COMPATIBILITY "Also build the separate MGARD 1.6.0-compatible decompression pipeline (src/mgard-x-160) so data compressed by MGARD 1.6.x can be decompressed. Roughly doubles MGARD-X build time." OFF)
+
 include(CTest)
 
 # Some boilerplate to setup nice output directories
@@ -106,6 +108,9 @@ if (MGARD_ENABLE_SERIAL OR
 
   include(MgardXGenerateSource)
   add_subdirectory (src/mgard-x)
+  if (MGARD_ENABLE_DATA_COMPATIBILITY)
+    add_subdirectory (src/mgard-x-160)
+  endif()
   add_subdirectory (include/mgard-x)
   add_subdirectory (include/mgard-x/MDR)
   add_subdirectory (include/mgard-x/MDR-X)
@@ -133,6 +138,7 @@ if (MGARD_ENABLE_SERIAL OR
                                                       $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
   install(TARGETS mgard-cpu)
 
+  set(MGARD_X_BUILD_PMDR OFF)
   if(MGARD_ENABLE_MDR)
     add_executable(mdr-x ${CMAKE_CURRENT_SOURCE_DIR}/src/mgard-x/Executables/mdr-x.cpp)
     target_link_libraries(mdr-x mgard-library  ${CMAKE_DL_LIBS})
@@ -144,23 +150,34 @@ if (MGARD_ENABLE_SERIAL OR
     target_include_directories(mdr-x-qoi PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
                                               $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
     install(TARGETS mdr-x-qoi)
-    find_package(MPI REQUIRED)
-    add_executable(pmdr-x-qoi ${CMAKE_CURRENT_SOURCE_DIR}/src/mgard-x/Executables/pmdr-x-qoi.cpp)
-    target_link_libraries(pmdr-x-qoi mgard-library MPI::MPI_CXX ${CMAKE_DL_LIBS})
-    target_include_directories(pmdr-x-qoi PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
-                                              $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
-    install(TARGETS pmdr-x-qoi)
-    add_executable(pmdr-x-qoi-io ${CMAKE_CURRENT_SOURCE_DIR}/src/mgard-x/Executables/pmdr-x-qoi-io.cpp)
-    target_link_libraries(pmdr-x-qoi-io mgard-library MPI::MPI_CXX ${CMAKE_DL_LIBS})
-    target_include_directories(pmdr-x-qoi-io PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
-                                              $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
-    install(TARGETS pmdr-x-qoi-io)
+    # MPI is only needed by the parallel pmdr-x executables; the rest of MDR-X
+    # (library, mdr-x, mdr-x-qoi) builds without it.
+    find_package(MPI COMPONENTS CXX)
+    if(MPI_CXX_FOUND)
+      set(MGARD_X_BUILD_PMDR ON)
+      add_executable(pmdr-x-qoi ${CMAKE_CURRENT_SOURCE_DIR}/src/mgard-x/Executables/pmdr-x-qoi.cpp)
+      target_link_libraries(pmdr-x-qoi mgard-library MPI::MPI_CXX ${CMAKE_DL_LIBS})
+      target_include_directories(pmdr-x-qoi PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+                                                $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
+      install(TARGETS pmdr-x-qoi)
+      add_executable(pmdr-x-qoi-io ${CMAKE_CURRENT_SOURCE_DIR}/src/mgard-x/Executables/pmdr-x-qoi-io.cpp)
+      target_link_libraries(pmdr-x-qoi-io mgard-library MPI::MPI_CXX ${CMAKE_DL_LIBS})
+      target_include_directories(pmdr-x-qoi-io PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+                                                $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
+      install(TARGETS pmdr-x-qoi-io)
+    else()
+      message(STATUS "MPI not found: skipping pmdr-x-qoi and pmdr-x-qoi-io.")
+    endif()
   endif()
 endif()
 
 #Adding library here so we can set compile definitions for it.
 add_library(mgard-library)
 
+if(MGARD_ENABLE_DATA_COMPATIBILITY)
+  target_compile_definitions(mgard-library PUBLIC MGARD_ENABLE_DATA_COMPATIBILITY)
+endif()
+
 if(MGARD_ENABLE_SERIAL)
   target_compile_definitions(mgard-library PUBLIC MGARD_ENABLE_SERIAL)
   set_source_files_properties(${MGARD_X_SERIAL_SRC} PROPERTIES LANGUAGE CXX)
@@ -486,6 +503,12 @@ message(STATUS "SYCL:        ${MGARD_ENABLE_SYCL}")
 list(POP_BACK CMAKE_MESSAGE_INDENT)
 message(STATUS "auto tuning:   ${MGARD_ENABLE_AUTO_TUNING}")
 message(STATUS "MDR:           ${MGARD_ENABLE_MDR}")
+if(MGARD_ENABLE_MDR)
+  list(APPEND CMAKE_MESSAGE_INDENT "  ")
+  message(STATUS "pmdr-x (MPI): ${MGARD_X_BUILD_PMDR}")
+  list(POP_BACK CMAKE_MESSAGE_INDENT)
+endif()
+message(STATUS "1.6.0 data:    ${MGARD_ENABLE_DATA_COMPATIBILITY}")
 message(STATUS "timing:        ${MGARD_ENABLE_TIMING}")
 message(STATUS "ASan:          ${MGARD_ENABLE_ASAN}")
 message(STATUS "UBSan:         ${MGARD_ENABLE_UBSAN}")

doc/MGARD-format.md

@@ -75,11 +75,20 @@ message DomainDecomposition {
     NOOP_METHOD = 0;
     MAX_DIMENSION = 1;
     BLOCK = 2;
+    VARIABLE = 3;
   }
 
   Method method = 1;
+  // MAX_DIMENSION (MGARD-X 1.6 and earlier): slabs of decomposition_size
+  // nodes along dimension decomposition_dimension.
   uint64 decomposition_dimension = 2;
+  // BLOCK without block_shape (MGARD-X 1.6 and earlier): cubic blocks of
+  // decomposition_size nodes per dimension.
   uint64 decomposition_size = 3;
+  // BLOCK: the shape of every block, one extent per dimension. Along each
+  // dimension block i starts at i * block_shape[d]; a remainder of fewer than
+  // 3 nodes is merged into the block before it.
+  repeated uint64 block_shape = 4;
 }
 
 message FunctionDecomposition {

doc/release notes/1.7.0.md

@@ -9,6 +9,10 @@
 * A BlockDelta (FLE-based) lossless backend for mgard-x, as a Huffman alternative.
 * A portable, warp-cooperative LZ4 implementation for mgard-x, removing the nvcomp dependency.
 * Blackwell (sm_120) GPU build support.
+* Decompression of data compressed by MGARD 1.6.x and earlier, through a separate MGARD 1.6.0-compatible decompression pipeline enabled with the new CMake option `MGARD_ENABLE_DATA_COMPATIBILITY` (default OFF). Decompression detects the version from the header and routes 1.6.x data automatically; output matches MGARD 1.6.0 (bit-identical on CPUs). Builds without the option report such data with the new status `DataCompatibilityNotEnabledFailure`.
+* Generic block domain decomposition with two modes (`Config::domain_decomposition_mode`): `Auto` (default) decomposes only when the data does not fit the memory limit and picks the block size, and `Manual` uses a user-given block shape (`Config::domain_decomposition_block_size`), which may differ per dimension. Available in the `mgard-x` and `mdr-x` CLIs as `-dd auto|manual` and `-dd-size`.
+* `MemoryManager::Copy3D` in RuntimeX (native 3D copies on CUDA and HIP), used for copying blocks between host and device in fewer transfers.
+* Opt-in ZSTD compression of MDR-X bitplane groups (`lossless = Huffman_Zstd`; `mdr-x -l huffman-zstd`).
 * Additional unit tests: bitplane encoders, DirectInterleaver, MGARDDecomposer, HybridLevelCompressor, and ComposedRefactor/Reconstructor; unit tests are now discoverable by CTest.
 
 ## Changed
@@ -18,6 +22,12 @@
 * Optimized the Huffman compress/decompress pipeline (roughly 1.9x faster compression).
 * Bumped the bundled ZSTD to v1.5.6 and protobuf to v3.21.12; stopped building nvcomp.
 * Raised the minimum ROCm requirement to 7.0 for HIP builds.
+* ***Breaking (API):*** replaced the MaxDim/Block/Variable domain decomposition types with the generic block decomposition. `Config::domain_decomposition`, `block_size`, `domain_decomposition_dim` and `domain_decomposition_sizes` are removed in favor of `domain_decomposition_mode` and `domain_decomposition_block_size`; variable-size decomposition is no longer supported. The CLIs' `-dd max-dim|block` became `-dd auto|manual`. Compressed data with the previous MaxDim and Block decomposition headers still decompresses.
+* ***Breaking (API):*** merged `max_larget_level` into `num_global_refactoring_level`, which now caps the levels of every multilevel hierarchy (multi-dimensional, MDR-X, and the hybrid global stage) and is recorded in the compressed header. Defaults are `num_local_refactoring_level = 1` and `num_global_refactoring_level = 3` (previously all levels for multi-dimensional compression). This changes the default compression ratio (e.g. relative 1e-3, L-infinity: 1D 2.89 -> 3.44, 3D 2.57 -> 2.85; L2 in 1D: 4.08 -> 3.65); error bounds are unchanged.
+* Renamed `MemoryManager::CopyND` to `Copy2D` in RuntimeX.
+* Reduced mgard-x memory usage: hierarchy level volumes are stored per level instead of in a dense array, hierarchies are moved rather than copied into the compressor and refactor caches, and the hybrid hierarchy builds only the global hierarchy it needs (new `HybridHierarchy`). Peak device memory for a 2^24-element 1D float input drops from 7.7 GB to 1.8 GB (multi-dimensional) and 2.1 GB (hybrid).
+* MPI is now optional for `MGARD_ENABLE_MDR`; only the `pmdr-x-qoi` and `pmdr-x-qoi-io` executables require it.
+* The MDR-X QoI executables always use one subdomain per variable and no longer take `-dd`.
 * Updated documentation: the MGARD-X guide for the hybrid hierarchy pipeline, a hybrid RoI user guide, the MGARD family tree, performance figures, and the publications list.
 
 ## Fixed
@@ -30,3 +40,14 @@
 * Fixed a floating-point exception in Zstd::Decompress.
 * Fixed CPUPipelines so OpenMP-only builds compile again.
 * Fixed clang-format violations flagged by CI.
+* Fixed decompression of domain-decomposed data in which a subdomain stored uncompressed has a size that is not a multiple of 8 bytes: the following subdomains were read at the wrong offset.
+* Fixed an MDR-X sign-buffer overflow in bitplane decoding during reconstruction (heap corruption on CPUs, out-of-bounds writes on GPUs) when a later subdomain needed a larger buffer.
+* Fixed MDR-X reconstruction writing back the last subdomain from the wrong buffer when the number of subdomains is a multiple of 3.
+* Fixed MDR-X refactoring/reconstruction sizing reused buffers from the first subdomain instead of the largest.
+* Fixed MaxDim domain decomposition along a dimension other than the slowest, which copied past the end of the data.
+* Fixed Zstd decompression truncating the stored size to 32 bits and ignoring decompression errors.
+* Fixed the compression output buffer overflowing for non-uniform grids, whose coordinates are stored in the header.
+* Fixed the `mgard-x` CLI ignoring decompression failures.
+* Fixed MDR-X requests fetching a full bitplane group for levels that need none, and stale bitplane counts when a reconstructor is reused.
+* Fixed the Huffman compression-ratio estimate pairing frequencies with the wrong code lengths, which made MDR-X store compressible bitplane groups uncompressed.
+* Fixed CPU (MGARD) Huffman truncation of wide outliers.

examples/mgard-x/MDR-X/CUDA/refactor.cu

@@ -166,7 +166,7 @@ int main(int argc, char **argv) {
 
   mgard_x::log::level |= mgard_x::log::INFO;
   mgard_x::Config config;
-  config.max_larget_level = target_level;
+  config.num_global_refactoring_level = target_level;
   mgard_x::Hierarchy<D, T, DeviceType> hierarchy(dims, config);
 
   test<D, T, DeviceType>(filename, num_bitplanes, hierarchy, metadata_file,

examples/mgard-x/MDR-X/HIP/refactor.cpp

@@ -153,7 +153,7 @@ int main(int argc, char **argv) {
 
   mgard_x::log::level |= mgard_x::log::INFO;
   mgard_x::Config config;
-  config.max_larget_level = target_level;
+  config.num_global_refactoring_level = target_level;
   mgard_x::Hierarchy<D, T, DeviceType> hierarchy(dims, config);
 
   test<D, T, DeviceType>(filename, num_bitplanes, hierarchy, metadata_file,

examples/mgard-x/MDR-X/SERIAL/refactor.cpp

@@ -153,7 +153,7 @@ int main(int argc, char **argv) {
 
   mgard_x::log::level |= mgard_x::log::INFO;
   mgard_x::Config config;
-  config.max_larget_level = target_level;
+  config.num_global_refactoring_level = target_level;
   mgard_x::Hierarchy<D, T, DeviceType> hierarchy(dims, config);
 
   test<D, T, DeviceType>(filename, num_bitplanes, hierarchy, metadata_file,