____________________________________________________________________________

                                  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.4 (fourth beta release), Released 21st December 2011
   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), R2008a
      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: 
- the indexing of input matrices has been modified to (x, 1) in 1D, (x, y) 
  in 2D, and (x, y, z) in 3D to be more intuitive 
- the corresponding inputs to makeGrid are now (Nx, dx) in 1D, 
  (Nx, dx, Ny, dy) in 2D, and (Nx, dx, Ny, dy, Nz, dz) in 3D 
- cumulative nonlinear effects can be modelled by setting medium.BonA 
- heterogeneous absorption values can now be used by defining 
  medium.alpha_coeff as a matrix 
- kspaceFirstOrder1D, kspaceFirstOrder2D, kspaceFirstOrder3D, and makeGrid 
  have been re-written to significantly reduce memory usage 
- source and sensor inputs can be defined as an object of kWaveTransducer 
  type (returned by makeTransducer) to allow simple simulations using 
  ultrasound transducers 
- source.ux, source.uy, and source.uz can be specified individually 
- time varying inputs source.p, source.ux, etc., can now contain any number 
  of time points (they do not need to be the same length as kgrid.t_array) 
- approximate GPU memory usage is reported when using k-Wave with the GPUmat
  or Accelereyes toolboxes 
- the reference sound speed used in the k-space operator can now be manually
  set by defining medium.sound_speed_ref 
- the statistics of the pressure field at each sensor element can now be 
  computed without storing the pressure field by setting sensor.record_mode 
  to 'statistics' 
- 3D sensor_data can now optionally be streamed to disk by setting the 
  optional input parameter 'StreamToDisk' to true
- toneBurst function inputs have changed 
- db2neper and neper2db now use exact conversion factor 
- frequency filtering applied when sensor.frequency_response is given is now 
  performed using gaussianFilter 
- B.01 release style inputs no longer supported 

Bug Fixes: 
- bug fix in defining the absorption parameters for heterogeneous media 
- bug fix in setting initial velocity for kspaceFirstOrder3D 
- bug fix in frequency filtering applied when kgrid.t_array has an odd number
  of time points 
- bug fix in kspaceFirstOrder2D when saving movies with 'MovieType' set to 
  'image' (the first frame did not display the sensor mask), and the movie 
  frames variable is now preallocated 
- bug fix in creating the spatial wavenumber matrices using the kWaveGrid 
  class when 1/Nx (etc) is a recurring number 

New Functions: 
- checkFactors 
- envelopeDetection 
- findClosest 
- gaussianFilter 
- logCompression 
- makeTransducer 
- mendousse 
- stackedPlot 

New Examples: 
- Defining An Ultrasound Transducer 
- Simulating Ultrasound Beam Patterns 
- Using An Ultrasound Transducer As A Sensor 
- Simulating B-mode Ultrasound Images 
- Modelling Nonlinear Wave Propagation

____________________________________________________________________________

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.
____________________________________________________________________________