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
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  */
199 {
200  public:
201 
202  /// Constructor.
204  /// Destructor.
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.
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?
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.
282 
283  /// operator = not allowed for public.
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.
296  /// VerboseInterval value.
298  /// CompressionLevel value.
300 
301  /// BenchmarkFlag value.
303  /// BenchmarkTimeStepsCount value.
305  /// Checkpoint interval in seconds.
307 
308  /// PrintVersion value.
310 
311  /// Store_p_raw value.
313  /// Store_p_rms value.
315  /// Store_p_max value.
317  /// Store_p_min value.
319  /// Store_p_max_all value.
321  /// Store_p_min_all value.
323  /// Store_p_final value.
325 
326  /// Store_u_raw value.
328  /// Store_u_non_staggered_raw value.
330  /// Store_u_rms value.
332  /// Store_u_max value.
334  /// Store_u_min value.
336  /// Store_u_max_all value.
338  /// Store_u_min_all value.
340  /// Store_u_final value.
342 
343  /// Copy sensor mask to the output file.
345  /// StartTimeStep value.
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 
std::string OutputFileName
Output file name.
bool Store_u_raw
Store_u_raw value.
void PrintUsageAndExit()
Print usage and exit.
std::string GetInputFileName() const
Get input file name.
size_t GetNumberOfThreads() const
Get number of threads.
size_t CompressionLevel
CompressionLevel value.
bool IsStore_u_rms() const
Is –u_rms set?
std::string GetCheckpointFileName() const
Get Checkpoint file name.
size_t GetVerboseInterval() const
Get verbose interval.
bool IsStore_p_max() const
Is –p_max set?
bool IsStore_p_min_all() const
Is –p_min_all set?
bool IsStore_p_rms() const
Is –p_rms set?
bool Store_u_min
Store_u_min value.
TCommandLineParameters & operator=(const TCommandLineParameters &src)
operator = not allowed for public.
bool IsStore_p_final() const
Is –p_final set?
bool Store_u_max
Store_u_max value.
size_t GetCheckpointInterval() const
Get checkpoint interval.
size_t VerboseInterval
VerboseInterval value.
bool Store_u_non_staggered_raw
Store_u_non_staggered_raw value.
bool Store_p_max
Store_p_max value.
bool IsStore_u_non_staggered_raw() const
Is –u_non_staggered_raw set?
bool IsStore_p_min() const
Is –p_min set?
bool Store_p_min_all
Store_p_min_all value.
bool IsStore_u_max() const
Is –u_max set?
bool IsCheckpointEnabled() const
Is checkpoint enabled?
void PrintSetup()
Print setup.
bool IsBenchmarkFlag() const
Is –benchmark flag set?
bool Store_p_raw
Store_p_raw value.
bool Store_u_final
Store_u_final value.
bool Store_p_min
Store_p_min value.
size_t GetBenchmarkTimeStepsCount() const
Get benchmark time step count.
bool IsStore_u_final() const
Is –u_final set?
std::string InputFileName
Input file name.
bool Store_p_max_all
Store_p_max_all value.
bool IsStore_u_min_all() const
Is –u_min set?
bool Store_u_rms
Store_u_rms value.
size_t GetCompressionLevel() const
Get compression level.
The class to parse and store command line parameters.
bool IsStore_u_min() const
Is –u_min_all set?
bool BenchmarkFlag
BenchmarkFlag value.
bool IsCopySensorMask() const
is –copy_mask set
bool Store_p_final
Store_p_final value.
size_t StartTimeStep
StartTimeStep value.
bool IsStore_u_raw() const
Is –u_raw set?
bool Store_u_min_all
Store_u_min_all value.
bool IsStore_p_max_all() const
Is –p_max_all set?
std::string CheckpointFileName
Checkpoint file name.
static const size_t DefaultCompressionLevel
Default compression level.
bool CopySensorMask
Copy sensor mask to the output file.
bool Store_u_max_all
Store_u_max_all value.
size_t BenchmarkTimeStepsCount
BenchmarkTimeStepsCount value.
bool PrintVersion
PrintVersion value.
size_t CheckpointInterval
Checkpoint interval in seconds.
static const size_t DefaultVerboseInterval
Default verbose interval.
virtual ~TCommandLineParameters()
Destructor.
bool Store_p_rms
Store_p_rms value.
bool IsVersion() const
Is –version flag set?
size_t GetStartTimeIndex() const
Get start time index when sensor data collection begins.
void ParseCommandLine(int argc, char **argv)
Parse command line.
bool IsStore_u_max_all() const
Is –u_max_all set?
size_t NumberOfThreads
NumberOfThreads value.
bool IsStore_p_raw() const
Is –p_raw set?
std::string GetOutputFileName() const
Get output file name.