bpdelaytool (Utility to manipulate delays in bandpass solution)

This page provides instruction for bpdelaytool utility program which can be used to manipulate delays (delay is the linear phase slope) in bandpass solutions. The example use cases are to calculate the delays (per antenna and beam, as appropriate) and take them out, or compute such delays for one calibration table and apply to another. The main motivation is to be able to extend the validity of some bandpass solution if only delays are expected to change (and could be solved for using different data). The operations performed by the tool can be seen as a pipeline reading some bandpass table, subtracting and adding delays determined from some other table and finally writing the result into the third table (see the figure below). Only reading the input table is required, writing the output table as well as adding or subtracting delays are completely optional. Therefore, in the minimal configuration with just one input, this tool would simply calculate delays in the input bandpass table and report their stats in the log.

Running the program

It can be run with the following command, where “config.in” is a file containing the configuration parameters described in the next section.

$ bpdelaytool -c config.in

Note, the bpdelaytool program is serial at the moment and should not be executed with more than one rank.

Configuration Parameters

The table below lists configuration parameters which can be used in config.in. As with most other YandaSoft applications, this utility requires bpdelaytool prefix for all parameters (it is not shown in the table below). The bpdelaytool works via standard calibration access interface and, therefore, recognises all related parameters and options for all inputs and the output (see Access to calibrator solutions for details). The accessor created for each input and the output separately and does not have to be of the same type (e.g. one could read from a table and write into a service or vice versa). But for simplicity, we refer to the calibration storage of any supported type as the calibration table.

Parameter	Type	Default	Description
The input section describes the table which is the starting point. Because this tool only modifies delays, the amplitude information from the input bandpass always propagates to the output.
input	string	“calibaccess”	A switch whether the input bandpass table is read via the calibration solution accessor (see below) or is initialised with the zero phase and unit amplitude (if input is set to “ideal”). Only “ideal” and “calibaccess” are supported. This option may be handy to create calibration tables adding or correcting some delays but leaving the amplitude intact.
input.calibaccess	string	“parset”	Type of input calibration accessor. All parameters required by the chosen accessor should be present (with the input prefix), see Access to calibrator solutions for details on other parameters. The input accessor is only set up (and corresponding section of configuration file got used) if input is set to calibaccess (this is the default).
input.resolution	quantity string	“1MHz”	Spectral resolution of the input table. In principle, the bandpass tables the tool deals with are not required to have the same spectral resolution. However, one needs to know the actual spectral resolution of the bandpass table to be able to work correctly in such circumstances. It is also necessary to report delays in the log in the physical units.
input.maxchan	unsigned integer	taken from the table section and, failed that, from the output table section	The maximum number of channels to read from the table. The calibration access layer provides a database-like interface which does not hold configuration parameters like the number of antennas, beams or channels. These need to be supplied externally. To simplify porting configurations, defaults are taken from the table configuration (assuming input.calibaccess is ‘table’), i.e. input.calibaccess.table.maxchan. And if that keyword doesn’t exist, the default is taken from the output table configuration, i.e. output.calibaccess.table.maxchan.
input.maxbeam	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of beams to read from the input table. See input.maxchan for more info. The same look up for default values applies.
input.maxant	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of antennas to read from the input table. See input.maxchan for more info. The same look up for default values applies.
The subtract section describes the input calibration table for which the delays are calculated and then taken out (i.e. subtracted) from the bandpass data when the output table is written.
subtract	string	None	This keyword can either be set to input or should be left undefined. The former is a short cut configuring the tool to take out the delay computed from the input table. Alternatively, the calibration accessor details should be given (with the subtract prefix). And the corresponding table will be used to compute delays to be subtracted.
subtract.calibaccess	string	None	Type of input calibration accessor. All parameters required by the chosen accessor should be present (with the subtract prefix), see Access to calibrator solutions for details on other parameters. Note, configuring accessor for the subtract section by setting this keyword to the accesor type is incompatible with the subtract = input option. If neither is given, no delay subtraction is performed.
subtract.resolution	quantity string	“1MHz”	Spectral resolution of the input table. See description of input.resolution for more information.
subtract.maxchan	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of chanels to read from the given table. See input.maxchan for more info. The similar look up for default values applies.
subtract.maxbeam	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of beams to read from the given table. See input.maxchan for more info. The similar look up for default values applies.
subtract.maxant	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of antennas to read from the given table. See input.maxchan for more info. The smilar look up for default values applies.
The add section describes the input calibration table for which the delays are calculated and then added on top of the bandpass data when the output table is written. Similar parameters to the subtract section are recognised. However, the short cut to take delays from the input table is not supported, so the accessor needs to be defined (provided delay addition is required).
add.calibaccess	string	None	Type of input calibration accessor. All parameters required by the chosen accessor should be present (with the add prefix), see Access to calibrator solutions for details on other parameters. If this keyword is left undefined, no addition of delays is performed.
add.resolution	quantity string	“1MHz”	Spectral resolution of the table. See the description of input.resolution for more information.
add.maxchan	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of chanels to read from the given table. See input.maxchan for more info. The similar look up for default values applies.
add.maxbeam	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of beams to read from the given table. See input.maxchan for more info. The similar look up for default values applies.
add.maxant	unsigned integer	taken from the table section and, failed that, from the output table section.	The maximum number of antennas to read from the given table. See input.maxchan for more info. The smilar look up for default values applies.
The output section, describes the details of the output table and corresponding accessor setup.
output.calibaccess	string	None	Type of output calibration accessor. All parameters required by the chosen accessor should be present (with the output prefix), see Access to calibrator solutions for details on other parameters. If this keyword is left undefined, no output table is written.
output.resolution	quantity string	“1MHz”	The implied spectral resolution of the table. See the description of the input.resolution for more information.
The following parameters of the output table-based accessor are repeated here for convenience as their defaults can be used for other calibration accessors created by the tool, unless overridden by the specific parameters. Note, all of them have the output.calibaccess.table prefix. See Access to calibrator solutions for more information on the setup of calibration table accessors.
maxchan	unsigned integer	16416	The maximum number of channels supported by the table, if a new table is going to be created by the output accessor.
maxbeam	unsigned integer	30	The maximum number of beams supported by the table, if a new table is going to be created by the output accessor.
maxant	unsigned integer	36	The maximum number of antennas supported by the table, if a new table is going to be created by the output accessor.

