# Gridding and Degridding¶

This section contains routines for

1. Gridding complex visibilities onto an image.

2. Degridding complex visibilities from an image.

## Nifty¶

 grid_config([nx, ny, eps, cell_size_x, ...]) Returns a wrapper around a NIFTY GridderConfiguration object. grid(vis, uvw, flags, weights, frequencies, ...) Grids the supplied visibilities in parallel. dirty(grid, grid_config) Computes the dirty image from gridded visibilities and the gridding configuration. degrid(grid, uvw, flags, weights, ...[, ...]) Degrids the visibilities from the supplied grid in parallel. model(image, grid_config) Computes model visibilities from an image and a gridding configuration.

Returns a wrapper around a NIFTY GridderConfiguration object.

Parameters
nxint, optional

Number of X pixels in the grid. Defaults to 1024.

nyint, optional

Number of Y pixels in the grid. Defaults to 1024.

cell_size_xfloat, optional

Cell size of the X pixel in arcseconds. Defaults to 2.0.

cell_size_yfloat, optional

Cell size of the Y pixel in arcseconds. Defaults to 2.0.

epsfloat

Gridder accuracy error. Defaults to 2e-13

Returns
grid_configGridderConfigWrapper

The NIFTY Gridder Configuration

africanus.gridding.nifty.dask.grid(vis, uvw, flags, weights, frequencies, grid_config, wmin=- 1e+30, wmax=1e+30, streams=None)[source]

Grids the supplied visibilities in parallel. Note that a grid is create for each visibility chunk.

Parameters
visdask.array.Array

visibilities of shape (row, chan, corr)

uvwdask.array.Array

uvw coordinates of shape (row, 3)

flagsdask.array.Array

flags of shape (row, chan, corr)

weightsdask.array.Array

weights of shape (row, chan, corr).

frequenciesdask.array.Array

frequencies of shape (chan,)

grid_configGridderConfigWrapper

Gridding Configuration

wminfloat

Minimum W coordinate to grid. Defaults to -1e30.

wmaxfloat

Maximum W coordinate to grid. Default to 1e30.

streamsint, optional

Number of parallel gridding operations. Default to None, in which case as many grids as visibility chunks will be created.

Returns
griddask.array.Array

grid of shape (ny, nx, corr)

Computes the dirty image from gridded visibilities and the gridding configuration.

Parameters
griddask.array.Array

Gridded visibilities of shape (nv, nu, ncorr)

grid_configGridderConfigWrapper

Gridding configuration

Returns
dirtydask.array.Array

dirty image of shape (ny, nx, corr)

africanus.gridding.nifty.dask.degrid(grid, uvw, flags, weights, frequencies, grid_config, wmin=- 1e+30, wmax=1e+30)[source]

Degrids the visibilities from the supplied grid in parallel.

Parameters
griddask.array.Array

gridded visibilities of shape (ny, nx, corr)

uvwdask.array.Array

uvw coordinates of shape (row, 3)

flagsdask.array.Array

flags of shape (row, chan, corr)

weightsdask.array.Array

weights of shape (row, chan, corr). Currently unsupported and ignored.

frequenciesdask.array.Array

frequencies of shape (chan,)

grid_configGridderConfigWrapper

Gridding Configuration

wminfloat

Minimum W coordinate to grid. Defaults to -1e30.

wmaxfloat

Maximum W coordinate to grid. Default to 1e30.

Returns
griddask.array.Array

grid of shape (ny, nx, corr)

Computes model visibilities from an image and a gridding configuration.

Parameters
imagedask.array.Array

Image of shape (ny, nx, corr).

grid_configGridderConfigWrapper

nifty gridding configuration object

Returns
model_visdask.array.Array

Model visibilities of shape (nu, nv, corr).

## wgridder¶

Wrappers around ‘ducc.wgridder <https://gitlab.mpcdf.mpg.de/mtr/ducc>_.

### Numpy¶

 dirty(uvw, freq, vis, freq_bin_idx, ...[, ...]) Compute visibility to image mapping using ducc gridder i.e. model(uvw, freq, image, freq_bin_idx, ...[, ...]) Compute image to visibility mapping using ducc degridder i.e. residual(uvw, freq, image, vis, ...[, ...]) Compute residual image given a model and visibilities using ducc degridder i.e. hessian(uvw, freq, image, freq_bin_idx, ...) Compute action of Hessian on an image using ducc
