LOW REST API

These docs are generated from the OpenAPI specification for the application. There is an issue with the RTD plugin which means the response types are not rendered. To see the API response bodies for the status codes listed below see the Swagger UI: https://k8s.stfc.skao.int/integration-ska-ost-senscalc-ui/senscalc/api/v<MAJOR_VERSION>/low/ui/

GET /subarrays

Returns the array configurations available

Status Codes:

200 OK – Successful response with the list of array configurations.

GET /continuum/calculate

Returns the sensitivity, image weighting parameters and weighted sensitivity, where applicable, given an integration time and weighting mode.

Query Parameters:

subarray_configuration (string) – Enumeration of the SKA LOW subarray configurations allowed for a continuum calculation. To define a custom configuration, set num_stations and do not set this parameter.
num_stations (number) – The number of LOW antenna stations. If set, subarray_configuration should not be set.
integration_time_h (number) – The integration time of the observation in hours
pointing_centre (string) – Pointing centre in HH:MM:SS[.ss] [+|-]DD:MM:SS[.ss] (Required)
freq_centre_mhz (number) – Central frequency in MHz. Combined with the bandwidth_mhz, it must define a spectral window that is contained within the Low frequency range.
bandwidth_mhz (number) – Bandwidth for the continuum observation in MHz. Combined with the freq_centre_mhz, it must define a spectral window that is contained within the Low frequency range.
spectral_averaging_factor (number) – Factor by which the spectral resolution should be averaged to calculate the effective resolution which is used in the calculation. The number of channels is set by the continuum bandwidth and the maximum value of the spectral averaging factor is half that number.
elevation_limit (number) – Lowest elevation that the LOW observation will be performed at. The maximum value is nominally 90 degrees, but the enforced limit is actually the highest elevation that can be achieved given the source declination and the latitude of the telescope.
weighting_mode (string) – Enumeration of the weighting strategy used. (Required)
robustness (number) – Robust parameter. Only required and considered if the weighting is set to robust.
n_subbands (integer) – If this parameter is provided, the ‘subbands’ field in the response body will contain a sensitivity result for each sub-band, which is Transformed by dividing the bandwidth in N sub-bands. If the value is given as 1 then this is equal to the main sensitivity calculation so no ‘subbands’ are returned in the response. However, if the value is given as 1 and subband_freq_centres_mhz is also provided, then 1 ‘subbands’ will be returned in the response.
subband_freq_centres_mhz (array) – Central frequency of each sub-band in MHz. Providing sub-band frequencies enables the provision of additional weighting outputs.

Status Codes:

200 OK – Successful response with the results of the continuum sensitivity calculation, continuum weighting, spectral weighting and weighted sensitivity calculations.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation

POST /continuum/calculate

Returns the sensitivity, image weighting parameters and weighted sensitivity, where applicable, given an integration time and weighting mode. Unlike the GET version of this operation, every parameter - including the reference coordinate(s) - is supplied in the JSON request body rather than as query parameters, giving a clean URL with no query string. The response is always a JSON array: one result per item in reference_coordinates.

Status Codes:

200 OK – Successful response from the POST /continuum/calculate operation. Always a JSON array, with one result per reference_coordinates item supplied in the request, in the same order they were supplied.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation

GET /zoom/calculate

Calculates an integration time in seconds given a target sensitivity (or vice-versa) for the zoom mode. The result contains a spectral line calculation and weighting parameters (line spectral mode) for the given zoom window.

Query Parameters:

subarray_configuration (string) – Enumeration of the SKA LOW subarray configurations allowed for a zoom calculation. To define a custom configuration, set num_stations and do not set this parameter.
num_stations (number) – The number of LOW antenna stations. If set, subarray_configuration should not be set.
integration_time_h (number) – The integration time of the observation in hours
pointing_centre (string) – Pointing centre in HH:MM:SS[.ss] [+|-]DD:MM:SS[.ss] (Required)
freq_centres_mhz (array) – Array of the central frequency of each zoom windows in MHz. Combined with the total_bandwidths_khz, each must define a spectral window that is contained within the Low frequency range. (Required)
spectral_averaging_factor (number) – Factor by which the spectral resolution should be averaged to calculate the effective resolution which is used in the calculation. The maximum value is half the number of channels (total bandwidth / spectral resolution) in the zoom window with the fewest channels.
spectral_resolutions_hz (array) – Spectral resolution/channel width of each of the the zoom window. The channel width of the narrowest zoom window is given by (781250 * 32/27)/(4096 * 16) = 14.129 Hz (rounded to 3 d.p.). The only other validation prevents the spectral resolution from exceeding the bandwidth of the largest zoom window. (Required)
total_bandwidths_khz (array) – The total bandwidth of each of the zoom windows in kHz. Combined with the freq_centres_mhz, each must define a spectral window that is contained within the Low frequency range. The LOW correlator does not force zoom windows to have a fixed bandwidth: the value can be anything between 2 and 55296 channels at the given spectral resolution. (Required)
elevation_limit (number) – Lowest elevation that the LOW observation will be performed at. The maximum value is nominally 90 degrees, but the enforced limit is actually the highest elevation that can be achieved given the source declination and the latitude of the telescope.
weighting_mode (string) – Enumeration of the weighting strategy used. (Required)
robustness (number) – Robust parameter. Only required and considered if the weighting is set to robust.

