hdf5-rust

HDF5 的 Rust 实现。

hdf5 crate（之前称为 hdf5-rs）提供了对 HDF5 库 API 的线程安全 Rust 绑定和高层级封装。一些特性包括

• 通过重入互斥锁确保非线程安全的 libhdf5 构建具有线程安全性。
• 对大多数 HDF5 类型的本地表示，包括变长字符串和数组。
• 使用 derive-macro 自动将用户结构体和枚举映射到 HDF5 类型。
• 通过 ndarray 提供多维数组的读取/写入接口。

还提供了直接的低级别绑定，并在 hdf5-sys crate 中提供。

需要版本 1.8.4 或更高版本的 HDF5 库。

示例

#[cfg(feature = "blosc")]
use hdf5::filters::blosc_set_nthreads;
use hdf5::{File, H5Type, Result};
use ndarray::{arr2, s};

#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
#[repr(u8)]
pub enum Color {
    R = 1,
    G = 2,
    B = 3,
}

#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
#[repr(C)]
pub struct Pixel {
    xy: (i64, i64),
    color: Color,
}

impl Pixel {
    pub fn new(x: i64, y: i64, color: Color) -> Self {
        Self { xy: (x, y), color }
    }
}

fn write_hdf5() -> Result<()> {
    use Color::*;
    let file = File::create("pixels.h5")?; // open for writing
    let group = file.create_group("dir")?; // create a group
    #[cfg(feature = "blosc")]
    blosc_set_nthreads(2); // set number of blosc threads
    let builder = group.new_dataset_builder();
    #[cfg(feature = "blosc")]
    let builder = builder.blosc_zstd(9, true); // zstd + shuffle
    let ds = builder
        .with_data(&arr2(&[
            // write a 2-D array of data
            [Pixel::new(1, 2, R), Pixel::new(2, 3, B)],
            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],
            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],
        ]))
        // finalize and write the dataset
        .create("pixels")?;
    // create an attr with fixed shape but don't write the data
    let attr = ds.new_attr::<Color>().shape([3]).create("colors")?;
    // write the attr data
    attr.write(&[R, G, B])?;
    Ok(())
}

fn read_hdf5() -> Result<()> {
    use Color::*;
    let file = File::open("pixels.h5")?; // open for reading
    let ds = file.dataset("dir/pixels")?; // open the dataset
    assert_eq!(
        // read a slice of the 2-D dataset and verify it
        ds.read_slice::<Pixel, _, _>(s![1.., ..])?,
        arr2(&[
            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],
            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],
        ])
    );
    let attr = ds.attr("colors")?; // open the attribute
    assert_eq!(attr.read_1d::<Color>()?.as_slice().unwrap(), &[R, G, B]);
    Ok(())
}

fn main() -> Result<()> {
    write_hdf5()?;
    read_hdf5()?;
    Ok(())
}

兼容性

平台

hdf5 crate 已在以下平台上进行测试：Linux、macOS、Windows（在 Ubuntu 16.04、18.04 和 20.04 上进行测试；Windows Server 2019，使用 MSVC 和 GNU 工具链；macOS Catalina）。

Rust

hdf5 crate 对所有三个官方发布渠道进行了持续测试，并需要一个合理近期的 Rust 编译器（例如，版本 1.51 或更高版本）。

HDF5

所需的 HDF5 版本为 1.8.4 或更高版本。用户代码无需在构建库时启用线程安全选项即可实现线程安全。

支持并测试了各种 HDF5 安装选项：通过包管理器如 homebrew 和 apt；Windows 上的全局安装；来自官方渠道和 conda-forge 的 conda 安装。在 Linux 和 macOS 上，支持并测试了 OpenMPI 和 MPICH 并行构建。

还可以通过启用 hdf5-sys/static 功能从源代码构建 HDF5 C 库并将其静态链接（需要 CMake）。

构建

HDF5 版本

hdf5-sys 和 hdf5 crate 的构建脚本都会检查它们链接的 HDF5 库的实际版本，并且某些功能可能会在编译时条件性地启用或禁用。虽然这允许在单个代码库中支持多个 HDF5 版本，但库用户在选择使用低级 FFI 绑定时应该注意这一点。

环境变量

如果设置了 HDF5_DIR，构建脚本将会在该路径（以及其他任何地方）查找 HDF5 的头文件和二进制文件（即，它将在 $HDF5_DIR/include 下查找头文件）。

如果设置了 HDF5_VERSION，构建脚本将检查库版本是否与指定的版本字符串匹配；在某些情况下，它也可能被构建脚本用来帮助定位库（例如，在 macOS 上通过 Homebrew 安装了 1.8 和 1.10）。

conda

可以链接到 hdf5 conda 包；一些注意事项和建议

• 将 HDF5_DIR 指向 conda 环境根目录。
• 构建脚本了解 conda 环境布局的细节，并将相应地调整路径（例如，Windows 环境中的 Library 子文件夹）。
• 在 Windows 上，环境的 bin 文件夹必须在 PATH 中（或者在运行 cargo 之前激活环境）。
• 在 Linux / macOS 上，建议设置 rpath，例如通过设置 RUSTFLAGS="-C link-args=-Wl,-rpath,$HDF5_DIR/lib"。
• 对于 macOS 上 HDF5 conda 包的老版本，可能还需要设置 DYLD_FALLBACK_LIBRARY_PATH="$HDF5_DIR/lib"。

Linux

构建脚本将首先尝试使用 pkg-config，这可能在 HDF5 的较新版本上无需进一步调整即可成功。然后构建脚本还将查找一些标准位置，这些位置是在 Ubuntu 上通过 apt 安装 HDF5 后可能找到的地方。

macOS

在 macOS 上，如果 Homebrew 可用，构建脚本将尝试通过 Homebrew 定位 HDF5。如果安装了 1.8 和 1.10 并可用，除非设置了 HDF5_VERSION，否则将使用默认的（1.10）版本。

Windows

hdf5 crate 完全支持 MSVC 工具链，允许使用 HDF5 的官方发布版，通常也是推荐的方式。尽管如此，之前的实验表明，在 gnu 目标上所有测试也通过，只需小心构建 HDF5 二进制文件本身并配置构建环境即可。

在 Windows 上构建时需要注意的一些事项

• hdf5.dll 应在构建时间和运行时（包括 gnu 和 msvc）的搜索路径中可用。这通常需要将 HDF5 安装目录的 bin 文件夹添加到 PATH。如果使用官方 HDF5 发布版（仅限 msvc），这通常会被安装程序自动完成。
• msvc：安装的 Visual Studio 版本应与 HDF5 二进制文件（2013 或 2015）匹配。请注意，不需要运行 vcvars 脚本；Rust 构建系统将处理此事。
• 在为任何目标构建时，请确保搜索路径中没有任何冲突（例如，MinGW 工具链的一些二进制文件可能覆盖 MSVS 可执行文件或反之亦然）。
• 对于 gnu 目标，建议的平台是TDM 分发版的 MinGW-GCC，因为它包含 32 位和 64 位的 bintools。
• 推荐配置msvc目标为VS2015 x64，因为这与CI构建配置相匹配，但是VS2013和x86也应该同样适用。

许可证

hdf5软件包主要根据MIT许可证和Apache许可证（版本2.0）的条款进行分发。请参阅LICENSE-APACHE和LICENSE-MIT以获取详细信息。