# kspaceSecondOrder

Fast time-domain simulation of wave propagation for homogeneous media.

## Syntax

sensor_data = kspaceSecondOrder(kgrid, medium, source, sensor) sensor_data = kspaceSecondOrder(kgrid, medium, source, sensor, ...) [sensor_data, field_data] = kspaceSecondOrder(kgrid, medium, source, sensor) [sensor_data, field_data] = kspaceSecondOrder(kgrid, medium, source, sensor, ...)

## Description

`kspaceSecondOrder`

simulates the time-domain propagation of linear compressional waves through a one, two, or three dimensional homogeneous acoustic medium given four input structures: `kgrid`

, `medium`

, `source`

, and `sensor`

. The computation is based on an exact second-order k-space model for media with power law absorption. At each time-step (defined by `kgrid.dt`

and `kgrid.Nt`

or `kgrid.t_array`

), the pressure at the positions defined by `sensor.mask`

are recorded and stored. If `kgrid.t_array`

is set to `'auto'`

, this array is automatically generated using the `makeTime`

method of the `kWaveGrid`

class. To prevent wave wrapping, the computational domain can be automatically expanded by a factor of two by setting the optional input `'ExpandGrid'`

to `true`

.

An initial pressure distribution can be specified by assigning a matrix (the same size as the computational grid) of arbitrary numeric values to `source.p0`

. An initial pressure gradient can similarly be specified using `source.dp0dt`

. The pressure is returned as an array of time series at the sensor locations defined by `sensor.mask`

. This is specified as a binary matrix (i.e., a matrix of 1's and 0's the same size as the computational grid) representing the grid points within the computational grid that will collect the data. The `sensor_data`

is returned using MATLAB's standard column-wise linear matrix index ordering with the recorded data indexed as `sensor_data(sensor_position, time)`

. The final pressure field over the complete computational grid can also be obtained by setting `sensor.record`

to `{'p', 'p_final'}`

. In this case, the output `sensor_data`

is returned as a structure with the outputs appended as the structure fields `sensor_data.p`

and `sensor_data.p_final`

.

Compared to the first-order simulation functions `kspaceFirstOrder1D`

, `kspaceFirstOrder2D`

, and `kspaceFirstOrder3D`

, `kspaceSecondOrder`

is restricted to homogeneous media and has less functionality. However, it is exact for a homogenous absorbing medium, is more computationally efficient, and allows an initial pressure gradient to be specified.

## Inputs

`kgrid` |
k-Wave grid object returned by `kWaveGrid` containing Cartesian and k-space grid fields |

`kgrid.t_array` |
evenly spaced array of time values [s] (set to `'auto'` by `kWaveGrid` ) |

`medium.sound_speed` |
homogeneous sound speed within the acoustic medium [m/s] |

`medium.alpha_power` |
power law absorption exponent |

`medium.alpha_coeff` |
power law absorption coefficient [dB/(MHz^y cm)] |

`source.p0` |
initial pressure within the acoustic medium |

`source.dp0dt` |
initial pressure gradient within the acoustic medium |

`sensor.mask` |
binary grid specifying where the pressure is recorded at each time-step |

`sensor.record` |
cell array of the acoustic parameters to record in the form `sensor.record = {'p'}` ; valid inputs are:` 'p'` (acoustic pressure)` 'p_final'` (final pressure field at all grid points) |

## Optional Inputs

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

Input | Valid Settings | Default | Description |
---|---|---|---|

`'ExpandGrid'` |
(Boolean scalar) |
`false` |
Boolean controlling whether the grid size is expanded on two sides to delay the time before wave wrapping occurs. |

`'MeshPlot'` |
(Boolean scalar) |
`false` |
Boolean controlling whether `imagesc` to plot the pressure field. |

`'PlotFrames'` |
(Boolean scalar) |
`false` |
Boolean controlling whether the pressure field for each time step is plotted in a new window. |

`'PlotFreq'` |
(integer numeric scalar) |
`10` |
The number of iterations which must pass before the simulation plot is updated. |

`'PlotScale'` |
(numeric two element vector) |
`[-1, 1]` |
[min, max] values used to control the scaling for `imagesc` (visualisation). |

`'PlotSim'` |
(Boolean scalar) |
`true` |
Boolean controlling whether the simulation iterations are progressively plotted. |

`'Smooth'` |
(Boolean scalar) |
`true` |
Boolean controlling whether `source.p0` is smoothed using `smooth` before computation. |

## Outputs

If `sensor.record`

is not defined by the user:

`sensor_data` |
time varying pressure recorded at the sensor positions given by `sensor.mask` |

If `sensor.record`

is defined by the user:

`sensor_data.p` |
time varying pressure recorded at the sensor positions given by `sensor.mask` (returned if `'p'` is set) |

`sensor_data.p_final` |
final pressure field at all grid points within the domain (returned if `'p_final'` is set) |

## Examples

- Comparison Of Modelling Functions
- Setting An Initial Pressure Gradient
- Modelling Power Law Absorption

## See Also

`kspaceFirstOrder1D`

, `kspaceFirstOrder2D`

, `kspaceFirstOrder3D`

, `kWaveGrid`

, `smooth`