primary_beam_cpu

API documentation for primary_beam_cpu.c.

Host methods to calculate perfect Gaussian and Analytic Dipole primary beam responses. Currently, the analytic dipole is fixed to being an MWA dipole. Both models assume there is no leakage and beams are purely real.

Functions

void twoD_Gaussian_cpu(user_precision_t x, user_precision_t y, user_precision_t xo, user_precision_t yo, user_precision_t sigma_x, user_precision_t sigma_y, user_precision_t cos_theta, user_precision_t sin_theta, user_precision_t sin_2theta, user_precision_t *beam_real, user_precision_t *beam_imag)

Calculate a two dimensional Gaussian.

Returns the Gaussian as defined on Wikipedia here via the equation:

\[ G(x,y) = \exp \left( -\left( a(x-x_o)^2 + 2b(x-x_o)(y-y_o) + c(y-y_o)^2 \right) \right) \]

where

\[\begin{split}\begin{eqnarray*} a &=& \frac{\cos(\theta)^2}{2\sigma_x^2} + \frac{\sin(\theta)^2}{2\sigma_y^2} \\ b &=& -\frac{\sin(2\theta)}{4\sigma_x^2} + \frac{\sin(2\theta)}{4\sigma_y^2} \\ c &=& \frac{\sin(\theta)^2}{2\sigma_x^2} + \frac{\cos(\theta)^2}{2\sigma_y^2} \end{eqnarray*}\end{split}\]

with \((x_0,y_0)\) the central coordinates, \((\sigma_x,\sigma_y)\) the standard deviations.

Parameters:

  • x – [in] x coordinate

  • y – [in] y coordinate

  • xo – [in] Central x coordinate

  • yo – [in] Central y coordinate

  • sigma_x – [in] Square root of variance in x

  • sigma_y – [in] Square root of variance in x

  • cos_theta – [in] Cosine of the rotation angle

  • sin_theta – [in] Sine of the rotation angle

  • sin_2theta – [in] Sine of two times the rotation angle

  • *beam_real – [inout] Real part of the Gaussian repsonse

  • *beam_imag – [inout] Imaginary part of the Gaussian reponse

void gaussian_beam_from_lm_cpu(double *beam_ls, double *beam_ms, double beam_ref_freq, double *freqs, user_precision_t fwhm_lm, user_precision_t cos_theta, user_precision_t sin_theta, user_precision_t sin_2theta, int num_components, int num_time_steps, int num_freqs, user_precision_complex_t *g1xs, user_precision_complex_t *g1ys)

Calculate a Gaussian primary beam response at the given interferometric sky \((l,m)\) coords and frequency.

The primary beam is to be calculated for each sky direction, each time step, and each frequency. The size of the beam repsonse on the sky changes with frequency, so need a reference frequency beam_ref_freq and full-width half-maximum (fwhm_lm, in \(l,m\) units) to scale the beam width with frequency. The Gaussian beam is held to point at a given az/za, so the sky positions to calculate in d_beam_ls, d_beam_ms should contain num_components*num_times values, as the COMPONENTs move through the beam with time. The outputs are stored in d_primay_beam_J00, d_primay_beam_J11, where 00 refers to the north-south polarisation, 11 the east-west polarisation, in order of time, frequency, COMPONENT.

Parameters:

  • *beam_ls – [in] Array of \(l\) coords to calculate beam at

  • *beam_ms – [in] Array pf \(m\) coords to calculate beam at

  • beam_ref_freq – [in] Reference frequency at which the FWHM is applicable (Hz)

  • *freqs – [in] Array of frequencies to calculate beam at (Hz)

  • fwhm_lm – [in] FWHM of the beam in \(l,m\) coords

  • cos_theta – [in] Cosine of the rotation angle

  • sin_theta – [in] Sine of the rotation angle

  • sin_2theta – [in] Sine of two times the rotation angle

  • num_freqs – [in] Number of frequencies being calculated

  • num_time_steps – [in] Number of time steps being calculated

  • num_components – [in] Number of COMPONENTS the beam is calculated for

  • *g1xs – [inout] array to store the beam Jones complex J[0,0] response in

  • *g1ys – [inout] array to store the beam Jones complex J[1,1] response in

