kspaceFirstOrder3D-OMP 1.0
The C++ implementation of the k-wave toolbox for the time-domain simulation of acoustic wave fields in 3D
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:

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