7. C++ API reference

The core of |galario| is implemented in C++ with a functional API. All functions are in namespace galario.

7.1. Sample and chi2 functions

lhere are four main functions that should serve the standard use of |galario|.

void sample_profile(int nr, const dreal *intensity, dreal Rmin, dreal dR, dreal dxy, int nxy, dreal inc, dreal dRA, dreal dDec, dreal duv, dreal PA, int nd, const dreal *u, const dreal *v, dcomplex *vis_int)

Compute visibilities for a model defined by a radial profile.

The parameters are described in more detail in the python function sampleProfile().

Parameters

  • nr – The number of points of the radial profile.

  • intensity – The intensities of the radial profile. Size: nr

  • Rmin – Inner edge of radial grid.

  • dR – Radial-grid cell size.

  • dxy – Image cell size.

  • nxy – Number of image pixels in x- and y-direction.

  • inc – Inclination.

  • dRa – Rectascension offset.

  • dDec – Dec. offset.

  • duv – The size of a pixel, uniform in u- and v-direction. Units: same as u, v.

  • PA – Position angle.

  • nd – Number of visibility points.

  • u – u coordinate of visibility points. Size: nd

  • v – v coordinate of visibility points. Size: nd

  • vis_int – Interpolated visibilities at the points u, v. Size: nd

void sample_image(int nx, int ny, const dreal *image, dreal dRA, dreal dDec, dreal duv, dreal PA, int nd, const dreal *u, const dreal *v, dcomplex *vis_int)

Compute visibilities for a model defined by a real image.

Parameters

  • nx – The number of points of image in x-direction

  • ny – The number of points of image in y-direction

  • image – A rectangular image of size nx*ny.

For the other parameters, see sample_profile().

dreal chi2_profile(int nr, const dreal *intensity, dreal Rmin, dreal dR, dreal dxy, int nxy, dreal inc, dreal dRA, dreal dDec, dreal duv, dreal PA, int nd, const dreal *u, const dreal *v, const dreal *vis_obs_re, const dreal *vis_obs_im, const dreal *weights)

Compute the \(\chi^2\) between observed visibilities and the interpolation based on a radial profile and return in chi2.

For details, see the python function chi2Profile().

All parameters are identical to sample_profile() except that the model visibilities are not returned but directly compared to weighted observations.

Parameters

  • vis_obs_re – The real part of the visibilities. Size: nd.

  • vis_obs_im – The imaginary part of the visibilities. Size: nd.

  • weights – The weights of the observations. Size: nd.

dreal chi2_image(int nx, int ny, const dreal *image, dreal dRA, dreal dDec, dreal duv, dreal PA, int nd, const dreal *u, const dreal *v, const dreal *vis_obs_re, const dreal *vis_obs_im, const dreal *weights)

Compute the \(\chi^2\) between observed visibilities and the interpolation based on the input image and return in chi2.

For details, see chi2_profile() and the python function chi2Image().

Danger

The values of duv and and u, v have to be consistent; i.e., \(\max |u| \leq \frac{n}{2} + 1\) and \(v \leq \frac{n}{2}\), where \(n\) is the number of rows and columns of the real input image. For performance reasons, the interpolate function does not check this. Inconsistent values may lead to segfaults.

7.2. Management functions

void init()

Initialize memory and environment for galario.

Call this function before any computation is performed.

void cleanup()

Free memory and clean up environment created by init(). Call after all computations in galario.

int threads(int num = 0)

Set the number of openMP threads that galario uses in parallel regions to num. The default of 0 doesn’t change the number of threads. Return the current number of threads.

By default, use the settings in the openMP runtime that can be affected for example by setting the OMP_NUM_THREADS variable.

For the cuda version, this sets the number of threads per block in cuda kernels.

For more details, see the python function threads().

int ngpus()

Get the number of available GPUs.

void use_gpu(int device_id)

Set the GPU to be used for the computations.

For details, see the python function use_gpu().

7.3. Individual operations

The following functions provide low-level access to individual operations performed by the sample and chi2 functions. A standard user will likely have little use for them. Refer to the python API documentation of the wrappers for details on the individual functions.

void sweep(int nr, dreal *intensity, dreal Rmin, dreal dR, int nxy, dreal dxy, dreal inc, dcomplex *image)
void uv_rotate(dreal PA, dreal dRA, dreal dDec, dreal *dRArot, dreal *dDecrot, int nd, const dreal *u, const dreal *v, dreal *urot, dreal *vrot)
dcomplex *copy_input(int nx, int ny, const dreal *image)
void galario_free(void*)

Free the memory buffer allocated and returned by copy_input().

void fft2d(int nx, int ny, dcomplex *image)
void fftshift(int nx, int ny, dcomplex *image)
void fftshift_axis0(int nx, int ny, dcomplex *matrix)
void interpolate(int nrow, int ncol, const dcomplex *image, int nd, const dreal *u, const dreal *v, const dreal duv, dcomplex *vis_int)
void apply_phase_sampled(dreal dRA, dreal dDec, int nd, const dreal *u, const dreal *v, dcomplex *vis_int)
void reduce_chi2(int nd, const dreal *vis_obs_re, const dreal *vis_obs_im, const dcomplex *vis_int, const dreal *weights, dreal *chi2)