Grid

Package: kwave.toolbox

Class used to define the spatial grid for a simulation.

Syntax

kgrid = Grid(gridSize, gridSpacing)
kgrid = Grid(gridSize, gridSpacing, gridPadding)

Description

Grid is the grid class used across the k-Wave Toolbox. An object of the Grid class defines the grid coordinates and spatial frequency (wavevector) matrices for a particular simulation.

The grid is assumed to be a regular Cartesian grid with grid spacing given by gridSpacing. The spatial grid matrices are indexed as: (x, 1) in 1D; (x, y) in 2D; and (x, y, z) in 3D. Typically the grid spacing in each direction is constant where gridSpacing is defined by a scalar.

To create the object, pass the gridSize in grid points and the gridSpacing in metres. For example, to create a 2D grid that is 128 x 128 with a grid spacing of 1 mm, call:

   kgrid = Grid([128, 128], 1e-3);

The origin is defined to be in the centre of the spatial grid. For odd dimensions, the origin is at the central point. For even dimensions, the origin is shifted one grid point in the positive direction. For example, in the x-direction, the origin when kgrid.Nx is even is at kgrid.xVec(end/2 + 1).

The wavevector components are defined with the zero frequency at the centre of the spectrum. These should be transformed using ifftshift before using with the MATLAB FFT functions (which are based on FFTW).

Optionally, the gridPadding can be specified in grid points. This defines an additional padding on the outside of the grid defined by gridSize. The padding is added to each side of the grid in each Cartesian direction, so the total grid size including padding will be gridSize + 2*gridPadding. Note, the grid and wavevector properties are defined relative to gridSize, not including the gridPadding.

To check if an input matrix matches the grid size specified by a Grid object, the validateSize method can be used.

Input Arguments

  • gridSize - (double) Number of grid points in each Cartesian direction [grid points].
  • gridSpacing - (double) Grid point spacing [m]. Can be specified as a scalar value, or the spacing in each Cartesian direction. Be careful if specifying different spacings in each direction, as the maximum supported frequency depends on the grid spacing.
  • gridPadding - (double) Grid padding [grid points]. Can be specified as a scalar value, or the padding in each Cartesian direction. If not specified, the padding is set to [0, 0, 0].

Properties

Properties which can be queried, but not modified, after the object is created.

  • dimensions - (double) Number of grid dimensions (1, 2, or 3).
  • gridSize - (double) Number of grid points in each direction defined as a 3-element row vector [gridPoints]. For 1D and 2D grids, the higher dimensions have a size of 1.
  • gridSpacing - (double) Grid point spacing in each direction defined as a 3-element row vector [m]. For 1D and 2D grids, the higher dimensions have a spacing of 0.
  • gridPadding - (double) Grid padding in each direction defined as a 3-element row vector [gridPoints]. For 1D and 2D grids, the higher dimensions have a padding of 0.
  • Nx, Ny, Nz - (double) Individual components of gridSize.
  • dx, dy, dz - (double) Individual components of gridSpacing.
  • xVec, yVec, zVec - (double) Grid coordinates in each direction [m].
  • x, y, z - (double) Nx by Ny by Nz matrices containing repeated copies of the grid coordinates [m].
  • xSize, ySize, zSize - (double) Physical size of grid [m].
  • totalGridPoints - (double) Total number of grid points.
  • kxVec, kyVec, kzVec - (double) Wavevector components in each direction [rad/m].
  • kx, ky, kz - (double) Nx by Ny by Nz matrices containing repeated copies of the wavevector components [rad/m].
  • k - (double) Nx by Ny by Nz matrix of scalar wavenumber [rad/m].
  • kxMax, kyMax, kzMax - (double) Maximum supported spatial frequency in each direction [rad/m].
  • kMax - (double) Maximum supported spatial frequency in all directions [rad/m]. If the grid spacing is different in each direction, kMax is given as the maximum spatial frequency that is supported in all directions, i.e., the minimum of [kxMax, kyMax, kzMax].

Methods