k-Wave File OverviewΒΆ

The C++ code has been designed as a standalone application supporting both 2D, 3D and axisymmetric simulations which are not dependent on MATLAB libraries or a MEX interface. This is of particular importance when using servers and supercomputers without MATLAB support. For this reason, simulation data must be transferred between the C++ code and MATLAB using external input and output files. These files are stored using the Hierarchical Data Format HDF5. This is a data model, library, and file format for storing and managing data. It supports a variety of datatypes, and is designed for flexible and efficient I/O and for high volume and complex data. The HDF5 technology suite includes tools and applications for managing, manipulating, viewing, and analysing data in the HDF5 format.

Each HDF5 file is a container for storing a variety of scientific data and is composed of two primary types of objects: groups and datasets. An HDF5 group is a structure containing zero or more HDF5 objects, together with supporting metadata. An HDF5 group can be seen as a disk folder. An HDF5 dataset is a multidimensional array of data elements, together with supporting metadata. An HDF5 dataset can be seen as a disk file. Any HDF5 group or dataset may also have an associated attribute list. An HDF5 attribute is a user-defined HDF5 structure that provides extra information about an HDF5 object. More information can be obtained from the HDF5 documentation.

kspaceFirstOrder-OMP v1.3 uses a new file format of version 1.2, which adds support for an axisymmetric coordinate system and removes the definition of derivative and shift operators, as well as the PML. These variables are instead generated in the preprocessing phase and make the file structure simpler. The code is happy to work with all previous file versions (1.0 and 1.1), however, some features will not be supported. Namely, the cuboid sensor mask, and u_non_staggered_raw are not supported in version 1.0, and axisymmetric simulations are not supported in version 1.1. When running from the C++ code using the MATLAB k-Wave Toolbox v1.3, the files will always be written in file format version 1.2. The output file is always written in version 1.2.

All datasets in the HDF5 files are stored as multi-dimensional datasets in row-major order. When working from within Matlab, the data is automatically rotated from column-major to row-major. For the sake of simplicity, we will present the dataset dimensions in a more natural column-major order (Nx, Ny, Nz), ignoring that the data is physically stored as (Nz, Ny, Nx).