calculateMassSourceCW

Compute k-Wave input plane from measured CW data.

Syntax

source_estimate = calculateMassSourceCW(measured_data, dx, freq, c0, source_offset)
source_estimate = calculateMassSourceCW(measured_data, dx, freq, c0, source_offset, grid_expansion)
source_estimate = calculateMassSourceCW(measured_data, dx, freq, c0, source_offset, [], ...)
source_estimate = calculateMassSourceCW(measured_data, dx, freq, c0, source_offset, grid_expansion, ...)
[source_estimate, output] = calculateMassSourceCW(measured_data, dx, freq, c0, source_offset)
...

Description

calculateMassSourceCW takes a measured 2D plane of complex pressure values (e.g., measured using a hydrophone in a scanning tank under steady state conditions) and calculates an equivalent CW additive pressure source positioned a given distance away that recreates the measured data when used as an input to k-Wave (i.e., by assigning the equivalent source as an input to acousticFieldPropagator, or by generating a time-varying input signal using createCWSignals and assigning this to source.p with source.p_mode = 'additive'). The measured data is assumed to be for a single-frequency continuous wave source, specified by freq, and is given as a complex 2D matrix.

The equivalent source is calculated using an iterative optimisation based on gradient descent, where functional gradients are calculated using the adjoint. Both the forward and adjoint operators are computed using acousticFieldPropagator. The calculation assumes the propagation is linear and the medium is lossless. The algorithm and approach are described in detail in [1].

If the source is larger than the measured input plane, for example, if measuring a focused bowl transducer, a suitable value should be specified for the value of grid_expansion. Note, the value of source_offset does not need to match the position of the real source in the experiment.

An alternative approach to project measured data using k-Wave is to directly use the measured data as a pressure source with a Dirichlet boundary condition (i.e., by generating a time-varying input signal from the measured data using createCWSignals and assigning this to source.p and setting source.p_mode = 'dirichlet'). However, this approach leads to errors in the imposed spatial gradient, which manifests as errors in the projected field. Thus, for accurate holographic projections using k-Wave, it is recommended to use calculateMassSourceCW to first calculate the input data (see [1] for a comparison).

[1] Treeby, B., Lucka, F., Martin, E., & Cox, B. T. (2018). Equivalent-Source Acoustic Holography for Projecting Measured Ultrasound Fields Through Complex Media. IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control, 65(10), 1857-1864.

Inputs

measured_data	2D matrix of complex pressure values [Pa].
dx	Spatial step between grid points in the input plane [m].
freq	Source frequency [Hz].
c0	Speed of sound in the medium [m/s].
source_offset	Offset between the measured input plane and the source plane [grid points]. For example, if source_offset = 1, the input plane and source plane are on adjacent grid points.
grid_expansion	Number of grid points used to expand the size of the estimated source plane in each lateral dimension relative to the measured input plane (set to 0 if not defined).

Optional Inputs

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

Input	Valid Settings	Default	Description
'NumSteps'	(integer)	20	Number of gradient descent steps.
'StepSize'	(numeric scalar)	0.5	Starting size of gradient descent step.
'StepSizeIncrement'	(numeric scalar)	1.1	Multiplicative factor used to increase the step size when the error is reduced.
'StepSizeDecrement'	(numeric scalar)	0.5	Multiplicative factor used to decrease the step size when the error is increased.
'Plot'	(Boolean scalar)	true	Boolean controlling whether the update steps are displayed.
'ReturnIterations'	(Boolean scalar)	false	Boolean controlling whether the source estimate at each gradient descent step is returned. If set to true, the source_estimate output is given as a 3D matrix, each x-y plane corresponds to the source estimate at each step.
'UseCpp'	(Boolean scalar)	false	Boolean controlling whether the simulations are run using the C++ implementation of acousticFieldPropagator.

Outputs

source_estimate	If 'ReturnIterations' is false (the default), source_estimate is given as a 2D matrix of complex pressure values [Pa]. If 'ReturnIterations' is true, source_estimate is given as a 3D matrix containing the source estimate after each iteration, indexed as (x, y, iteration).
output	Structure containing details of the optimisation with the following fields:
	.linf_error
	.l2_error
	.step_size
	.number_steps
	.number_function_calls
	.modelled_data

See Also

acousticFieldPropagator, calculateMassSource