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

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

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