k-Wave Toolbox |

## Controlling The Absorbing Boundary Layer Example

On this page…
Overview Controlling the properties of the absorbing boundary layer Switching off the PML A partially effective PML Setting the PML to be outside the computational grid

### Overview

The first-order simulation codes included within the k-Wave Toolbox (`kspaceFirstOrder1D`, `kspaceFirstOrder2D`, and `kspaceFirstOrder3D`) are based on the numerical solution of coupled first-order differential equations for wave propagation in a heterogeneous medium. The inherent advantage of using these equations (compared to the conventional second-order wave equation) is that an absorbing boundary layer can be easily be included. Without this boundary layer, the computation of the spatial derivates via FFT causes waves leaving one side of the domain to 'reappear' at the opposite side. When it is included, infinite domain simulations can be computed without needing to increase the size of the actual computational domain as waves reaching the domain boundaries are absorbed.

Within the first-order codes, a special type of absorbing boundary condition called a perfectly matched layer (PML) is implemented. This example demonstrates how to control the parameters of the PML within k-Wave via optional input parameters.

- open the file in the MATLAB Editor
- run the file in MATLAB

Back to Top

### Controlling the properties of the absorbing boundary layer

The PML has three inherent properties, each of which can be controlled via optional input parameters. The size of the layer on each edge is set by `'PMLSize'` given in pixels (the default setting is 20), and the absorption within the layer is set by `'PMLAlpha'` given in Nepers per metre (the default setting is 4). The location of the layer can also be set to be inside or outside the computational grid created by the user by changing the value of the boolean flag `'PMLInside'` (the default setting is `true`). If `'PMLInside'` is set to `false` (not currently supported in 3D), the input grids are enlarged on each edge by the size given by `'PMLSize'`.

For accurate simulations, care must be taken that the initial pressure distribution and the sensor mask don't lie within the PML. This can be avoided by setting `'PMLInside'` to `false`. Note, the computation speed will still be dependent on the total size of the grid including the PML (i.e., computations will be fastest for grids where the number of pixels is given by a power of two).

Back to Top

### Switching off the PML

The effect of the PML can be illustrated most clearly by switching it completely off by setting the optional input `'PMLAlpha'` to `0` (set `example_number = 1` within the example m-file). This sets the absorption within the layer to zero, thus the waves leaving one side of the domain reappear at the opposite side. A visualisation of the recorded time-series is given below.

Back to Top

### A partially effective PML

The effectiveness of the PML depends on its size and absorption, but also on the time step used in the simulation (the more time steps the wave spends in the layer, the more it will be absorbed). A partially effective PML can be illustrated reducing the size of the PML by setting the optional input `'PMLSize'` to `5` (set `example_number = 2` within the example m-file). The layer absorbs some (but not all) of the waves approaching the boundaries, and some of the wave wrapping seen in the previous example is still evident.

Back to Top

### Setting the PML to be outside the computational grid

By default, the PML will be inside the grid defined by the user, so care must be taken that the sensor positions or initial pressure are not within this region. This can be avoided by setting the optional input `'PMLInside'` to `false` (set `example_number = 3` within the example m-file). This mode gives several additional command line status readouts, including feedback on expanding the input grids, and the size of the computational grid (in this case 168 by 168 pixels). Compare the computational speed in this example with that in the Homogeneous Propagation Medium Example (where the computational grid size was 128 by 128 pixels or 2^7).

    Running k-space simulation...
      dt: 20ns, t_end: 12.06us, time steps: 604
      input grid size: 128 by 128 pixels (12.8 by 12.8mm)
      maximum supported frequency: 7.5MHz
      smoothing p0 distribution...
      expanding computational grid...
      computational grid size: 168 by 168 pixels
      calculating Delaunay triangulation...
      precomputation completed in 1.5815s
      starting time loop...
      computation completed in 9.0124s

As the inner part of the computation grid is identical to that in the Homogeneous Propagation Medium Example, the recorded time-series (shown below) is also identical. Here the default size and absorption for the PML are adequate to prevent any visible wave wrapping. For any particular example, if the performance of the PML is not sufficient, increasing the size of the PML or reducing the time-step used in `t_array` will give improvements.

Back to Top

© 2009, 2010 Bradley Treeby and Ben Cox.