Gridders

Overview

The gridders are ASKAPsoft equivalents of Fourier Machines in casa/aips++. They are used for the following 3 operations:

• Putting visibility data onto a regular grid prior to Fourier transform to image space (called gridding or reverse operation).

• Predicting visibility data from a regular grid following the Fourier transform from the image space (called degridding or forward operation)

• Computing PSFs (a special mode of gridding substituting visibility data and convolution functions)

There is a number of gridders available in ASKAPsoft. The same code is used for the actual gridding/degridding for all gridders. The main difference between various gridders is the convolution function used and how the look up is done (i.e. which convolution function among a number of functions stored in the cache is used for a particular visibility point based on the associated metadata). The choice of convolution functions together with the solver used in minor cycle (see Solvers) largely determine the imaging algorithm. Some gridders (called stacking gridders below) maintain a stack of grids instead of a single grid. An appropriate grid is selected on the basis of associated metadata for each visibility point instead of or in addition to look up of a particular convolution function. These two different variants of gridders are used as two approaches to treat the w-term (non-coplanar baselines). In general, stacking approach is more memory hungry although can be faster than the projection approach.

The gridders can also be divided into two groups: mosaicing and non-mosaicing gridders. The former use convolution functions which include illumination patterns. They are, therefore, primary beam aware and can deal with the datasets containing multiple pointing centres. The output image is always corrected for the primary beam, if a mosaicing gridder is used. The weights image represents the sensitivity pattern. The non-mosaicing gridders effectively assume an infinitely wide primary beam (illumination pattern is a delta function). They will produce incorrect result if dataset contains multiple pointings (either physical pointings of the dish or multiple offset beams). The output image is not corrected for primary beam, if non-mosaicing gridder is used. The weights image is constant across the whole field of view in this case.

Available gridders

The following gridders are available in ASKAPsoft:

Gridder	Accounts for w-term	Mosaicing	Convolution function	Notes
Box	No	No	Box function	Very crude nearest neighbour gridder
SphFunc	No	No	Spheroidal function	The simplest useful gridder (just optimal aliasing rejection)
WProject	Yes (projection)	No	Spheroidal function + FT of the w-term	Uses W projection to account for the w term in the Fourier transform
MPIWProject	Yes (projection)	No	Spheroidal function + FT of the w-term	Uses W projection to account for the w term in the Fourier transform. It provides the same function as WProject gridder but using MPI memory to reduce the memory usage
WStack	Yes (stacking)	No	Spheroidal function	Uses stacking in image space to account for the w term in the Fourier transform
AWProject	Yes (projection)	Yes	Spheroidal function + FT of the w-term + autocorrelation of antenna illumination	In addition to WProject, takes into account primary beam
AProjectWStack	Yes (stacking)	Yes	autocorrelation of antenna illumination	In addition to WStack, takes into account primary beam

Parset parameters of the gridders

Common Parameters

The following are common to all gridders:

