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

- Main Page
- Classes
- Files

- File List
- File Members

Classes
Parameters/CommandLineParameters.h File Reference

The header file containing the command line parameters. More...

`#include <cstdlib>`
`#include <string>`
Include dependency graph for CommandLineParameters.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Classes
class | TCommandLineParameters
| The class to parse and store command line parameters. More...

## Detailed Description

Author:
  Jiri Jaros
  CECS, ANU, Australia
  jiri.jaros@anu.edu.au

Version:
  kspaceFirstOrder3D 2.13

Date:
  29 August 2012, 11:25 (created)
  11 October 2012, 17:05 (revised)

## Command Line Parameters

The C++ code requires two mandatory parameters and accepts a few optional parameters and flags. The mandatory parameters `-i` and `-o` specify the input and output file. The file names respect the path conventions for particular operating system. If any of the files is not specified, cannot be found or created, an error message is shown.

The `-t` parameter sets the number of threads used, which defaults the system maximum. On CPUs with Intel Hyper-Threading (HT), performance will generally be better if HT is disabled in the BIOS settings. If HT is switched on, the default will be to create twice as many threads as there are physical processor cores, which might slow down the code execution. Therefore, if the HT is on, try specifying the number of threads manually for best performance (e.g., 4 for Intel Quad-Core). We recommend experimenting with this parameter to find the best configuration. Note, if there are other tasks being executed on the system, it might be useful to further limit the number of threads to prevent system overload.

The `-r` parameter specifies how often information about the simulation progress is printed to the command line. By default, the C++ code prints out the progress of the simulation, the elapsed time, and the estimated time of completion in intervals corresponding to 5% of the total number of times steps.

The `-c` parameter specifies the compression level used by the ZIP library to reduce the size of the output file. The actual compression rate is highly dependent on the shape of the sensor mask and the range of stored quantities. In general, the output data is very hard to compress, and using higher compression levels can greatly increase the time to save data while not having a large impact on the final file size. The default compression level of 3 represents a balance between compression ratio and performance that is suitable in most cases.

The `--benchmark` parameter enables the total length of simulation (i.e., the number of time steps) to be overwritten by setting a new number of time steps to simulate. This is particularly useful for performance evaluation and benchmarking. As the code performance is relatively stable, 50-100 time steps is usually enough to predict the simulation duration. This parameter can also be used to quickly find the ideal number of CPU threads to use.

The `-h` and `--help` parameters print all the parameters of the C++ code, while the `--version` parameter reports the code version and internal build number.

The remaining flags specify the output quantities to be recorded during the simulation and stored on disk analogous to the sensor.record input. If the `-p` or `--p` raw flags are set (these are equivalent), a time series of the acoustic pressure at the grid points specified by the sensor mask is recorded. If the `--p` rms and/or `--p` max flags are set, the root mean square and/or maximum values of the pressure at the grid points specified by the sensor mask are recorded. Finally, if the `--p` final flag is set, the values for the entire acoustic pressure field in the final time step of the simulation is stored (this will always include the PML, regardless of the setting for ``PMLInside'` ). Flags to record the acoustic particular velocity are defined in an analogous fashion.

In addition to returning the acoustic pressure and particle velocity, the acoustic intensity at the grid points specified by the sensor mask can also be calculated and stored. To account for the staggered grid scheme, approximate values for the particle velocity at the unstaggered grid points are automatically calculated using linear interpolation before multiplication by the acoustic pressure. Two means of aggregation are possible: `-I` or `--I_avg` calculates and stores the average acoustic intensity, while `--I` max calculates the maximum acoustic intensity.

Any combination of `p`, `u` and `I` fags is admissible. If no output flag is set, a time-series for the acoustic pressure is recorded. If it is not necessary to collect the output quantities over the entire simulation, the starting time step when the collection begins can be specified using the -s parameter. Note, the index for the first time step is 1 (this follows the MATLAB indexing convention).

    ---------------------------------- Usage ---------------------------------
    Mandatory parameters:
      -i <input_file_name>            : HDF5 input file
      -o <output_file_name>           : HDF5 output file

    Optional parameters:
      -t <num_threads>                : Number of CPU threads (default = MAX)
      -r <interval_in_%>              : Progress print interval (default = 5%)
      -c <comp_level>                 : Output file compression level <0,9>
                                          (default = 3)
      --benchmark <steps>             : Run a specified number of time steps

      -h                              : Print help
      --help                          : Print help
      --version                       : Print version

    Output flags:
      -p                              : Store acoustic pressure
                                          (default if nothing else is on)
                                          (the same as --p_raw)
      --p_raw                         : Store raw time series of p (default)
      --p_rms                         : Store rms of p
      --p_max                         : Store max of p
      --p_final                       : Store final pressure field

      -u                              : Store ux, uy, uz
                                          (the same as --u_raw)
      --u_raw                         : Store raw time series of ux, uy, uz
      --u_rms                         : Store rms of ux, uy, uz
      --u_max                         : Store max of ux, uy, uz
      --u_final                       : Store final acoustic velocity

      -I                              : Store intensity
                                          (the same as --I_avg)
      --I_avg                         : Store avg of intensity
      --I_max                         : Store max of intensity

      -s <timestep>                   : Time step when data collection begins
                                          (default = 1)
    --------------------------------------------------------------------------

## License

This file is part of the C++ extension of the k-Wave Toolbox (http://www.k-wave.org).
Copyright (C) 2012 Jiri Jaros and Bradley Treeby

This file is part of k-Wave. k-Wave is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

k-Wave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with k-Wave. If not, see <http://www.gnu.org/licenses/>.

Definition in file CommandLineParameters.h.

All Classes Files Functions Variables Typedefs Enumerations