Example 1

This parset configures the tool to calculate delays in the bandpass stored in inputbp.tab and summarise the result in the log.

bpdelaytool.input.calibaccess = table
bpdelaytool.input.calibaccess.table = inputbp.tab
bpdelaytool.input.resolution=18.518518519kHz
bpdelaytool.input.maxchan=15552
bpdelaytool.input.maxbeam=36
bpdelaytool.input.maxant=36

Example 2

With this configuration the tool will remove delays from the bandpass stored in inputbp.tab and write the resulting table to outputbp.tab.

bpdelaytool.input.calibaccess = table
bpdelaytool.input.calibaccess.table = inputbp.tab

bpdelaytool.subtract=input

bpdelaytool.output.calibaccess=table
bpdelaytool.output.calibaccess.table = outputbp.tab
bpdelaytool.output.calibaccess.table.maxant = 36
bpdelaytool.output.calibaccess.table.maxbeam = 36
bpdelaytool.output.calibaccess.table.maxchan = 288

Example 3

Create a bandpass table with fine resolution containing just the delay slope (i.e. the amplitude is 1 for all channels) correcting the delay obtained from the given table which has 1 MHz resolution.

bpdelaytool.input = ideal

bpdelaytool.subtract.calibaccess = table
bpdelaytool.subtract.calibaccess.table = inputbp.tab
bpdelaytool.subtract.resolution=1MHz
bpdelaytool.subtract.maxchan = 288

bpdelaytool.output.calibaccess=table
bpdelaytool.output.calibaccess.table = outputbp.tab
bpdelaytool.output.calibaccess.table.maxant = 36
bpdelaytool.output.calibaccess.table.maxbeam = 36
bpdelaytool.output.calibaccess.table.maxchan = 15552
bpdelaytool.output.resolution=18.518518519kHz

Example 4

Keep the amplitude part and replace the delays found in the input table by delays calculated using another table.

bpdelaytool.input.calibaccess = table
bpdelaytool.input.calibaccess.table = inputbp.tab

bpdelaytool.subtract=input

bpdelaytool.add.calibaccess=table
bpdelaytool.add.calibaccess.table = table2take_delays_from.tab

bpdelaytool.output.calibaccess=table
bpdelaytool.output.calibaccess.table = outputbp.tab
bpdelaytool.output.calibaccess.table.maxant = 36
bpdelaytool.output.calibaccess.table.maxbeam = 36
bpdelaytool.output.calibaccess.table.maxchan = 288