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