Status Codes:

200 OK – Successful response with the results of the zoom sensitivity calculation, weighting calculations. Weighted results using these responses are also returned.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation

POST /zoom/calculate

Calculates an integration time in seconds given a target sensitivity (or vice-versa) for the zoom mode. The result contains a spectral line calculation and weighting parameters (line spectral mode) for the given zoom window. Unlike the GET version of this operation, every parameter - including the reference coordinate(s) - is supplied in the JSON request body rather than as query parameters, giving a clean URL with no query string, exactly like the continuum POST endpoint. reference_coordinates is the sole, required way to specify one or more targets, one result is returned per reference_coordinates item supplied, in the same order, and the response is always an array.

Status Codes:

200 OK – Successful response from POST /zoom/calculate - always an array, one element per reference_coordinates item supplied, in the same order, each in the same shape as ZoomSensitivitySuccess.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation

GET /pss/calculate

Calculate the sensitivity of an SKA LOW observation in PSS mode for the input parameters.

Query Parameters:

subarray_configuration (string) – Enumeration of the SKA LOW subarray configurations allowed for a PSS calculation. To define a custom configuration, set num_stations and do not set this parameter.
num_stations (number) – The number of LOW antenna stations. If set, subarray_configuration should not be set.
integration_time_h (number) – The integration time of the observation in hours
pointing_centre (string) – Pointing centre in HH:MM:SS[.ss] [+|-]DD:MM:SS[.ss]
elevation_limit (number) – Lowest elevation that the LOW observation will be performed at. The maximum value is nominally 90 degrees, but the enforced limit is actually the highest elevation that can be achieved given the source declination and the latitude of the telescope.
freq_centre_mhz (number) – Central frequency in MHz. Combined with the bandwidth_mhz, it must define a spectral window that is contained within the Low frequency range.
bandwidth_mhz (number) – Bandwidth in MHz. This parameter is ignored if pulsar_mode is folded_pulse. Combined with the freq_centre_mhz, it must define a spectral window that is contained within the Low frequency range.
dm (number) – Dispersion Measure in pc/cm^3
intrinsic_pulse_width (number) – Intrinsic pulse width in milliseconds. If pulsar_mode is folded pulse, this must be less than the pulse period.
pulse_period (number) – Pulse period in milliseconds. This parameter is ignored if pulsar_mode is single_pulse.
pulsar_mode (string) – Sensitivity calculation type. Must be one of folded_pulse or single_pulse. (Required)

Status Codes:

200 OK – Successful response with the results of the PSS sensitivity calculation.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.

GET /sefd/lookup

Returns the Stokes I SEFD values for a range of frequencies.

Query Parameters:

start_freq_mhz (number) – Start frequency in MHz (>= 49.609375) (Required)
stop_freq_mhz (number) – Stop frequency in MHz (<= 349.609375) (Required)
step_freq_mhz (number) – Frequency step in MHz (0.1 - 300) (Required)
num_stations (number) – The number of LOW antenna stations for SEFD lookup. Minimum is 1. (Required)
az (number) – Azimuth angle in degrees (0-360) (Required)
el (number) – Elevation angle in degrees (0-90) (Required)
start_lst (number) – Start local sidereal time (LST) in hours (0-24) (Required)
end_lst (number) – End local sidereal time (LST) in hours (0-24) (Required)

Status Codes:

200 OK – SEFD values for the given frequency range.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation

GET /aovert/lookup

Returns the A/T values for a range of frequencies.

Query Parameters:

start_freq_mhz (number) – Start frequency in MHz (>= 49.609375) (Required)
stop_freq_mhz (number) – Stop frequency in MHz (<= 349.609375) (Required)
step_freq_mhz (number) – Frequency step in MHz (0.1 - 300) (Required)
num_stations (number) – The number of LOW antenna stations for SEFD lookup. Minimum is 1. (Required)
az (number) – Azimuth angle in degrees (0-360) (Required)
el (number) – Elevation angle in degrees (0-90) (Required)
start_lst (number) – Start local sidereal time (LST) in hours (0-24) (Required)
end_lst (number) – End local sidereal time (LST) in hours (0-24) (Required)

Status Codes:

200 OK – A/T values for the given frequency range.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation