kspaceFirstOrder3D-CUDA  1.1
The CUDA/C++ implementation of the k-wave toolbox for the time-domain simulation of acoustic wave fields in 3D
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
CommandLineParameters.h
Go to the documentation of this file.
1 /**
2  * @file CommandLineParameters.h
3  *
4  * @author Jiri Jaros \n
5  * Faculty of Information Technology \n
6  * Brno University of Technology \n
7  * jarosjir@fit.vutbr.cz
8  *
9  * @brief The header file containing the command line parameters.
10  *
11  * @version kspaceFirstOrder3D 3.4
12  *
13  * @date 29 August 2012, 11:25 (created) \n
14  * 10 August 2016, 13:27 (revised)
15  *
16  * @section Params Command Line Parameters
17  *
18  * The CUDA/C++ code requires two mandatory parameters and accepts a few optional parameters and
19  * flags. Ill parameters, bad simulation files, and runtime errors such as out-of-memory problems,
20  * lead to an exception followed by an error message shown and execution termination.
21  *
22  * The mandatory parameters \c -i and \c -o specify the input and output file. The file names
23  * respect the path conventions for particular operating system. If any of the files is not
24  * specified, cannot be found or created, an error message is shown and the code terminates.
25  *
26  * The \c -t parameter sets the number of threads used, which defaults the system maximum. For the
27  * CUDA version, the number of threads is not critical, as the CPU only preprocess data. When
28  * running on desktops with multiple GPUs, or clusters with per-GPU resource allocations, it may
29  * be useful to limit the number of CPU threads.
30  *
31  * The \c -g parameter allows to explicitly select a GPU for the execution. The CUDA capable GPUs
32  * can be listed by the system command \c nvidia-smi. If the parameter is not specified, the code
33  * uses the first free GPU. If the GPUs are set in the CUDA DEFAULT mode, the first CUDA device
34  * is selected. In order to get the automatic round-robin GPU selection working (to e.g. execute
35  * multiple instances of the code on distinct GPUs), please set the GPUs into PROCESS_EXCLUSIVE mode.
36  * On clusters with a PBS scheduler, this is usually done automatically, so no need to change it
37  * by user.
38  *
39  * The \c -r parameter specifies how often information about the simulation progress is printed out
40  * to the command line. By default, the CUDA/C++ code prints out the progress of the simulation,
41  * the elapsed time, and the estimated time of completion in intervals corresponding to 5% of
42  * the total number of times steps.
43  *
44  * The \c -c parameter specifies the compression level used by the ZIP library to reduce the size of
45  * the output file. The actual compression rate is highly dependent on the shape of the sensor mask
46  * and the range of stored quantities and may be computationally expensive. In general, the output
47  * data is very hard to compress, and using higher compression levels can greatly increase the
48  * time to save data while not having a large impact on the final file size. That's why we decided
49  * to disable compression in default settings.
50  *
51  * The \c <tt>\--benchmark</tt> parameter enables the total length of simulation (i.e., the number
52  * of time steps) to be overridden by setting a new number of time steps to simulate. This is
53  * particularly useful for performance evaluation and benchmarking. As the code performance is
54  * relatively stable, 50-100 time steps is usually enough to predict the simulation duration.
55  * This parameter can also be used to quickly check the simulation is set up correctly.
56  *
57  * The \c <tt>\--verbose</tt> parameter enables to select between three levels of verbosity. For
58  * routine simulations, the verbose level of 0 (the default one) is usually sufficient. For more
59  * information about the simulation, checking the parameters of the simulation, code version,
60  * GPU used, file paths, and debugging running scripts, verbose levels 1 and 2 may be very useful.
61  *
62  * The \c -h and <tt>\--help</tt> parameters print all the parameters of the C++ code. The
63  * <tt>\--version </tt>parameter reports detail information about the code useful for debugging and
64  * bug reports. It prints out the internal version, the build date and time, the git hash allowing
65  * us to track the version of the source code, the operating system, the compiler name and version
66  * and the instruction set used.
67  *
68  * For jobs that are expected to run for a very long time, it may be useful to checkpoint and
69  * restart the execution. One motivation is the wall clock limit per task on clusters where jobs
70  * must fit within a given time span (e.g. 24 hours). The second motivation is a level of
71  * fault-tolerance, where you can back up the state of the simulation after a predefined period.
72  * To enable checkpoint-restart, the user is asked to specify a file to store the actual state of
73  * the simulation by <tt>\--checkpoint_file</tt> and the period in seconds after which the
74  * simulation will be interrupted by <tt>\--checkpoint_interval</tt>. When running on a cluster,
75  * please allocate enough time for the checkpoint procedure that can take a non-negligible amount
76  * of time (7 matrices have to be stored in the checkpoint file and all aggregated quantities are
77  * flushed into the output file). Please note, that the checkpoint file name and path is not checked
78  * at the beginning of the simulation, but at the time the code starts checkpointing. Thus make sure
79  * the file path was correctly specified ((otherwise you will not find out the simulation crashed
80  * until the first leg of the simulation finishes)). The rationale behind this is that to keep as
81  * high level of fault tolerance as possible, the checkpoint file should be touched even when really
82  * necessary.
83  *
84  * When controlling a multi-leg simulation by a script loop, the parameters of the code remains the
85  * same in all legs. The first leg of the simulation creates a checkpoint file while the last one
86  * deletes it. If the checkpoint file is not found the simulation starts from the beginning. In
87  * order to find out how many steps have been finished, please open the output file and read
88  * the variable <tt>t_index</tt> and compare it with <tt>Nt</tt> (e.g. by the h5dump command).
89  *
90  *
91  * The remaining flags specify the output quantities to be recorded during the simulation and
92  * stored on disk analogous to the sensor.record input. If the \c -p or <tt>\--p\_raw</tt> flags
93  * are set (these are equivalent), a time series of the acoustic pressure at the grid points
94  * specified by the sensor mask is recorded. If the <tt>\--p_rms</tt>, <tt>\--p_max</tt>,
95  * <tt>\--p_min</tt> flags are set, the root mean square and/or maximum and/or minimum values of
96  * the pressure at the grid points specified by the sensor mask are recorded. If the
97  * <tt>\--p_final</tt> flag is set, the values for the entire acoustic pressure field in the final
98  * time step of the simulation is stored (this will always include the PML, regardless of the
99  * setting for <tt> `PMLInside'</tt>).
100  * The flags <tt>\--p_max_all</tt> and <tt>\--p_min_all</tt> allow to calculate the maximum and
101  * minimum values over the entire acoustic pressure field, regardless on the shape of the sensor
102  * mask. Flags to record the acoustic particle velocity are defined in an analogous fashion. For
103  * proper calculation of acoustic intensity, the particle velocity has to be shifted onto the same
104  * grid as the acoustic pressure. This can be done by setting <tt>\--u_non_staggered_raw</tt> flag,
105  * that first shifts the particle velocity and then samples the grid points specified by the sensor
106  * mask. Since the shift operation requires additional FFTs, the impact on the simulation time may
107  * be significant.
108  *
109  * Any combination of <tt>p</tt> and <tt>u</tt> flags is admissible. If no output flag is set,
110  * a time-series for the acoustic pressure is recorded. If it is not necessary to collect the output
111  * quantities over the entire simulation, the starting time step when the collection begins can
112  * be specified using the -s parameter. Note, the index for the first time step is 1 (this follows
113  * the MATLAB indexing convention).
114  *
115  * The <tt>\--copy_sensor_mask</tt> will copy the sensor from the input file to the output one at the end
116  * of the simulation. This helps in post-processing and visualisation of the outputs.
117  *
118  *
119 \verbatim
120 ┌───────────────────────────────────────────────────────────────┐
121 │ kspaceFirstOrder3D-CUDA v1.1 │
122 ├───────────────────────────────────────────────────────────────┤
123 │ Usage │
124 ├───────────────────────────────────────────────────────────────┤
125 │ Mandatory parameters │
126 ├───────────────────────────────────────────────────────────────┤
127 │ -i <file_name> │ HDF5 input file │
128 │ -o <file_name> │ HDF5 output file │
129 ├───────────────────────────────┴───────────────────────────────┤
130 │ Optional parameters │
131 ├───────────────────────────────┬───────────────────────────────┤
132 │ -t <num_threads> │ Number of CPU threads │
133 │ │ (default = 4) │
134 │ -g <device_number> │ GPU device to run on │
135 │ │ (default = the first free) │
136 │ -r <interval_in_%> │ Progress print interval │
137 │ │ (default = 5%) │
138 │ -c <compression_level> │ Compression level <0,9> │
139 │ │ (default = 0) │
140 │ --benchmark <time_steps> │ Run only a specified number │
141 │ │ of time steps │
142 │ --verbose <level> │ Level of verbosity <0,2> │
143 │ │ 0 - basic, 1 - advanced, │
144 │ │ 2 - full │
145 │ │ (default = basic) │
146 │ -h, --help │ Print help │
147 │ --version │ Print version and build info │
148 ├───────────────────────────────┼───────────────────────────────┤
149 │ --checkpoint_file <file_name> │ HDF5 Checkpoint file │
150 │ --checkpoint_interval <sec> │ Checkpoint after a given │
151 │ │ number of seconds │
152 ├───────────────────────────────┴───────────────────────────────┤
153 │ Output flags │
154 ├───────────────────────────────┬───────────────────────────────┤
155 │ -p │ Store acoustic pressure │
156 │ │ (default output flag) │
157 │ │ (the same as --p_raw) │
158 │ --p_raw │ Store raw time series of p │
159 │ --p_rms │ Store rms of p │
160 │ --p_max │ Store max of p │
161 │ --p_min │ Store min of p │
162 │ --p_max_all │ Store max of p (whole domain) │
163 │ --p_min_all │ Store min of p (whole domain) │
164 │ --p_final │ Store final pressure field │
165 ├───────────────────────────────┼───────────────────────────────┤
166 │ -u │ Store ux, uy, uz │
167 │ │ (the same as --u_raw) │
168 │ --u_raw │ Store raw time series of │
169 │ │ ux, uy, uz │
170 │ --u_non_staggered_raw │ Store non-staggered raw time │
171 │ │ series of ux, uy, uz │
172 │ --u_rms │ Store rms of ux, uy, uz │
173 │ --u_max │ Store max of ux, uy, uz │
174 │ --u_min │ Store min of ux, uy, uz │
175 │ --u_max_all │ Store max of ux, uy, uz │
176 │ │ (whole domain) │
177 │ --u_min_all │ Store min of ux, uy, uz │
178 │ │ (whole domain) │
179 │ --u_final │ Store final acoustic velocity │
180 ├───────────────────────────────┼───────────────────────────────┤
181 │ -s <time_step> │ When data collection begins │
182 │ │ (default = 1) │
183 └───────────────────────────────┴───────────────────────────────┘
184 \endverbatim
185  *
186  * @section License
187  * This file is part of the C++ extension of the k-Wave Toolbox
188  * (http://www.k-wave.org).\n Copyright (C) 2016 Jiri Jaros and Bradley Treeby.
189  *
190  * This file is part of the k-Wave. k-Wave is free software: you can redistribute it and/or modify
191  * it under the terms of the GNU Lesser General Public License as published by the Free Software
192  * Foundation, either version 3 of the License, or (at your option) any later version.
193  *
194  * k-Wave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
195  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
196  * General Public License for more details.
197  *
198  * You should have received a copy of the GNU Lesser General Public License along with k-Wave.
199  * If not, see http://www.gnu.org/licenses/.
200  */
201 
202 #ifndef TCOMMAND_LINE_PARAMETERS_H
203 #define TCOMMAND_LINE_PARAMETERS_H
204 
205 #include <cstdlib>
206 #include <string>
207 
208 /**
209  * @class TCommandLineParameters
210  * @brief The class to parse and store command line parameters.
211  * @details The class to parse and store command line parameters.
212  */
214 {
215  public:
216  /// Only TParameters can create this class.
217  friend class TParameters;
218 
219  /// Destructor.
221 
222  /// Get input file name.
223  const std::string& GetInputFileName() const {return inputFileName;};
224  /// Get output file name.
225  const std::string& GetOutputFileName() const {return outputFileName;};
226  /// Get Checkpoint file name.
227  const std::string& GetCheckpointFileName() const {return checkpointFileName;};
228 
229  /// Get GPU device ID specified by the user (not necessary the one the code runs on).
230  int GetCUDADeviceIdx() const {return cudaDeviceIdx;};
231 
232  /// Is --benchmark flag set?
233  bool IsBenchmarkFlag() const {return benchmarkFlag;};
234  /// Is --version flag set?
235  bool IsVersion() const {return printVersion; };
236  /// Get benchmark time step count.
238 
239  /// Get compression level.
240  size_t GetCompressionLevel() const {return compressionLevel;};
241  /// Get number of threads.
242  size_t GetNumberOfThreads() const {return numberOfThreads;};
243  /// Get progress print interval.
245  /// Get start time index when sensor data collection begins.
246  size_t GetStartTimeIndex() const {return startTimeStep;};
247 
248  /// Is checkpoint enabled?
249  bool IsCheckpointEnabled() const {return (checkpointInterval > 0); };
250  /// Get checkpoint interval
251  size_t GetCheckpointInterval() const {return checkpointInterval; };
252 
253  /// Is --p_raw set?
254  bool IsStore_p_raw() const {return store_p_raw;};
255  /// Is --p_rms set?
256  bool IsStore_p_rms() const {return store_p_rms;};
257  /// Is --p_max set?
258  bool IsStore_p_max() const {return store_p_max;};
259  /// Is --p_min set?
260  bool IsStore_p_min() const {return store_p_min;};
261  /// Is --p_max_all set?
262  bool IsStore_p_max_all() const {return store_p_max_all;};
263  /// Is --p_min_all set?
264  bool IsStore_p_min_all() const {return store_p_min_all;};
265  /// Is --p_final set?
266  bool IsStore_p_final() const {return store_p_final;};
267 
268  /// Is --u_raw set?
269  bool IsStore_u_raw() const {return store_u_raw;};
270  /// Is --u_non_staggered_raw set?
272  /// Is --u_rms set?
273  bool IsStore_u_rms() const {return store_u_rms;};
274  /// Is --u_max set?
275  bool IsStore_u_max() const {return store_u_max;};
276  /// Is --u_min set?
277  bool IsStore_u_min() const {return store_u_min;};
278  /// Is --u_max_all set?
279  bool IsStore_u_max_all() const {return store_u_max_all;};
280  /// Is --u_min set?
281  bool IsStore_u_min_all() const {return store_u_min_all;};
282  /// Is --u_final set?
283  bool IsStore_u_final() const {return store_u_final;};
284 
285  /// Is --copy_mask set set?
286  bool IsCopySensorMask() const {return copySensorMask;};
287 
288  /// Print usage..
289  void PrintUsage();
290  /// Print setup.
292  /// Parse command line.
293  void ParseCommandLine(int argc, char** argv);
294 
295  protected:
296  /// Default constructor - only friend class can create an instance.
298 
299  /// Copy constructor not allowed for public.
301 
302  /// operator = not allowed for public.
304 
305  private:
306  /// Input file name.
307  std::string inputFileName;
308  /// Output file name.
309  std::string outputFileName;
310  /// Checkpoint file name.
311  std::string checkpointFileName;
312 
313  /// Number of CPU threads value.
315 
316  /// Id of selected GPU devices.
318 
319  /// ProgressInterval value.
321  /// CompressionLevel value.
323 
324  /// BenchmarkFlag value.
326  /// BenchmarkTimeStepsCount value.
328  /// Checkpoint interval in seconds
330 
331  /// print version of the code and exit.
333 
334  /// Store_p_raw value.
336  /// Store_p_rms value.
338  /// Store_p_max value.
340  /// Store_p_min value.
342  /// Store_p_max_all value.
344  /// Store_p_min_all value.
346  /// Store_p_final value.
348 
349  /// Store_u_raw value.
351  /// Store_u_non_staggered_raw value.
353  /// Store_u_rms value.
355  /// Store_u_max value.
357  /// Store_u_min value.
359  /// Store_u_max_all value.
361  /// Store_u_min_all value.
363  /// Store_u_final value.
365 
366  /// Copy sensor mask to the output file.
368  /// StartTimeStep value.
370 
371  /// Default compression level.
372  static const size_t DEFAULT_COMPRESSION_LEVEL = 0;
373  /// Default progress print interval.
374  static const size_t DEFAULT_PROGRESS_PRINT_INTERVAL = 5;
375 };// end of class TCommandLineParameters
376 //--------------------------------------------------------------------------------------------------
377 
378 #endif /* TCOMMAND_LINE_PARAMETERS_H */
379 
bool store_u_final
Store_u_final value.
bool store_p_max
Store_p_max value.
size_t GetNumberOfThreads() const
Get number of threads.
bool IsStore_u_rms() const
Is –u_rms set?
const std::string & GetCheckpointFileName() const
Get Checkpoint file name.
bool IsStore_p_max() const
Is –p_max set?
bool copySensorMask
Copy sensor mask to the output file.
bool store_p_final
Store_p_final value.
bool IsStore_p_min_all() const
Is –p_min_all set?
size_t numberOfThreads
Number of CPU threads value.
bool store_p_raw
Store_p_raw value.
bool IsStore_p_rms() const
Is –p_rms set?
bool store_p_min_all
Store_p_min_all value.
size_t checkpointInterval
Checkpoint interval in seconds.
const std::string & GetOutputFileName() const
Get output file name.
bool store_u_non_staggered_raw
Store_u_non_staggered_raw value.
TCommandLineParameters & operator=(const TCommandLineParameters &src)
operator = not allowed for public.
bool IsStore_p_final() const
Is –p_final set?
const std::string & GetInputFileName() const
Get input file name.
size_t GetCheckpointInterval() const
Get checkpoint interval.
void PrintComandlineParamers()
Print setup.
bool benchmarkFlag
BenchmarkFlag value.
int cudaDeviceIdx
Id of selected GPU devices.
bool store_p_min
Store_p_min 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_u_min_all
Store_u_min_all value.
bool IsStore_u_max() const
Is –u_max set?
bool printVersion
print version of the code and exit.
bool IsCheckpointEnabled() const
Is checkpoint enabled?
static const size_t DEFAULT_PROGRESS_PRINT_INTERVAL
Default progress print interval.
size_t progressPrintInterval
ProgressInterval value.
int GetCUDADeviceIdx() const
Get GPU device ID specified by the user (not necessary the one the code runs on). ...
size_t GetProgressPrintInterval() const
Get progress print interval.
bool IsBenchmarkFlag() const
Is –benchmark flag set?
std::string inputFileName
Input file name.
bool store_p_max_all
Store_p_max_all value.
Class storing all parameters of the simulation.
Definition: Parameters.h:49
bool store_u_max
Store_u_max value.
size_t GetBenchmarkTimeStepsCount() const
Get benchmark time step count.
std::string outputFileName
Output file name.
bool store_u_raw
Store_u_raw value.
bool IsStore_u_final() const
Is –u_final set?
size_t benchmarkTimeStepCount
BenchmarkTimeStepsCount value.
TCommandLineParameters()
Default constructor - only friend class can create an instance.
bool IsStore_u_min_all() const
Is –u_min set?
bool store_u_max_all
Store_u_max_all 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 set?
void PrintUsage()
Print usage..
bool store_p_rms
Store_p_rms value.
bool IsCopySensorMask() const
Is –copy_mask set set?
std::string checkpointFileName
Checkpoint file name.
bool IsStore_u_raw() const
Is –u_raw set?
bool IsStore_p_max_all() const
Is –p_max_all set?
static const size_t DEFAULT_COMPRESSION_LEVEL
Default compression level.
bool store_u_min
Store_u_min value.
size_t startTimeStep
StartTimeStep value.
virtual ~TCommandLineParameters()
Destructor.
bool IsVersion() const
Is –version flag set?
size_t GetStartTimeIndex() const
Get start time index when sensor data collection begins.
size_t compressionLevel
CompressionLevel value.
bool store_u_rms
Store_u_rms value.
void ParseCommandLine(int argc, char **argv)
Parse command line.
bool IsStore_u_max_all() const
Is –u_max_all set?
bool IsStore_p_raw() const
Is –p_raw set?