africanus.gridding.wgridder.dirty(uvw, freq, vis, freq_bin_idx, freq_bin_counts, nx, ny, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]

Compute visibility to image mapping using ducc gridder i.e.

$I^D = R^\dagger \Sigma^{-1} V$

where $$R^\dagger$$ is an implicit gridding operator, $$V$$ denotes visibilities of shape (row, chan) and $$I^D$$ is the dirty image of shape (band, nx, ny).

The number of imaging bands (band) must be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

Note that, if self adjoint gridding and degridding operators are required then weights should be the square root of what is typically referred to as imaging weights and should also be passed into the degridder. In this case, the data needs to be pre-whitened.

Parameters
uvwnumpy.ndarray

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqnumpy.ndarray

Observational frequencies of shape (chan,).

visnumpy.ndarray

Visibilities of shape (row,chan).

freq_bin_idxnumpy.ndarray

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsnumpy.ndarray

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

weightsnumpy.ndarray, optional

Imaging weights of shape (row, chan).

flag:class:numpy.ndarray, optional

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one. If set to zero will use all available cores.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

double_accumbool, optional

If true ducc will accumulate in double precision regardless of the input type.

Returns
modelnumpy.ndarray

Dirty image corresponding to visibilities of shape (nband, nx, ny).

africanus.gridding.wgridder.model(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True)[source]

Compute image to visibility mapping using ducc degridder i.e.

$V = Rx$

where $$R$$ is an implicit degridding operator, $$V$$ denotes visibilities of shape (row, chan) and $$x$$ is the image of shape (band, nx, ny).

The number of imaging bands (band) has to be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

There is an option to provide weights during degridding to cater for self adjoint gridding and degridding operators. In this case weights should actually be the square root of what is typically referred to as imaging weights. In this case the degridder computes the whitened model visibilities i.e.

$V = \Sigma^{-\frac{1}{2}} R x$

where $$\Sigma$$ refers to the inverse of the weights (i.e. the data covariance matrix when using natural weighting).

Parameters
uvwnumpy.ndarray

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqnumpy.ndarray

Observational frequencies of shape (chan,).

modelnumpy.ndarray

Model image to degrid of shape (nband, nx, ny).

freq_bin_idxnumpy.ndarray

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsnumpy.ndarray

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

weightsnumpy.ndarray, optional

Imaging weights of shape (row, chan).

flag:class:numpy.ndarray, optional

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one. If set to zero will use all available cores.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

Returns
visnumpy.ndarray

Visibilities corresponding to model of shape (row,chan).

africanus.gridding.wgridder.residual(uvw, freq, image, vis, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]

Compute residual image given a model and visibilities using ducc degridder i.e.

$I^R = R^\dagger \Sigma^{-1}(V - Rx)$

where $$R$$ is an implicit degridding operator, $$V$$ denotes visibilities of shape (row, chan) and $$x$$ is the image of shape (band, nx, ny).

The number of imaging bands (band) must be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

Note that, if the gridding and degridding operators both apply the square root of the imaging weights then the visibilities that are passed in should be pre-whitened. In this case the function computes

$I^R = R^\dagger \Sigma^{-\frac{1}{2}}(\tilde{V} - \Sigma^{-\frac{1}{2}}Rx)$

which is identical to the above expression if $$\tilde{V} = \Sigma^{-\frac{1}{2}}V$$.

Parameters
uvwnumpy.ndarray

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqnumpy.ndarray

Observational frequencies of shape (chan,).

modelnumpy.ndarray

Model image to degrid of shape (band, nx, ny).

visnumpy.ndarray

Visibilities of shape (row,chan).

weightsnumpy.ndarray

Imaging weights of shape (row, chan).

freq_bin_idxnumpy.ndarray

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsnumpy.ndarray

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

flag:class:numpy.ndarray, optional

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

nuint, optional

The number of pixels in the padded grid along the $$x$$ direction. Chosen automatically by default.

nvint, optional

The number of pixels in the padded grid along the $$y$$ direction. Chosen automatically by default.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

double_accumbool, optional

If true ducc will accumulate in double precision regardless of the input type.

Returns
residualnumpy.ndarray

Residual image corresponding to model of shape (band, nx, ny).

africanus.gridding.wgridder.hessian(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]

Compute action of Hessian on an image using ducc

