cuPyNumeric HDF5 并行读写

要解决什么问题

在 HPC 或 GPU 后处理流水线里，cuPyNumeric 数组往往要落盘成 单文件 .h5 / .hdf5，或从已有 HDF5 数据集恢复。常见坑是：用单进程 h5py 把整块数组经主机内存搬一遍——既慢，也容易在大规模分布式 rank 上踩内存上限。本技能聚焦 Legate 集体 I/O：每个 rank 只读写自己负责的瓦片，文件侧通过 HDF5 虚拟数据集（VDS） 呈现为一个逻辑数组。

技能如何工作

核心 API 来自 legate.io.hdf5，常用三个函数：

• to_file(array, path, dataset_name)：把 cuPyNumeric ndarray / LogicalArray 写入 HDF5；可直接传 ndarray（实现 __legate_data_interface__），不必先 np.array(...) 来回转。
• from_file(path, dataset_name)：读入分布式 LogicalArray；用 cn.asarray(la) 零拷贝桥接成 cuPyNumeric ndarray。
• from_file_batched(path, dataset_name, chunk_size)：按块读文件（分块的是文件读取，不是最终数组形状）；每块带全局偏移，边界块会被裁剪，需按实际块形状拼接。

dataset_name 必须是数据集在文件内的完整路径（如 /data、/group/x），不要传组名。Legate I/O 是异步的：to_file 只是排队写入；在 h5py、子进程或其它工具打开文件前，应调用 get_legate_runtime().issue_execution_fence(block=True)。同一 Legate 程序内后续的 from_file 通常可省略栅障。SPMD 下每个 rank 使用相同的 path，不要用按 rank 的临时文件名。

GPU 上把 HDF5 直接读到 GPU 内存时，应设置 LEGATE_IO_USE_VFD_GDS=1（基于 nv-legate/vfd-gds，非 KvikIO）：默认 POSIX VFD 的 ZCMEM 分段缓冲约 128 MB，更大 GPU 读取可能中止；GDS VFD 可规避该限制，无 GPUDirect 存储时 cuFile 也可兼容回退。仅读到 CPU 主机内存时可不设置。

适用边界与注意点

• 仅单文件 HDF5；Parquet/Arrow/cuDF、自定义分片布局、Zarr/S3 分块输出、.npz/pickle 等应走其它路径（如 parallel-data-load 或 h5py 纯读取）。
• 导入 legate.io.hdf5 前需已安装 h5py（模块加载时会 import h5py）。
• to_file 会覆盖已存在的 path，且 path 必须是文件路径不能是目录；数组需有界形状（未指定 shape 的原始 LogicalArray 会报 ValueError）。
• 在 cuPyNumeric 源码树内运行可能遮蔽已安装包；建议在树外目录执行。
• API 路径为 legate.io.hdf5（Legate 26.01+），勿再用旧版 legate.core.io.hdf5。