create_sky_model

API documentation for create_sky_model.c.

TODO Should stick a bunch of information about sky model formats in here

Methods to read in and crop a WODEN style sky model to everything above the horizon.

Author

J.L.B. Line

Defines

SRC_KEY

“SOURCE” - Line beginning / containing SOURCE information (includes number of COMPONENTS)

SRC_END

“ENDSOURCE” - Line ending SOURCE information

COMP_KEY

“COMPONENT” - Line beginning / containing COMPONENT information

COMP_END

“ENDCOMPONENT” - Line ending COMPONENT information

FREQ_KEY

“FREQ” (Deprecated) - Lines contains FREQ information

LINEAR_KEY

“LINEAR” - Line contains simple exponential SED information

POINT_KEY

“POINT” - Line contains POINT RA, Dec information

GAUSSIAN_KEY

“GAUSSIAN” - Line contains GAUSSIAN RA, Dec information

GPARAMS_KEY

“GPARAMS” - Line contains GAUSSIAN major, minor, PA information

SHAPELET_KEY

“SHAPELET” - Line containing SHAPELET RA, Dec information

SPARAMS_KEY

“SPARAMS” - Line contains SHAPELET beta1 (major), beta2 (minor), PA information

SCOEFF_KEY

“SCOEFF” - Line contains SHAPELET basis numbers n1, n2m coefficient information

Enums

enum e_sky_crop

enum to describe if we are cropping the sky model by entire SOURCEs, or by invidual COMPONENTs

Values:

enumerator CROP_SOURCES

cropping by SOURCE

enumerator CROP_COMPONENTS

cropping by COMPONENT

enum e_horizon

enum to describe if a SOURCE/COMPONENT is above or below the horizon

Values:

enumerator BELOW

above the horizon

enumerator ABOVE

below the horizon

Functions

int read_source_catalogue(const char *filename, source_catalogue_t *srccat)

Takes a path to WODEN-style sky model and populates a source_catalogue_t struct with the contents of filename.

The WODEN sourcelist at filename should contain a number of sources, with the basic structure: 

       SOURCE source_name P 1 G 0 S 0 0
       COMPONENT POINT 4.0 -27.0
       LINEAR 1.8e+08 10.0 0 0 0 -0.8
       ENDCOMPONENT
       ENDSOURCE

For a more detailed explanation of the sky model, please see the documentation at

Todo:

Link the online documentation when there is a link.

Note that srccat should be memory intialised, so declare with something like source_catalogue_t *raw_srccat = malloc( sizeof(source_catalogue_t) ); before feeding into this function.

Parameters

  • *srccat – [in] Struct to contain sky model information.

  • *filename – [in] Path to a WODEN-style sky model

Returns

Integer where 0 if read was successful, 1 if failed

void convert_radec2azza(double ra, double dec, double lst, double latitude, double *az, double *za)

Convert Right Ascension, Declination into Azimuth and Zenith Angle for the given LST and Latitude.

All angles are in radians. Uses the erfa function eraHd2ae to perform the calculation.

Parameters

  • ra – [in] Right Ascension (radians)

  • dec – [in] Declination (radians)

  • lst – [in] Local Sidereal Time (radians)

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

  • *az – [inout] Azimuth (radians)

  • *za – [inout] Zenith Angle (radians)

void horizon_test(double za, e_sky_crop sky_crop_type, e_horizon *all_comps_above_horizon, int *num_comp_retained, int *num_shape_coeff_retained, int num_shape_coeff_component, user_precision_t *shape_param_indexes, int shape)

Checks if a zenith angle for a COMPONENT is above the horizon, and returns the correct indexes of COMPONENTS to retain if so.

Depending on what type of sky cropping we are doing (see crop_sky_model function below) as specified by sky_crop_type. If cropping by SOURCE, and COMPONENT below horizon, sets all_comps_above_horizon = BELOW. If cropping by COMPONENT, and above horizon, update the number of retained COMPONENTs num_comp_retained

If the component is a SHAPELET, we also have to update num_shape_coeff_retained this is how many shapelet coefficients are retained, as one SHAPELET COMPONENT (with one az,za) can have multiple shapelet coefficients. The array of ints shape_param_indexes maps the shapelet coefficients to each SHAPELET COMPONENT, so the function uses the int shape to check which coefficients match this particular COMPONENT by looping through shape_param_indexes.

Parameters

  • za – [in] Zenith Angle (radians)

  • sky_crop_type – [in] e_sky_crop for SOURCE or COMPONENT cropping

  • *all_comps_above_horizon – [inout] Pointer to e_horizon type for whether all COMPONENTs of the SOURCE this COMPONENT belongs to are above the horizon

  • *num_comp_retained – [inout] Number of COMPONENTs retained for this SOURCE

  • *num_shape_coeff_retained – [inout] Number of SHAPELET coefficients retained for this SOURCE

  • num_shape_coeff_component – [in] The total number of shapelet coefficients in this SOURCE

  • *shape_param_indexes – [in] Map of which shapelet coefficients match this SHAPELET COMPONENT

  • shape – [in] Index of this SHAPELET COMPONENT within this SOURCE

catsource_t *crop_sky_model(source_catalogue_t *raw_srccat, double *lsts, double latitude, int num_time_steps, e_sky_crop sky_crop_type)

Takes the WODEN sky model raw_srccat, and crops either all SOURCEs or COMPONENTs that are below the horizon (at the initial time step), returning the cropped sky model. Also calculates $az,za$ for all time steps for the retained COMPONENTs.

A WODEN sky model can be made of multiple SOURCEs, each of which can have any number of COMPONENTS. We can either crop an entire SOURCE if below horizon, or retain all COMPONENTs that are above the horizon. Say if you put an all-sky diffuse map into one SOURCE, you should crop by COMPONENT, as some part of the SOURCE will always be below the horizon.

A complicating factor to the cropping is that each SHAPELET COMPONENT has any number of associated shapelet coefficients, which must be mapped correctly in the output cropped sky model cropped_src. The function horizon_test is used to do this mapping.

Todo:

Consider cropping sources iteratively for each time step. If the user runs a very long simulation, we may end up with large chunks of empty sky. This will however require far more erfa az,za calculations, so for simulations with millions of sources, more practical to just tell the user to run multiple shorter simulations.

Parameters

  • *raw_srccat – [in] Pointer to a populated source_catalogue_t struct of all input sky model parameters

  • *lsts – [in] Array of local sidereal times for the simulation

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

  • num_time_steps – [in] Number of time steps for the simulation

  • sky_crop_type – [in] e_sky_crop for SOURCE or COMPONENT cropping

Returns

cropped_src, a catsource_t sky model with only SOURCE/COMPONENTS above the horizon for simulation