#include <stdlib.h>
#include <stdio.h>
#include <math.h>
#include <string.h>
#include <mwalib.h>
#include "vcsbeam.h"
#include "gpu_macros.h"

Include dependency graph for calibration.c:

Functions
void	vmLoadRTSSolution (vcsbeam_context *vm)
	Loads a Real Time System (RTS) calibration solution. More...

void	read_dijones_file (gpuDoubleComplex *Dd, gpuDoubleComplex A, double amp, uintptr_t nant, char fname)
	Reads in an RTS DIJones file. More...

void	read_bandpass_file (gpuDoubleComplex *Jm, gpuDoubleComplex Jf, MetafitsMetadata cal_metadata, char *filename)
	Reads an RTS Bandpass file. More...

void	vmLoadOffringaSolution (vcsbeam_context *vm)
	Reads in a calibration solution from an Offringa-style solution file. More...

void	remove_reference_phase (gpuDoubleComplex J, gpuDoubleComplex Jref)
	Rotates the phases of the elements of a complex matrix with respect to a reference matrix. More...

void	zero_PQ_and_QP (gpuDoubleComplex *J)
	Zeroes the off-diagonal terms of the given matrix. More...

void	parse_calibration_correction_file (uint32_t gpstime, calibration *cal)
	Parses the PQ phase correction for the given GPS time from the file `pq_phase_correction.txt`. More...

void	vmApplyCalibrationCorrections (vcsbeam_context *vm)
	Applies various corrections/adjustments to the calibration solutions. More...

void	vmParseFlaggedTilenamesFile (char filename, calibration cal)
	Parse the flagged tile names in the given file. More...

bool	tilename_is_flagged (char tilename, calibration cal)
	Tests whether a tile with the given tilename has been flagged. More...

void	vmSetCustomTileFlags (vcsbeam_context *vm)
	Flags tiles by setting the corresponding calibration matrices to zero. More...

void	init_calibration (calibration *cal)
	Sets the member variables of the given calibration struct to their default values. More...

void	free_calibration (calibration *cal)
	Frees the memory associated with a calibration struct. More...

Function Documentation

◆ free_calibration()

void free_calibration ( calibration * cal )

Frees the memory associated with a calibration struct.

Parameters

cal	The calibration struct to be freed

This function frees memory associated with cal, but not cal itself.

◆ init_calibration()

void init_calibration ( calibration * cal )

Sets the member variables of the given calibration struct to their default values.

Parameters

cal	A pointer to the calibration struct to be initialised

◆ parse_calibration_correction_file()

void parse_calibration_correction_file	(	uint32_t	gpstime,
		calibration *	cal
	)

Parses the PQ phase correction for the given GPS time from the file pq_phase_correction.txt.

Parameters

gpstime	The GPS second to search for
cal	The calibration struct to store the read-in information

◆ read_bandpass_file()

void read_bandpass_file	(	gpuDoubleComplex ***	Jm,
		gpuDoubleComplex ***	Jf,
		MetafitsMetadata *	cal_metadata,
		char *	filename
	)

Reads an RTS Bandpass file.

Parameters

[out]	Jm	A buffer for the measured matrices, \({\bf J}_m\)
[out]	Jf	A buffer for the fitted matrices, \({\bf J}_f\)
	cal_metadata	The metadata struct for the calibration observation
	filename	The name of the Bandpass file to be read

This function populates the \({\bf J}_m\) and \({\bf J}_f\) arrays with values read in from the given Bandpass file. The Bandpass files contain only values for antennas and fine channels that have not been flagged. Nothing is done for those antennas/channels that have been flagged, so the onus is on the caller to initialise the \({\bf J}_m\) and \({\bf J}_f\) arrays to values to their preferred values.

◆ read_dijones_file()

void read_dijones_file	(	gpuDoubleComplex **	Dd,
		gpuDoubleComplex *	A,
		double *	amp,
		uintptr_t	nant,
		char *	fname
	)

Reads in an RTS DIJones file.

Parameters

[out]	Dd	The buffer to store the read-in matrices
[out]	A	The buffer to store the alignment matrix
[out]	amp	A (single-element) buffer to store the calibration amplitude
[in]	nant	The number of antennas to read in
	fname	The name of the file to read

Read in an RTS file and return the direction independent Jones matrix for each antenna. This implements Eq. (29) in Ord et al. (2019).

This function assumes that the RTS "DIJones" files are in a very specific format. However, this code is maintained independently from the RTS, so if the RTS changes, this code may break.

◆ remove_reference_phase()

void remove_reference_phase	(	gpuDoubleComplex *	J,
		gpuDoubleComplex *	Jref
	)

Rotates the phases of the elements of a complex matrix with respect to a reference matrix.

Parameters

[in,out]	J	The matrix whose phases are to be rotated, \({\bf J}\)
[in]	Jref	The reference matrix, \({\bf J}_\text{ref}\)

Each element in \({\bf J}\) is divided by the corresponding element in \({\bf J}_\text{ref}\), normalised to unit magnitude. That is, if

\[ \begin{aligned} {\bf J} &= \begin{bmatrix} J_0 & J_1 \\ J_2 & J_3 \end{bmatrix}, & {\bf J}_\text{ref} &= \begin{bmatrix} J_{\text{ref},0} & J_{\text{ref},1} \\ J_{\text{ref},2} & J_{\text{ref},3} \end{bmatrix}, \end{aligned} \]