$R^\dagger \Sigma^{-1} R x$

where $$R$$ is an implicit degridding operator and $$x$$ is the image of shape (band, nx, ny).

The number of imaging bands (band) must be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

Parameters
uvwnumpy.ndarray

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqnumpy.ndarray

Observational frequencies of shape (chan,).

modelnumpy.ndarray

Model image to degrid of shape (band, nx, ny).

weightsnumpy.ndarray

Imaging weights of shape (row, chan).

freq_bin_idxnumpy.ndarray

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsnumpy.ndarray

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

flag:class:numpy.ndarray, optional

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

nuint, optional

The number of pixels in the padded grid along the $$x$$ direction. Chosen automatically by default.

nvint, optional

The number of pixels in the padded grid along the $$y$$ direction. Chosen automatically by default.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

double_accumbool, optional

If true ducc will accumulate in double precision regardless of the input type.

Returns
residualnumpy.ndarray

Residual image corresponding to model of shape (band, nx, ny).

 dirty(uvw, freq, vis, freq_bin_idx, ...[, ...]) Compute visibility to image mapping using ducc gridder i.e. model(uvw, freq, image, freq_bin_idx, ...[, ...]) Compute image to visibility mapping using ducc degridder i.e. residual(uvw, freq, image, vis, ...[, ...]) Compute residual image given a model and visibilities using ducc degridder i.e. hessian(uvw, freq, image, freq_bin_idx, ...) Compute action of Hessian on an image using ducc
africanus.gridding.wgridder.dask.dirty(uvw, freq, vis, freq_bin_idx, freq_bin_counts, nx, ny, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]

Compute visibility to image mapping using ducc gridder i.e.

$I^D = R^\dagger \Sigma^{-1} V$

where $$R^\dagger$$ is an implicit gridding operator, $$V$$ denotes visibilities of shape (row, chan) and $$I^D$$ is the dirty image of shape (band, nx, ny).

The number of imaging bands (band) must be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

Note that, if self adjoint gridding and degridding operators are required then weights should be the square root of what is typically referred to as imaging weights and should also be passed into the degridder. In this case, the data needs to be pre-whitened.

Parameters
uvwdask.array.Array

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqdask.array.Array

Observational frequencies of shape (chan,).

visdask.array.Array

Visibilities of shape (row,chan).

freq_bin_idxdask.array.Array

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsdask.array.Array

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

weightsdask.array.Array, optional

Imaging weights of shape (row, chan).

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one. If set to zero will use all available cores.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

double_accumbool, optional

If true ducc will accumulate in double precision regardless of the input type.

Returns
modeldask.array.Array

Dirty image corresponding to visibilities of shape (nband, nx, ny).

africanus.gridding.wgridder.dask.model(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True)[source]

Compute image to visibility mapping using ducc degridder i.e.

$V = Rx$

where $$R$$ is an implicit degridding operator, $$V$$ denotes visibilities of shape (row, chan) and $$x$$ is the image of shape (band, nx, ny).

The number of imaging bands (band) has to be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

There is an option to provide weights during degridding to cater for self adjoint gridding and degridding operators. In this case weights should actually be the square root of what is typically referred to as imaging weights. In this case the degridder computes the whitened model visibilities i.e.

$V = \Sigma^{-\frac{1}{2}} R x$

where $$\Sigma$$ refers to the inverse of the weights (i.e. the data covariance matrix when using natural weighting).

Parameters
uvwdask.array.Array

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqdask.array.Array

Observational frequencies of shape (chan,).

modeldask.array.Array

Model image to degrid of shape (nband, nx, ny).

freq_bin_idxdask.array.Array

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsdask.array.Array

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

weightsdask.array.Array, optional

Imaging weights of shape (row, chan).

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one. If set to zero will use all available cores.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

Returns
visdask.array.Array

Visibilities corresponding to model of shape (row,chan).

africanus.gridding.wgridder.dask.residual(uvw, freq, image, vis, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]

Compute residual image given a model and visibilities using ducc degridder i.e.

$I^R = R^\dagger \Sigma^{-1}(V - Rx)$

where $$R$$ is an implicit degridding operator, $$V$$ denotes visibilities of shape (row, chan) and $$x$$ is the image of shape (band, nx, ny).

The number of imaging bands (band) must be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

