# kspaceFirstOrder3DC

3D time-domain simulation of wave propagation using C++ code.

## Syntax

See `kspaceFirstOrder3D`.

## Description

`kspaceFirstOrder3DC` provides an blind interface to the C++ version of `kspaceFirstOrder3D` (called `kspaceFirstOrder3D-OMP`). The function works by appending the optional input `'SaveToDisk'` to the user inputs and then calling `kspaceFirstOrder3D` to save the input files to disk. The contents of `sensor.record` (if set) are parsed as input flags, and the C++ code is run using the `system` command. The output files are then automatically loaded from disk and returned in the same fashion as `kspaceFirstOrder3D`. The input and output files are saved to the temporary directory native to the operating system, and are deleted after the function runs.

This function requires the C++ binary/executable of `kspaceFirstOrder3D-OMP` to be downloaded from www.k-wave.org/download.php and placed in the "binaries" directory of the k-Wave toolbox.

Note, not all input options are currently supported, and all display options are ignored (only command line outputs are given). See the k-Wave user manual for more information.

This function is not recommended for large simulations, as the input variables will reside twice in main memory (once in MATLAB, and once in C++). For large simulations, the C++ code should be called outside of MATLAB. Again, see the k-Wave manual for more information.

## Optional Inputs

Optional 'string', value pairs that may be used to modify the default computational settings.

Input | Valid Settings | Default | Description
--- | --- | --- | ---
`'BinaryName'` | (string) | `'kspaceFirstOrder3D-OMP'` on linux and `'kspaceFirstOrder3D-OMP.exe'` on windows | Name of the binary file.
`'BinaryPath'` | (string) | `'binaries/'` | Path of the binary file.
`'DataName'` | (string) | `'kwave_[input/output]_data_[date].h5'` | Prefix used to generate a custom name for the input and output data files (this is appended with `'_input.h5'`and `'_output.h5'`).````
`'DataPath'` | (string) | path returned by `tempdir` | Location of the folder where the input and output HDF5 files should be stored.
`'DeleteData'` | (Boolean scalar) | `true` | Boolean controlling whether the input and output HDF5 files should be deleted after running the simulation.
`'FunctionName'` | (string) | `kspaceFirstOrder3D` | name of the k-Wave MATLAB function used to generate the input file using the `'SaveToDisk'` option.