then this function computes

\[ \begin{bmatrix} J_0\frac{|J_{\text{ref},0}|}{J_{\text{ref},0}} & J_1\frac{|J_{\text{ref},1}|}{J_{\text{ref},1}} \\ J_2\frac{|J_{\text{ref},2}|}{J_{\text{ref},2}} & J_3\frac{|J_{\text{ref},3}|}{J_{\text{ref},3}}. \end{bmatrix} \]

This operation does not affect the magnitudes of the elements of \({\bf J}\), but only their phases.

◆ tilename_is_flagged()

bool tilename_is_flagged	(	char *	tilename,
		calibration *	cal
	)

Tests whether a tile with the given tilename has been flagged.

Parameters

tilename	The tile name whose flagged status is sought
cal	The calibration struct containing the list of flagged tiles

Returns: True if an only if the tile with the given tilename is flagged in in cal

◆ vmApplyCalibrationCorrections()

void vmApplyCalibrationCorrections ( vcsbeam_context * vm )

Applies various corrections/adjustments to the calibration solutions.

This function applies to the calibration solutions given in vm→D. The corrections to be applied are taken from the calibration struct vm→cal.

Three (optional) corrections are applied:

Subtract the phases from each antenna by a reference antenna (see remove_reference_phase()).
Remove the PQ and QP (i.e. off-diagonal) terms (see zero_PQ_and_QP()).
Apply a phase slope to the QQ terms (implemented in this function).

◆ vmLoadOffringaSolution()

void vmLoadOffringaSolution ( vcsbeam_context * vm )

Reads in a calibration solution from an Offringa-style solution file.

A full description of the Offringa file format can be found here.

The input file is taken from vm→cal.caldir.

Only the coarse channel specified in vm→coarse_chan_idx will be read in.

This function assumes that memory for the Jones matrices (D) has already been allocated.

◆ vmLoadRTSSolution()

void vmLoadRTSSolution ( vcsbeam_context * vm )

Loads a Real Time System (RTS) calibration solution.

Returns: An array of Jones matrices (vm→D)

Reads in the RTS solution from the DI_Jones and Bandpass files in the vm→cal.caldir directory. It only reads the solution for the coarse channel specified in vm→coarse_chan_idxs_to_process[0]. Flagged channels and flagged antennas are set to zero.

The Jones matrices, \(D\), are output in the \((Q,P)\) basis:

\[\begin{bmatrix} D_{qq} & D_{qp} \\ D_{pq} & D_{pp} \end{bmatrix}.\]

The RTS bandpass solutions ("Bandpass...") are included if vm→cal.use_bandpass is set, otherwise only the coarse channel solutions ("DI_Jones...") are used.

This function assumes that a buffer for vm→D has already been allocated.

The RTS matrices are actually given in the \((P,Q)\), and this function reorders the matrices to be in the \((Q,P)\) basis, required by VCSBeam:

\[ \begin{bmatrix} D_{pp} & D_{pq} \\ D_{qp} & D_{qq} \end{bmatrix} \rightarrow \begin{bmatrix} D_{qq} & D_{qp} \\ D_{pq} & D_{pp} \end{bmatrix} \]

This reording is a "reversal" of the matrix elements (i.e. if one reads the elements from left to right, top to bottom).

See also: RTS; RTS file format

◆ vmParseFlaggedTilenamesFile()

void vmParseFlaggedTilenamesFile	(	char *	filename,
		calibration *	cal
	)

Parse the flagged tile names in the given file.

Parameters

filename	The name of the file to be parsed
cal	The calibration struct where to store the parsed information

◆ vmSetCustomTileFlags()

void vmSetCustomTileFlags ( vcsbeam_context * vm )

Flags tiles by setting the corresponding calibration matrices to zero.

If vm→cal.flags_file has been set, this function parses it (by calling vmParseFlaggedTilenamesFile()), and then sets all of the calibration solutions for the named tiles to zero. Afterwards, vmSetNumNotFlaggedRFInputs() is called.

◆ zero_PQ_and_QP()

void zero_PQ_and_QP ( gpuDoubleComplex * J )

Zeroes the off-diagonal terms of the given matrix.

Parameters

[in,out] J A complex-valued 2x2 matrix, \({\bf J}\)

This function sets the off-diagonal terms to zero, thus:

\[ {\bf J} = \begin{bmatrix} J_0 & J_1 \\ J_2 & J_3 \end{bmatrix} \rightarrow \begin{bmatrix} J_0 & 0 \\ 0 & J_3 \end{bmatrix}. \]

Functions

Function Documentation

◆ free_calibration()

◆ init_calibration()

◆ parse_calibration_correction_file()

◆ read_bandpass_file()

◆ read_dijones_file()

◆ remove_reference_phase()

◆ tilename_is_flagged()

◆ vmApplyCalibrationCorrections()

◆ vmLoadOffringaSolution()

◆ vmLoadRTSSolution()

◆ vmParseFlaggedTilenamesFile()

◆ vmSetCustomTileFlags()

◆ zero_PQ_and_QP()