Release Notes
Current Version: k-Wave Toolbox Version 1.3
Contents
- V.1.3 (released 28 Feb 2020)
- V.1.2.1 (released 14 Dec 2017)
- V.1.2 (released 28 Aug 2017)
- V.1.1.1 (released 09 Oct 2015)
- V.1.1 (released 03 Oct 2014)
- V.1.0 (released 13 Nov 2012)
- B.0.5 (released 28 Feb 2012)
- B.0.4 (released 21 Dec 2011)
- B.0.3 (released 15 Feb 2011)
- B.0.2 (released 23 Jan 2010)
- B.0.1 (released 22 July 2009)
Change Log - V.1.3
Release Date: 28 Feb 2020
New Features and Changes:
- axisymmetric simulations are now supported using
kspaceFirstOrderASandkspaceFirstOrderASC - single-frequency simulations in homogeneous media can be computed without time-stepping using
acousticFieldPropagatorandacousticFieldPropagatorC - time-varying sources in
kspaceFirstOrder1D,kspaceFirstOrder2D, andkspaceFirstOrder3D(and the corresponding C++ codes) now include a k-space correction which improves accuracy for small numbers of points per period - legacy behaviour for time-varying sources can be obtained by setting
source.p_mode = 'additive-no-correction'andsource.u_mode = 'additive-no-correction' - holographic projections of planar input data can be performed using
angularSpectrumandangularSpectrumCW - measured pressure fields can be mapped to k-Wave inputs for accurate holographic projections using
calculateMassSourceandcalculateMassSourceCW 'PMLSize'can now be set to'auto'to automatically choose grid sizes with small prime factors- 2D simulations can now be run using optimised C++ and C++/CUDA codes using
kspaceFirstOrder2DCandkspaceFirstOrder2DG kspaceFirstOrder3DC(etc) now automatically calls thecombine_sensor_datamethod if an object of thekWaveTransducerclass is used as a sensorkspaceFirstOrder3DC(etc) now supports optional inputs to define the number of threads, thread binding, and the verbosity level- the compiled C++ codes have been combined into two binaries now called
kspaceFirstOrder-OMP(which supports 2D, 3D, and axisymmetric domains) andkspaceFirstOrder-CUDA(which supports 2D and 3D domains) - the input file for the C++ code has been updated to version 1.2 (the k-space and shift variables, and PML vectors are no longer required)
pstdElastic2DandpstdElastic3Dcan now return the particle velocity split into compressional and shear components by settingsensor.record = {'u_split_field'}kWaveDiffusionnow allows command line updates to be suppressed by setting the optional input'DisplayUpdates', falsekWaveDiffusionnow prints a warning if dimension sizes have high prime factorstoneBurstnow allows the number of ring-up and ring-down cycles to be specifiedmakeDiscandmakeBallnow allow non-integer radius values and maintain correct radius on axisspectandextractAmpPhasenow work for 4D input matriceswaterAbsorptionnow allows temperature to be defined as a vectorgetWinnow allows'Symmetry'input to be defined as a vectorsmoothfunction inputs have changed (kgridinput no longer required)
Bug Fixes:
- bug fix in
waterSoundSpeedfor matrix inputs (generated error) - bug fix in
focusedBowlONeilwhenaxial_position = radius(sometimes returned 0) - bug fix in
getBLIfor functions with odd numbers of grid points (used incorrect wavenumbers) - bug fix in
extractAmpPhasefor optional input'Dim', 1(generated error) - bug fix in
kWaveDiffusionwhen using theplotTempmethod in 3D with an odd number of grid points (generated error) - bug fix in
smoothfor matrices with even numbers of grid points (incorrectly filtered DC component) - bug fix in Simulating B-mode Ultrasound Images and Simulating B-mode Images Using A Phased Array examples (attenuation value for time gain compensation given in incorrect units)
New Functions:
acousticFieldPropagatoracousticFieldPropagatorCangularSpectrumangularSpectrumCWcalculateMassSourcecalculateMassSourceCWgetOptimalPMLSizekspaceFirstOrder2DCkspaceFirstOrder2DGkspaceFirstOrderASkspaceFirstOrderASCreorderBinarySensorDataroundEvenroundOddwaterDensitywaterNonlinearity
Deprecated Functions:
speedSoundWater(renamed towaterSoundSpeed)attenuationWater(renamed towaterAbsorption)
New Examples:
- Simulations In An Axisymmetric Coordinate System
- Simulating CW Fields Using The Acoustic Field Propagator
- Holographic Projections Using The Angular Spectrum Method
- Equivalent Source Holography
Change Log - V.1.2.1
Release Date: 14th December 2017
Bug Fixes:
- bug fix in
kWaveDiffusionwhen usingsource.Qwithmedium.diffusion_coeff(source term incorrectly scaled)
Change Log - V.1.2
Release Date: 28 Aug 2017
New Features and Changes:
- thermal simulations are now supported using the
kWaveDiffusionclass andbioheatExact - focused bowl transducers can be created using
makeArcandmakeMultiArcin 2D, andmakeBowlandmakeMultiBowlin 3D - a warning is printed if dimension sizes have high prime factors
- default HDF5 compression level is now 0 (increases speed of saving input file for C++ codes)
- the compression level for HDF5 files can be set using the optional input
'HDFCompressionLevel' - movies are now saved using
VideoWriter(see help for changes to optional inputs) kspaceFirstOrder3DGnow allows the device number of the GPU to be selectedhounsfield2densitynow returns matrices of the same data type as the inputkWaveGridis now implemented as a handle class (only handles are passed to functions to save memory)kWaveGridnow returns wavenumber vectors for discrete cosine and sine transformswriteMatrixnow accepts an optional compression level inputmakeGridhas been deprecated, with grids created using the syntaxkgrid = kWaveGrid(...)makeTimehas been deprecated, and is now a method ofkWaveGridmakeTransducerhas been deprecated, with transducers created using the syntaxtransducer = kWaveTransducer(...)- update to
overlayPlotto allow optional inputs scaleSInow returns no scale for zero valuesmakeCirclenow supports circles not contained within the gridspeedSoundWaternow checks temperature limits- update to style used in MATLAB documentation
Bug Fixes:
- bug fix in
kspaceFirstOrder1D,kspaceFirstOrder2D, andkspaceFirstOrder3Dfor nonlinear simulations (convective nonlinearity term implemented incorrectly) - bug fix in using simulation functions in MATLAB 2016b and later (error with use of
narginandnargoutin subscripts) - bug fix in
kspaceFirstOrder2Dwhen usingsensor.directivity_pattern = 'gradient'(directional response incorrect) - bug fix in
kspaceFirstOrder3DGwhen using a sensor mask defined by opposing corners and recording intensity (generated error) - bug fix in
kspaceFirstOrder3D-OMPwhen using akWaveTransducersource with checkpoint restart (wrong index used for time signal on restart) - bug fix in
kspaceLineReconandkspacePlaneRecon(incorrect use offftshiftcaused energy loss at certain frequencies) - bug fix in
findClosest(returned correct index but incorrect closest value) - bug fix in setting apodization in
kWaveTransducerclass with only one active element (returned NaN) - bug fix in
writeGridfor odd dimension sizes (used even wavenumber components)
New Functions:
bioheatExactcreateCWSignalsextractAmpPhasefocusedBowlONeilfourierShiftgetComputerInfokWaveDiffusionmakeArcmakeMultiArcmakeBowlmakeMultiBowl
Deprecated Functions:
makeGridmakeTimemakeTransducertimeShift
New Examples:
- Heat Diffusion In A Homogeneous Medium
- Constant Rate Of Heat Deposition
- Using A Binary Sensor Mask
- Heating By A Focused Ultrasound Transducer
- Iterative Image Reconstruction Using The Adjoint
Change Log - V.1.1.1
Release Date: 9th October 2015
Bug Fixes:
- bug fix in
pstdElastic2DandpstdElastic3Dwhen defining material coefficients on staggered grid (generated incorrect results)
Change Log - V.1.1
Release Date: 3rd October 2014
New Features and Changes:
- simulations in elastic media are now supported using the
pstdElastic2DandpstdElastic3Dfunctions - 3D simulations can be run on an NVIDIA graphics processing unit (GPU) using a native C++/CUDA code
- rectangular binary sensor masks can be defined by assigning the grid coordinates of two opposing corners to
sensor.mask sensor.recordnow supports the additional input options'p_min','p_max_all','p_min_all','u_min','u_max_all','u_min_all', and'u_non_staggered'- simulation functions have been restructured to reduce code duplication
- the accuracy of the acoustic intensity output for frequencies close to Nyquist limit has been improved
- the C++ code now supports command line inputs for checkpoint-restart and importing FFTW wisdom
- the C++ code now exploits AVX instructions in addition to SSE
- attenuation compensation for photoacoustic tomography can be performed using time-variant filtering via
attenComp - vessel filtering for photoacoustic tomography can be performed using
vesselFilter kspaceFirstOrder3DCnow supports optional inputs to specify the name and location of the binary and data filesmakeSphereandmakeSphericalSectioncan be set to return logical matrices to reduce memory usageresizenow supports 1D inputscheckFactorsnow also reports prime numbers
Bug Fixes:
- bug fix in using a Cartesian sensor mask with nearest neighbour interpolation and
sensor.recordset to'p_min'(generated error) - bug fix in using
sensor.directivity_anglewith the optional input'DataCast'set to'gpuArray-single'(generated error) - bug fix in
kspaceFirstOrder3DCwhen performing time reversal image reconstruction usingsensor.time_reversal_boundary_datawith'PMLInside'set tofalse(PML was not removed) - bug fix in
kspaceFirstOrder3DCwhen calling script on a different drive using Windows (generated error) - bug fix in
kspaceSecondOrderwhen setting absorption values withmedium.alpha_powerto values less than 1 (returned NaN) - bug fix in
kspaceSecondOrderwhen usingsensor.record = {'p_final'}(generated error, grid expansion not removed) - bug fix in
makeSpherefor grid sizes with uneven dimensions (generated error) - bug fix in
makeSphereto centre sphere on the kgrid origin (previously offset by 1) - bug fix in
writeMatrixfor source variables larger than 1 MB (incorrect chunk size generated error)
New Functions:
attenCompcheckStabilityfitPowerLawParamsgetBLIgetSpacedPointsh5comparekspaceFirstOrder3DGmaxNDminNDoverlayPlotpstdElastic2DpstdElastic3Drevolve2DtimeShiftvesselFilterwriteAttributeswriteFlagswriteGrid
New Examples:
- Defining A Sensor Mask By Opposing Corners
- Attenuation Compensation Using Time Variant Filtering
- Running C++ Simulations
- Saving Input Files in Parts
- Explosive Source In A Layered Medium
- Plane Wave Absorption
- Shear Waves And Critical Angle Reflection
- Simulations In Three Dimensions
Change Log - V.1.0
Release Date: 13th November 2012
New Features and Changes:
- 3D simulations can now be run using an optimised C++ code
- the data recorded by the sensor mask is now set using
sensor.record = {'p', 'u', 'p_final', ...} - time-varying and averaged acoustic intensity can be returned by setting
sensor.record = {'I', 'I_avg', ...} - the inputs
'ReturnVelocity'andsensor.record_modeand the outputfield_datahave been deprecated - the time index at which the sensor starts recording can be set using
sensor.record_start_index 'DataCast'can now be set to'gpuArray-single'or'gpuArray-double'to automatically run simulations on a graphics processing unit (GPU) using the Parallel Computing Toolbox (R2012a or later)- output variables are now created and returned using the data type specified by
'DataCast' - output variables can be returned in double precision by setting
'DataRecast'totrue - Cartesian sensor masks with linear interpolation are now supported for all
'DataCast'settings and the interpolation speed during runtime has been significantly improved 'CartInterp'set to'linear'is now the default setting for 1D, 2D, and 3D simulations- the calculation of
kgrid.kwithinmakeGridhas been modified to improve memory efficiency spectrumhas been renamed tospectto avoid a naming conflict with the MATLAB signal processing toolbox, and now accepts matrix inputsmakeTimenow uses the maximum sound speed to computedt, and the minimum sound speed to computet_endunmaskSensorDatafunction inputs have changed
Bug Fixes:
- bug fix in using
'PlotLayout'set totruewhenmedium.sound_speedormedium.densityare scalar (generated plot error) - bug fix in list of data cast variables for
'DataCast'set to'GPUsingle' - bug fix in setting the source scale parameter for time varying pressure sources in heterogeneous media with
p_modeset to'dirichlet' - bug fix in setting the axis limits in
kspaceFirstOrder2Dwith'MeshPlot'set totrue - bug fix in
makeGridwhen defining the wavenumber variableskgrid.k,kgrid.kx(etc) for grid sizes with an odd number of grid points - bug fix in
makeSpherefor grid sizes with an odd number of grid points - bug fix in
getWinfortypeset to'Gaussian'or'Kaiser'with a user input for'Param'(param value was not used) - bug fix in the
scan_linemethod ofkWaveTransducerfor scan lines formed using a negative steering angle (generated error) - bug fix in
grid2cartfor 1D inputs (list of Cartesian points returned in the wrong direction) - bug fix in computing axis units in
kspaceSecondOrder
New Functions:
beamPlotfocusgetFDMatrixgradientSpectgradientFDkspaceFirstOrder3DCmakeLinemakeSphericalSectionreorderSensorDatascaleFigscanConversionwriteMatrix
New Examples:
Change Log - B.0.5
Release Date: 28th February 2012
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_modeandsource.u_modeto'dirichlet' - the implementation of source terms in
kspaceFirstOrder1D,kspaceFirstOrder2D,kspaceFirstOrder3Dhas been modified to reduce code duplication - the performance of the PML has been improved and the default value for
'PMLAlpha'changed to2 - the plotting speed in
kspaceFirstOrder1Dhas 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
stackedPlotfunctionality 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
kWaveTransducerclass (no scaling was applied) - bug fix in applying long time varying sources using the
kWaveTransducerclass (data type was set incorrectly) - bug fix in
kspaceFirstOrder1Dusing velocity sources (source incorrectly named) - bug fix in using
'PlotLayout', truewith'DataCast', 'gsingle'(generated blank jacket figure) - bug fix in
'StreamToDisk'option (error generated ifkgrid.Ntexactly divisible by saving frequency)
New Functions:
New Examples:
Change Log - B.0.4
Release Date: 21st December 2011
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
makeGridare 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_coeffas a matrix kspaceFirstOrder1D,kspaceFirstOrder2D,kspaceFirstOrder3D, andmakeGridhave been re-written to significantly reduce memory usagesourceandsensorinputs can be defined as an object ofkWaveTransducertype (returned bymakeTransducer) to allow simple simulations using ultrasound transducerssource.ux,source.uy, andsource.uzcan 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 askgrid.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_modeto'statistics' - 3D
sensor_datacan now optionally be streamed to disk by setting the optional input parameter'StreamToDisk'totrue toneBurstfunction inputs have changeddb2neperandneper2dbnow use exact conversion factor- frequency filtering applied when
sensor.frequency_responseis given is now performed usinggaussianFilter - 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_arrayhas an odd number of time points - bug fix in
kspaceFirstOrder2Dwhen 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
makeGridclass when 1/Nx (etc) is a recurring number
New Functions:
checkFactorsenvelopeDetectionfindClosestgaussianFilterlogCompressionmakeTransducermendoussestackedPlot
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
Change Log - B.0.3
Release Date: 15th February 2011
New Features and Changes:
- support for time varying velocity inputs via
source.u_mask,source.uxetc - sensor data now also returns velocity if
'ReturnVelocity'is set totrue - 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 usesTriScattererdInterpand is supported in 3D'PMLInside'set tofalseis now supported in 3D- estimated simulation times are given
- the PML can be hidden by setting
'PlotPML'tofalse 'PlotScale'can now also be set to'auto'and the display can be log compressed by setting'LogScale'totrue- 2D simulations can now also be displayed as a mesh plot by setting
'MeshPlot'totrue - 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
kspaceSecondOrderbased on a second-order lossy wave equation for homogeneous media makeGridnow uses class definitionsspectrumnow supports all window shapes defined ingetWinsmoothnow uses a Blackman window as default and supports all window shapes defined ingetWinresizefunction inputs have changed and now supports 3D inputs- bug fix in
kspacePlaneReconremapping
New Functions:
addNoiseapplyFilterbenchmarkexpandMatrixfwhmgaussiangetAlphaFiltergetDateStringgetWininterpftnkspaceSecondOrdersaveTiffStackvoxelPlot
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
Change Log - B.0.2
Release Date: 23rd January 2010
New Features:
- inputs redefined as structures
- power law absorption
- 2D sensor directivity
- time varying pressure inputs
New Functions:
attenuationWaterdb2neperfilterTimeSeriesgrid2cartneper2dbnumDimpowerLawKramersKronigscaleSIscaleTimespectrumspeedSoundWatertoneBurst
Change Log - B.0.1
Release Date: 22nd July 2009
First Beta Release.