| 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
CommandLineParameters.h
Go to the documentation of this file.
1 /**
2 * @file CommandLineParameters.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 command line parameters.
9 *
10 * @version kspaceFirstOrder3D 2.15
11 *
12 * @date 29 August 2012, 11:25 (created) \n
13 * 02 October 2014, 12:15 (revised)
14 *
15 * @section Params Command Line Parameters
16 *
17 * The C++ code requires two mandatory parameters and accepts a few optional parameters and flags.
18 * The mandatory parameters \c -i and \c -o specify the input and output file. The
19 * file names respect the path conventions for particular operating system.
20 * If any of the files is not specified, cannot be found or created, an error
21 * message is shown.
22 *
23 * The \c -t parameter sets the number of threads used, which defaults the system maximum.
24 * On CPUs with Intel Hyper-Threading (HT), the performance is sometimes better if HT
25 * is disabled in the BIOS settings. If HT is switched on, the default will be to
26 * spawn twice as many threads as there are physical processor cores, which may but again
27 * may not slow down the code execution. Therefore, if the HT is on, try specifying the
28 * number of threads manually for best performance (e.g. 4 for Intel i7). We
29 * recommend experimenting with this parameter to find the best configuration.
30 * Note, if there are other tasks being executed on the system, it might be useful
31 * to further limit the number of threads to prevent system overload.
32 *
33 * The \c -r parameter specifies how often information about the simulation progress
34 * is printed out to the command line. By default, the C++ code prints out the
35 * progress of the simulation, the elapsed time, and the estimated time of
36 * completion in intervals corresponding to 5% of the total number of times steps.
37 *
38 * The \c -c parameter specifies the compression level used by the ZIP library to
39 * reduce the size of the output file. The actual compression rate is highly dependent
40 * on the shape of the sensor mask and the range of stored quantities. In general,
41 * the output data is very hard to compress, and using higher compression levels
42 * can greatly increase the time to save data while not having a large impact on
43 * the final file size. That's why we decided to disable compression in default settings.
44 *
45 * The \c <tt>--benchmark</tt> parameter enables the total length of simulation (i.e.,
46 * the number of time steps) to be overridden by setting a new number of time
47 * steps to simulate. This is particularly useful for performance evaluation and
48 * benchmarking. As the code performance is relatively stable, 50-100 time steps is
49 * usually enough to predict the simulation duration. This parameter can also be
50 * used to quickly find the ideal number of CPU threads to use.
51 *
52 *
53 *
54 * For jobs that are expected to run for a very long time, it may be useful to
55 * checkpoint and restart the execution. One motivation is the wall clock limit
56 * per task on clusters where jobs must fit within a given time span
57 * (e.g. 24 hours). The second motivation is a level of fault-tolerance, where
58 * you can back up the state of the simulation after a predefined period.
59 * To enable checkpoint-restart, the user is asked to specify a file to store the
60 * actual state of the simulation by <tt>--checkpoint_file</tt> and the
61 * period in seconds after which the simulation will be interrupted by <tt>--checkpoint_interval</tt>.
62 * When running on a cluster, please allocate enough time for the checkpoint procedure
63 * that can take a non-negligible amount of time (7 matrices have to be stored in
64 * the checkpoint file and all aggregated quantities are flushed into the output file).
65 *
66 * When controlling a multi-leg simulation by a script loop, the parameters of the code
67 * remains the same in all legs. The first leg of the simulation creates a checkpoint
68 * file while the last one deletes it. If the checkpoint file is not found the
69 * simulation starts from the beginning. In order to find out how many steps have been
70 * finished, please open the output file and read the variable <tt>t_index</tt>.
71 *
72 *
73 * The \c -h and \c --help parameters print all the parameters of the C++ code.
74 * The <tt> --version </tt>parameter reports detail information about the code useful for
75 * debugging and bug reports. It prints out the internal version, the build date and time, the
76 * git hash allowing us to track the version of the source code, the operating system,
77 * the compiler name and version and the instruction set used.
78 *
79 *
80 * The remaining flags specify the output quantities to be recorded during the
81 * simulation and stored on disk analogous to the sensor.record input. If
82 * the \c -p or \c --p\_raw flags are set (these are equivalent), a time series of
83 * the acoustic pressure at the grid points specified by the sensor mask is
84 * recorded. If the \c --p_rms, \c --p_max, \c --p_min flags are set,
85 * the root mean square and/or maximum and/or minimum values of the pressure at
86 * the grid points specified by the sensor mask are recorded. If the
87 * \c --p_final flag is set, the values for the entire acoustic pressure field
88 * in the final time step of the simulation is stored (this will always include
89 * the PML, regardless of the setting for <tt> `PMLInside'</tt>).
90 * The flags \c --p_max_all and \c --p_min_all allow to calculate the maximum and
91 * minimum values over the entire acoustic pressure field, regardless on the shape
92 * of the sensor mask.
93 * Flags to record the acoustic particle velocity are defined in an analogous fashion.
94 * For proper calculation of acoustic intensity, the particle velocity has to be
95 * shifted onto the same grid as the acoustic pressure. This can be done by setting
96 * \c --u_non_staggered_raw flag, that first shifts the particle velocity and then
97 * samples the grid points specified by the sensor mask. Since the shift operation
98 * requires additional FFTs, the impact on the simulation time may be significant.
99 *
100 * Any combination of <tt>p</tt> and <tt>u</tt> flags is admissible. If no output flag is set,
101 * a time-series for the acoustic pressure is recorded. If it is not necessary
102 * to collect the output quantities over the entire simulation, the starting time
103 * step when the collection begins can be specified using the -s parameter.
104 * Note, the index for the first time step is 1 (this follows the MATLAB indexing convention).
105 *
106 * The \c --copy_sensor_mask will copy the sensor from the input file to the output
107 * one at the end of the simulation. This helps in post-processing and visualisation of
108 * the outputs.
109 *
110 \verbatim
111 ---------------------------------- Usage ---------------------------------
112 Mandatory parameters:
113 -i <input_file_name> : HDF5 input file
114 -o <output_file_name> : HDF5 output file
115
116 Optional parameters:
117 -t <num_threads> : Number of CPU threads
118 (default = 4)
119 -r <interval_in_%> : Progress print interval
120 (default = 5%)
121 -c <comp_level> : Output file compression level <0,9>
122 (default = 0)
123 --benchmark <steps> : Run a specified number of time steps
124
125 --checkpoint_file <file_name> : HDF5 checkpoint file
126 --checkpoint_interval <seconds> : Stop after a given number of seconds and
127 store the actual state
128
129 -h : Print help
130 --help : Print help
131 --version : Print version
132
133 Output flags:
134 -p : Store acoustic pressure
135 (default if nothing else is on)
136 (the same as --p_raw)
137 --p_raw : Store raw time series of p (default)
138 --p_rms : Store rms of p
139 --p_max : Store max of p
140 --p_min : Store min of p
141 --p_max_all : Store max of p (whole domain)
142 --p_min_all : Store min of p (whole domain)
143 --p_final : Store final pressure field
144
145 -u : Store ux, uy, uz
146 (the same as --u_raw)
147 --u_raw : Store raw time series of ux, uy, uz
148 --u_non_staggered_raw : Store non-staggered raw time series of
149 ux, uy, uz
150 --u_rms : Store rms of ux, uy, uz
151 --u_max : Store max of ux, uy, uz
152 --u_min : Store min of ux, uy, uz
153 --u_max_all : Store max of ux, uy, uz (whole domain)
154 --u_min_all : Store min of ux, uy, uz (whole domain)
155 --u_final : Store final acoustic velocity
156
157 --copy_sensor_mask : Copy sensor mask to the output file
158
159 -s <timestep> : Time step when data collection begins
160 (default = 1)
161 --------------------------------------------------------------------------
162 \endverbatim
163 *
164 *
165 * @section License
166 * This file is part of the C++ extension of the k-Wave Toolbox (http://www.k-wave.org).\n
167 * Copyright (C) 2014 Jiri Jaros and Bradley Treeby
168 *
169 * This file is part of k-Wave. k-Wave is free software: you can redistribute it
170 * and/or modify it under the terms of the GNU Lesser General Public License as
171 * published by the Free Software Foundation, either version 3 of the License,
172 * or (at your option) any later version.
173 *
174 * k-Wave is distributed in the hope that it will be useful, but
175 * WITHOUT ANY WARRANTY; without even the implied warranty of
176 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
177 * See the GNU Lesser General Public License for more details.
178 *
179 * You should have received a copy of the GNU Lesser General Public License
180 * along with k-Wave. If not, see <http://www.gnu.org/licenses/>.
181 */
182
183
184
185
186 #ifndef TCOMMANDLINESPARAMETERS_H
187 #define TCOMMANDLINESPARAMETERS_H
188
189 #include <cstdlib>
190 #include <string>
191
192
193 /**
194 * @class TCommandLineParameters
195 * @brief The class to parse and store command line parameters.
196 * @details The class to parse and store command line parameters.
197 */
198 class TCommandLineParameters
199 {
200 public:
201
202 /// Constructor.
203 TCommandLineParameters();
204 /// Destructor.
205 virtual ~TCommandLineParameters() {};
206
207 /// Get input file name.
208 std::string GetInputFileName() const {return InputFileName;};
209 /// Get output file name.
210 std::string GetOutputFileName() const {return OutputFileName;};
211 /// Get Checkpoint file name.
212 std::string GetCheckpointFileName() const {return CheckpointFileName;};
213
214 /// Is --benchmark flag set?
215 bool IsBenchmarkFlag() const {return BenchmarkFlag;};
216 /// Is --version flag set?
217 bool IsVersion() const {return PrintVersion; };
218 /// Get benchmark time step count.
219 size_t GetBenchmarkTimeStepsCount() const {return BenchmarkTimeStepsCount;};
220
221 /// Get compression level.
222 size_t GetCompressionLevel() const {return CompressionLevel;};
223 /// Get number of threads.
224 size_t GetNumberOfThreads() const {return NumberOfThreads;};
225 /// Get verbose interval.
226 size_t GetVerboseInterval() const {return VerboseInterval;};
227 /// Get start time index when sensor data collection begins.
228 size_t GetStartTimeIndex() const {return StartTimeStep;};
229
230 /// Is checkpoint enabled?
231 bool IsCheckpointEnabled() const {return (CheckpointInterval > 0);};
232 /// Get checkpoint interval.
233 size_t GetCheckpointInterval() const {return CheckpointInterval; };
234
235 /// Is --p_raw set?
236 bool IsStore_p_raw() const {return Store_p_raw;};
237 /// Is --p_rms set?
238 bool IsStore_p_rms() const {return Store_p_rms;};
239 /// Is --p_max set?
240 bool IsStore_p_max() const {return Store_p_max;};
241 /// Is --p_min set?
242 bool IsStore_p_min() const {return Store_p_min;};
243 /// Is --p_max_all set?
244 bool IsStore_p_max_all() const {return Store_p_max_all;};
245 /// Is --p_min_all set?
246 bool IsStore_p_min_all() const {return Store_p_min_all;};
247
248 /// Is --p_final set?
249 bool IsStore_p_final() const {return Store_p_final;};
250
251 /// Is --u_raw set?
252 bool IsStore_u_raw() const {return Store_u_raw;};
253 /// Is --u_non_staggered_raw set?
254 bool IsStore_u_non_staggered_raw() const {return Store_u_non_staggered_raw;};
255 /// Is --u_rms set?
256 bool IsStore_u_rms() const {return Store_u_rms;};
257 /// Is --u_max set?
258 bool IsStore_u_max() const {return Store_u_max;};
259 /// Is --u_min_all set?
260 bool IsStore_u_min() const {return Store_u_min;};
261 /// Is --u_max_all set?
262 bool IsStore_u_max_all() const {return Store_u_max_all;};
263 /// Is --u_min set?
264 bool IsStore_u_min_all() const {return Store_u_min_all;};
265 /// Is --u_final set?
266 bool IsStore_u_final() const {return Store_u_final;};
267
268 /// is --copy_mask set
269 bool IsCopySensorMask() const {return CopySensorMask;};
270
271 /// Print usage and exit.
272 void PrintUsageAndExit();
273 /// Print setup.
274 void PrintSetup();
275 /// Parse command line.
276 void ParseCommandLine(int argc, char** argv);
277
278
279 protected:
280 /// Copy constructor not allowed for public.
281 TCommandLineParameters(const TCommandLineParameters& src);
282
283 /// operator = not allowed for public.
284 TCommandLineParameters& operator = (const TCommandLineParameters& src);
285
286 private:
287 /// Input file name.
288 std::string InputFileName;
289 /// Output file name.
290 std::string OutputFileName;
291 /// Checkpoint file name.
292 std::string CheckpointFileName;
293
294 /// NumberOfThreads value.
295 size_t NumberOfThreads;
296 /// VerboseInterval value.
297 size_t VerboseInterval;
298 /// CompressionLevel value.
299 size_t CompressionLevel;
300
301 /// BenchmarkFlag value.
302 bool BenchmarkFlag;
303 /// BenchmarkTimeStepsCount value.
304 size_t BenchmarkTimeStepsCount;
305 /// Checkpoint interval in seconds.
306 size_t CheckpointInterval;
307
308 /// PrintVersion value.
309 bool PrintVersion;
310
311 /// Store_p_raw value.
312 bool Store_p_raw;
313 /// Store_p_rms value.
314 bool Store_p_rms;
315 /// Store_p_max value.
316 bool Store_p_max;
317 /// Store_p_min value.
318 bool Store_p_min;
319 /// Store_p_max_all value.
320 bool Store_p_max_all;
321 /// Store_p_min_all value.
322 bool Store_p_min_all;
323 /// Store_p_final value.
324 bool Store_p_final;
325
326 /// Store_u_raw value.
327 bool Store_u_raw;
328 /// Store_u_non_staggered_raw value.
329 bool Store_u_non_staggered_raw;
330 /// Store_u_rms value.
331 bool Store_u_rms;
332 /// Store_u_max value.
333 bool Store_u_max;
334 /// Store_u_min value.
335 bool Store_u_min;
336 /// Store_u_max_all value.
337 bool Store_u_max_all;
338 /// Store_u_min_all value.
339 bool Store_u_min_all;
340 /// Store_u_final value.
341 bool Store_u_final;
342
343 /// Copy sensor mask to the output file.
344 bool CopySensorMask;
345 /// StartTimeStep value.
346 size_t StartTimeStep;
347
348
349 /// Default compression level.
350 static const size_t DefaultCompressionLevel = 0;
351 /// Default verbose interval.
352 static const size_t DefaultVerboseInterval = 5;
353 };// end of class TCommandLineParameters
354
355 #endif /* TCOMMANDLINESPARAMETERS_H */
356
TCommandLineParameters::OutputFileName
std::string OutputFileName
Output file name.
Definition: CommandLineParameters.h:290
TCommandLineParameters::Store_u_raw
bool Store_u_raw
Store_u_raw value.
Definition: CommandLineParameters.h:327
TCommandLineParameters::PrintUsageAndExit
void PrintUsageAndExit()
Print usage and exit.
Definition: CommandLineParameters.cpp:92
TCommandLineParameters::GetInputFileName
std::string GetInputFileName() const
Get input file name.
Definition: CommandLineParameters.h:208
TCommandLineParameters::GetNumberOfThreads
size_t GetNumberOfThreads() const
Get number of threads.
Definition: CommandLineParameters.h:224
TCommandLineParameters::CompressionLevel
size_t CompressionLevel
CompressionLevel value.
Definition: CommandLineParameters.h:299
TCommandLineParameters::IsStore_u_rms
bool IsStore_u_rms() const
Is –u_rms set?
Definition: CommandLineParameters.h:256
TCommandLineParameters::GetCheckpointFileName
std::string GetCheckpointFileName() const
Get Checkpoint file name.
Definition: CommandLineParameters.h:212
TCommandLineParameters::GetVerboseInterval
size_t GetVerboseInterval() const
Get verbose interval.
Definition: CommandLineParameters.h:226
TCommandLineParameters::IsStore_p_max
bool IsStore_p_max() const
Is –p_max set?
Definition: CommandLineParameters.h:240
TCommandLineParameters::IsStore_p_min_all
bool IsStore_p_min_all() const
Is –p_min_all set?
Definition: CommandLineParameters.h:246
TCommandLineParameters::IsStore_p_rms
bool IsStore_p_rms() const
Is –p_rms set?
Definition: CommandLineParameters.h:238
TCommandLineParameters::Store_u_min
bool Store_u_min
Store_u_min value.
Definition: CommandLineParameters.h:335
TCommandLineParameters::operator=
TCommandLineParameters & operator=(const TCommandLineParameters &src)
operator = not allowed for public.
TCommandLineParameters::IsStore_p_final
bool IsStore_p_final() const
Is –p_final set?
Definition: CommandLineParameters.h:249
TCommandLineParameters::Store_u_max
bool Store_u_max
Store_u_max value.
Definition: CommandLineParameters.h:333
TCommandLineParameters::GetCheckpointInterval
size_t GetCheckpointInterval() const
Get checkpoint interval.
Definition: CommandLineParameters.h:233
TCommandLineParameters::VerboseInterval
size_t VerboseInterval
VerboseInterval value.
Definition: CommandLineParameters.h:297
TCommandLineParameters::Store_u_non_staggered_raw
bool Store_u_non_staggered_raw
Store_u_non_staggered_raw value.
Definition: CommandLineParameters.h:329
TCommandLineParameters::Store_p_max
bool Store_p_max
Store_p_max value.
Definition: CommandLineParameters.h:316
TCommandLineParameters::IsStore_u_non_staggered_raw
bool IsStore_u_non_staggered_raw() const
Is –u_non_staggered_raw set?
Definition: CommandLineParameters.h:254
TCommandLineParameters::IsStore_p_min
bool IsStore_p_min() const
Is –p_min set?
Definition: CommandLineParameters.h:242
TCommandLineParameters::Store_p_min_all
bool Store_p_min_all
Store_p_min_all value.
Definition: CommandLineParameters.h:322
TCommandLineParameters::IsStore_u_max
bool IsStore_u_max() const
Is –u_max set?
Definition: CommandLineParameters.h:258
TCommandLineParameters::IsCheckpointEnabled
bool IsCheckpointEnabled() const
Is checkpoint enabled?
Definition: CommandLineParameters.h:231
TCommandLineParameters::PrintSetup
void PrintSetup()
Print setup.
Definition: CommandLineParameters.cpp:158
TCommandLineParameters::IsBenchmarkFlag
bool IsBenchmarkFlag() const
Is –benchmark flag set?
Definition: CommandLineParameters.h:215
TCommandLineParameters::Store_p_raw
bool Store_p_raw
Store_p_raw value.
Definition: CommandLineParameters.h:312
TCommandLineParameters::Store_u_final
bool Store_u_final
Store_u_final value.
Definition: CommandLineParameters.h:341
TCommandLineParameters::Store_p_min
bool Store_p_min
Store_p_min value.
Definition: CommandLineParameters.h:318
TCommandLineParameters::GetBenchmarkTimeStepsCount
size_t GetBenchmarkTimeStepsCount() const
Get benchmark time step count.
Definition: CommandLineParameters.h:219
TCommandLineParameters::IsStore_u_final
bool IsStore_u_final() const
Is –u_final set?
Definition: CommandLineParameters.h:266
TCommandLineParameters::InputFileName
std::string InputFileName
Input file name.
Definition: CommandLineParameters.h:288
TCommandLineParameters::Store_p_max_all
bool Store_p_max_all
Store_p_max_all value.
Definition: CommandLineParameters.h:320
TCommandLineParameters::TCommandLineParameters
TCommandLineParameters()
Constructor.
Definition: CommandLineParameters.cpp:67
TCommandLineParameters::IsStore_u_min_all
bool IsStore_u_min_all() const
Is –u_min set?
Definition: CommandLineParameters.h:264
TCommandLineParameters::Store_u_rms
bool Store_u_rms
Store_u_rms value.
Definition: CommandLineParameters.h:331
TCommandLineParameters::GetCompressionLevel
size_t GetCompressionLevel() const
Get compression level.
Definition: CommandLineParameters.h:222
TCommandLineParameters
The class to parse and store command line parameters.
Definition: CommandLineParameters.h:198
TCommandLineParameters::IsStore_u_min
bool IsStore_u_min() const
Is –u_min_all set?
Definition: CommandLineParameters.h:260
TCommandLineParameters::BenchmarkFlag
bool BenchmarkFlag
BenchmarkFlag value.
Definition: CommandLineParameters.h:302
TCommandLineParameters::IsCopySensorMask
bool IsCopySensorMask() const
is –copy_mask set
Definition: CommandLineParameters.h:269
TCommandLineParameters::Store_p_final
bool Store_p_final
Store_p_final value.
Definition: CommandLineParameters.h:324
TCommandLineParameters::StartTimeStep
size_t StartTimeStep
StartTimeStep value.
Definition: CommandLineParameters.h:346
TCommandLineParameters::IsStore_u_raw
bool IsStore_u_raw() const
Is –u_raw set?
Definition: CommandLineParameters.h:252
TCommandLineParameters::Store_u_min_all
bool Store_u_min_all
Store_u_min_all value.
Definition: CommandLineParameters.h:339
TCommandLineParameters::IsStore_p_max_all
bool IsStore_p_max_all() const
Is –p_max_all set?
Definition: CommandLineParameters.h:244
TCommandLineParameters::CheckpointFileName
std::string CheckpointFileName
Checkpoint file name.
Definition: CommandLineParameters.h:292
TCommandLineParameters::DefaultCompressionLevel
static const size_t DefaultCompressionLevel
Default compression level.
Definition: CommandLineParameters.h:350
TCommandLineParameters::CopySensorMask
bool CopySensorMask
Copy sensor mask to the output file.
Definition: CommandLineParameters.h:344
TCommandLineParameters::Store_u_max_all
bool Store_u_max_all
Store_u_max_all value.
Definition: CommandLineParameters.h:337
TCommandLineParameters::BenchmarkTimeStepsCount
size_t BenchmarkTimeStepsCount
BenchmarkTimeStepsCount value.
Definition: CommandLineParameters.h:304
TCommandLineParameters::PrintVersion
bool PrintVersion
PrintVersion value.
Definition: CommandLineParameters.h:309
TCommandLineParameters::CheckpointInterval
size_t CheckpointInterval
Checkpoint interval in seconds.
Definition: CommandLineParameters.h:306
TCommandLineParameters::DefaultVerboseInterval
static const size_t DefaultVerboseInterval
Default verbose interval.
Definition: CommandLineParameters.h:352
TCommandLineParameters::~TCommandLineParameters
virtual ~TCommandLineParameters()
Destructor.
Definition: CommandLineParameters.h:205
TCommandLineParameters::Store_p_rms
bool Store_p_rms
Store_p_rms value.
Definition: CommandLineParameters.h:314
TCommandLineParameters::IsVersion
bool IsVersion() const
Is –version flag set?
Definition: CommandLineParameters.h:217
TCommandLineParameters::GetStartTimeIndex
size_t GetStartTimeIndex() const
Get start time index when sensor data collection begins.
Definition: CommandLineParameters.h:228
TCommandLineParameters::ParseCommandLine
void ParseCommandLine(int argc, char **argv)
Parse command line.
Definition: CommandLineParameters.cpp:203
TCommandLineParameters::IsStore_u_max_all
bool IsStore_u_max_all() const
Is –u_max_all set?
Definition: CommandLineParameters.h:262
TCommandLineParameters::NumberOfThreads
size_t NumberOfThreads
NumberOfThreads value.
Definition: CommandLineParameters.h:295
TCommandLineParameters::IsStore_p_raw
bool IsStore_p_raw() const
Is –p_raw set?
Definition: CommandLineParameters.h:236
TCommandLineParameters::GetOutputFileName
std::string GetOutputFileName() const
Get output file name.
Definition: CommandLineParameters.h:210