kspaceFirstOrder3D-OMP  1.1
The C++ implementation of the k-wave toolbox for the time-domain simulation of acoustic wave fields in 3D
 All Classes Files Functions Variables Typedefs Enumerations Friends Pages
HDF5_File.h
Go to the documentation of this file.
1 /**
2  * @file HDF5_File.h
3  * @author Jiri Jaros \n
4  * Faculty of Information Technology\n
5  * Brno University of Technology \n
6  * jarosjir@fit.vutbr.cz
7  *
8  * @brief The header file containing the HDF5 related classes
9  *
10  * @version kspaceFirstOrder3D 2.15
11  * @date 27 July 2012, 14:14 (created) \n
12  * 02 October 2014, 12:45 (revised)
13  *
14  *
15  *
16  * @section HDF HDF5 File Structure
17  *
18  * The C++ code has been designed as a standalone application which is not dependent
19  * on MATLAB libraries or a MEX interface. This is of particular importance when
20  * using servers and supercomputers without MATLAB support. For this reason, simulation
21  * data must be transferred between the C++ code and MATLAB using external input
22  * and output files. These files are stored using the Hierarchical Data Format
23  * HDF5 (http://www.hdfgroup.org/HDF5/). This is a data model, library, and file
24  * format for storing and managing data. It supports a variety of datatypes, and
25  * is designed for flexible and efficient I/O and for high volume and complex data.
26  * The HDF5 technology suite includes tools and applications for managing,
27  * manipulating, viewing, and analysing data in the HDF5 format.
28  *
29  *
30  *
31  * Each HDF5 file is a container for storing a variety of scientific data and is composed
32  * of two primary types of objects: groups and datasets. A HDF5 group is a structure
33  * containing zero or more HDF5 objects, together with supporting metadata. A HDF5
34  * group can be seen as a disk folder. A HDF5 dataset is a multidimensional array of
35  * data elements, together with supporting metadata. A HDF5 dataset can be seen as a
36  * disk file. Any HDF5 group or dataset may also have an associated attribute list. A
37  * HDF5 attribute is a user-defined HDF5 structure that provides extra information about a
38  * HDF5 object. More information can be obtained from the HDF5 documentation (http://www.hdfgroup.org/HDF5/doc/index.html).
39  *
40  *
41  * kspaceFirstOrder3D-OMP v1.1 introduces a new version of the HDF5 input and
42  * output file format. The code is happy to work with both versions (1.0 and 1.1), however when
43  * working with an input file of version 1.0, some features are not supported,
44  * namely the cuboid sensor mask, and u_non_staggered_raw.
45  * When running from within the actual K-Wave Toolbox, the files will always be generated
46  * in version 1.1
47  *
48  * The HDF5 input file for the C++ simulation code contains a file header with
49  * brief description of the simulation stored in string attributes,
50  * and the root group `/' which stores all the simulation properties in the form
51  * of 3D datasets (a complete list of input datasets is given bellow).
52  * The HDF5 checkpoint file contains the same file header as the input file and
53  * the root group `/' with a few datasets keeping the actual simulation state
54  * The HDF5 output file contains a file header with the simulation description
55  * as well as performance statistics, such as the simulation time and memory
56  * consumption, stored in string attributes.
57  * The results of the simulation are stored in the root group `/' in the form of 3D datasets.
58  *
59  *
60  * \verbatim
61 ==============================================================================================================
62  Input File/Checkpoint File Header
63 =============================================================================================================
64 created_by Short description of the tool that created this file
65 creation_date Date when the file was created
66 file_description Short description of the content of the file (e.g. simulation name)
67 file_type Type of the file (input)
68 major_version Major version of the file definition (1)
69 minor_version Minor version of the file definition (1)
70 ==============================================================================================================
71  \endverbatim
72  *
73  * \verbatim
74 ==============================================================================================================
75  Output File Header
76 ==============================================================================================================
77 created_by Short description of the tool that created this file
78 creation_date Date when the file was created
79 file_description Short description of the content of the file (e.g. simulation name)
80 file_type Type of the file (output)
81 major_version Major version of the file definition (1)
82 minor_version Minor version of the file definition (1)
83 -------------------------------------------------------------------------------------------------------------
84 host_names List of hosts (computer names) the simulation was executed on
85 number_of_cpu_cores Number of CPU cores used for the simulation
86 data_loading_phase_execution_time Time taken to load data from the file
87 pre-processing_phase_execution_time Time taken to pre-process data
88 simulation_phase_execution_time Time taken to run the simulation
89 post-processing_phase_execution_time Time taken to complete the post-processing phase
90 total_execution_time Total execution time
91 peak_core_memory_in_use Peak memory required per core during the simulation
92 total_memory_in_use Total Peak memory in use
93 ==============================================================================================================
94  \endverbatim
95  *
96  *
97  *
98  * The input and checkpoint file stores all quantities as three dimensional datasets with
99  * dimension sizes designed by <tt>(Nx, Ny, Nz)</tt>. In order to support scalars
100  * and 1D and 2D arrays, the unused dimensions are set to 1.
101  * For example, scalar variables are stored with a dimension size of <tt>(1,1,1)</tt>,
102  * 1D vectors oriented in y-direction are stored with a dimension size of <tt>(1, Ny, 1)</tt>,
103  * and so on. If the dataset stores a complex variable, the real and imaginary parts
104  * are stored in an interleaved layout and the lowest used dimension size is
105  * doubled (i.e., Nx for a 3D matrix, Ny for a 1D vector oriented in the y-direction). The
106  * datasets are physically stored in row-major order (in contrast to column-major order used
107  * by MATLAB) using either the <tt>`H5T_IEEE_F32LE'</tt> data type for floating point datasets or
108  * <tt>`H5T_STD_U64LE'</tt> for integer based datasets.
109  * All the datasets are store under the root group.
110  *
111  *
112  * The output file of version 1.0 could only store recorded quantities as 3D datasets
113  * under the root group. However, with version 1.1 and the new cuboid corner sensor
114  * mask, the sampled quantities may be laid out as 4D quantities stored under specific
115  * groups. The dimensions are always <tt>(Nx, Ny, Nz, Nt)</tt>, every sampled cuboid
116  * is stored as a distinct dataset and the datasets are grouped under a group named
117  * by the quantity stored. This makes the file clearly readable and easy to parse.
118  *
119  *
120  * In order to enable compression and more efficient data processing, big datasets
121  * are not stored as monolithic blocks
122  * but broken into chunks that may be compressed by the ZIP library and stored
123  * separately. The chunk size is defined as follows:
124  *
125  * \li <tt> (1M elements, 1, 1) </tt> in the case of 1D variables - index sensor mask (8MB blocks).
126  * \li <tt> (Nx, Ny, 1) </tt> in the case of 3D variables (one 2D slab).
127  * \li <tt> (Nx, Ny, Nz, 1) </tt> in the case of 4D variables (one time step).
128  * \li <tt> (N_sensor_points, 1, 1) </tt> in the case of the output time series (one time step of the simulation).
129  *
130  *
131  * All datasets have two attributes that specify the content of the dataset. The \c `data_type'
132  * attribute specifies the data type of the dataset. The admissible values are either \c `float' or
133  * \c `long'. The \c `domain_type' attribute specifies the domain of the dataset. The admissible
134  * values are either \c `real' for the real domain or \c `complex' for the complex domain. The
135  * C++ code reads these attributes and checks their values.
136  *
137  *
138  *
139  * \verbatim
140 ==============================================================================================================
141  Input File Datasets
142 ==============================================================================================================
143 Name Size Data type Domain Type Condition of Presence
144 ==============================================================================================================
145  1. Simulation Flags
146 --------------------------------------------------------------------------------------------------------------
147  ux_source_flag (1, 1, 1) long real
148  uy_source_flag (1, 1, 1) long real
149  uz_source_flag (1, 1, 1) long real
150  p_source_flag (1, 1, 1) long real
151  p0_source_flag (1, 1, 1) long real
152  transducer_source_flag (1, 1, 1) long real
153  nonuniform_grid_flag (1, 1, 1) long real must be set to 0
154  nonlinear_flag (1, 1, 1) long real
155  absorbing_flag (1, 1, 1) long real
156 --------------------------------------------------------------------------------------------------------------
157  2. Grid Properties
158 --------------------------------------------------------------------------------------------------------------
159  Nx (1, 1, 1) long real
160  Ny (1, 1, 1) long real
161  Nz (1, 1, 1) long real
162  Nt (1, 1, 1) long real
163  dt (1, 1, 1) float real
164  dx (1, 1, 1) float real
165  dy (1, 1, 1) float real
166  dz (1, 1, 1) float real
167  x_shift_neg_r (Nx/2+1, 1, 1) float complex File version 1.1
168  y_shift_neg_r (1, Ny/2+1, 1) float complex File version 1.1
169  z_shift_neg_r (1, 1, Nz/2+1) float complex File version 1.1
170 --------------------------------------------------------------------------------------------------------------
171  3 Medium Properties
172 --------------------------------------------------------------------------------------------------------------
173  3.1 Regular Medium Properties
174  rho0 (Nx, Ny, Nz) float real heterogenous
175  (1, 1, 1) float real homogenous
176  rho0_sgx (Nx, Ny, Nz) float real heterogenous
177  (1, 1, 1) float real homogenous
178  rho0_sgy (Nx, Ny, Nz) float real heterogenous
179  (1, 1, 1) float real homogenous
180  rho0_sgz (Nx, Ny, Nz) float real heterogenous
181  (1, 1, 1) float real homogenous
182  c0 (Nx, Ny, Nz) float real heterogenous
183  (1, 1, 1) float real homogenous
184  c_ref (1, 1, 1) float real
185 
186  3.2 Nonlinear Medium Properties (defined if (nonlinear_flag == 1))
187  BonA (Nx, Ny, Nz) float real heterogenous
188  (1, 1, 1) float real homogenous
189 
190  3.3 Absorbing Medium Properties (defined if (absorbing_flag == 1))
191  alpha_coef (Nx, Ny, Nz) float real heterogenous
192  (1, 1, 1) float real homogenous
193  alpha_power (1, 1, 1) float real
194 --------------------------------------------------------------------------------------------------------------
195  4. Sensor Variables
196 --------------------------------------------------------------------------------------------------------------
197  sensor_mask_type (1, 1, 1) long real File version 1.1 (0 = index, 1 = corners)
198  sensor_mask_index (Nsens, 1, 1) long real File version 1.0 always, File version 1.1 if sensor_mask_type == 0
199  sensor_mask_corners (Ncubes, 6, 1) long real File version 1.1, if sensor_mask_type == 1
200 --------------------------------------------------------------------------------------------------------------
201  5 Source Properties
202 --------------------------------------------------------------------------------------------------------------
203  5.1 Velocity Source Terms (defined if (ux_source_flag == 1 || uy_source_flag == 1 || uz_source_flag == 1))
204  u_source_mode (1, 1, 1) long real
205  u_source_many (1, 1, 1) long real
206  u_source_index (Nsrc, 1, 1) long real
207  ux_source_input (1, Nt_src, 1) float real u_source_many == 0
208  (Nsrc, Nt_src, 1) float real u_source_many == 1
209  uy_source_input (1, Nt_src, 1) float real u_source_many == 0
210  (Nsrc, Nt_src, 1) float real u_source_many == 1
211  uz_source_input (1, Nt_src, 1) float real u_source_many == 0
212  (Nt_src, Nsrc, 1) float real u_source_many == 1
213 
214  5.2 Pressure Source Terms (defined if p_source_flag == 1))
215  p_source_mode (1, 1, 1) long real
216  p_source_many (1, 1, 1) long real
217  p_source_index (Nsrc, 1, 1) long real
218  p_source_input (Nsrc, Nt_src, 1) float real p_source_many == 1
219  (1, Nt_src, 1) float real p_source_many == 0
220 
221  5.3 Transducer Source Terms (defined if (transducer_source_flag == 1))
222  u_source_index (Nsrc, 1, 1) long real
223  transducer_source_input (Nt_src, 1, 1) float real
224  delay_mask (Nsrc, 1, 1) float real
225 
226  5.4 IVP Source Terms (defined if ( p0_source_flag ==1))
227  p0_source_input (Nx, Ny, Nz) float real
228 --------------------------------------------------------------------------------------------------------------
229  6. K-space and Shift Variables
230 --------------------------------------------------------------------------------------------------------------
231  ddx_k_shift_pos_r (Nx/2 + 1, 1, 1) float complex
232  ddx_k_shift_neg_r (Nx/2 + 1, 1, 1) float complex
233  ddy_k_shift_pos (1, Ny, 1) float complex
234  ddy_k_shift_neg (1, Ny, 1) float complex
235  ddz_k_shift_pos (1, 1, Nz) float complex
236  ddz_k_shift_neg (1, 1, Nz) float complex
237 --------------------------------------------------------------------------------------------------------------
238  7. PML Variables
239 --------------------------------------------------------------------------------------------------------------
240  pml_x_size (1, 1, 1) long real
241  pml_y_size (1, 1, 1) long real
242  pml_z_size (1, 1, 1) long real
243  pml_x_alpha (1, 1, 1) float real
244  pml_y_alpha (1, 1, 1) float real
245  pml_z_alpha (1, 1, 1) float real
246 
247  pml_x (Nx, 1, 1) float real
248  pml_x_sgx (Nx, 1, 1) float real
249  pml_y (1, Ny, 1) float real
250  pml_y_sgy (1, Ny, 1) float real
251  pml_z (1, 1, Nz) float real
252  pml_z_sgz (1, 1, Nz) float real
253 ==============================================================================================================
254  \endverbatim
255 
256 \verbatim
257 ==============================================================================================================
258  Checkpoint File Datasets
259 ==============================================================================================================
260 Name Size Data type Domain Type Condition of Presence
261 ==============================================================================================================
262  1. Grid Properties
263 --------------------------------------------------------------------------------------------------------------
264  Nx (1, 1, 1) long real
265  Ny (1, 1, 1) long real
266  Nz (1, 1, 1) long real
267  Nt (1, 1, 1) long real
268  t_index (1, 1, 1) long real
269 --------------------------------------------------------------------------------------------------------------
270  2. Simulation state
271 --------------------------------------------------------------------------------------------------------------
272  p (Nx, Ny, Nz) float real
273  ux_sgx (Nx, Ny, Nz) float real
274  uy_sgy (Nx, Ny, Nz) float real
275  uz_sgz (Nx, Ny, Nz) float real
276  rhox (Nx, Ny, Nz) float real
277  rhoy (Nx, Ny, Nz) float real
278  rhoz (Nx, Ny, Nz) float real
279 --------------------------------------------------------------------------------------------------------------
280 \endverbatim
281 
282 
283  \verbatim
284 ==============================================================================================================
285  Output File Datasets
286 ==============================================================================================================
287 Name Size Data type Domain Type Condition of Presence
288 ==============================================================================================================
289  1. Simulation Flags
290 --------------------------------------------------------------------------------------------------------------
291  ux_source_flag (1, 1, 1) long real
292  uy_source_flag (1, 1, 1) long real
293  uz_source_flag (1, 1, 1) long real
294  p_source_flag (1, 1, 1) long real
295  p0_source_flag (1, 1, 1) long real
296  transducer_source_flag (1, 1, 1) long real
297  nonuniform_grid_flag (1, 1, 1) long real
298  nonlinear_flag (1, 1, 1) long real
299  absorbing_flag (1, 1, 1) long real
300  u_source_mode (1, 1, 1) long real if u_source
301  u_source_many (1, 1, 1) long real if u_source
302  p_source_mode (1, 1, 1) long real if p_source
303  p_source_many (1, 1, 1) long real if p_source
304 --------------------------------------------------------------------------------------------------------------
305  2. Grid Properties
306 --------------------------------------------------------------------------------------------------------------
307  Nx (1, 1, 1) long real
308  Ny (1, 1, 1) long real
309  Nz (1, 1, 1) long real
310  Nt (1, 1, 1) long real
311  dt (1, 1, 1) float real
312  dx (1, 1, 1) float real
313  dy (1, 1, 1) float real
314  dz (1, 1, 1) float real
315 -------------------------------------------------------------------------------------------------------------
316  3. PML Variables
317 --------------------------------------------------------------------------------------------------------------
318  pml_x_size (1, 1, 1) long real
319  pml_y_size (1, 1, 1) long real
320  pml_z_size (1, 1, 1) long real
321  pml_x_alpha (1, 1, 1) float real
322  pml_y_alpha (1, 1, 1) float real
323  pml_z_alpha (1, 1, 1) float real
324 
325  pml_x (Nx, 1, 1) float real
326  pml_x_sgx (Nx, 1, 1) float real
327  pml_y (1, Ny, 1) float real
328  pml_y_sgy (1, Ny, 1) float real
329  pml_z (1, 1, Nz) float real
330  pml_z_sgz (1, 1, Nz) float real
331 --------------------------------------------------------------------------------------------------------------
332  4. Sensor Variables (present if --copy_sensor_mask)
333 --------------------------------------------------------------------------------------------------------------
334  sensor_mask_type (1, 1, 1) long real File version 1.1 and --copy_sensor_mask
335  sensor_mask_index (Nsens, 1, 1) long real File version 1.1 and if sensor_mask_type == 0
336  sensor_mask_corners (Ncubes, 6, 1) long real File version 1.1 and if sensor_mask_type == 1
337 --------------------------------------------------------------------------------------------------------------
338  5a. Simulation Results: if sensor_mask_type == 0 (index), or File version == 1.0
339 --------------------------------------------------------------------------------------------------------------
340  p (Nsens, Nt - s, 1) float real -p or --p_raw
341  p_rms (Nsens, 1, 1) float real --p_rms
342  p_max (Nsens, 1, 1) float real --p_max
343  p_min (Nsens, 1, 1) float real --p_min
344  p_max_all (Nx, Ny, Nz) float real --p_max_all
345  p_min_all (Nx, Ny, Nz) float real --p_min_all
346  p_final (Nx, Ny, Nz) float real --p_final
347 
348 
349  ux (Nsens, Nt - s, 1) float real -u or --u_raw
350  uy (Nsens, Nt - s, 1) float real -u or --u_raw
351  uz (Nsens, Nt - s, 1) float real -u or --u_raw
352 
353  ux_non_staggered (Nsens, Nt - s, 1) float real --u_non_staggered_raw (File version ==1.1)
354  uy_non_staggered (Nsens, Nt - s, 1) float real --u_non_staggered_raw (File version ==1.1)
355  uz_non_staggered (Nsens, Nt - s, 1) float real --u_non_staggered_raw (File version ==1.1)
356 
357  ux_rms (Nsens, 1, 1) float real --u_rms
358  uy_rms (Nsens, 1, 1) float real --u_rms
359  uz_rms (Nsens, 1, 1) float real --u_rms
360 
361  ux_max (Nsens, 1, 1) float real --u_max
362  uy_max (Nsens, 1, 1) float real --u_max
363  uz_max (Nsens, 1, 1) float real --u_max
364 
365  ux_min (Nsens, 1, 1) float real --u_min
366  uy_min (Nsens, 1, 1) float real --u_min
367  uz_min (Nsens, 1, 1) float real --u_min
368 
369  ux_max_all (Nx, Ny, Nz) float real --u_max_all
370  uy_max_all (Nx, Ny, Nz) float real --u_max_all
371  uz_max_all (Nx, Ny, Nz) float real --u_max_all
372 
373  ux_min_all (Nx, Ny, Nz) float real --u_min_all
374  uy_min_all (Nx, Ny, Nz) float real --u_min_all
375  uz_min_all (Nx, Ny, Nz) float real --u_min_all
376 
377  ux_final (Nx, Ny, Nz) float real --u_final
378  uy_final (Nx, Ny, Nz) float real --u_final
379  uz_final (Nx, Ny, Nz) float real --u_final
380 --------------------------------------------------------------------------------------------------------------
381  5b. Simulation Results: if sensor_mask_type == 1 (corners) and File version == 1.1
382 --------------------------------------------------------------------------------------------------------------
383  /p group of datasets, one per cuboid -p or --p_raw
384  /p/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
385  /p/2 (Cx, Cy, Cz, Nt-s) float real 2nd sampled cuboid, etc.
386 
387  /p_rms group of datasets, one per cuboid --p_rms
388  /p_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
389 
390  /p_max group of datasets, one per cuboid --p_max
391  /p_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
392 
393  /p_min group of datasets, one per cuboid --p_min
394  /p_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
395 
396  p_max_all (Nx, Ny, Nz) float real --p_max_all
397  p_min_all (Nx, Ny, Nz) float real --p_min_all
398  p_final (Nx, Ny, Nz) float real --p_final
399 
400 
401  /ux group of datasets, one per cuboid -u or --u_raw
402  /ux/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
403  /uy group of datasets, one per cuboid -u or --u_raw
404  /uy/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
405  /uz group of datasets, one per cuboid -u or --u_raw
406  /uz/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
407 
408  /ux_non_staggered group of datasets, one per cuboid --u_non_staggered_raw
409  /ux_non_staggered/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
410  /uy_non_staggered group of datasets, one per cuboid --u_non_staggered_raw
411  /uy_non_staggered/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
412  /uz_non_staggered group of datasets, one per cuboid --u_non_staggered_raw
413  /uz_non_staggered/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
414 
415  /ux_rms group of datasets, one per cuboid --u_rms
416  /ux_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
417  /uy_rms group of datasets, one per cuboid --u_rms
418  /uy_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
419  /uz_rms group of datasets, one per cuboid --u_rms
420  /uy_rms/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
421 
422  /ux_max group of datasets, one per cuboid --u_max
423  /ux_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
424  /uy_max group of datasets, one per cuboid --u_max
425  /ux_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
426  /uz_max group of datasets, one per cuboid --u_max
427  /ux_max/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
428 
429  /ux_min group of datasets, one per cuboid --u_min
430  /ux_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
431  /uy_min group of datasets, one per cuboid --u_min
432  /ux_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
433  /uz_min group of datasets, one per cuboid --u_min
434  /ux_min/1 (Cx, Cy, Cz, Nt-s) float real 1st sampled cuboid
435 
436  ux_max_all (Nx, Ny, Nz) float real --u_max_all
437  uy_max_all (Nx, Ny, Nz) float real --u_max_all
438  uz_max_all (Nx, Ny, Nz) float real --u_max_all
439 
440  ux_min_all (Nx, Ny, Nz) float real --u_min_all
441  uy_min_all (Nx, Ny, Nz) float real --u_min_all
442  uz_min_all (Nx, Ny, Nz) float real --u_min_all
443 
444  ux_final (Nx, Ny, Nz) float real --u_final
445  uy_final (Nx, Ny, Nz) float real --u_final
446  uz_final (Nx, Ny, Nz) float real --u_final
447 ==============================================================================================================
448 \endverbatim
449  *
450  *
451  *
452  *
453  * @section License
454  * This file is part of the C++ extension of the k-Wave Toolbox (http://www.k-wave.org).\n
455  * Copyright (C) 2014 Jiri Jaros and Bradley Treeby
456  *
457  * This file is part of k-Wave. k-Wave is free software: you can redistribute it
458  * and/or modify it under the terms of the GNU Lesser General Public License as
459  * published by the Free Software Foundation, either version 3 of the License,
460  * or (at your option) any later version.
461  *
462  * k-Wave is distributed in the hope that it will be useful, but
463  * WITHOUT ANY WARRANTY; without even the implied warranty of
464  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
465  * See the GNU Lesser General Public License for more details.
466  *
467  * You should have received a copy of the GNU Lesser General Public License
468  * along with k-Wave. If not, see <http://www.gnu.org/licenses/>.
469  *
470  */
471 
472 #ifndef THDF5_FILE_H
473 #define THDF5_FILE_H
474 
475 
476 #include <hdf5.h>
477 #include <hdf5_hl.h>
478 #include <string>
479 #include <map>
480 
481 // Linux build
482 #ifdef __linux__
483  #include <unistd.h>
484 #endif
485 
486 #ifdef _WIN64
487  #include <io.h>
488 #endif
489 
490 #include <Utils/DimensionSizes.h>
491 
492 using namespace std;
493 
494 // Class with File header
495 class THDF5_FileHeader;
496 
497 
498 /**
499  * @class THDF5_File
500  * @brief Class wrapping the HDF5 routines.
501  * @details This class is responsible for working with HDF5 files. It offers routines
502  * to manage files (create, open, close) as well as creating, reading and modifying the
503  * contents (groups and datasets).
504  *
505  */
506 class THDF5_File
507 {
508  public:
509 
510  /**
511  * @enum THDF5_MatrixDataType
512  * @brief HDF5 matrix data type (float or uint64).
513  */
514  enum THDF5_MatrixDataType {hdf5_mdt_float = 0, hdf5_mdt_long = 1};
515 
516  /**
517  * @enum THDF5_MatrixDomainType
518  * @brief HDF5 Matrix domain type (real or complex).
519  */
520  enum THDF5_MatrixDomainType {hdf5_mdt_real = 0, hdf5_mdt_complex = 1};
521 
522 
523  /// Constructor of the class
524  THDF5_File();
525 
526  //----------------------- Basic file operations --------------------------//
527  /// Create the file, overwrite if exist.
528  void Create(const char * FileName,
529  unsigned int Flags = H5F_ACC_TRUNC );
530 
531  /// Open the file.
532  void Open(const char * FileName,
533  unsigned int Flags = H5F_ACC_RDONLY);
534  /**
535  * @brief Is the file opened?
536  * @details Is the file opened?
537  * @return true if the file is opened
538  */
539  bool IsOpened() const
540  {
541  return HDF5_FileId != H5I_BADID;
542  };
543 
544  /**
545  * @brief Does the file exist? static method.
546  * @details Check if the file exist
547  * @param [in] FileName
548  * @return true if the file exists
549  */
550  static bool IsAccessible(const char * FileName)
551  {
552  #ifdef __linux__
553  return (access(FileName, F_OK) == 0);
554  #endif
555 
556  #ifdef _WIN64
557  return (_access_s(FileName, 0) == 0 );
558  #endif
559  };
560 
561  /// Close file.
562  void Close();
563 
564  //----------------------- Group manipulators -----------------------------//
565  /// Create a HDF5 group at a specified place in the file tree.
566  hid_t CreateGroup(const hid_t ParentGroup,
567  const char * GroupName);
568 
569  /// Open a HDF5 group at a specified place in the file tree.
570  hid_t OpenGroup(const hid_t ParentGroup,
571  const char * GroupName);
572 
573  /// Close HDF5 group.
574  void CloseGroup(const hid_t Group);
575 
576  /**
577  * @brief Get handle to the root group.
578  * @details Get handle to the root group.
579  * @return - handle to the root group
580  */
581  hid_t GetRootGroup() const
582  {
583  return HDF5_FileId;
584  };
585 
586 
587  //---------------------- Dataset manipulators ----------------------------//
588  /// Open the HDF5 dataset at a specified place in the file tree.
589  hid_t OpenDataset(const hid_t ParentGroup,
590  const char * DatasetName);
591 
592  /// Create the HDF5 dataset at a specified place in the file tree (3D/4D).
593  hid_t CreateFloatDataset(const hid_t ParentGroup,
594  const char * DatasetName,
595  const TDimensionSizes & DimensionSizes,
596  const TDimensionSizes & ChunkSizes,
597  const size_t CompressionLevel);
598 
599  /// Create the HDF5 dataset at a specified place in the file tree (3D only).
600  hid_t CreateIndexDataset(const hid_t ParentGroup,
601  const char * DatasetName,
602  const TDimensionSizes & DimensionSizes,
603  const TDimensionSizes & ChunkSizes,
604  const size_t CompressionLevel);
605 
606  /// Close the HDF5 dataset
607  void CloseDataset (const hid_t HDF5_Dataset_id);
608 
609 
610  //------------------ Dataset Read/Write operations -----------------------//
611  /// Write a hyper-slab into the dataset - float dataset.
612  void WriteHyperSlab(const hid_t HDF5_Dataset_id,
613  const TDimensionSizes & Position,
614  const TDimensionSizes & Size,
615  const float * Data);
616  /// Write a hyper-slab into the dataset - index dataset.
617  void WriteHyperSlab(const hid_t HDF5_Dataset_id,
618  const TDimensionSizes & Position,
619  const TDimensionSizes & Size,
620  const size_t * Data);
621 
622  /// Write a cuboid selected inside MatrixData into a Hyperslab.
623  void WriteCuboidToHyperSlab(const hid_t HDF5_Dataset_id,
624  const TDimensionSizes & HyperslabPosition,
625  const TDimensionSizes & CuboidPosition,
626  const TDimensionSizes & CuboidSize,
627  const TDimensionSizes & MatrixDimensions,
628  const float * MatrixData);
629 
630  /// Write sensor data selected by the sensor mask - Occasionally very slow, do not use!
631  void WriteSensorByMaskToHyperSlab(const hid_t HDF5_Dataset_id,
632  const TDimensionSizes & HyperslabPosition,
633  const size_t IndexSensorSize,
634  const size_t * IndexSensorData,
635  const TDimensionSizes & MatrixDimensions,
636  const float * MatrixData);
637 
638  /// Write the scalar value under a specified group - float value.
639  void WriteScalarValue(const hid_t ParentGroup,
640  const char * DatasetName,
641  const float Value);
642  /// Write the scalar value under a specified group - index value.
643  void WriteScalarValue(const hid_t ParentGroup,
644  const char * DatasetName,
645  const size_t Value);
646 
647  /// Read the scalar value under a specified group - float value.
648  void ReadScalarValue(const hid_t ParentGroup,
649  const char * DatasetName,
650  float & Value);
651  /// Read the scalar value under a specified group - index value.
652  void ReadScalarValue(const hid_t ParentGroup,
653  const char * DatasetName,
654  size_t & Value);
655 
656  /// Read data from the dataset under a specified group - float dataset.
657  void ReadCompleteDataset(const hid_t ParentGroup,
658  const char * DatasetName,
659  const TDimensionSizes & DimensionSizes,
660  float * Data);
661  /// Read data from the dataset under a specified group - index dataset.
662  void ReadCompleteDataset(const hid_t ParentGroup,
663  const char * DatasetName,
664  const TDimensionSizes & DimensionSizes,
665  size_t * Data);
666 
667 
668  //------------------- Attributes Read/Write operations -------------------//
669 
670  /// Get dimension sizes of the dataset under a specified group.
671  TDimensionSizes GetDatasetDimensionSizes(const hid_t ParentGroup,
672  const char * DatasetName);
673 
674  /// Get number of dimensions of the dataset under a specified group.
675  size_t GetDatasetNumberOfDimensions(const hid_t ParentGroup,
676  const char * DatasetName);
677 
678  /// Get dataset element count under a specified group.
679  size_t GetDatasetElementCount(const hid_t ParentGroup,
680  const char * DatasetName);
681 
682 
683  /// Write matrix data type into the dataset under a specified group.
684  void WriteMatrixDataType(const hid_t ParentGroup,
685  const char * DatasetName,
686  const THDF5_MatrixDataType & MatrixDataType);
687 
688  /// Write matrix domain type into the dataset under the root group.
689  void WriteMatrixDomainType(const hid_t ParentGroup,
690  const char * DatasetName,
691  const THDF5_MatrixDomainType & MatrixDomainType);
692 
693  /// Read matrix data type from the dataset.
694  THDF5_File::THDF5_MatrixDataType ReadMatrixDataType(const hid_t ParentGroup,
695  const char * DatasetName);
696  /// Read matrix domain type from the dataset under a specified group
697  THDF5_File::THDF5_MatrixDomainType ReadMatrixDomainType(const hid_t ParentGroup,
698  const char * DatasetName);
699 
700  /// Write string attribute into the dataset under the root group.
701  void WriteStringAttribute(const hid_t ParentGroup,
702  const char * DatasetName,
703  const char * AttributeName,
704  const string & Value);
705  /// Read string attribute from the dataset under the root group.
706  string ReadStringAttribute (const hid_t ParentGroup,
707  const char * DatasetName,
708  const char * AttributeName);
709 
710  /// Destructor
711  virtual ~THDF5_File();
712 
713  protected:
714 
715  /// Copy constructor is not allowed for public.
716  THDF5_File(const THDF5_File& src);
717  /// Operator = is not allowed for public.
718  THDF5_File & operator = (const THDF5_File& src);
719 
720 
721  private:
722  /// String representation of the Domain type in the HDF5 file
723  static const char * HDF5_MatrixDomainTypeName;
724  /// String representation of the Data type in the HDF5 file
725  static const char * HDF5_MatrixDataTypeName;
726 
727  /// String representation of different domain types
728  static const string HDF5_MatrixDomainTypeNames[];
729  /// String representation of different data types
730  static const string HDF5_MatrixDataTypeNames[];
731 
732  /// HDF file handle
733  hid_t HDF5_FileId;
734  /// File name
735  string FileName;
736 
737 }; // THDF5_File
738 //------------------------------------------------------------------------------
739 
740 
741 
742 /**
743  * @class THDF5_FileHeader
744  * @brief Class for HDF5 header
745  * @details This class manages all information that can be stored in the input
746  * output or checkpoint file.
747  *
748  */
749 class THDF5_FileHeader
750 {
751  public:
752 
753  /**
754  * @enum THDF5_FileHeaderItems
755  * @brief List of all header items
756  */
757  enum THDF5_FileHeaderItems{hdf5_fhi_created_by = 0,
758  hdf5_fhi_creation_date = 1,
759  hdf5_fhi_file_description = 2,
760  hdf5_fhi_major_version = 3,
761  hdf5_fhi_minor_version = 4,
762  hdf5_fhi_file_type = 5,
763  hdf5_fhi_host_name = 6,
764  hdf5_fhi_total_memory_consumption = 7,
765  hdf5_fhi_peak_core_memory_consumption = 8,
766  hdf5_fhi_total_execution_time = 9,
767  hdf5_fhi_data_load_time = 10,
768  hdf5_fhi_preprocessing_time = 11,
769  hdf5_fhi_simulation_time = 12,
770  hdf5_fhi_postprocessing_time = 13,
771  hdf5_fhi_number_of_cores = 14
772  };
773 
774  /**
775  * @enum THDF5_FileType
776  * @brief HDF5 file type
777  */
778  enum THDF5_FileType {hdf5_ft_input = 0,
779  hdf5_ft_output = 1,
780  hdf5_ft_checkpoint = 2,
781  hdf5_ft_unknown = 3};
782 
783  /**
784  * @enum THDF5_FileVersion
785  * @brief HDF5 file version
786  */
787  enum THDF5_FileVersion {hdf5_fv_10 = 0,
788  hdf5_fv_11 = 1,
789  hdf5_fv_unknown = 2};
790 
791 
792  /// Constructor.
793  THDF5_FileHeader();
794  /// Copy constructor.
795  THDF5_FileHeader(const THDF5_FileHeader & other);
796  /// Destructor.
797  ~THDF5_FileHeader();
798 
799  /// Read header from the input file.
800  void ReadHeaderFromInputFile(THDF5_File & InputFile);
801  /// Read Header from output file (necessary for checkpoint-restart).
802  void ReadHeaderFromOutputFile(THDF5_File & OutputFile);
803  /// Read Header from checkpoint file (necessary for checkpoint-restart).
804  void ReadHeaderFromCheckpointFile(THDF5_File & CheckpointFile);
805 
806  /// Write header to the output file
807  void WriteHeaderToOutputFile(THDF5_File & OutputFile);
808  /// Write header to the output file
809  void WriteHeaderToCheckpointFile(THDF5_File & CheckpointFile);
810 
811  /**
812  * @brief Set code name.
813  * @details Set code name to the header.
814  * @param CodeName - code version
815  */
816  void SetCodeName(const string& CodeName)
817  {
818  HDF5_FileHeaderValues[hdf5_fhi_created_by] = CodeName;
819  };
820 
821  /// Set creation time.
822  void SetActualCreationTime();
823 
824  /**
825  * @brief Get string version of current Major version.
826  * @details Get string version of current Major version.
827  * @return current version
828  */
829  static string GetCurrentHDF5_MajorVersion()
830  {
831  return HDF5_MajorFileVersionsNames[0];
832  };
833 
834  /**
835  * @brief Get string version of current Minor version.
836  * @details Get string version of current Minor version.
837  * @return current minor version
838  */
839  static string GetCurrentHDF5_MinorVersion()
840  {
841  return HDF5_MinorFileVersionsNames[1];
842  };
843 
844  /// Set major file version.
845  void SetMajorFileVersion()
846  {
847  HDF5_FileHeaderValues[hdf5_fhi_major_version] = GetCurrentHDF5_MajorVersion();
848  };
849  /// Set minor file version.
850  void SetMinorFileVersion()
851  {
852  HDF5_FileHeaderValues[hdf5_fhi_minor_version] = GetCurrentHDF5_MinorVersion();
853  };
854 
855  /// Set major file version in a string.
856  THDF5_FileVersion GetFileVersion();
857 
858  /**
859  * @brief Check major file version.
860  * @details Check major file version.
861  * @return true if ok
862  */
863  bool CheckMajorFileVersion()
864  {
865  return (HDF5_FileHeaderValues[hdf5_fhi_major_version] == GetCurrentHDF5_MajorVersion());
866  };
867  /**
868  * @brief Check minor file version.
869  * @details Check minor file version.
870  * @return true if ok
871  */
872  bool CheckMinorFileVersion()
873  {
874  return (HDF5_FileHeaderValues[hdf5_fhi_minor_version] <= GetCurrentHDF5_MinorVersion());
875  };
876 
877  /// Get File type.
878  THDF5_FileHeader::THDF5_FileType GetFileType();
879  /// Set file type.
880  void SetFileType(const THDF5_FileHeader::THDF5_FileType FileType);
881 
882  /// Set host name.
883  void SetHostName();
884  /// Set memory consumption.
885  void SetMemoryConsumption(size_t TotalMemory);
886  /// Set execution times.
887  void SetExecutionTimes(const double TotalTime,
888  const double LoadTime,
889  const double PreProcessingTime,
890  const double SimulationTime,
891  const double PostprocessingTime);
892 
893  /// Get execution times stored in the output file header.
894  void GetExecutionTimes(double& TotalTime,
895  double& LoadTime,
896  double& PreProcessingTime,
897  double& SimulationTime,
898  double& PostprocessingTime);
899  /// Set number of cores.
900  void SetNumberOfCores();
901 
902 private:
903  /// Populate the map with the header items.
904  void PopulateHeaderFileMap();
905 
906  /// map for the header values.
907  map<THDF5_FileHeaderItems, string> HDF5_FileHeaderValues;
908  /// map for the header names.
909  map<THDF5_FileHeaderItems, string> HDF5_FileHeaderNames;
910 
911  ///String representation of different file types.
912  static const string HDF5_FileTypesNames[];
913  /// String representations of Major file versions.
914  static const string HDF5_MajorFileVersionsNames[];
915  /// String representations of Major file versions.
916  static const string HDF5_MinorFileVersionsNames[];
917 
918 };// THDF5_FileHeader
919 //------------------------------------------------------------------------------
920 
921 #endif /* THDF5_FILE_H */
THDF5_FileHeader
Class for HDF5 header.
Definition: HDF5_File.h:749
THDF5_FileHeader::HDF5_FileHeaderValues
map< THDF5_FileHeaderItems, string > HDF5_FileHeaderValues
map for the header values.
Definition: HDF5_File.h:907
THDF5_File::FileName
string FileName
File name.
Definition: HDF5_File.h:735
THDF5_File::HDF5_MatrixDomainTypeName
static const char * HDF5_MatrixDomainTypeName
String representation of the Domain type in the HDF5 file.
Definition: HDF5_File.h:723
THDF5_FileHeader::SetMinorFileVersion
void SetMinorFileVersion()
Set minor file version.
Definition: HDF5_File.h:850
THDF5_FileHeader::SetMajorFileVersion
void SetMajorFileVersion()
Set major file version.
Definition: HDF5_File.h:845
THDF5_FileHeader::THDF5_FileVersion
THDF5_FileVersion
HDF5 file version.
Definition: HDF5_File.h:787
THDF5_File::IsAccessible
static bool IsAccessible(const char *FileName)
Does the file exist? static method.
Definition: HDF5_File.h:550
THDF5_File::IsOpened
bool IsOpened() const
Is the file opened?
Definition: HDF5_File.h:539
THDF5_FileHeader::THDF5_FileType
THDF5_FileType
HDF5 file type.
Definition: HDF5_File.h:778
THDF5_FileHeader::GetCurrentHDF5_MajorVersion
static string GetCurrentHDF5_MajorVersion()
Get string version of current Major version.
Definition: HDF5_File.h:829
THDF5_File::HDF5_MatrixDataTypeName
static const char * HDF5_MatrixDataTypeName
String representation of the Data type in the HDF5 file.
Definition: HDF5_File.h:725
THDF5_FileHeader::THDF5_FileHeaderItems
THDF5_FileHeaderItems
List of all header items.
Definition: HDF5_File.h:757
THDF5_File::HDF5_FileId
hid_t HDF5_FileId
HDF file handle.
Definition: HDF5_File.h:733
THDF5_File::GetRootGroup
hid_t GetRootGroup() const
Get handle to the root group.
Definition: HDF5_File.h:581
DimensionSizes.h
The header file containing the structure with 3D dimension sizes.
THDF5_FileHeader::GetCurrentHDF5_MinorVersion
static string GetCurrentHDF5_MinorVersion()
Get string version of current Minor version.
Definition: HDF5_File.h:839
THDF5_FileHeader::CheckMajorFileVersion
bool CheckMajorFileVersion()
Check major file version.
Definition: HDF5_File.h:863
THDF5_FileHeader::CheckMinorFileVersion
bool CheckMinorFileVersion()
Check minor file version.
Definition: HDF5_File.h:872
THDF5_FileHeader::HDF5_FileHeaderNames
map< THDF5_FileHeaderItems, string > HDF5_FileHeaderNames
map for the header names.
Definition: HDF5_File.h:909
THDF5_FileHeader::SetCodeName
void SetCodeName(const string &CodeName)
Set code name.
Definition: HDF5_File.h:816
THDF5_File::THDF5_MatrixDomainType
THDF5_MatrixDomainType
HDF5 Matrix domain type (real or complex).
Definition: HDF5_File.h:520
THDF5_File::THDF5_MatrixDataType
THDF5_MatrixDataType
HDF5 matrix data type (float or uint64).
Definition: HDF5_File.h:514
THDF5_File
Class wrapping the HDF5 routines.
Definition: HDF5_File.h:506
TDimensionSizes
Structure with 4D dimension sizes (3 in space and 1 in time).
Definition: DimensionSizes.h:63