k-Wave

1 K-WaveA MATLAB toolbox for the time domainsimulation of acoustic wave fieldsUser ManualManual Version (August 27, 2016), Toolbox Release by Bradley Treeby, Ben Cox, and Jiri JarosContents1 Overview .. History and Contributors .. What s in this Manual .. Installation .. License .. Alternative Software ..42 Numerical Governing Equations .. Acoustic Source Terms .. Overview of thek-space pseudospectral method .. Discretek-space Equations .. Modelling Power Law Acoustic Absorption .. Perfectly Matched Layer .. Accuracy, Stability and the CFL Number .. Smoothing and the Band-Limited Interpolant .. 233 First-Order Simulation Overview .. Defining the Computational Grid .. Defining the Acoustic Medium.

2 Defining the Acoustic Source Terms .. Defining the Sensor .. Optional Input Parameters .. Using a Diagnostic Ultrasound Transducer as a Source or Sensor .. Improving Performance using the DataCast Option .. 484 Using optimised CPU and GPU Overview .. Running Simulations using the Optimised Codes .. Reloading the Output Data into MATLAB .. Running the Code using a Bash Script .. Running the Code from MATLAB .. Format of the HDF5 Input and Output files .. Compiling the CPU/GPU Source Code in Linux .. Compiling the CPU/GPU Source Code in Windows .. Performance and Memory Usage .. 64 Appendix A List of Optional Input Parameters68 Appendix B Format of the C++ HDF5 Files71 Appendix C Performance Evaluation of the CPU and GPU code79 Chapter Overviewk-Wave is an open source, third party, MATLAB toolbox designed for the time-domainsimulation of propagating acoustic waves in 1D, 2D, or 3D.

3 The toolbox has a wide rangeof functionality, but at its heart is an advanced numerical model that can account for bothlinear and nonlinear wave propagation, an arbitrary distribution of heterogeneous materialparameters, and power law acoustic absorption [1, 2]. The interface to the simulation func-tions has been designed to be both flexible and user friendly, while the computational en-gine has been optimised for speed and accuracy. The functions are called using MATLAB scripts with user-defined input parameters, so some familiarity with the MATLAB environ-ment is necessary to get started. However, the toolbox now includes more than 50 workedexamples and is also supported by an online forum ( ). k-Wave is still under active development, and its functionality is still evolving. This pro-cess is helped immensely by feedback from you, the user community.

4 So if something ismissing, doesn t work the way it should, or fails to do what you d hoped, please get History and ContributorsThe k-Wave toolbox was originally developed within the Photoacoustic Imaging Group atUniversity College London (UCL). The first beta version, released in July 2009, focussedprimarily on forward and inverse initial value problems for the simulation and reconstruc-tion of photoacoustic1wave fields in lossless media [1]. Subsequent releases of the toolboxhave extended this functionality to include time varying pressure and velocity sources,acoustic absorption, nonlinearity, elastic materials, and models for ultrasound transduc-ers. The overall development of the toolbox has been driven by Bradley Treeby and BenCox (UCL), while the C++ version ofkspaceFirstOrder3 Dis developed by Jiri Jaros(Brno University of Technology).

5 A considerable number of other users, collaborators,1 Photoacoustic tomography is a biomedical imaging modality based on the thermoelastic generation ofultrasound waves using pulsed laser light [3].12 CHAPTER 1. INTRODUCTIONand students have also contributed to this project, both directly (through code develop-ment) and indirectly (through suggestions, usage feedback, and bug reports). A sincerethanks goes to the user community for continuing to support the What s in this ManualThis manual includes a general introduction to the governing equations and numericalmethods used in the main simulation functions in k-Wave for fluid media. It also providesa basic overview of the software architecture and a number of canonical examples. Thecontent is divided into three main sections, which can be read largely 2 describes the underlying governing equations and numerical methods, Sec.

6 3describes how to use the main simulation functions in MATLAB, and Sec. 4 describeshow to install and use the C++ code. More details on the elastic code can be found in[4].The manual is intended to accompany the extensive html documentation that is alsoprovided with the toolbox. After installation, the html documentation can be accessedfrom the MATLAB help browser by selecting k-Wave Toolbox from the contents versions of MATLAB prior to 2012b, the help browser is opened by clicking on theblue question mark iconon the menu bar. In MATLAB 2012b (and later), the doc-umentation is accessed by selecting Help from the ribbon bar, and then clicking on Supplemental Software . In MATLAB 2015a (and later), the documentation is accessedby selecting Help from the ribbon bar, and then selecting k-Wave Toolbox from underthe Supplemental Software heading.

7 This additional documentation provides detailedinformation on how to use individual functions as well as more than 50 worked InstallationThe k-Wave toolbox is installed by adding the root k-Wave folder to the MATLAB can be done using the Set Path dialog box which is accessed by typing>> pathtoolat the MATLAB command dialog box can also be accessed using the dropdownmenus File Set Path if using MATLAB 2012a and earlier, or the the Set Path button on the ribbon bar if using MATLAB 2012b and later. Once the dialog box is open,the toolbox is installed by clicking Add Folder , selecting the k-Wave toolbox folder, andclicking save . The toolbox can be uninstalled in the same Linux users, using the Set Path dialog box requires write access Thisfile can be found under<.

8 >/toolbox/local. To find where MATLABis installed, type>> matlabrootat the MATLAB command , the toolbox can be installed by adding the lineaddpath( <.. >/ k-Wave Toolbox );2 The>>symbol is the default MATLAB command prompt and is used here to denote commands thatare entered in the MATLAB command window. The symbol itself is not actually LICENSE3to , where<.. >is replaced with the location of the tool-box, and the slashes should be in the direction native to your operating system. If exists, create one, and save it in the MATLAB startup installation, restart MATLAB. You should then be able to see the k-Wave help filesin the MATLAB help browser. Try selecting one of the examples and then clicking runthe file . If you can t see k-Wave Toolbox in the contents list of the MATLAB helpbrowser, try typing>> help k-Waveat the command prompt to see if the toolbox hasbeen installed correctly.

9 If it has and you still can t see the help files, open Preferences and select Help and make sure k-Wave Toolbox or All Products is installation, to make the k-Wave documentation searchable from within the MAT-LAB help browser, run>> builddocsearchdb( <.. >/ k-Wave Toolbox/helpfiles );again using the slash direction native to your operating system. Note, the created databasefile will only work with the version of MATLAB used to create using the C++ or CUDA versions ofkspaceFirstOrder3D(see discussion in Chapter4), the appropriate binaries (and library files if using Windows) should also be placed in the root binaries folder ofthe Licensek-Wavec 2009-2016 Bradley Treeby, Ben Cox, and Jiri k-Wave toolbox is distributed by the copyright owners under the terms of the GNUL esser General Public License (LGPL).

10 This is a set of additional permissions addedto the GNU General Public License (GPL). The full text of both licenses is includedwith the toolbox in the folder license or is available online LGPL license places copyleft restrictions on the k-Wave toolbox. Essentially, anyonecan use the software for any purpose (commercial or non-commercial), the source codefor the toolbox is freely available, and anyone can redistribute the software (in its originalform or modified) as long as the distributed product comes with the full source code andis also licensed under the LGPL. You can make private modified versions of the toolboxwithout any obligation to divulge the modifications so long as the modified software is notdistributed to anyone else. The copyleft restrictions only apply directly to the toolbox,but not to other (non-derivative) software that simply links to or uses the is distributed in the hope that it will be useful, but WITHOUT ANY WAR-RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FORA PARTICULAR PURPOSE.