____________________________________________________________________________

                                  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 pseudospectral 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.5 (fifth beta release), Released 28th February 2012
   Written by Bradley Treeby and Ben Cox

   Tested using:
      Mac OS X Lion: MATLAB R2011a
      Windows 7 64-bit: MATLAB R2010b, R2011a
      Windows XP 32-bit: MATLAB R2007a (see Troubleshooting notes), R2009a
      Linux (Fedora 14, Ubuntu 10.04): R2010b, R2011a

Please report bugs and suggestions on http://www.k-wave.org/forum
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: 
- time varying pressure and velocity inputs can now be either applied as 
  mass and force sources (the default), or enforced as a Dirichlet boundary 
  condition by setting source.p_mode and source.u_mode to 'dirichlet' 
- the implementation of source terms in kspaceFirstOrder1D, 
  kspaceFirstOrder2D, kspaceFirstOrder3D has been modified to reduce code 
  duplication 
- the performance of the PML has been improved and the default value for 
  'PMLAlpha' changed to 2 
- the plotting speed in kspaceFirstOrder1D has been improved 
- the axis limits for the 'PlotLayout' option have been modified to allow 
  easier interpretation 
- the default status bar position has been shifted to below the plot window 
- estimated simulation times are now based on the first 50 times steps with 
  the first step excluded 
- stackedPlot functionality has been extended and the default axis limits 
  fixed 
- help files are now searchable using the MATLAB Help browser and k-Wave 
  version is listed using ver 

Bug Fixes: 
- bug fix in setting the scale parameter for time varying pressure and 
  velocity sources in heterogeneous media 
- bug fix in setting the scale parameter using the kWaveTransducer class 
  (no scaling was applied) 
- bug fix in applying long time varying sources using the kWaveTransducer 
  class (data type was set incorrectly) 
- bug fix in kspaceFirstOrder1D using velocity sources (source incorrectly 
  named) 
- bug fix in using 'PlotLayout', true with 'DataCast', 'gsingle' (generated 
  blank jacket figure) 
- bug fix in 'StreamToDisk' option (error generated if kgrid.Nt exactly 
  divisible by saving frequency) 

New Functions: 
- hounsfield2density 
- sharpness 

New Examples: 
- 2D Iterative Image Improvement Using Time Reversal 
- Automatic Sound Speed Selection
____________________________________________________________________________

LICENSE
____________________________________________________________________________

k-Wave (c) 2009-2012 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.
____________________________________________________________________________