____________________________________________________________________________

                                  k-Wave

                    A MATLAB toolbox for the time-domain 
                     simulation of acoustic wave fields
____________________________________________________________________________

PRODUCT OVERVIEW
____________________________________________________________________________

k-Wave is a freely available 3rd party toolbox for MATLAB developed for the 
time-domain simulation of acoustic wave propagation. It uses a grid-based 
iterative k-space pseudo-spectral solution method to coupled first-order 
acoustic equations. It has been designed to make tissue realistic 
simulations of ultrasound and photoacoustics fast and easy to use.

   Version B.0.3 (third beta release), Released 15th February 2011
   Written by Bradley Treeby and Ben Cox

   Tested using Matlab R2007a and R2010b running on Microsoft Windows XP, 
   Vista, and 7 (32 and 64 bit), and Linux Fedora 11, and Mac OS.

Please send reports of bugs and suggestions to mail@k-wave.org. The toolbox 
may be downloaded from http://www.k-wave.org.
____________________________________________________________________________

INSTALLATION INSTRUCTIONS
____________________________________________________________________________

WINDOWS: 

  1. Save and unpack the k-Wave zip file to a suitable folder, eg. 

     C:\Program Files\MATLAB\<version>\toolbox\k-Wave Toolbox

  2. Add this folder to the MATLAB path. This can be done by selecting 
     "Set Path" using the dropdown menus (File, Set Path) then clicking 
     "Add Folder", selecting the k-Wave Toolbox folder and clicking "save". 
     Alternatively, this can be done by adding the line

     addpath('<pathname>\k-Wave Toolbox');

     eg. addpath('C:\Program Files\MATLAB\R2009b\toolbox\k-Wave Toolbox');

     to the startup.m file. If no startup.m file exists, create one and save
     it in the MATLAB startup directory or any directory in the MATLAB path. 

  3. Restart Matlab, or run the command

     >> startup

     at the command line to add the path to the current Matlab session.

  4. Open the help browser by clicking on the blue question mark icon on 
     the menu bar, then select 'k-Wave Toolbox' under the contents tab. To 
     get started, try running some of the examples by first selecting them 
     and then clicking on 'run the file'.


LINUX: 

  1. Save and unpack the k-Wave zip file to a suitable folder, eg. 

     ~/Matlab/k-Wave

  2. Add this folder to the MATLAB path. This can be done by adding the 
     line

     addpath('<pathname>/k-Wave Toolbox');

     eg. addpath('~/Matlab/k-Wave');

     to the startup.m file. If no startup.m file exists, create one and save
     it in the MATLAB startup directory or any directory in the MATLAB path.

  3. Restart Matlab, or run the command

     >> startup

     at the command line to add the path to the current Matlab session.

  4. Open the help browser by clicking on the blue question mark icon on 
     the menu bar, then select 'k-Wave Toolbox' under the contents tab. To 
     get started, try running some of the examples by first selecting them 
     and then clicking on 'run the file'.

____________________________________________________________________________

RELEASE NOTES
____________________________________________________________________________

New Features and Changes: 
  - support for time varying velocity inputs via source.u_mask, source.ux 
    etc 
  - sensor data now also returns velocity if 'ReturnVelocity' is set to true 
  - sensor frequency response can be defined using sensor.frequency_response 
  - time reversal image reconstructions can include compensation for 
    acoustic attenuation 
  - 'CartInterp' set to 'linear' now uses TriScattererdInterp and is 
    supported in 3D 
  - 'PMLInside' set to false is now supported in 3D 
  - estimated simulation times are given 
  - the PML can be hidden by setting 'PlotPML' to false 
  - 'PlotScale' can now also be set to 'auto' and the display can be log 
    compressed by setting 'LogScale' to true 
  - 2D simulations can now also be displayed as a mesh plot by setting 
    'MeshPlot' to true 
  - movie frame capture in 2D can be controlled using 'MovieType' 
  - default smoothing now only applies to the initial pressure distribution 
  - kgrid.x_off (etc) fields are no longer supported 
  - bug fix in setting initial velocity for time staggered grids 
  - new k-space simulation function kspaceSecondOrder based on a 
    second-order lossy wave equation for homogeneous media 
  - makeGrid now uses class definitions 
  - spectrum now supports all window shapes defined in getWin 
  - smooth now uses a Blackman window as default and supports all window 
    shapes defined in getWin 
  - resize function inputs have changed and now supports 3D inputs 
  - bug fix in kspacePlaneRecon remapping 

New Functions: 
  - addNoise 
  - applyFilter 
  - benchmark 
  - expandMatrix 
  - fwhm 
  - gaussian 
  - getAlphaFilter 
  - getDateString 
  - getWin 
  - interpftn 
  - kspaceSecondOrder 
  - saveTiffStack 
  - voxelPlot 

New Examples: 
  - Recording The Particle Velocity 
  - Defining A Gaussian Sensor Frequency Response 
  - Comparison Of Modelling Functions 
  - Setting An Initial Pressure Gradient 
  - Photoacoustic Waveforms in 1D, 2D and 3D 
  - Dipole Point Source In A Homogeneous Propagation Medium 
  - The Doppler Effect 
  - Diffraction Through A Slit 
  - Focussed Detector in 3D 
  - Modelling Sensor Directivity in 2D 
  - Modelling Sensor Directivity in 3D 
  - Focussed 2D Array with Directional Elements 
  - Image Reconstruction With Directional Sensors 
  - Image Reconstruction With Bandlimited Sensors 
  - Image Reconstruction With Compensation For Acoustic Absorption 
  - Source Smoothing 
  - Modelling Power Law Absorption

____________________________________________________________________________

LICENSE
____________________________________________________________________________

k-Wave (c) 2009, 2010, 2011 Bradley Treeby and Ben Cox

The k-Wave toolbox is distributed by the copyright owners under the terms of
the GNU Lesser General Public License (LGPL) which is a set of additional 
permissions added to the GNU General Public License (GPL). The full text of 
both licenses is included with the toolbox in the folder 'license'.

The licence places copyleft restrictions on the k-Wave toolbox. Essentially,
anyone can use the software for any purpose (commercial or non-commercial), 
the source code for the toolbox is freely available, and anyone can 
redistribute the software (in its original form or modified) as long as the
distributed product comes with the full source code and is also licensed 
under the LGPL. You can make private modified versions of the toolbox 
without any obligation to divulge the modifications so long as the modified
software is not distributed 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 toolbox. 

k-Wave is distributed in the hope that it will be useful, but WITHOUT ANY 
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 
details (http://www.gnu.org/licenses/lgpl.html). 

If you find the toolbox useful for your academic work, please consider 
citing:

B. E. Treeby and B. T. Cox, "k-Wave: MATLAB toolbox for the simulation and 
reconstruction of photoacoustic wave-fields," J. Biomed. Opt., vol. 15, no. 
2, p. 021314, 2010.

along with any other relevant publications.
____________________________________________________________________________