 |
kspaceFirstOrder3D-OMP
1.1
The C++ implementation of the k-wave toolbox for the time-domain simulation of acoustic wave fields in 3D
|
|
kspaceFirstOrder3D-OMP
1.1
The C++ implementation of the k-wave toolbox for the time-domain simulation of acoustic wave fields in 3D
|
The header file containing the HDF5 related classes. More...
#include <hdf5.h>#include <hdf5_hl.h>#include <string>#include <map>#include <Utils/DimensionSizes.h>
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... | |
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).
kspaceFirstOrder3D-OMP v1.1 introduces a new version of the HDF5 input and output file format. The code is happy to work with both versions (1.0 and 1.1), however when working with an input file of version 1.0, some features are not supported, namely the cuboid sensor mask, and u_non_staggered_raw. When running from within the actual K-Wave Toolbox, the files will always be generated in version 1.1
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 bellow). The HDF5 checkpoint file contains the same file header as the input file and the root group `/' with a few datasets keeping the actual simulation state 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/Checkpoint 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 (1)
============================================================================================================================================================================================================================
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 (1)
-------------------------------------------------------------------------------------------------------------
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
==============================================================================================================The input and checkpoint file stores all quantities 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. All the datasets are store under the root group.
The output file of version 1.0 could only store recorded quantities as 3D datasets under the root group. However, with version 1.1 and the new cuboid corner sensor mask, the sampled quantities may be laid out as 4D quantities stored under specific groups. The dimensions are always (Nx, Ny, Nz, Nt), every sampled cuboid is stored as a distinct dataset and the datasets are grouped under a group named by the quantity stored. This makes the file clearly readable and easy to parse.
In order to enable compression and more efficient data processing, big datasets are not stored as monolithic blocks but broken into chunks that may be compressed by the ZIP library and stored separately. The chunk size is defined as follows:
(1M elements, 1, 1) in the case of 1D variables - index sensor mask (8MB blocks). (Nx, Ny, 1) in the case of 3D variables (one 2D slab). (Nx, Ny, Nz, 1) in the case of 4D variables (one time step). (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
x_shift_neg_r (Nx/2+1, 1, 1) float complex File version 1.1
y_shift_neg_r (1, Ny/2+1, 1) float complex File version 1.1
z_shift_neg_r (1, 1, Nz/2+1) float complex File version 1.1
--------------------------------------------------------------------------------------------------------------
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_type (1, 1, 1) long real File version 1.1 (0 = index, 1 = corners)
sensor_mask_index (Nsens, 1, 1) long real File version 1.0 always, File version 1.1 if sensor_mask_type == 0
sensor_mask_corners (Ncubes, 6, 1) long real File version 1.1, if sensor_mask_type == 1
--------------------------------------------------------------------------------------------------------------
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
============================================================================================================================================================================================================================
Checkpoint File Datasets
==============================================================================================================
Name Size Data type Domain Type Condition of Presence
==============================================================================================================
1. 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
t_index (1, 1, 1) long real
--------------------------------------------------------------------------------------------------------------
2. Simulation state
--------------------------------------------------------------------------------------------------------------
p (Nx, Ny, Nz) float real
ux_sgx (Nx, Ny, Nz) float real
uy_sgy (Nx, Ny, Nz) float real
uz_sgz (Nx, Ny, Nz) float real
rhox (Nx, Ny, Nz) float real
rhoy (Nx, Ny, Nz) float real
rhoz (Nx, Ny, 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. Sensor Variables (present if --copy_sensor_mask)
--------------------------------------------------------------------------------------------------------------
sensor_mask_type (1, 1, 1) long real File version 1.1 and --copy_sensor_mask
sensor_mask_index (Nsens, 1, 1) long real File version 1.1 and if sensor_mask_type == 0
sensor_mask_corners (Ncubes, 6, 1) long real File version 1.1 and if sensor_mask_type == 1
--------------------------------------------------------------------------------------------------------------
5a. Simulation Results: if sensor_mask_type == 0 (index), or File version == 1.0
--------------------------------------------------------------------------------------------------------------
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_min (Nsens, 1, 1) float real --p_min
p_max_all (Nx, Ny, Nz) float real --p_max_all
p_min_all (Nx, Ny, Nz) float real --p_min_all
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_non_staggered (Nsens, Nt - s, 1) float real --u_non_staggered_raw (File version ==1.1)
uy_non_staggered (Nsens, Nt - s, 1) float real --u_non_staggered_raw (File version ==1.1)
uz_non_staggered (Nsens, Nt - s, 1) float real --u_non_staggered_raw (File version ==1.1)
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_min (Nsens, 1, 1) float real --u_min
uy_min (Nsens, 1, 1) float real --u_min
uz_min (Nsens, 1, 1) float real --u_min
ux_max_all (Nx, Ny, Nz) float real --u_max_all
uy_max_all (Nx, Ny, Nz) float real --u_max_all
uz_max_all (Nx, Ny, Nz) float real --u_max_all
ux_min_all (Nx, Ny, Nz) float real --u_min_all
uy_min_all (Nx, Ny, Nz) float real --u_min_all
uz_min_all (Nx, Ny, Nz) float real --u_min_all
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
--------------------------------------------------------------------------------------------------------------
5b. Simulation Results: if sensor_mask_type == 1 (corners) and File version == 1.1
--------------------------------------------------------------------------------------------------------------
/p group of datasets, one per cuboid -p or --p_raw
/p/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/p/2 (Cx, Cy, Cz, Nt-s) float real 2nd sampled cuboid, etc.
/p_rms group of datasets, one per cuboid --p_rms
/p_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/p_max group of datasets, one per cuboid --p_max
/p_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/p_min group of datasets, one per cuboid --p_min
/p_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
p_max_all (Nx, Ny, Nz) float real --p_max_all
p_min_all (Nx, Ny, Nz) float real --p_min_all
p_final (Nx, Ny, Nz) float real --p_final
/ux group of datasets, one per cuboid -u or --u_raw
/ux/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uy group of datasets, one per cuboid -u or --u_raw
/uy/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uz group of datasets, one per cuboid -u or --u_raw
/uz/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/ux_non_staggered group of datasets, one per cuboid --u_non_staggered_raw
/ux_non_staggered/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uy_non_staggered group of datasets, one per cuboid --u_non_staggered_raw
/uy_non_staggered/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uz_non_staggered group of datasets, one per cuboid --u_non_staggered_raw
/uz_non_staggered/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/ux_rms group of datasets, one per cuboid --u_rms
/ux_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uy_rms group of datasets, one per cuboid --u_rms
/uy_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uz_rms group of datasets, one per cuboid --u_rms
/uy_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/ux_max group of datasets, one per cuboid --u_max
/ux_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uy_max group of datasets, one per cuboid --u_max
/ux_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uz_max group of datasets, one per cuboid --u_max
/ux_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/ux_min group of datasets, one per cuboid --u_min
/ux_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uy_min group of datasets, one per cuboid --u_min
/ux_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
/uz_min group of datasets, one per cuboid --u_min
/ux_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
ux_max_all (Nx, Ny, Nz) float real --u_max_all
uy_max_all (Nx, Ny, Nz) float real --u_max_all
uz_max_all (Nx, Ny, Nz) float real --u_max_all
ux_min_all (Nx, Ny, Nz) float real --u_min_all
uy_min_all (Nx, Ny, Nz) float real --u_min_all
uz_min_all (Nx, Ny, Nz) float real --u_min_all
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
==============================================================================================================
This file is part of the C++ extension of the k-Wave Toolbox (http://www.k-wave.org).
Copyright (C) 2014 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.
1.8.6