void calculate_gaussian_beam_cpu(int num_components, int num_time_steps, int num_freqs, user_precision_t ha0, user_precision_t sdec0, user_precision_t cdec0, user_precision_t fwhm_lm, user_precision_t cos_theta, user_precision_t sin_theta, user_precision_t sin_2theta, double beam_ref_freq, double *freqs, double *beam_has, double *beam_decs, user_precision_complex_t *g1xs, user_precision_complex_t *g1ys)

Calculate the Gaussian primary beam response at the given hour angle and declinations beam_point_has, beam_point_decs. Note the XX and YY repsonses are equal in this toy example.

The primary beam is to be calculated for each sky direction, each time step, and each frequency. The size of the beam repsonse on the sky changes with frequency, so need a reference frequency beam_ref_freq and full-width half-maximum (fwhm_lm, in \(l,m\) units) to scale the beam width with frequency. The Gaussian beam is held to point at a given az/za, so the sky positions to calculate in d_beam_ls, d_beam_ms should contain num_components*num_times values, as the COMPONENTs move through the beam with time. The outputs are stored in d_primay_beam_J00, d_primay_beam_J11, where 00 refers to the north-south polarisation, 11 the east-west polarisation, in order of time, frequency, COMPONENT. This function uses the beam centre pointing ha0, dec0 to calculate an \(l,m\) coord system in which to calculate the Gaussian beam, using gaussian_beam_from_lm_cpu.

Parameters:

  • num_components – [in] Number of COMPONENTS the beam is calculated for

  • num_time_steps – [in] Number of time steps being calculated

  • num_freqs – [in] Number of frequencies being calculated

  • ha0 – [in] Hour angle of beam pointing centre (radians)

  • sdec0 – [in] Sine of Declination of the beam pointing centre (radians)

  • cdec0 – [in] Cosine of Declination of the beam pointing centre (radians)

  • fwhm_lm – [in] FWHM of the beam in \(l,m\) coords

  • cos_theta – [in] Cosine of the rotation angle

  • sin_theta – [in] Sine of the rotation angle

  • sin_2theta – [in] Sine of two times the rotation angle

  • beam_ref_freq – [in] Reference frequency at which the FWHM is applicable (Hz)

  • *freqs – [in] Array of frequencies to calculate beam at (Hz)

  • *beam_has – [in] Array of Hour Angles to calculate the beam toward

  • *beam_decs – [in] Array of Declinations to calculate the beam toward

  • *g1xs – [inout] Device array to store the beam Jones complex J[0,0] response in

  • *g1ys – [inout] Device array to store the beam Jones complex J[1,1] response in

void analytic_dipole_cpu(user_precision_t az, user_precision_t za, user_precision_t wavelength, user_precision_complex_t *beam_X, user_precision_complex_t *beam_Y)

Calculate the beam response of a north-south (X) and east-west (Y) analytic dipole on an infinite ground screen, for the given sky direciton az,za and wavelength.

Dipoles are assumed to be MWA, and given a length of 0.3 metres. Beam size on the sky scales with frequency hence the need for wavelength

Parameters:

  • az – [in] Azimuth (radians)

  • za – [in] Zenith Angle (radians)

  • wavelength – [in] Wavelength (metres)

  • beam_X – [inout] Complex beam value for north-south dipole

  • beam_Y – [inout] Complex beam value for east-west dipole

void calculate_analytic_dipole_beam_cpu(int num_components, int num_time_steps, int num_freqs, user_precision_t *azs, user_precision_t *zas, double *freqs, user_precision_complex_t *g1xs, user_precision_complex_t *g1ys)

