hdf5-rust

HDF5 for Rust。

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

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

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

需要版本 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 包已知在以下平台上运行：Linux、macOS、Windows（在 Ubuntu 16.04、18.04 和 20.04 上测试；Windows Server 2019，具有 MSVC 和 GNU 工具链；macOS Catalina）。

Rust

hdf5 包在所有三个官方发布渠道上持续进行测试，并需要一个相当新的 Rust 编译器（例如版本 1.51 或更高版本）。

HDF5

所需 HDF5 版本为 1.8.4 或更高。库不必使用线程安全选项构建，就可以使用用户代码实现线程安全性。

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

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

构建

HDF5 版本

为 hdf5-sys 和 hdf5 包提供的构建脚本会检查它们链接的 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 后可以找到 HDF5。

macOS

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

Windows

hdf5 包完全支持 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 目标的平台是 MinGW-GCC 的 TDM 分发版，因为它包含适用于 32 位和 64 位的 bintools。
• 推荐用于 msvc 目标的设置是 VS2015 x64，因为它与 CI 构建配置相匹配，然而 VS2013 和 x86 也应该同样有效。

许可证

hdf5 库主要在 MIT 许可证和 Apache 许可证（版本 2.0）的条款下分发。请参阅LICENSE-APACHE 和 LICENSE-MIT 以获取详细信息。