| 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
OutputHDF5Stream.h
Go to the documentation of this file.
1 /**
2 * @file OutputHDF5Stream.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 of classes responsible for storing output
9 * quantities into the output HDF5 file.
10 *
11 * @version kspaceFirstOrder3D 2.15
12 *
13 * @date 11 July 2012, 10:30 (created) \n
14 * 26 September 2014, 18:33 (revised)
15 *
16 * @section License
17 * This file is part of the C++ extension of the k-Wave Toolbox (http://www.k-wave.org).\n
18 * Copyright (C) 2014 Jiri Jaros and Bradley Treeby
19 *
20 * This file is part of k-Wave. k-Wave is free software: you can redistribute it
21 * and/or modify it under the terms of the GNU Lesser General Public License as
22 * published by the Free Software Foundation, either version 3 of the License,
23 * or (at your option) any later version.
24 *
25 * k-Wave is distributed in the hope that it will be useful, but
26 * WITHOUT ANY WARRANTY; without even the implied warranty of
27 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
28 * See the GNU Lesser General Public License for more details.
29 *
30 * You should have received a copy of the GNU Lesser General Public License
31 * along with k-Wave. If not, see <http://www.gnu.org/licenses/>.
32 */
33
34
35 #ifndef OUTPUTHDF5STREAM_H
36 #define OUTPUTHDF5STREAM_H
37
38 #include <string>
39 #include <vector>
40 #include <stdexcept>
41
42 #include <MatrixClasses/RealMatrix.h>
43 #include <MatrixClasses/IndexMatrix.h>
44
45 #include <HDF5/HDF5_File.h>
46
47 using namespace std;
48
49 /**
50 * @class TBaseOutputHDF5Stream
51 * @brief Abstract base class for output data streams (sampled data).
52 * @details Abstract base class for output data streams (sampled data).
53 *
54 */
55 class TBaseOutputHDF5Stream
56 {
57 public:
58
59 /**
60 * @enum TReductionOperator
61 * @brief How to aggregate data.
62 * @details How to aggregate data \n
63 * roNONE - store actual data (time series)
64 * roRMS - calculate root mean square \n
65 * roMAX - store maximum
66 * roMIN - store minimum
67 */
68 enum TReductionOperator
69 {
70 roNONE, roRMS, roMAX, roMIN
71 };
72
73 /**
74 * @brief Constructor - there is no sensor mask by default!
75 * @details Constructor - there is no sensor mask by default!
76 * it links the HDF5 dataset, source (sampled matrix) and the reduction
77 * operator together. The constructor DOES NOT allocate memory because the
78 * size of the sensor mask is not known at the time the instance of
79 * the class is being created.
80 *
81 * @param [in] HDF5_File - Handle to the HDF5 (output) file
82 * @param [in] HDF5_RootObjectName - The root object that stores the sample
83 * data (dataset or group)
84 * @param [in] SourceMatrix - The source matrix (only real matrices
85 * are supported)
86 * @param [in] ReductionOp - Reduction operator
87 * @param [in] BufferToReuse - An external buffer can be used to line
88 * up the grid points
89 */
90 TBaseOutputHDF5Stream(THDF5_File & HDF5_File,
91 const char * HDF5_RootObjectName,
92 const TRealMatrix & SourceMatrix,
93 const TReductionOperator ReductionOp,
94 float * BufferToReuse = NULL)
95 : HDF5_File (HDF5_File),
96 HDF5_RootObjectName(NULL),
97 SourceMatrix (SourceMatrix),
98 ReductionOp (ReductionOp),
99 BufferReuse (BufferToReuse != NULL),
100 BufferSize (0),
101 StoreBuffer (BufferToReuse)
102 {
103 // copy the dataset name (just for sure)
104 this->HDF5_RootObjectName = new char[strlen(HDF5_RootObjectName)];
105 strcpy(this->HDF5_RootObjectName, HDF5_RootObjectName);
106 };
107
108 /**
109 * @brief Destructor.
110 * @details Destructor.
111 */
112 virtual ~TBaseOutputHDF5Stream()
113 {
114 delete [] HDF5_RootObjectName;
115 };
116
117 /// Create a HDF5 stream and allocate data for it.
118 virtual void Create() = 0;
119
120 /// Reopen the output stream after restart.
121 virtual void Reopen() = 0;
122
123 /// Sample data into buffer, apply reduction or flush to disk - based on a sensor mask.
124 virtual void Sample() = 0;
125
126 /// Apply post-processing on the buffer and flush it to the file.
127 virtual void PostProcess();
128
129 /// Checkpoint the stream.
130 virtual void Checkpoint() = 0;
131
132 /// Close stream (apply post-processing if necessary, flush data and close).
133 virtual void Close() = 0;
134
135 protected:
136 /// Default constructor not allowed.
137 TBaseOutputHDF5Stream();
138 /// Copy constructor not allowed.
139 TBaseOutputHDF5Stream(const TBaseOutputHDF5Stream & src);
140 /// Operator = not allowed (we don't want any data movements).
141 TBaseOutputHDF5Stream & operator = (const TBaseOutputHDF5Stream & src);
142
143 /// A generic function to allocate memory - not used in the base class.
144 virtual void AllocateMemory();
145 /// A generic function to free memory - not used in the base class.
146 virtual void FreeMemory();
147
148 /// HDF5 file handle.
149 THDF5_File & HDF5_File;
150 /// Dataset name.
151 char * HDF5_RootObjectName;
152 /// Source matrix to be sampled.
153 const TRealMatrix& SourceMatrix;
154 /// Reduction operator.
155 const TReductionOperator ReductionOp;
156
157 /// if true, the container reuses e.g. Temp_1_RS3D, Temp_2_RS3D, Temp_3_RS3D.
158 bool BufferReuse;
159 /// Buffer size.
160 size_t BufferSize;
161 /// Temporary buffer for store - only if Buffer Reuse = false!
162 float * StoreBuffer;
163
164 /// chunk size of 4MB in number of float elements.
165 static const size_t ChunkSize_4MB = 1048576;
166
167 /// The minimum number of elements to start sampling in parallel (4MB).
168 static const size_t MinGridpointsToSampleInParallel = 1048576;
169 };// end of TOutputHDF5Stream
170 //------------------------------------------------------------------------------
171
172
173 /**
174 * @class TIndexOutputHDF5Stream.
175 * @brief Output stream for quantities sampled by an index sensor mask.
176 * @details Output stream for quantities sampled by an index sensor mask.
177 * This class writes data to a single dataset in a root group of the HDF5
178 * file (time-series as well as aggregations).
179 *
180 */
181 class TIndexOutputHDF5Stream : public TBaseOutputHDF5Stream
182 {
183 public:
184
185 /// Constructor - links the HDF5 dataset, SourceMatrix, and SensorMask together.
186 TIndexOutputHDF5Stream(THDF5_File & HDF5_File,
187 const char * HDF5_ObjectName,
188 const TRealMatrix & SourceMatrix,
189 const TIndexMatrix & SensorMask,
190 const TReductionOperator ReductionOp,
191 float * BufferToReuse = NULL);
192
193
194 /// Destructor.
195 virtual ~TIndexOutputHDF5Stream();
196
197 /// Create a HDF5 stream and allocate data for it.
198 virtual void Create();
199
200 /// Reopen the output stream after restart and reload data.
201 virtual void Reopen();
202
203 /// Sample data into buffer, apply reduction or flush to disk - based on a sensor mask.
204 virtual void Sample();
205
206 /// Apply post-processing on the buffer and flush it to the file.
207 virtual void PostProcess();
208
209 /// Checkpoint the stream.
210 virtual void Checkpoint();
211
212 /// Close stream (apply post-processing if necessary, flush data and close).
213 virtual void Close();
214
215 protected:
216
217 /// Flush the buffer to the file.
218 virtual void FlushBufferToFile();
219
220 /// Sensor mask to sample data.
221 const TIndexMatrix & SensorMask;
222 /// Handle to a HDF5 dataset.
223 hid_t HDF5_DatasetId;
224
225 /// Time step to store (N/A for aggregated).
226 size_t SampledTimeStep;
227 }; // end of TIndexOutputHDF5Stream
228 //------------------------------------------------------------------------------
229
230
231 /**
232 * @class TCuboidOutputHDF5Stream
233 * @brief Output stream for quantities sampled by a cuboid corner sensor mask.
234 * @details Output stream for quantities sampled by a cuboid corner sensor mask.
235 * This class writes data into separated datasets (one per cuboid) under
236 * a given dataset in the HDF5 file (time-series as well as aggregations).
237 *
238 */
239 class TCuboidOutputHDF5Stream : public TBaseOutputHDF5Stream
240 {
241 public:
242 /// Constructor - links the HDF5 File, SourceMatrix, and SensorMask together.
243 TCuboidOutputHDF5Stream(THDF5_File & HDF5_File,
244 const char * HDF5_GroupName,
245 const TRealMatrix & SourceMatrix,
246 const TIndexMatrix & SensorMask,
247 const TReductionOperator ReductionOp,
248 float * BufferToReuse = NULL);
249
250 /// Destructor.
251 virtual ~TCuboidOutputHDF5Stream();
252
253 /// Create a HDF5 stream and allocate data for it.
254 virtual void Create();
255
256 /// Reopen the output stream after restart and reload data.
257 virtual void Reopen();
258
259 /// Sample data into buffer and apply reduction, or flush to disk - based on a sensor mask.
260 virtual void Sample();
261
262 /// Apply post-processing on the buffer and flush it to the file.
263 virtual void PostProcess();
264
265 /// Checkpoint the stream and close.
266 virtual void Checkpoint();
267
268 /// Close stream (apply post-processing if necessary, flush data and close).
269 virtual void Close();
270
271 protected:
272 /**
273 * @struct TCuboidInfo
274 * @brief This structure information about a HDF5 dataset (one cuboid).
275 * Namely, its HDF5_ID, Starting position in a lineup buffer.
276 */
277 struct TCuboidInfo
278 {
279 /// ID of the dataset storing the given cuboid.
280 hid_t HDF5_CuboidId;
281 /// Having a single buffer for all cuboids, where this one starts.
282 size_t StartingPossitionInBuffer;
283 };
284
285 /// Create a new dataset for a given cuboid specified by index (order).
286 virtual hid_t CreateCuboidDataset(const size_t Index);
287
288 /// Flush the buffer to the file.
289 virtual void FlushBufferToFile();
290
291 /// Sensor mask to sample data.
292 const TIndexMatrix & SensorMask;
293
294 /// Handle to a HDF5 dataset.
295 hid_t HDF5_GroupId;
296
297 /// vector keeping handles and positions of all cuboids
298 std::vector<TCuboidInfo> CuboidsInfo;
299
300 /// Timestep to store (N/A for aggregated).
301 size_t SampledTimeStep;
302
303 };// end of TCubodiOutputHDF5Stream
304 //------------------------------------------------------------------------------
305
306
307
308
309 /**
310 * @class TWholeDomainOutputHDF5Stream
311 * @brief Output stream for quantities sampled in the whole domain.
312 * @details Output stream for quantities sampled in the whole domain.
313 * The data is stored in a single dataset (aggregated quantities only).
314 */
315 class TWholeDomainOutputHDF5Stream : public TBaseOutputHDF5Stream
316 {
317
318 public:
319 /// Constructor - links the HDF5 File, SourceMatrix, and SensorMask together.
320 TWholeDomainOutputHDF5Stream(THDF5_File & HDF5_File,
321 const char * HDF5_DatasetName,
322 const TRealMatrix & SourceMatrix,
323 const TReductionOperator ReductionOp,
324 float * BufferToReuse = NULL);
325
326 /// Destructor.
327 virtual ~TWholeDomainOutputHDF5Stream();
328
329 /// Create a HDF5 stream and allocate data for it.
330 virtual void Create();
331
332 /// Reopen the output stream after restart and reload data.
333 virtual void Reopen();
334
335 /// Sample data into buffer and apply reduction, or flush to disk (no sensor mask here).
336 virtual void Sample();
337
338 /// Apply post-processing on the buffer and flush it to the file.
339 virtual void PostProcess();
340
341 ///Checkpoint the stream and close.
342 virtual void Checkpoint();
343
344 /// Close stream (apply post-processing if necessary, flush data and close).
345 virtual void Close();
346
347 protected:
348 /// Flush the buffer to the file.
349 virtual void FlushBufferToFile();
350
351 /// Handle to a HDF5 dataset.
352 hid_t HDF5_DatasetId;
353
354 /// Time step to store (N/A for aggregated).
355 size_t SampledTimeStep;
356 };// end of TWholeDomainOutputHDF5Stream
357 //------------------------------------------------------------------------------
358
359 #endif /* OUTPUTREALSTREAM_H */
TIndexOutputHDF5Stream::SampledTimeStep
size_t SampledTimeStep
Time step to store (N/A for aggregated).
Definition: OutputHDF5Stream.h:226
TCuboidOutputHDF5Stream::CuboidsInfo
std::vector< TCuboidInfo > CuboidsInfo
vector keeping handles and positions of all cuboids
Definition: OutputHDF5Stream.h:298
TBaseOutputHDF5Stream::TReductionOperator
TReductionOperator
How to aggregate data.
Definition: OutputHDF5Stream.h:68
TBaseOutputHDF5Stream::HDF5_RootObjectName
char * HDF5_RootObjectName
Dataset name.
Definition: OutputHDF5Stream.h:151
TWholeDomainOutputHDF5Stream
Output stream for quantities sampled in the whole domain.
Definition: OutputHDF5Stream.h:315
TCuboidOutputHDF5Stream
Output stream for quantities sampled by a cuboid corner sensor mask.
Definition: OutputHDF5Stream.h:239
TBaseOutputHDF5Stream::ReductionOp
const TReductionOperator ReductionOp
Reduction operator.
Definition: OutputHDF5Stream.h:155
TIndexOutputHDF5Stream::SensorMask
const TIndexMatrix & SensorMask
Sensor mask to sample data.
Definition: OutputHDF5Stream.h:221
RealMatrix.h
The header file containing the class for real matrices.
TBaseOutputHDF5Stream::BufferReuse
bool BufferReuse
if true, the container reuses e.g. Temp_1_RS3D, Temp_2_RS3D, Temp_3_RS3D.
Definition: OutputHDF5Stream.h:158
HDF5_File.h
The header file containing the HDF5 related classes.
TCuboidOutputHDF5Stream::SensorMask
const TIndexMatrix & SensorMask
Sensor mask to sample data.
Definition: OutputHDF5Stream.h:292
TCuboidOutputHDF5Stream::TCuboidInfo::HDF5_CuboidId
hid_t HDF5_CuboidId
ID of the dataset storing the given cuboid.
Definition: OutputHDF5Stream.h:280
TCuboidOutputHDF5Stream::SampledTimeStep
size_t SampledTimeStep
Timestep to store (N/A for aggregated).
Definition: OutputHDF5Stream.h:301
TBaseOutputHDF5Stream::StoreBuffer
float * StoreBuffer
Temporary buffer for store - only if Buffer Reuse = false!
Definition: OutputHDF5Stream.h:162
TBaseOutputHDF5Stream::SourceMatrix
const TRealMatrix & SourceMatrix
Source matrix to be sampled.
Definition: OutputHDF5Stream.h:153
TIndexOutputHDF5Stream
Output stream for quantities sampled by an index sensor mask.
Definition: OutputHDF5Stream.h:181
IndexMatrix.h
The header file containing the class for 64b integer matrices.
TBaseOutputHDF5Stream
Abstract base class for output data streams (sampled data).
Definition: OutputHDF5Stream.h:55
TBaseOutputHDF5Stream::TBaseOutputHDF5Stream
TBaseOutputHDF5Stream(THDF5_File &HDF5_File, const char *HDF5_RootObjectName, const TRealMatrix &SourceMatrix, const TReductionOperator ReductionOp, float *BufferToReuse=NULL)
Constructor - there is no sensor mask by default!
Definition: OutputHDF5Stream.h:90
TRealMatrix
The class for real matrices.
Definition: RealMatrix.h:48
TCuboidOutputHDF5Stream::TCuboidInfo
This structure information about a HDF5 dataset (one cuboid). Namely, its HDF5_ID, Starting position in a lineup buffer.
Definition: OutputHDF5Stream.h:277
TIndexMatrix
The class for 64b unsigned integers (indices). It is used for sensor_mask_index or sensor_corners_mas...
Definition: IndexMatrix.h:50
TWholeDomainOutputHDF5Stream::SampledTimeStep
size_t SampledTimeStep
Time step to store (N/A for aggregated).
Definition: OutputHDF5Stream.h:355
TBaseOutputHDF5Stream::BufferSize
size_t BufferSize
Buffer size.
Definition: OutputHDF5Stream.h:160
TCuboidOutputHDF5Stream::TCuboidInfo::StartingPossitionInBuffer
size_t StartingPossitionInBuffer
Having a single buffer for all cuboids, where this one starts.
Definition: OutputHDF5Stream.h:282
TCuboidOutputHDF5Stream::HDF5_GroupId
hid_t HDF5_GroupId
Handle to a HDF5 dataset.
Definition: OutputHDF5Stream.h:295
TBaseOutputHDF5Stream::~TBaseOutputHDF5Stream
virtual ~TBaseOutputHDF5Stream()
Destructor.
Definition: OutputHDF5Stream.h:112
TWholeDomainOutputHDF5Stream::HDF5_DatasetId
hid_t HDF5_DatasetId
Handle to a HDF5 dataset.
Definition: OutputHDF5Stream.h:352
TIndexOutputHDF5Stream::HDF5_DatasetId
hid_t HDF5_DatasetId
Handle to a HDF5 dataset.
Definition: OutputHDF5Stream.h:223
TBaseOutputHDF5Stream::HDF5_File
THDF5_File & HDF5_File
HDF5 file handle.
Definition: OutputHDF5Stream.h:149
THDF5_File
Class wrapping the HDF5 routines.
Definition: HDF5_File.h:506