Calculate the Analytic Dipole over an infinite ground screen primary beam response at the given Azimuth and Zenith Angles azs,zas, and frequencies d_freqs.

The primary beam is to be calculated for each sky direction, each time step, and each frequency. The Analytic dipole beam is stationary on the sky, so the Azimuth and Zenith Angles in azs,zas should contain num_components*num_times values, as the COMPONENTs move through the beam with time. The outputs are stored in g1xs, g1ys, where x refers to the north-south polarisation, y the east-west polarisation, in order of time, frequency, COMPONENT. Beam outputs are normalised to zenith.

Parameters:

  • num_components – [in] Number of COMPONENTS the beam is calculated for

  • num_time_steps – [in] Number of time steps being calculated

  • num_freqs – [in] Number of frequencies being calculated

  • *freqs – [in] Array of frequencies to calculate beam at (Hz)

  • *azs – [in] Array of Azimuth angles to calculate the beam towards (radians)

  • *zas – [in] Array of Zenith Angles to calculate the beam towards (radians)

  • *g1xs – [inout] Complex array to store the north-south gains

  • *g1ys – [inout] Complex array to store the east-west gains

void RTS_MWA_beam_cpu(user_precision_t az, user_precision_t za, double ha, double dec, double wavelength, double *metre_delays, double latitude, int norm, user_precision_complex_t *gx, user_precision_complex_t *Dx, user_precision_complex_t *Dy, user_precision_complex_t *gy)

Calculate the analytic MWA beam response to a single az/za direction for a give wavelength and set of delays (metre_delays)

Based on the RTS code found in mwa_tile::local_FillMatrices. I think this code inherently does some kind of parallatic rotation, hence needs the ha/dec along with the az/za. The delays added to the paths of individual dipoles allow the beam to be ‘pointed’. The physical length of these paths should be given in metre_delays (this conversion from the delays given in the MWA metafits is handled by primary_beam_cpu::calculate_RTS_MWA_analytic_beam_cpu)

Parameters:

  • az – [in] Azimuth to calculate the beam toward (radians)

  • za – [in] Zenith angle to calculate the beam toward (radians)

  • ha – [in] Corresponding hour angle to the given az, za

  • dec – [in] Corresponding Declination to the given az, za

  • wavelength – [in] Wavelength to calculate the beam at (metres)

  • metre_delays – [in] The physical delays lengths added to each dipole to steer the beam (metres)

  • latitude – [in] Latitude of the array (radians)

  • norm – [in] Whether to normalise to zenith or not (1 to normalise, 0 to not)

  • *gx – [inout] The gain for the north-south beam

  • *Dx – [inout] The leakage for the north-south beam

  • *Dy – [inout] The leakage for the east-west beam

  • *gy – [inout] The gain for the east-west beam

void calculate_RTS_MWA_analytic_beam_cpu(int num_components, int num_time_steps, int num_freqs, user_precision_t *azs, user_precision_t *zas, int *delays, double latitude, int norm, double *beam_has, double *beam_decs, double *freqs, user_precision_complex_t *gxs, user_precision_complex_t *Dxs, user_precision_complex_t *Dys, user_precision_complex_t *gys)

Calculate the analytic MWA primary beam to a set of sky directions azs and zas for a given set of delays delays as listed in an MWA metafits file, and frequencies freqs.

The MWA primary beam is stationary on the sky for a given set of delays, so the Azimuth and Zenith Angles in azs,zas should contain num_components*num_times values, as the COMPONENTs move through the beam with time. The delays added to the paths of individual dipoles allow the beam to be ‘pointed’. The delays as listed in the metafits (given as delays) are listed in units of the delay time added internally to the tile (in seconds). This function coverts them into a path length (metres), as needed by primary_beam_cpu::RTS_MWA_beam_cpu`.

Parameters:

  • num_components – [in] Number of COMPONENTS the beam is calculated for

  • num_time_steps – [in] Number of time steps being calculated

  • num_freqs – [in] Number of frequencies being calculated

  • *azs – [in] Array of Azimuth angles to calculate the beam towards (radians)

  • *zas – [in] Array of Zenith Angles to calculate the beam towards (radiany)

  • *delays – [in] Delays that specificy the pointing (as reported in the MWA metafits)

  • latitude – [in] Latitude of the array (radians)

  • norm – [in] Whether to normalise to zenith or not (1 to normalise, 0 to not)

  • *beam_has – [in] Hour angles corresponding to azs,zas (radians)

  • *beam_decs – [in] Declinations corresponding to azs,zas (radians)

  • *freqs – [in] Array of frequencies to calculate beam at (Hz)

  • *gxs – [inout] The gains for the north-south beam

  • *Dxs – [inout] The leakages for the north-south beam

  • *Dys – [inout] The leakages for the east-west beam

  • *gys – [inout] The gains for the east-west beam

void run_hyperbeam_cpu(int num_components, int num_time_steps, int num_freqs, int num_beams, uint8_t parallactic, double *freqs, struct FEEBeam *fee_beam, uint32_t *hyper_delays, int num_amps, double *amps, double *azs, double *zas, double *latitudes, user_precision_complex_t *gxs, user_precision_complex_t *Dxs, user_precision_complex_t *Dys, user_precision_complex_t *gys)

Calculate the FEE MWA primary beam model to a set of sky directions azs and zas for a given initialised mwa_hyperbeam device beam object *gpu_fee_beam. NOTE that the azs, zas need to increment by component (fastest changing), then time (slowest changing). This is the OPPOSITE of what happens for all other functions, but is needed for pointer arithmatic that must be done to feed things into mwa_hyperbeam efficiently. Soz boz.

Calls mwa_hyperbeam::fee_calc_jones_gpu_device to calculate the beam responses on the device. This function requires an initialised struct FEEBeam *gpu_fee_beam object (initialised using mwa_hyperbeam::new_gpu_fee_beam), which in turn needs a struct FEEBeam *fee_beam (initialised using mwa_hyperbeam::new_fee_beam). Running these functions gathers the spherical harmnoic coefficients for the requested frequencies, as well as the delays to point the beam. If these aren’t setup correctly, this will fall flat on it’s face.

Once the beam repsonses have been calculated, split them up into the WODEN d_primay_beam_J* arrays using the kernel primary_beam_gpu::kern_map_hyperbeam_gains.

Parameters:

  • num_components – [in] Number of COMPONENTS the beam is calculated for

  • num_time_steps – [in] Number of time steps being calculated

  • num_freqs – [in] Number of frequencies being calculated

  • num_beams – [in] How many primary beams are being simulated. If making all primary beams the same, set to 1, otherwise number of antennas(tiles).

  • parallactic – [in] Whether to rotate by parallactic angle or not

  • *freqs – [in] Array of frequencies to calculate beam at (Hz)

  • *fee_beam – [in] An initialised mwa_hyperbeam struct fee_beam

  • *hyper_delays – [in] MWA beam delays (as found in metafits file)

  • *azs – [in] Array of Azimuth angles to calculate the beam towards (radians)

  • *zas – [in] Array of Zenith Angles to calculate the beam towards (radians)

  • *latitudes – [in] The latitude of the array for each time step (radians); this can be NULL if parallactic = 0

  • num_amps – [in] Number of MWA dipole amplitudes to use

  • *amps – [in] Bespoke MWA dipole amplitudes for each antenna(tile). Should be 2*num_ants*16 long

  • *gxs – [inout] The gains for the north-south beam

  • *Dxs – [inout] The leakages for the north-south beam

  • *Dys – [inout] The leakages for the east-west beam

  • *gys – [inout] The gains for the east-west beam