Parameter	Type	Default	Description
padding	float	1.0	Factor by which the grid is padded. Internally the gridder is setup with the grid padding size larger as if the larger shape would be given. However, only the inner part of the image is filled in for the degridding operation or send back as a result for gridding. The Fourier transform is done on a padded grid. This option is mainly intended for faceting (to reduce aliasing from other facets), but will work for all gridders and in the non-faceted case. Note that at present this will damage the Wiener filter if preservecf = true.
alldatapsf	bool	false	Set to true to use all data for PSF calculations instead of just the representative feed and field. If this flag is false (default), only data for the first encountered feed and field will be used to compute PSF (to avoid a false improving of the PSF due to a better uv-coverage of a combined dataset. This feature is introduced largely for real ATCA data and is not very relevant for ASKAP with its parallel mosaicing.
oversampleweight	bool	false	Set to true to use actual oversampling offset of the convolution function in weight computation, rather than the zero offset in both coordinates. It gives more accurate fluxes, but increases the size of weight buffer with the factor of oversampling squared (and make weight finalisation more time consuming)
MaxPointingSeparation	string	“-1rad”	If specified, this parameter controls the data selection at the gridder level based on the angular separation between the pointing centre and the image centre. If this separation exceeds the given threshold, the appropriate visibility sample is rejected. Negative threshold (default) means no rejection, so all data are used by default. This option may be useful if only a small field of view is imaged out of a larger dataset. The threshold is specified as a quantity string, i.e. “1deg”. It can be used with all gridders, not just mosaicing ones.
snapshotimaging	bool	false	If true, snapshot imaging is done. In this mode, a w=au+bv plane is fitted to baseline coordinates and the effective w-term becomes a difference between the actual w-term and the fitted plane. The subtraction of such a plane is equivalent to the coordinate distortion. Therefore, every time the fit is updated, the current dirty and weight images are regridded into a stable frame. How often the new fit is done depends on the w-tolerance parameter, which must be given if the snap-shot imaging is used.
snapshotimaging.wtolerance	double	none	Required tolerance on residual w-term for snap-shot imaging (in wavelengths).This parameter must be given if the snap-shot imaging is used. An exception is thrown if the antenna layout is significantly non-coplanar and the required tolerance cannot be achieved by plane fitting.
snapshotimaging.clipping	double	0	Optional clipping to avoid edge effects during image reprojection. This parameter represents the fraction of the image size (on each directional axis) which is zeroed (equally from both sides). It should be a non-negative number less than 1. Set it to 0 (default) to avoid any clipping. Applies to all images (image.*, residual.*, weights.*, etc.).
snapshotimaging.weightsclipping	double	the general snapshot imaging clipping factor	Optional clipping of the weights image to avoid edge effects during image reprojection. As the general clipping mentioned above can create its own edge effects, clipping only the weights will stop edge effects from contaminating the sky model during deconvolution. Thus they can be cleaned away and their residuals will be ignored during any linmos operation. See the general clipping factor above for usage.
snapshotimaging.reprojectpsf	bool	false	If true, the PSF will be reprojected and accumulated the same way as the dirty image. Otherwise, a single image (labelled with the target coordinates) will be constructed.
snapshotimaging.coorddecimation	uint	3	The decimation factor used for coordinate system interpolation during regridding. A decimation factor of 0 (or 1) implies no decimation, which is the slowest and most accurate. A larger factor will result in faster, but less accurate regridding.
snapshotimaging.interpmethod	string	“cubic”	Interpolation method for image reprojection, i.e cubic, lanczos, linear.
snapshotimaging.longtrack	bool	false	If true the best fit W plane for the snapshot is predicted by advancing the uvw in time and finding that plane which minimises the deviation in the future. Some minutes from the current time. This allows the max deviation to remain within tolerance for almost twice as long as the default scheme. This can have a substantial effect on processing time for long tracks. It should be a factor of two faster.
bwsmearing	bool	false	If true, the effect of bandwidth smearing is predicted.
bwsmearing.chanbw	double	1e6	Effective bandwidth of a single spectral channel in Hz for the bandwidth smearing simulation.
bwsmearing.nsteps	int	10	Number of integration steps for bandwidth smearing simulation (i.e. how finer the spectral resolution is before averaging). A larger number ensures a more accurate result at the price of performance.
parotation	bool	false	Enable parallactic angle rotation based on feed angle recorded in the feed table.
parotation.angle	double	0.0	Rotation to apply in addition to value in feed table. For ASKAP data where feed table has zero you should use: angle = -polaxis + 45 (deg) and swappols=true to get correct Q and U images
swappols	bool	false	Swap the polarisations in the Stokes conversion matrix. E.g., to swap ASKAP X and Y feed outputs Only works when parotation=true.
cleargrids	bool	false	Clear the grids when no longer needed. The imager code sets this automatically, based on whether the grids are written out or not.
reusegrids	bool	false	Reuse the PSF and PCF grids for subsequent major cyles, this overrrides the setting of cleargrids for those two grids

Note, SphFunc and Box gridders don’t have any additional parameters to those listed above. Oversampling factor which is a configurable parameter for some other gridders is hard coded to be 128 for the SphFunc gridder and 1 for the Box gridder.

Parameters related to gridders that take the w-term into account

Parameter	Type	Default	Description
wmax	double	largest w value relative to the tangent of the first image (or the largest residual w when using snapshots)	Largest allowed absolute value of the w term in wavelengths. An exception will be thrown if the dataset contains w-term exceeding this value (W scaling error: recommend allowing larger range of w).
wmaxclip	bool	false	By default, throws an exception if w term is outside the valid range [-wmax,wmax]. If true data outside the valid range is discarded during gridding. If clipping is used the value of wmax should not be increased in subsequent processing steps as unprocessed data may reappear (e.g., cont. subtraction followed by imaging)
wpercentile	double	99.0	Calculate approximate w distribution and set wmax to the given percentile of the distribution, that includes, e.g., 99% of w values. Also sets wmaxclip to true.

Note, the previous default for wmax was 35000 for WProject and WStack and 10000 for AWProject and AProjectWStack. Using wpercentile with imager will not work correctly with multiple MeasurementSets per worker, only the first one will be used to calculate the statistics. Set Cimager.includeflagged=false to exclude flagged data from the statistics.

Parameters related to w-term (specific to WProject, MPIWProject and WStack)

The following parameters are applicable to gridders that take the w-term into account. The table below is specific to WProject and WStack. The same two parameters understood by AProjectWStack and AWProject gridders, but defaults are different. Therefore, their description is repeated in the discussion of the mosaicing gridders.

Parameter	Type	Default	Description
nwplanes	int	65	Number of w-planes. Number of w planes must be an odd positive number. For the WProject gridder this scales up the number of convolution functions calculated. For the WStack gridder this is the number of grids maintained. You may (and will) run out of memory for a large number of w planes, especially for the stacking algorithm
wstats	bool	false	If true, the gridder will log the statistics at the end showing the number of times each w-plane has been used since the construction of the gridder

Note, no additional parameters are required for the WStack gridder because the convolution function is just a prolate spheroidal function with well defined support. Oversampling factor which is a configurable parameter for some other gridders is hard coded to be 128. The WProject gridder uses non-trivial convolution functions which have w-term applied and requires some additional parameters to find, e.g. how the support of the convolution function is searched. These parameters are given in the following section.

Parameters related to anti-aliasing function (specific to SphFunc and WProject)

The following parameters are applicable to gridders that use the SphFunc prolate spheroid as part of the gridding kernel (i.e., SphFunc and WProject).

Parameter	Type	Default	Description
alpha	float	1	The prolate spheroidal alpha function. Setting alpha to zero leads to great alias rejection at the edge of image, and may help to reduce preconditioning artefacts when the robustness parameter is negative.

Non-linear sampling in w-space (specific to WProject,WStack, AWProject and AProjectWStack)

These parameters apply to all gridders which take w-term into account. By default w-planes (either stacking grids or projection planes) are spaced linearly (or equidistantly) in w. The following parameters allow the user to enable and control non-linear sampling. Regardless of the parameters, the first and last w-planes always correspond to -wmax and +wmax, respectively, and the (nwplanes-1)/2 plane corresponds to w=0.

Parameter	Type	Default	Description
wsampling	string	“linear”	Type of the sampling in the w-space. The default is linear, which means that w-planes are set at equal distances in w. “powerlaw” means that w(plane) is proportional to pow(plane - (nwplanes-1)/2,exponent), where the exponent is a free parameter (must be given). “gaussian” means the distribution of w(plane) derived from truncated gaussian distribution in the range -wmax to wmax. This distribution is parameterized by a single parameter (must be given) nwplanes50, which means the number of w-planes (float is allowed) covering inner 50% of the -wmax to +wmax range of w-terms. The parameters A and sigma of the distribution w ~ A*(1-exp(-plane^2/(2*sigma^2)) are derived nwplanes50 by assuming that the first and the last w-planes always correspond to -wmax and +wmax respectively and the mid-range plane corresponds to w=0. Note, nwplanes50 should be a positive number not exceeding approximately 70% of the number of w-planes (it can be shown mathematically, that a distribution of this type with a larger concentration of w-planes does not exist).
wsampling.exponent	double	none	Exponent of the power law (can’t be 0)
wsampling.nwplanes50	double	none	Parameter of the gaussian w-sampling. The number of w-planes covering inner 50% of the -wmax to +wmax value range of w-terms
wsampling.export	string	“”	If this parameter is not an empty string, the actual distribution of w-planes is exported. If the value of this parameter is equal to “log”, the distribution is exported into a usual log stream in a human readable form. Otherwise, the value of this parameter is interpreted as a file name, and the distribution is exported into this file in a machine readable form (three columns of data being the plane number, the resulting w-term and the plane number obtained as a result of the reverse conversion of the w-term into plane number)

An example of the power-law distribution of the w-planes with exponent=0.5 is given below

Additional parameters for gridders with non-trivial convolution functions (WProject, MPIWProject, AWProject, AProjectWStack)

This section gives parameters understood by gridders based on non-trivial (i.e. not box or prolate spheroidal) convolution functions. For WProject gridder this section describes all remaining parameters in addition to those given above (common for all gridders and shared with WStack). Mosaicing gridders have further parameters. Note, AProjectWStack does not understand cutoff, variablesupport and offsetsupport parameters as the support size is defined by antenna aperture and is not searched.

Parameter	Type	Default	Description
cutoff	double	1e-3	Cutoff in determining support (note, relative cutoff must be greater than 0.0 and less than 1.0). The support is searched starting from the edge of the image inwards. As soon as the value of the convolution function exceeds cutoff times the peak (or just cutoff if absolute cutoff is used, see below), the distance from the centre (the largest value of two coordinates is used) becomes the support size. At the moment, we use a single value of the support, which is the largest across all family of convolution functions stored in the cache. The smaller the cutoff, the larger the support size and the more accurate gridding is performed.
cutoff.absolute	bool	false	If set to true, the cutoff value given by the parameter listed above is treated as an absolute cutoff value, rather than the fraction of the peak. This is an experimental feature.
oversample	int	8	Oversampling factor. Convolution functions will be computed for this number of pixels per uv-cell.
maxsupport	int	256	The largest allowed support size in pixels. The grid used to compute the convolution function (before the support is searched and the appropriate inner part of the grid is extracted) is initialised to have the size equal to the smallest of maxsupport and the image size. WProject uses maxsupport x maxsupport grid at the moment regardless of the image size.
limitsupport	int	0	Upper limit of support. If the determined support size happens to be greater than this value, the support will be capped to this value. This limit is applied after the convolution functions are calculated, before an inner part of the grid is extracted to be stored in the convolution function cache. The default value of 0 indicates no limit is imposed.
variablesupport	bool	false	If true, the support will be searched separately for each convolution function. This can speed things up considerably, unless costs to search the support dominates. It was also found that when variable support is used, the algorithm is more sensitive to cutoff value. Too high cutoff value has a significant impact on the image quality if the variable support is used.
offsetsupport	bool	false	If true, an offset of the convolution function will be treated separately (the support will be defined by size and offset, which can be non-zero in general). This option reduces the memory footprint and speeds up greeting. It can only be used in conjunction with variablesupport=true
tablename	string	“”	Name of table to save convolution function into. This option largely exists for debugging to be able to inspect the non-trivial convolution function. It should not be normally used. If the string is empty (default) the convolution function is not saved. If the string is prefixed with “image:” (i.e. image:cfuncs.img), convolution functions corresponding to the first oversampling plane in both axes are stored in the image cube instead. Planes of the cube correspond to remaining planes (apart from oversampling) of the convolution function cache. In this mode, only reverse (and non-PSF) gridder stores its convolution functions.
usedouble	bool	false	If true, use double precision when calculating convolution functions in the WProject gridder. Double used to be the default, but there is little if any difference in the output with single precision.
sharecf	bool	false	If true, use a (static) cache for the convolution functions in the WProject gridder. This saves both time and memory, especially for large images and spectral line cubes. Tests show no significant changes in continuum imaging but small differences in spectral cubes, it is not clear yet if these are a problem. Feedback welcome
cfrank	integer	1	The number of ranks/processes used to distribute the convolution function calculation. Note: this parameter is only used by the MPIWProject gridder. Also, it requires the variablesupport parameter to be set to true.

Note, that an exception is raised if the support size found during the support search (before being capped by limitsupport) exceeds (number of pixels)/(2*oversample), Overflowing convolution function - increase maxSupport or decrease overSample. If the cutoff is too small, one may find it impossible to increase maxsupport (and image size) due to the amount of available memory. Decreasing oversampling factor compromises the quality of imaging. Therefore, in some cases making the cutoff larger is the only option to proceed with calculations on a given machine.

Parameters specific to mosaicing gridders (AWProject and AProjectWStack)

Mosaicing gridders (AWProject and AProjectWStack) are aware about the primary beam of the instrument and need additional parameters to define how it looks like (via illumination pattern), when it needs to be recomputed (tolerances) and how big the cache should be (maxfeeds and maxfields). Some parameters given in the two previous sections have different defaults and therefore are repeated here.

Parameter	Type	Default	Description
nwplanes	int	65	Number of w-planes. Number of w planes must be odd. See above
maxsupport	int	128	The largest allowed support size in pixels. See above
frequencydependent	bool	true	If true, illumination pattern will be computed separately for each spectral channel
spheroidaltaper	bool	false	Whether or not to apply an image-domain spheroidal taper to the A-function during gridding and degridding (but not to the mosaicing weights). The taper function is the same as the anti-aliasing function used in the SphFunc, WProject and WStack gridders.
spheroidalweightscutoff	double	0	If the spheroidalTaper is below this cutoff, set weights to zero. This stops the beam function being boosted at small and inaccurate taper values. A cutoff of 0.01 seems reasonable.
maxfeeds	int	1	Maximum number of feeds allowed
maxfields	int	1	Maximum number of fields allowed
pointingtolerance	string	“0.0001rad”	Pointing tolerance. Fields separated by a larger amount considered separate fields and the appropriate data are gridded with independent convolution functions. An exception is thrown if the number of fields exceeds maxfields.
patolerance	string	“0.1rad”	Parallactic angle tolerance
freqtolerance	string	undefined	Frequency tolerance (relative, threshold for df/f), negative value or word infinite mean the frequency axis is ignored
illumination	string	“disk”	Illumination model used with this gridder. Default is disk. Dish and blockage sizes are defined regardless of the model used (because all illumination models require them). Different models require different parameters. Current options: disk, ASKAP, ATCA, SKA_LOW.
illumination.*Property*			Additional parameters of illumination model (see below). Exact list of available properties depends on the illumination model used. Diameter and blockage (below) are given as gridder parameters. None of the extra properties are required for disk illumination.
diameter	double	none	Dish diameter in metres
blockage	double	none	Size of the central whole in metres

ASKAP Illumination

This experimental pattern uses the holography based beam models to derive the average illumination pattern for an ASKAP antenna for a given beam number. The current beam models do not go quite far enough out for the illumination pattern to be calculated cleanly by FFT, so to avoid edge effects an additional taper can be applied beyond the beam cutoff level to force the beam pattern to zero at the edge. The only primarybeam type that can be specified here is the ASKAP_PB. See linmos (Linear Mosaic Applicator) for additional primarybeam parameters.

Parameter	Type	Default	Description
illumination.primarybeam	string	ASKAP_PB	The only valid choice for the primary beam is ASKAP_PB which is the default
illumination.primarybeam.ASKAP_PB.image	string	none	FITS image file with 4/5 axes (see linmos). Specify the full filename (including .fits)
illumination.primarybeam.ASKAP_PB.taper	bool	true	Apply a gaussian taper to the beam model beyond the cutoff level specified in the next parameter
illumination.primarybeam.ASKAP_PB.taper.cutoff	double	0.04	Cutoff level in the beam pattern beyond which the extra tapering is applied

An example of the disk illumination for diameter 22m and blockage of 2m. For all illumination examples given below the frequency is assumed to be 1.4 GHz

ATCA Illumination

This illumination pattern allows to simulate additional effects (e.g. feed leg shadows, tapering) on top of the disk illumination. With the tapering, feedlegs and wedges parameters set to false, this illumination pattern is equivalent to disk (blockage and diameter are given as parameters of the gridder, rather than as parameters of illumination pattern because they apply to both currently implemented types of illumination). ATCA illumination has the following parameters:

Parameter	Type	Default	Description
illumination.tapering	bool	true	This option switches on Jamesian tapering (i.e. imperfect illumination). The parameters of the taper are hard coded at the moment and correspond to the ATCA model.
illumination.tapering.defocusing	string	0rad	Only valid if illumination.tapering = true. An additional phase term is applied to the Jamesian illumination.The phase varies quadratically with radius from 0 at the dish centre to the value given in this parameter at the edge.
illumination.feedlegs	bool	true	If true, feed leg shadows are simulated (i.e. partial blockage of the radiation by the struts supporting the subreflector/focus cabin)
illumination.feedlegs.width	string	1.8m	Only applicable if illumination.feedlegs = true. The width of the shadows in the absolute units (as dish diameter is also given in the absolute units)
illumination.feedlegs.rotation	string	45deg	Only applicable if illumination.feedlegs = true. The angle the shadows are rotated. It corresponds to installation angle of the actual feeds. If this parameter is zero, the shadows go in the u and v direction. At ATCA the feeds are installed at 45 deg angle, which is the default.
illumination.feedlegs.shadowing	double	0.75	Only applicable if illumination.feedlegs = true. This parameter describes how transparent feed leg shadows are. Zero indicates a total blockage, one a total transparency.
illumination.feedlegs.wedges	bool	true	Only applicable if illumination.feedlegs = true. If this parameter is set to true, shadow wedges resulted from multiple reflections (e.g. in the Cassegrain design). The wedges are simulated as triangular shadows on top of the feed leg shadows (adding more opacity)
illumination.feedlegs.wedges.shadowing	vector<double>	[0.6,0.5]	Only valid if illumination.feedlegs.wedges = true. Transparency factors for wedges corresponding to the horizontal and vertical (without rotation) feed legs. Zero indicates a total blockage, one is for total transparency.This opacities are applied linearly on top of the normal feed leg shadowing factor. Either one or two values could be given. If one value is given it corresponds to all wedges.
illumination.feedlegs.wedges.angle	string	15deg	Only valid if illumination.feedlegs.wedges = true. Opening angle for all triangular wedges.
illumination.feedlegs.wedges.startradius	string	3.5m	Only valid if illumination.feedlegs.wedges = true. The radius of the vertex for all triangular wedges.

Example of the ATCA illumination model created with default parameters (i.e. with feed legs and wedges enabled)

Example of the ATCA illumination model without wedges and with default values of other parameters.

Example of the ATCA illumination model without feedlegs (and wedges). All other parameters have default values. This case is essentially a disk with tapering.

Examples

Simple example:

Cimager.gridder                                 = WProject
Cimager.gridder.WProject.wmax                   = 15000
Cimager.gridder.WProject.nwplanes               = 129
Cimager.gridder.WProject.oversample             = 8
Cimager.gridder.WProject.maxsupport             = 1024
Cimager.gridder.WProject.tablename              = WProject.tab

Example with ATCA illumination pattern:

Cimager.gridder                                   = AProjectWStack
Cimager.gridder.alldatapsf                        = true
Cimager.gridder.padding                           = 1
Cimager.gridder.AProjectWStack.wmax               = 1.0
Cimager.gridder.AProjectWStack.diameter           = 22m
Cimager.gridder.AProjectWStack.blockage           = 3.6m
Cimager.gridder.AProjectWStack.nwplanes           = 1
Cimager.gridder.AProjectWStack.oversample         = 16
Cimager.gridder.AProjectWStack.cutoff             = 0.001
Cimager.gridder.AProjectWStack.maxfeeds           = 1
Cimager.gridder.AProjectWStack.maxfields          = 1
Cimager.gridder.AProjectWStack.maxsupport         = 1024
Cimager.gridder.AProjectWStack.frequencydependent = true

Cimager.gridder.AProjectWStack.illumination                             = ATCA
Cimager.gridder.AProjectWStack.illumination.tapering                    = true
Cimager.gridder.AProjectWStack.illumination.tapering.defocusing         = 0deg
Cimager.gridder.AProjectWStack.illumination.feedlegs                    = true
Cimager.gridder.AProjectWStack.illumination.feedlegs.width              = 1.0m
Cimager.gridder.AProjectWStack.illumination.feedlegs.rotation           = 45deg
Cimager.gridder.AProjectWStack.illumination.feedlegs.shadowing          = 0.75
Cimager.gridder.AProjectWStack.illumination.feedlegs.wedges             = true
Cimager.gridder.AProjectWStack.illumination.feedlegs.wedges.shadowing   = [0.6,0.5]
Cimager.gridder.AProjectWStack.illumination.feedlegs.wedges.angle       = 15deg
Cimager.gridder.AProjectWStack.illumination.feedlegs.wedges.startradius = 3.5m