kwave.kspaceFirstOrderAS module

kspaceFirstOrderAS(kgrid, source, sensor, medium, simulation_options, execution_options)[source]

Axisymmetric time-domain simulation of wave propagation.

kspaceFirstOrderAS simulates the time-domain propagation of compressional waves through an axisymmetric homogeneous or heterogeneous acoustic medium. The code is functionally very similar to kspaceFirstOrder2D. However, a 2D axisymmetric coordinate system is used instead of a 2D Cartesian coordinate system. In this case, x corresponds to the axial dimension, and y corresponds to the radial dimension. In the radial dimension, the first grid point corresponds to the grid origin, i.e., y = 0. In comparison, for kspaceFirstOrder2D, the Cartesian point y = 0 is in the middle of the computational grid.

The input structures kgrid, medium, source, and sensor are defined in exactly the same way as for kspaceFirstOrder2D. However, computationally, there are several key differences. First, the axisymmetric code solves the coupled first-order equations accounting for viscous absorption (not power law), so only medium.alpha_power = 2 is supported. This value is set by default, and doesn’t need to be defined. This also means that medium.alpha_mode and medium.alpha_filter are not supported. Second, for a homogeneous medium, the k-space correction used to counteract the numerical dispersion introduced by the finite-difference time step is not exact (as it is for the other fluid codes). However, the approximate k-space correction still works very effectively, so dispersion errors should still be small. See kspaceFirstOrder2D for additional details on the function inputs.

In the x-dimension (axial), the FFT is used to compute spatial gradients. In the y-dimension (radial), two choices of symmetry are possible. These are whole-sample-symmetric on the interior radial boundary (y = 0) and either whole-sample-symmetric or whole-sample-asymmetric on the exterior radial boundary. These are abbreviated WSWA and WSWS. The WSWA and WSWS symmetries are implemented using both discrete trigonometric transforms (DTTs), and via the FFT by manually mirroring the domain. The latter options are abbreviated as WSWA-FFT and WSWS-FFT. The WSWA/WSWS options and the corresponding WSWA-FFT/WSWS-FFT options agree to machine precision. When using the PML, the choice of symmetry doesn’t matter, and all options give very similar results (to several decimal places). Computationally, the DTT implementations are more efficient, but require additional compiled MATLAB functions (not currently part of k-Wave). The symmetry can be set by using the optional input ‘RadialSymmetry’. The WSWA-FFT symmetry is set by default.

Note: For heterogeneous medium parameters, medium.sound_speed and medium.density must be given in matrix form with the same dimensions as kgrid. For homogeneous medium parameters, these can be given as single numeric values. If the medium is homogeneous and velocity inputs or outputs are not required, it is not necessary to specify medium.density.

Parameters:

  • kgrid (kWaveGrid) – kWaveGrid instance

  • medium (kWaveMedium) – kWaveMedium instance

  • source (kSource) – kWaveSource instance

  • sensor (NotATransducer | kSensor) – kWaveSensor instance

  • **kwargs

  • simulation_options (SimulationOptions)

  • execution_options (SimulationExecutionOptions)

Returns:

kspaceFirstOrderASC(kgrid, source, sensor, medium, simulation_options, execution_options)[source]

Axisymmetric time-domain simulation of wave propagation using C++ code.

kspaceFirstOrderASC provides a blind interface to the C++ version of kspaceFirstOrderAS (called kspaceFirstOrder-OMP) in the same way as kspaceFirstOrder3DC. Note, the C++ code does not support all input options, and all display options are ignored (only command line outputs are given). See the k-Wave user manual for more information.

The function works by appending the optional input ‘save_to_disk’ to the user inputs and then calling kspaceFirstOrderAS to save the input files to disk. The contents of sensor.record (if set) are parsed as input flags, and the C++ code is run using the system command. The output files are then automatically loaded from disk and returned in the same fashion as kspaceFirstOrderAS. The input and output files are saved to the temporary directory native to the operating system, and are deleted after the function runs.

For small simulations, running the simulation on a smaller number of cores can improve performance as the matrices are often small enough to fit within cache. It is recommended to adjust the value of ‘NumThreads’ to optimise performance for a given simulation size and computer hardware. By default, simulations smaller than 128^2 are set to run using a single thread (this behaviour can be over-ridden using the ‘NumThreads’ option). In some circumstances, for very small simulations, the C++ code can be slower than the MATLAB code.

This function requires the C++ binary/executable of kspaceFirstOrder-OMP to be downloaded from http://www.k-wave.org/download.php and placed in the “binaries” directory of the k-Wave toolbox (the same binary is used for simulations in 2D, 3D, and axisymmetric coordinates). Alternatively, the name and location of the binary can be specified using the optional input parameters ‘BinaryName’ and ‘BinariesPath’.

This function is essentially a wrapper and directly uses the capabilities of kspaceFirstOrder3DC by replacing the binary name with the name of the GPU binary.

Parameters:

Returns: