| kspaceFirstOrder3D-OMP 1.0 The C++ implementation of the k-wave toolbox for the time-domain simulation of acoustic wave fields in 3D

- Main Page
- Classes
- Files

- File List
- File Members

Classes
HDF5/HDF5_File.h File Reference

The header file containing the HDF5 related classes. More...

`#include <hdf5.h>`
`#include <hdf5_hl.h>`
`#include <string>`
`#include <map>`
`#include <Utils/DimensionSizes.h>`
Include dependency graph for HDF5_File.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Classes
class | THDF5_File
| Class wrapping the HDF5 routines. More...
class | THDF5_FileHeader
| Class for HDF5 header. More...

## Detailed Description

Author:
  Jiri Jaros
  CECS, ANU, Australia
  jiri.jaros@anu.edu.au

Version:
  kspaceFirstOrder3D 2.13

Date:
  27 July 2012, 14:14 (created)
  17 September 2012, 15:35 (revised)

## HDF5 File Structure

The C++ code has been designed as a standalone application which is 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 (http://www.hdfgroup.org/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. A HDF5 group is a structure containing zero or more HDF5 objects, together with supporting metadata. A HDF5 group can be seen as a disk folder. A HDF5 dataset is a multidimensional array of data elements, together with supporting metadata. A HDF5 dataset can be seen as a disk file. Any HDF5 group or dataset may also have an associated attribute list. A HDF5 attribute is a user-defined HDF5 structure that provides extra information about a HDF5 object. More information can be obtained from the HDF5 documentation (http://www.hdfgroup.org/HDF5/doc/index.html).

The HDF5 input file for the C++ simulation code contains a file header with brief description of the simulation stored in string attributes, and the root group `/' which stores all the simulation properties in the form of 3D datasets (a complete list of input datasets is given in Appendix B). The HDF5 output file contains a file header with the simulation description as well as performance statistics, such as the simulation time and memory consumption, stored in string attributes. The results of the simulation are stored in the root group `/' in the form of 3D datasets.

    ==============================================================================================================
                                            Input File Header
    =============================================================================================================
    created_by                              Short description of the tool that created this file
    creation_date                           Date when the file was created
    file_description                        Short description of the content of the file (e.g. simulation name)
    file_type                               Type of the file (input)
    major_version                           Major version of the file definition (1)
    minor_version                           Minor version of the file definition (0)
    ==============================================================================================================

    ==============================================================================================================
                                            Output File Header
    ==============================================================================================================
    created_by                              Short description of the tool that created this file
    creation_date                           Date when the file was created
    file_description                        Short description of the content of the file (e.g. simulation name)
    file_type                               Type of the file (output)
    major_version                           Major version of the file definition (1)
    minor_version                           Minor version of the file definition (0)
    -------------------------------------------------------------------------------------------------------------
    host_names                              List of hosts (computer names) the simulation was executed on
    number_of_cpu_cores                     Number of CPU cores used for the simulation
    data_loading_phase_execution_time       Time taken to load data from the file
    pre-processing_phase_execution_time     Time taken to pre-process data
    simulation_phase_execution_time         Time taken to run the simulation
    post-processing_phase_execution_time    Time taken to complete the post-processing phase
    total_execution_time                    Total execution time
    peak_core_memory_in_use                 Peak memory required per core during the simulation
    total_memory_in_use Total               Peak memory in use
    ==============================================================================================================

All input and output parameters are stored as three dimensional datasets with dimension sizes designed by `(Nx, Ny, Nz)`. In order to support scalars and 1D and 2D arrays, the unused dimensions are set to 1 . For example, scalar variables are stored with a dimension size of `(1,1,1)`, 1D vectors oriented in y-direction are stored with a dimension size of `(1, Ny, 1)`, and so on. If the dataset stores a complex variable, the real and imaginary parts are stored in an interleaved layout and the lowest used dimension size is doubled (i.e., Nx for a 3D matrix, Ny for a 1D vector oriented in the y-direction). The datasets are physically stored in row-major order (in contrast to column-major order used by MATLAB) using either the ``H5T_IEEE_F32LE'` data type for floating point datasets or ``H5T_STD_U64LE'` for integer based datasets.

In order to enable compression of big datasets (3D variables, output time series), selected datasets are not stored as monolithic blocks but broken into chunks that are compressed by the ZIP library and stored separately. The chunk size is defined as follows:

- `(Nx, Ny, 1)` in the case of 3D variables (one 2D slab).
- `(N_sensor_points, 1, 1)` in the case of the output time series (one time step of the simulation).

All datasets have two attributes that specify the content of the dataset. The ``data_type'` attribute specifies the data type of the dataset. The admissible values are either ``float'` or ``long'`. The ``domain_type'` attribute specifies the domain of the dataset. The admissible values are either ``real'` for the real domain or ``complex'` for the complex domain. The C++ code reads these attributes and checks their values.

    ==============================================================================================================
                                            Input File Datasets
    ==============================================================================================================
    Name                            Size           Data type       Domain Type      Condition of Presence
    ==============================================================================================================
      1. Simulation Flags
    --------------------------------------------------------------------------------------------------------------
      ux_source_flag                (1, 1, 1)       long            real
      uy_source_flag                (1, 1, 1)       long            real
      uz_source_flag                (1, 1, 1)       long            real
      p_source_flag                 (1, 1, 1)       long            real
      p0_source_flag                (1, 1, 1)       long            real
      transducer_source_flag        (1, 1, 1)       long            real
      nonuniform_grid_flag          (1, 1, 1)       long            real            must be set to 0
      nonlinear_flag                (1, 1, 1)       long            real
      absorbing_flag                (1, 1, 1)       long            real
    --------------------------------------------------------------------------------------------------------------
      2. Grid Properties
    --------------------------------------------------------------------------------------------------------------
      Nx                            (1, 1, 1)       long            real
      Ny                            (1, 1, 1)       long            real
      Nz                            (1, 1, 1)       long            real
      Nt                            (1, 1, 1)       long            real
      dt                            (1, 1, 1)       float           real
      dx                            (1, 1, 1)       float           real
      dy                            (1, 1, 1)       float           real
      dz                            (1, 1, 1)       float           real
    --------------------------------------------------------------------------------------------------------------
      3 Medium Properties
    --------------------------------------------------------------------------------------------------------------
      3.1 Regular Medium Properties

      rho0                          (Nx, Ny, Nz)    float         real              heterogenous
      		           	(1, 1, 1)       float         real              homogenous
      rho0_sgx                      (Nx, Ny, Nz)    float         real              heterogenous
                                    (1, 1, 1)       float         real              homogenous
      rho0_sgy                      (Nx, Ny, Nz)    float         real              heterogenous
                                    (1, 1, 1)       float         real              homogenous
      rho0_sgz                      (Nx, Ny, Nz)    float         real              heterogenous
    				(1, 1, 1)       float         real              homogenous
      c0                            (Nx, Ny, Nz)    float         real              heterogenous
      		       		(1, 1, 1)       float         real              homogenous
      c_ref                         (1, 1, 1)       float         real

      3.2 Nonlinear Medium Properties (defined if (nonlinear_flag == 1))

      BonA                          (Nx, Ny, Nz)    float         real              heterogenous
                                    (1, 1, 1)       float         real              homogenous

      3.3 Absorbing Medium Properties (defined if (absorbing_flag == 1))

      alpha_coef                    (Nx, Ny, Nz)    float         real              heterogenous
                                    (1, 1, 1)       float         real              homogenous
      alpha_power                   (1, 1, 1)       float         real
    --------------------------------------------------------------------------------------------------------------
      4. Sensor Variables
    --------------------------------------------------------------------------------------------------------------
    sensor_mask_index               (Nsens, 1, 1)   long          real
    --------------------------------------------------------------------------------------------------------------
      5 Source Properties
    --------------------------------------------------------------------------------------------------------------
      5.1 Velocity Source Terms (defined if (ux_source_flag == 1 || uy_source_flag == 1 || uz_source_flag == 1))

      u_source_mode                 (1, 1, 1)          long       real
      u_source_many                 (1, 1, 1)          long       real
      u_source_index                (Nsrc, 1, 1)       long       real
      ux_source_input               (1, Nt_src, 1)     float      real              u_source_many == 0
                                    (Nsrc, Nt_src, 1)  float      real              u_source_many == 1
      uy_source_input               (1, Nt_src,  1)    float      real              u_source_many == 0
                                    (Nsrc, Nt_src, 1)  float      real              u_source_many == 1
      uz_source_input               (1, Nt_src, 1)     float      real              u_source_many == 0
                                    (Nt_src, Nsrc, 1)  float      real              u_source_many == 1

      5.2 Pressure Source Terms (defined if p_source_flag == 1))

      p_source_mode                 (1, 1, 1)          long       real
      p_source_many                 (1, 1, 1)          long       real
      p_source_index                (Nsrc, 1, 1)       long       real
      p_source_input                (Nsrc, Nt_src, 1)  float      real              p_source_many == 1
                                    (1, Nt_src, 1)     float      real              p_source_many == 0

      5.3 Transducer Source Terms (defined if (transducer_source_flag == 1))

      u_source_index        	(Nsrc, 1, 1)    long          real
      transducer_source_input       (Nt_src, 1, 1)  float         real
      delay_mask			(Nsrc, 1, 1)    float         real

      5.4 IVP Source Terms (defined if ( p0_source_flag ==1)

      p0_source_input               (Nx, Ny, Nz)    float         real

    --------------------------------------------------------------------------------------------------------------
      6. K-space and Shift Variables
    --------------------------------------------------------------------------------------------------------------
      ddx_k_shift_pos_r     	(Nx/2 + 1, 1, 1)  float       complex
      ddx_k_shift_neg_r             (Nx/2 + 1, 1, 1)  float       complex
      ddy_k_shift_pos               (1, Ny, 1)        float       complex
      ddy_k_shift_neg               (1, Ny, 1)        float       complex
      ddz_k_shift_pos               (1, 1, Nz)        float       complex
      ddz_k_shift_neg               (1, 1, Nz)        float       complex
    --------------------------------------------------------------------------------------------------------------
      7. PML Variables
    --------------------------------------------------------------------------------------------------------------
      pml_x_size                    (1, 1, 1)       long          real
      pml_y_size                    (1, 1, 1)       long          real
      pml_z_size                    (1, 1, 1)       long          real
      pml_x_alpha                   (1, 1, 1)       float         real
      pml_y_alpha                   (1, 1, 1)       float         real
      pml_z_alpha                   (1, 1, 1)       float         real

      pml_x                         (Nx, 1, 1)      float         real
      pml_x_sgx                     (Nx, 1, 1)      float         real
      pml_y                         (1, Ny, 1)      float         real
      pml_y_sgy                     (1, Ny, 1)      float         real
      pml_z                         (1, 1, Nz)      float         real
      pml_z_sgz                     (1, 1, Nz)      float         real
    ==============================================================================================================

    ==============================================================================================================
                                            Output File Datasets
    ==============================================================================================================
    Name                            Size           Data type        Domain Type     Condition of Presence
    ==============================================================================================================
      1. Simulation Flags
    --------------------------------------------------------------------------------------------------------------
      ux_source_flag                (1, 1, 1)       long          real
      uy_source_flag                (1, 1, 1)       long          real
      uz_source_flag                (1, 1, 1)       long          real
      p_source_flag                 (1, 1, 1)       long          real
      p0_source_flag                (1, 1, 1)       long          real
      transducer_source_flag        (1, 1, 1)       long          real
      nonuniform_grid_flag          (1, 1, 1)       long          real
      nonlinear_flag		(1, 1, 1)       long          real
      absorbing_flag		(1, 1, 1)       long          real
      u_source_mode                 (1, 1, 1)       long          real              if u_source
      u_source_many                 (1, 1, 1)       long          real              if u_source
      p_source_mode                 (1, 1, 1)       long          real              if p_source
      p_source_many                 (1, 1, 1)       long          real              if p_source

    --------------------------------------------------------------------------------------------------------------
      2. Grid Properties
    --------------------------------------------------------------------------------------------------------------
      Nx                            (1, 1, 1)       long          real
      Ny                            (1, 1, 1)       long          real
      Nz                            (1, 1, 1)       long          real
      Nt                            (1, 1, 1)       long          real
      dt                            (1, 1, 1)       float         real
      dx                            (1, 1, 1)       float         real
      dy                            (1, 1, 1)       float         real
      dz                            (1, 1, 1)       float         real
    -------------------------------------------------------------------------------------------------------------
      3. PML Variables
    --------------------------------------------------------------------------------------------------------------
      pml_x_size                    (1, 1, 1)       long          real
      pml_y_size                    (1, 1, 1)       long          real
      pml_z_size                    (1, 1, 1)       long          real
      pml_x_alpha                   (1, 1, 1)       float         real
      pml_y_alpha                   (1, 1, 1)       float         real
      pml_z_alpha                   (1, 1, 1)       float         real

      pml_x                         (Nx, 1, 1)      float         real
      pml_x_sgx                     (Nx, 1, 1)      float         real
      pml_y                         (1, Ny, 1)      float         real
      pml_y_sgy                     (1, Ny, 1)      float         real
      pml_z                         (1, 1, Nz)      float         real
      pml_z_sgz                     (1, 1, Nz)      float         real
    --------------------------------------------------------------------------------------------------------------
      4. Simulation Results
    --------------------------------------------------------------------------------------------------------------

      p                             (Nsens, Nt - s, 1) float      real              -p or --p_raw
      p_rms                         (Nsens, 1, 1)      float      real              --p_rms
      p_max                         (Nsens, 1, 1)      float      real              --p_max
      p_final                       (Nx, Ny, Nz)       float      real              --p_final

      ux                            (Nsens, Nt - s, 1) float      real              -u or --u_raw
      uy                            (Nsens, Nt - s, 1) float      real              -u or --u_raw
      uz                            (Nsens, Nt - s, 1) float      real              -u or --u_raw

      ux_rms                        (Nsens, 1, 1)      float      real              --u_rms
      uy_rms                        (Nsens, 1, 1)      float      real              --u_rms
      uz_rms                        (Nsens, 1, 1)      float      real              --u_rms

      ux_max                        (Nsens, 1, 1)      float      real              --u_max
      uy_max                        (Nsens, 1, 1)      float      real              --u_max
      uz_max                        (Nsens, 1, 1)      float      real              --u_max

      ux_final                      (Nx, Ny, Nz)       float      real              --u_final
      uy_final                      (Nx, Ny, Nz)       float      real              --u_final
      uz_final                      (Nx, Ny, Nz)       float      real              --u_final

      Ix_avg                        (Nsens, 1, 1)      float      real              -I or --I_avg
      Iy_avg                        (Nsens, 1, 1)      float      real              -I or --I_avg
      Iz_avg                        (Nsens, 1, 1)      float      real              -I or --I_avg

      Ix_max                        (Nsens, 1, 1)      float      real              --I_max
      Iy_max                        (Nsens, 1, 1)      float      real              --I_max
      Iz_max                        (Nsens, 1, 1)      float      real              --I_max
    ==============================================================================================================

## License

This file is part of the C++ extension of the k-Wave Toolbox (http://www.k-wave.org).
Copyright (C) 2012 Jiri Jaros and Bradley Treeby

This file is part of k-Wave. k-Wave is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

k-Wave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with k-Wave. If not, see <http://www.gnu.org/licenses/>.

Definition in file HDF5_File.h.

All Classes Files Functions Variables Typedefs Enumerations