Note that, if the gridding and degridding operators both apply the square root of the imaging weights then the visibilities that are passed in should be pre-whitened. In this case the function computes

$I^R = R^\dagger \Sigma^{-\frac{1}{2}}(\tilde{V} - \Sigma^{-\frac{1}{2}}Rx)$

which is identical to the above expression if $$\tilde{V} = \Sigma^{-\frac{1}{2}}V$$.

Parameters
uvwdask.array.Array

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqdask.array.Array

Observational frequencies of shape (chan,).

modeldask.array.Array

Model image to degrid of shape (band, nx, ny).

visdask.array.Array

Visibilities of shape (row,chan).

weightsdask.array.Array

Imaging weights of shape (row, chan).

freq_bin_idxdask.array.Array

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsdask.array.Array

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

nuint, optional

The number of pixels in the padded grid along the $$x$$ direction. Chosen automatically by default.

nvint, optional

The number of pixels in the padded grid along the $$y$$ direction. Chosen automatically by default.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

double_accumbool, optional

If true ducc will accumulate in double precision regardless of the input type.

Returns
residualdask.array.Array

Residual image corresponding to model of shape (band, nx, ny).

africanus.gridding.wgridder.dask.hessian(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]

Compute action of Hessian on an image using ducc

$R^\dagger \Sigma^{-1} R x$

where $$R$$ is an implicit degridding operator and $$x$$ is the image of shape (band, nx, ny).

The number of imaging bands (band) must be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

Parameters
uvwdask.array.Array

uvw coordinates at which visibilities were obtained with shape (row, 3).

freqdask.array.Array

Observational frequencies of shape (chan,).

modeldask.array.Array

Model image to degrid of shape (band, nx, ny).

weightsdask.array.Array

Imaging weights of shape (row, chan).

freq_bin_idxdask.array.Array

Starting indices of frequency bins for each imaging band of shape (band,).

freq_bin_countsdask.array.Array

The number of channels in each imaging band of shape (band,).

cellfloat

The cell size of a pixel along the $$x$$ direction in radians.

Flags of shape (row,chan). Will only process visibilities for which flag!=0

cellyfloat, optional

The cell size of a pixel along the $$y$$ direction in radians. By default same as cell size along $$x$$ direction.

nuint, optional

The number of pixels in the padded grid along the $$x$$ direction. Chosen automatically by default.

nvint, optional

The number of pixels in the padded grid along the $$y$$ direction. Chosen automatically by default.

epsilonfloat, optional

The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.

The number of threads to use. Defaults to one.

do_wstackingbool, optional

Whether to correct for the w-term or not. Defaults to True

double_accumbool, optional

If true ducc will accumulate in double precision regardless of the input type.

Returns
residualdask.array.Array

Residual image corresponding to model of shape (band, nx, ny).

## Utilities¶

 estimate_cell_size(u, v, wavelength[, ...]) Estimate the cell size in arcseconds given baseline u and v coordinates, as well as the wavelengths, $$\lambda$$.
africanus.gridding.util.estimate_cell_size(u, v, wavelength, factor=3.0, ny=None, nx=None)[source]

Estimate the cell size in arcseconds given baseline u and v coordinates, as well as the wavelengths, $$\lambda$$.

The cell size is computed as:

\begin{align}\begin{aligned}\Delta u = 1.0 / \left( 2 \times \text{ factor } \times \max (\vert u \vert) / \min( \lambda) \right)\\\Delta v = 1.0 / \left( 2 \times \text{ factor } \times \max (\vert v \vert) / \min( \lambda) \right)\end{aligned}\end{align}

If ny and nx are provided the following checks are performed and exceptions are raised on failure:

\begin{align}\begin{aligned}\Delta u * \text{ ny } \leq \min (\lambda) / \min (\vert u \vert)\\\Delta v * \text{ nx } \leq \min (\lambda) / \min (\vert v \vert)\end{aligned}\end{align}
Parameters
unumpy.ndarray or float

Maximum u coordinate in metres.

vnumpy.ndarray or float

Maximum v coordinate in metres.

wavelengthnumpy.ndarray or float

Wavelengths, in metres.

factorfloat, optional

Scaling factor

nyint, optional

Grid y dimension

nxint, optional

Grid x dimension

Returns
numpy.ndarray

Cell size of u and v in arcseconds with shape (2,)`

Raises
ValueError

If the cell size criteria are not matched.