Use Case:  Search source calibrators.

Use case to find in the archive sources to be used for calibration purposes with the perspective of observations in interferometric mode. The archive is sollicated to retrieve a list of potential calibrators according to different criteria. These calibrators have already been observed with ALMA and a history of the measurements is provided. The source parameters can originate from any data-set in the ALMA archive. Area of searches are from a few to many square degrees depending on the calibration purpose. Statistics based on data existing in the archive are alos provided.

Goal: Retrieve from the archive a list of calibrators with their parameters.

Contact Author:   F.Viallefond

Priority: Critical

Performance:  Response to user inputs in near real time.

Frequency:  For each project, perform this for each frequency setting.

Preconditions: 

1. Database is running
2. User got authenticated
3. The coordinates of the position(s) of the main target(s) to be observed are known.
4. The sky frequency(ies) to be used is (are) known.
5. The targeted angular resolution (or antenna configuration) is known.
6. The typical anticipated weather conditions for the observation are known (day-night, season)

1. Set the maximum tolerable distance (in degrees) from the main target to search for amplitude calibrator candidates.
   
2. Set tolerable lower and upper limits in frequency about the sky frequency to be used to find the candidates.
   
3. Find the candidates (batch mode). If no sources found go to the alternate course.
   
4. For each candidate, using all the ALMA observations for these candidates, get:
   - the baseline length range (in meters and kilo-lambda), with an upper limits for the maximum baseline lenght if relevant, which can be used for calibration purpose.
   - a list of flux measurements and the corresponding frequency in ascending observing date. (if there is a large number of measurements, a graphic versus time could be generated, including when that is possible error barres).
   - if possible, the expected flux at the sky frequency based on the shape of the continuum spectrum.
   - the primary flux calibrator used in each case when these fluxes were derived.
   - the dates of observation for these candidates.
   
5. Select a small number (2 to 3) of a priori best candidates in that list (there is a trade-off between several parameters to perform this selection).
   
6. Retrieve the parameters with anticipated fluxes at the sky frequency(ies) to be observed.
   

1. Relax the level of tolerence for the maximum distance to target criterion and find the strongest sources with their ranges of LST to to be potentially observable (i.e. above a minimum elevation) within the Scheduling Block.
   
2. Search candidates.
   
3. For each candidate (eventually using all the ALMA observations for these candidates), get for each:
   - the maximum baselines length which can be used for calibration purpose.
   - a list of flux measurements and the corresponding frequency in ascending observing date. (if there is a large number of measurements, a graphic versus time could be generated, including when that is possible error barres).
   - the primary flux calibrator used in each case when these fluxes wer derived.
   
4. Select in this list the potential targets to be used as primary flux calibrators.
   
5. Retrieve the parameters for these primary calibrators.
   

1. Relax constraints on the maximum distance from the main target(s) but keep constraints that the calibrator must be observable above a critical elevation.
   
2. Relax criteria associated to the antenna configuration (histogram of baseline lengths).
3. Find the strongest observable sources at the sky-frequency to be used for the band-pass calibration.
   
4. Provide typical complex gain uncertainties already achieved using these sources for frequencies in proximity to the target frequencies (statistics from existing data, with weather conditions as those anticipated, in the archive).

1. Set a broad frequency window in the 3mm band.
   
2. Set a tight limit to the maximum distance to the main target.
   
3. Set a limit to which the atmospheric phase error are tolerable. The attribute for this setting may be rejected until it is in a domain of validity for the given typical anticipated weather conditions and the antenna configuration used.
   
4. Reset the antenna configuration as a criterion to be used for finding candidates.
   
5. Find a list of candidates for phase referencing allowing enough signal to noise.
   
6. Select in this list one or 2 sources to be used for phase referencing. (see alternate course in case no candidate found)
   
7. Retrieve the parameters for these phase reference calibrators.
   

Postconditions:

1. List of calibrators is set (a precondition for observations).
2. Parameters for these calibrators have been retrieved.

Issues to be Determined or Resolved:   Who has the responsability to provide the various trade-offs while doing the source selections?

Notes:   This Use Case was created by F. Viallefond.