HogeFugaHogera

IT系の備忘録とか、他徒然なるままに

3. HDF5ファイルの作成

HDF5 C言語 翻訳 IT
3.1. HDF5ファイルって何？

HDF5ファイルとは科学データと補助メタデータから成るバイナリファイルです。
HDF5ファイルを作るには、プリケーションはファイル名だけではなく、ファイルアクセスモード、ファイル作成プロパティリストとファイルアクセスプロパティリストを指定する必要が有ります。これら用語を以下に示します。

ファイルアクセスモード (File access mode):
ファイル作成時、既にファイルが存在した場合の動きを決めます。

  • H5F_ACC_TRUNC はファイルが既に存在する場合、アプリケーションが新しいデータをファイルに上書きするため現在の内容は削除される事を示す。
  • H5F_ACC_EXCL はファイルが存在する場合にはopenが失敗する。ファイルが存在しなければ、ファイルアクセスパラメータは無視される。

いずれの場合でも、アプリケーションは作成が成功したファイルに対して読み書きができます。

存在するファイルを開く場合には２つの異なるアクセスモードがあることに注意してください:

  • H5F_ACC_RDONLYはアプリケーションが読み込みアクセスすることを示すが、データの書き込みは許可しない。
  • H5F_ACC_RDWRはアプリケーションが読み書きアクセスすることを示す。

ファイル作成プロパティリスト (File creation property list):
ファイル作成プロパティリストはファイルメタデータの制御に使われます。ファイルメタデータにはユーザーブロック*1のサイズについての情報で成り立ち、様々なファイルのデータ構造のサイズがHDF5ライブラリ等により使われます。このチュートリアルでは、デフォルトのファイル作成プロパティリストであるH5P_DEFAULTが使われます。

ファイルアクセスプロパティリスト (File access property list):
ファイルアクセスプロパティリストはファイルにおいてI/O操作の異なるメソッドの制御に使われます。加えてファイルの閉じられ方の制御にも使う事ができます (あるファイルによる全てのオブジェクトが閉じられるまで、実ファイルのクローズを遅らせるかどうか)。デフォルトのファイルアクセスプロパティリストであるH5P_DEFAULTがこのチュートリアルでは使われます。

ファイルアクセス、作成のプロパティリストとアクセスモードの詳細については H5F section of the HDF5 Users' Guide and Reference Manualを参照してください。

HDF5ファイルの作成と閉じるの手順は以下となります。

  1. ファイル作成とプロパティリストとアアクセスプロパティリストを（必要なら）指定する。
  2. ファイルを作成する。
  3. ファイルと、必要ならプロパティリストも閉じる。
3.2. サンプルプログラム

内容
以下はHDF5ファイルの作成と閉じ方のサンプル*2です。

C:

#include "hdf5.h"
#define FILE "file.h5"

int main(void) {
    hid_t file_id; // ファイル識別子
    herr_t status;

    // デフォルトプロパティでファイルを作成する。
    file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);

    // ファイルへのアクセスを終わらせる。
    status = H5Fclose(file_id);

    return 0;
}

注記
hdf5.hというヘッダファイルは定義と宣言を含んでいるので、HDF5ライブラリを使うあらゆるプログラムはインクルードする必要があります。

H5Fcreate: HDF5ファイルを作り、ファイル識別子を返します。ファイル作成時に自動的にrootグループが作られます。全てのファイルにはrootグループがあり、rootグループのパス名は必ず/となります。

H5Fclose: HDF5ファイルへのアクセスと終わらせます。HDF5にもうプログラムからアクセスしないならば、ファイルを使用によるリソースを解放するためにH5Fcloseを呼ぶべきです。 この呼び出しは必ず行う必要が有ります。

あるファイルに対してH5Fcloseが呼ばれた際に、そのファイルに含まれる1つ以上のオブジェクトがまだ開かれている場合、オブジェクトが個別に閉じられるまで、それらオブジェクトにアクセス可能なままとなります。もしオブジェクトが不注意にも開かれたままだと、これは他のユーザに対するアクセス問題の原因となります。ファイルアクセスプロパティはそのファイルの閉じられ方を制御します。

ファイルの中身
HDF GroupeはHDF5ファイルの中身を調べるためのツールを開発しました。HDF5チュートリアルを通して使われるそのツールはHDF5のダンパーであり、h5dumpと言い、人に読みやすい形に変換してファイルの内容を表示します。h5dumpの出力はHDF5 DDL文法に則る形でのASCII表示です。この文法はHDF5に対してBNF(バッカス・ナウア記法)によるDDL（Data Definition Language, データ定義言語）で定義されています。

HDF5の内容を見るためには以下のように打ち込みます。

$ h5dump <filename>

図4.1はfile.h5の中身を有向グラフで表しています。

f:id:einstee:20160501003759p:plain
図4.1 file.h5の中身

図4.2はfile.h5をテキストで表したものです(h5dumpで作成)。file.h5とよばれるHDF5ファイルは/やルートグループと呼ばれるグループで成り立ちます。

HDF5 "./file.h5" {
GROUP "/" {
}
}

図4.2 DDLでのfile.h5

DDLによるファイル定義
図4.3はHDF5ファイルを作成するための簡略化DDLファイル定義です。簡単のため、簡略化DDLがこのチュートリアル上では使われます。完璧かつ厳密なDDLはHDFに対応するBNFによるDDL、HDF5 User's Guideの項目から見つけることができます。

以下の記号定義がDDLとして使われる。

  • ::=: 定義する
  • <tname>: tnameという名前を持ったトークン
  • <a> | <b>: <a>か<b>のどちらか
  • <a>*: <a>の0以上の出現

ファイル定義の簡略化DDLは以下のようになる:

  • <file> ::= HDF5 "<file_name>" { <root_group> }
  • <root_group> ::= GROUP "/" { <group_attribute>* <group_member>* }
  • <group_attribute> ::= <attribute>
  • <group_member> ::~ <group> | <dataset>

図4.3 HDF5ファイル定義

*1:ユーザブロックはHDF5ライブラリで無視される、ファイルのはじめの箇所にある固定長ブロックのデータです。ユーザブロックはアプリケーションにとって有益となるデータや情報をを保存するために使用できます。

*2:原文ではCとFORTRAN両方のサンプルがありますが、訳者の都合によりCのみとなります。