1 /* 2 * Copyright (c) 2013-2020, The OSKAR Developers. 3 * See the LICENSE file at the top-level directory of this distribution. 4 */ 5 6 #ifndef OSKAR_STATION_ACCESSORS_H_ 7 #define OSKAR_STATION_ACCESSORS_H_ 8 9 /** 10 * @file oskar_station_accessors.h 11 */ 12 13 #include <oskar_global.h> 14 #include <mem/oskar_mem.h> 15 #include <telescope/station/element/oskar_element.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /* Data common to all station types. */ 22 23 /** 24 * @brief 25 * Returns the unique identifier of the station within the telescope model. 26 * 27 * @details 28 * Returns the unique identifier of the station within the telescope model. 29 * 30 * @param[in] model Pointer to station model. 31 * 32 * @return The unique identifier. 33 */ 34 OSKAR_EXPORT 35 int oskar_station_unique_id(const oskar_Station* model); 36 37 /** 38 * @brief 39 * Returns the numerical precision of data stored in the station model. 40 * 41 * @details 42 * Returns the numerical precision of data stored in the station model. 43 * 44 * @param[in] model Pointer to station model. 45 * 46 * @return The data type (OSKAR_SINGLE or OSKAR_DOUBLE). 47 */ 48 OSKAR_EXPORT 49 int oskar_station_precision(const oskar_Station* model); 50 51 /** 52 * @brief 53 * Returns the memory location of data stored in the station model. 54 * 55 * @details 56 * Returns the memory location of data stored in the station model. 57 * 58 * @param[in] model Pointer to station model. 59 * 60 * @return The memory location. 61 */ 62 OSKAR_EXPORT 63 int oskar_station_mem_location(const oskar_Station* model); 64 65 OSKAR_EXPORT 66 int oskar_station_type(const oskar_Station* model); 67 68 OSKAR_EXPORT 69 int oskar_station_normalise_final_beam(const oskar_Station* model); 70 71 OSKAR_EXPORT 72 double oskar_station_lon_rad(const oskar_Station* model); 73 74 OSKAR_EXPORT 75 double oskar_station_lat_rad(const oskar_Station* model); 76 77 OSKAR_EXPORT 78 double oskar_station_alt_metres(const oskar_Station* model); 79 80 OSKAR_EXPORT 81 double oskar_station_offset_ecef_x(const oskar_Station* model); 82 83 OSKAR_EXPORT 84 double oskar_station_offset_ecef_y(const oskar_Station* model); 85 86 OSKAR_EXPORT 87 double oskar_station_offset_ecef_z(const oskar_Station* model); 88 89 OSKAR_EXPORT 90 double oskar_station_polar_motion_x_rad(const oskar_Station* model); 91 92 OSKAR_EXPORT 93 double oskar_station_polar_motion_y_rad(const oskar_Station* model); 94 95 OSKAR_EXPORT 96 double oskar_station_beam_lon_rad(const oskar_Station* model); 97 98 OSKAR_EXPORT 99 double oskar_station_beam_lat_rad(const oskar_Station* model); 100 101 OSKAR_EXPORT 102 int oskar_station_beam_coord_type(const oskar_Station* model); 103 104 OSKAR_EXPORT 105 oskar_Mem* oskar_station_noise_freq_hz(oskar_Station* model); 106 107 OSKAR_EXPORT 108 const oskar_Mem* oskar_station_noise_freq_hz_const(const oskar_Station* model); 109 110 OSKAR_EXPORT 111 oskar_Mem* oskar_station_noise_rms_jy(oskar_Station* model); 112 113 OSKAR_EXPORT 114 const oskar_Mem* oskar_station_noise_rms_jy_const(const oskar_Station* model); 115 116 /* Data used only for Gaussian beam stations. */ 117 118 OSKAR_EXPORT 119 double oskar_station_gaussian_beam_fwhm_rad(const oskar_Station* model); 120 121 OSKAR_EXPORT 122 double oskar_station_gaussian_beam_reference_freq_hz(const oskar_Station* model); 123 124 /* Data used only for aperture array stations. */ 125 126 OSKAR_EXPORT 127 int oskar_station_identical_children(const oskar_Station* model); 128 129 OSKAR_EXPORT 130 int oskar_station_num_elements(const oskar_Station* model); 131 132 OSKAR_EXPORT 133 int oskar_station_num_element_types(const oskar_Station* model); 134 135 OSKAR_EXPORT 136 int oskar_station_normalise_array_pattern(const oskar_Station* model); 137 138 OSKAR_EXPORT 139 int oskar_station_normalise_element_pattern(const oskar_Station* model); 140 141 OSKAR_EXPORT 142 int oskar_station_enable_array_pattern(const oskar_Station* model); 143 144 OSKAR_EXPORT 145 int oskar_station_common_element_orientation(const oskar_Station* model); 146 147 OSKAR_EXPORT 148 int oskar_station_common_pol_beams(const oskar_Station* model); 149 150 OSKAR_EXPORT 151 int oskar_station_array_is_3d(const oskar_Station* model); 152 153 OSKAR_EXPORT 154 int oskar_station_apply_element_errors(const oskar_Station* model); 155 156 OSKAR_EXPORT 157 int oskar_station_apply_element_weight(const oskar_Station* model); 158 159 OSKAR_EXPORT 160 unsigned int oskar_station_seed_time_variable_errors(const oskar_Station* model); 161 162 OSKAR_EXPORT 163 int oskar_station_swap_xy(const oskar_Station* model); 164 165 OSKAR_EXPORT 166 double oskar_station_element_euler_index_rad( 167 const oskar_Station* model, int feed, int dim, int index); 168 169 OSKAR_EXPORT 170 oskar_Mem* oskar_station_element_euler_rad( 171 oskar_Station* model, int feed, int dim); 172 173 OSKAR_EXPORT 174 const oskar_Mem* oskar_station_element_euler_rad_const( 175 const oskar_Station* model, int feed, int dim); 176 177 OSKAR_EXPORT 178 oskar_Mem* oskar_station_element_true_enu_metres( 179 oskar_Station* model, int feed, int dim); 180 181 OSKAR_EXPORT 182 const oskar_Mem* oskar_station_element_true_enu_metres_const( 183 const oskar_Station* model, int feed, int dim); 184 185 OSKAR_EXPORT 186 oskar_Mem* oskar_station_element_measured_enu_metres( 187 oskar_Station* model, int feed, int dim); 188 189 OSKAR_EXPORT 190 const oskar_Mem* oskar_station_element_measured_enu_metres_const( 191 const oskar_Station* model, int feed, int dim); 192 193 OSKAR_EXPORT 194 oskar_Mem* oskar_station_element_cable_length_error_metres( 195 oskar_Station* model, int feed); 196 197 OSKAR_EXPORT 198 const oskar_Mem* oskar_station_element_cable_length_error_metres_const( 199 const oskar_Station* model, int feed); 200 201 OSKAR_EXPORT 202 oskar_Mem* oskar_station_element_gain(oskar_Station* model, int feed); 203 204 OSKAR_EXPORT 205 const oskar_Mem* oskar_station_element_gain_const( 206 const oskar_Station* model, int feed); 207 208 OSKAR_EXPORT 209 oskar_Mem* oskar_station_element_gain_error(oskar_Station* model, int feed); 210 211 OSKAR_EXPORT 212 const oskar_Mem* oskar_station_element_gain_error_const( 213 const oskar_Station* model, int feed); 214 215 OSKAR_EXPORT 216 oskar_Mem* oskar_station_element_phase_offset_rad( 217 oskar_Station* model, int feed); 218 219 OSKAR_EXPORT 220 const oskar_Mem* oskar_station_element_phase_offset_rad_const( 221 const oskar_Station* model, int feed); 222 223 OSKAR_EXPORT 224 oskar_Mem* oskar_station_element_phase_error_rad( 225 oskar_Station* model, int feed); 226 227 OSKAR_EXPORT 228 const oskar_Mem* oskar_station_element_phase_error_rad_const( 229 const oskar_Station* model, int feed); 230 231 OSKAR_EXPORT 232 oskar_Mem* oskar_station_element_weight(oskar_Station* model, int feed); 233 234 OSKAR_EXPORT 235 const oskar_Mem* oskar_station_element_weight_const( 236 const oskar_Station* model, int feed); 237 238 OSKAR_EXPORT 239 oskar_Mem* oskar_station_element_types(oskar_Station* model); 240 241 OSKAR_EXPORT 242 const oskar_Mem* oskar_station_element_types_const(const oskar_Station* model); 243 244 OSKAR_EXPORT 245 const int* oskar_station_element_types_cpu_const(const oskar_Station* model); 246 247 OSKAR_EXPORT 248 const char* oskar_station_element_mount_types_const(const oskar_Station* model); 249 250 OSKAR_EXPORT 251 int oskar_station_has_child(const oskar_Station* model); 252 253 OSKAR_EXPORT 254 oskar_Station* oskar_station_child(oskar_Station* model, int i); 255 256 OSKAR_EXPORT 257 const oskar_Station* oskar_station_child_const(const oskar_Station* model, 258 int i); 259 260 OSKAR_EXPORT 261 int oskar_station_has_element(const oskar_Station* model); 262 263 OSKAR_EXPORT 264 oskar_Element* oskar_station_element(oskar_Station* model, 265 int element_type_index); 266 267 OSKAR_EXPORT 268 const oskar_Element* oskar_station_element_const(const oskar_Station* model, 269 int element_type_index); 270 271 OSKAR_EXPORT 272 int oskar_station_num_permitted_beams(const oskar_Station* model); 273 274 OSKAR_EXPORT 275 const oskar_Mem* oskar_station_permitted_beam_az_rad_const( 276 const oskar_Station* model); 277 278 OSKAR_EXPORT 279 const oskar_Mem* oskar_station_permitted_beam_el_rad_const( 280 const oskar_Station* model); 281 282 283 /* Setters. */ 284 285 /** 286 * @brief 287 * Sets the unique station identifier. 288 * 289 * @details 290 * Sets the unique station identifier, recursively if necessary. 291 * This should be set only when the telescope model is being initialised. 292 * 293 * @param[in] model Pointer to station model. 294 * @param[in] counter Updated identifier. 295 */ 296 OSKAR_EXPORT 297 void oskar_station_set_unique_ids(oskar_Station* model, int* counter); 298 299 /** 300 * @brief 301 * Sets the station type (aperture array, Gaussian beam, etc). 302 * 303 * @details 304 * Sets the station type (aperture array, Gaussian beam, etc). 305 * 306 * @param[in] model Pointer to station model. 307 * @param[in] type Enumerator describing the station type. 308 */ 309 OSKAR_EXPORT 310 void oskar_station_set_station_type(oskar_Station* model, int type); 311 312 /** 313 * @brief 314 * Sets the flag to specify whether the beam should be completely normalised 315 * (default false). 316 * 317 * @details 318 * Sets the flag to specify whether the station beam should be completely 319 * normalised to a peak value of 1.0 (default false). 320 * 321 * @param[in] model Pointer to station model. 322 * @param[in] value True or false. 323 */ 324 OSKAR_EXPORT 325 void oskar_station_set_normalise_final_beam(oskar_Station* model, int value); 326 327 /** 328 * @brief 329 * Sets the geographic coordinates of the station centre. 330 * 331 * @details 332 * Sets the longitude, latitude and altitude of the station centre. 333 * 334 * @param[in] model Pointer to station model. 335 * @param[in] longitude_rad East-positive longitude, in radians. 336 * @param[in] latitude_rad North-positive geodetic latitude in radians. 337 * @param[in] altitude_m Altitude above ellipsoid in metres. 338 */ 339 OSKAR_EXPORT 340 void oskar_station_set_position(oskar_Station* model, 341 double longitude_rad, double latitude_rad, double altitude_m, 342 double offset_ecef_x, double offset_ecef_y, double offset_ecef_z); 343 344 /** 345 * @brief 346 * Sets the polar motion components. 347 * 348 * @details 349 * Sets the polar motion components for the station. 350 * This function operates recursively to set polar motion components for all 351 * child stations too. 352 * 353 * @param[in] model Pointer to station model. 354 * @param[in] pm_x_rad Polar motion x-component, in radians. 355 * @param[in] pm_y_rad Polar motion y-component, in radians. 356 */ 357 OSKAR_EXPORT 358 void oskar_station_set_polar_motion(oskar_Station* model, 359 double pm_x_rad, double pm_y_rad); 360 361 /** 362 * @brief 363 * Sets the coordinates of the phase centre. 364 * 365 * @details 366 * Sets the longitude and latitude of the station phase centre on the sky. 367 * 368 * @param[in] model Pointer to station model. 369 * @param[in] coord_type Beam coordinate type (either 370 * OSKAR_SPHERICAL_TYPE_EQUATORIAL or 371 * OSKAR_SPHERICAL_TYPE_AZEL). 372 * @param[in] longitude_rad Beam longitude in radians. 373 * @param[in] latitude_rad Beam latitude in radians. 374 */ 375 OSKAR_EXPORT 376 void oskar_station_set_phase_centre(oskar_Station* model, 377 int coord_type, double longitude_rad, double latitude_rad); 378 379 /** 380 * @brief 381 * Sets the parameters of the Gaussian beam used for Gaussian beam stations. 382 * 383 * @details 384 * Sets the parameters of the Gaussian beam used for Gaussian beam stations. 385 * 386 * @param[in] model Pointer to station model. 387 * @param[in] fwhm_rad Full-width-half-maximum of the Gaussian beam, in radians. 388 * @param[in] ref_freq_hz Reference frequency at which FWHM applies, in Hz. 389 */ 390 OSKAR_EXPORT 391 void oskar_station_set_gaussian_beam_values(oskar_Station* model, 392 double fwhm_rad, double ref_freq_hz); 393 394 /** 395 * @brief 396 * Sets the flag to specify whether the beam should be normalised (default false). 397 * 398 * @details 399 * Sets the flag to specify whether the station beam should be normalised 400 * by dividing by the number of elements (default false). 401 * 402 * @param[in] model Pointer to station model. 403 * @param[in] value True or false. 404 */ 405 OSKAR_EXPORT 406 void oskar_station_set_normalise_array_pattern(oskar_Station* model, int value); 407 408 /** 409 * @brief 410 * Sets the flag to specify whether each element beam should be normalised 411 * (default false). 412 * 413 * @details 414 * Sets the flag to specify whether each element beam should be normalised 415 * to its value at the zenith (default false). 416 * 417 * @param[in] model Pointer to station model. 418 * @param[in] value True or false. 419 */ 420 OSKAR_EXPORT 421 void oskar_station_set_normalise_element_pattern( 422 oskar_Station* model, int value); 423 424 /** 425 * @brief 426 * Sets the flag to specify whether the array pattern is enabled. 427 * 428 * @details 429 * Sets the flag to specify whether the full station beam should be evaluated 430 * by computing the array pattern (default true). 431 * 432 * @param[in] model Pointer to station model. 433 * @param[in] value True or false. 434 */ 435 OSKAR_EXPORT 436 void oskar_station_set_enable_array_pattern(oskar_Station* model, int value); 437 438 /** 439 * @brief 440 * Sets the seed used to generate time-variable errors. 441 * 442 * @param[in] model Pointer to station model. 443 * @param[in] value Seed value. 444 */ 445 OSKAR_EXPORT 446 void oskar_station_set_seed_time_variable_errors(oskar_Station* model, 447 unsigned int value); 448 449 /** 450 * @brief 451 * Sets the option to swap X and Y antenna responses in the output. 452 * 453 * @param[in] model Pointer to station model. 454 * @param[in] value True or false. 455 */ 456 OSKAR_EXPORT 457 void oskar_station_set_swap_xy(oskar_Station* model, int value); 458 459 #ifdef __cplusplus 460 } 461 #endif 462 463 #endif /* include guard */ 464