telescope.Scheduler - EranOfek/AstroPack GitHub Wiki

telescope.Scheduler

A class for telescope and observatory scheduling tools. The class enables managing observing lists including their selection and observation properties, tools to calculate visibility, select targets, and simulate observations.

This class uses variables in deg or days units.

Properties

Important properties

  • ListName - Optional list name.
  • JD - JD, this can be user-specified (see UseRealTime property). Return current time JD.
  • List - List of targets. This is an AstroCatalog that contains a table object. The table contains a long list of columns which are described in the columns list section.
  • UseRealTime - A logical indicating if to use real time. If false, then use user specified time, if the user did not updated the JD property, then JD will be empty.

Additional properies:

  • Defaults - Structure containing default columns value (see Columns list section).
  • MaxSunAlt - Max. Sun altitude. Default is -11.5 (use +90 to ignore Sun).
  • MinSunDist - Min. Sun angular distance for target visibility. Default is 30 deg.
  • CadenceMethodMap - Cadence method mapping. Currently only periodic is supported. Do not touch.
  • AltConstraints - A two-column matrix of [Az, Alt] constraints. Default is [0 15; 90 15; 180 15; 270 15; 360 15].
  • MountAltConstraints - An optional AltConstraints per mount. A structure array in which each element contains a 'Con' field with [Az, Alt].
  • MoonConstraints - Moon angular distance constraints. A two-column matrix of [Moon Illum. frac, Ang. Dist]. Default is [0 0; 0.1 1; 0.2 1; 0.3 1; 0.4 2; 0.5 3; 0.6 5;0.7 10;0.8 15; 0.9 30; 1.0 30].
  • GeoPos - Geodetic position of observatory [Lon, Lat, Height(m)]. Default is [35.041201 30.053014 415].
  • FileName - Optional file name.

Hidden properties

  • RA - Access and modify J2000 RA in the targets table.
  • Dec - Access and modify J2000 Dec in the targets table.
  • TotalExpTime - Total exposure time (Nexp*ExpTime) per target.

The following are populated by the popNightVisibility function:

  • NightVisibility - (FFU) A matrix of night visibility. Line per target. Column per time.
  • NightSunSet - SunSet.
  • NightSunRise - SunRise.
  • TimeRes - Time resolution for visibility calculations. Default is 5./1440.

Hidden, dependent properties (useful for target selection):

  • FieldName - FieldName in targets list.
  • LST - Current LST.
  • HA - Current HA of targets (use getHA to calculate HA for specific JD).
  • EclLon - Ecl. Lon. of targets.
  • EclLat - Ecl. Lat. of targets.
  • GalLon - Gal. Lon. of targets.
  • GalLat - Gal. Lon. of targets.
  • Az - Current Azimuth of targets.
  • Alt - Current Altitude of targets.
  • AirMass - Current Hardie airmass of targets.
  • ParAng - Current Parallactic Angle of targets.
  • GalExt - Galactic extinction [E(B-V)] of targets.
  • SunAz - Current Sun Az.
  • SunAlt - Current Sun Alt.
  • MoonAz - Current Moon Az.
  • MoonAlt - Current Moon Alt.
  • MoonPhase - Current Moon Phase.

Additional hidden properties

  • ColRA - Name of column containing J2000 RA. Default is 'RA'.
  • ColDec - Name of column containing J2000 Dec. Default is 'Dec'.
  • ColFieldName - Name of column containing FieldName Default is 'FieldName'.
  • ColKeep - Columns to keep when using loadTable merge and merge_replace options. See loadTable for details. Default is {'Priority','NightCounter','GlobalCounter','LastJD'}.

Columns list

The targets table contains by default the following columns. Some of the columns are optional, and additional columns may be added. Some of the columns are used for the cadence and priority calculations, which is described in the Cadence and prioritization section.

  • "FieldName" - Field Name string.
  • "RA" - J2000 RA [deg].
  • "Dec" - J2000 Dec [deg].
  • "MinAlt" - Min. Alt [deg]. Default is 15.
  • "MaxAlt" - Max. Alt [deg]. Default is 90+eps.
  • "MaxHA" - Max. abs value of HA [deg]. Default is 120.
  • "MountNum" - Mount number. If NaN, then MountNum is not used when assigning targets. Default is NaN.
  • "Nexp" - Number of exposures. Default is 20.
  • "ExpTime" - Exp. Time per exposure. Default is 20 [s].
  • "BasePriority" - Base priority. Minimum priority for the target. Default is 0.1.
  • "Priority" - Not used. FFU.
  • "NightCounter" - Counter specifying the number of times the target was observed, so far, during the night. Use the increaseCounter method to increase its value.
  • "MaxNightCounter" - Not used. Default is NaN.
  • "GlobalCounter" - Global counter specifying the total number of times the target was observed, so far. Use the increaseCounter method to increase its value.
  • "MaxCounter" - Max. number of times to observe the target. Default is Inf.
  • "LastJD" - JD of latest observation. Use the increaseCounter method to increase its value.
  • "CadenceMethod" - Not used.
  • "StartJD" - Min. JD to observe target. Default is 0.
  • "StopJD" - Max. JD to observe target. Default is Inf.

The cadence has two time scales. Long-cadence which is used to specify cadence over time scales larger than a day, and nightly cadence that is used to specify the cadence of multiple observations taken at the same night. The default cadence function has a Fermi-function shape. First it rises from BasePriority to WeightHigh/WeightLow, at time of Cadence/NightCadence after the last observations (LastJD). The function rises on time scale of CadenceRiseTime/NightCadenceRiseTime. Next, the function decays on time scale of WeightDecayTime/NightWeightDecayTime to the level of WeightLow/NightWeightLow.

Long-cadence parameters:

  • "Cadence" - Multi-night cadence [day] to observe the target. Default is 0.7.
  • "WeightHigh" - WeightHigh in Fermi-function weight. Default 1.1.
  • "WeightLow" - WeightLow in Fermi-function weight. Default 1.0.
  • "CadenceRiseTime" - The time scale on which the priority increase from BasePriority to WeightHigh. Default is 0.2.
  • "WeightDecayTime" - The time scale on which the priority decay from WeightHigh to WeightLow. Default is 10.

Nightly-cadence parameters:

  • "NightCadence" - Night cadence [day] to observe the target. Default is 1./24.
  • "NightWeightHigh" - WeightHigh in Fermi-function weight. Default 1.5.
  • "NightWeightLow" - WeightLow in Fermi-function weight. Default 1.4.
  • "NightCadenceRiseTime" - The time scale on which the priority increase from BasePriority to NightWeightHigh. Default is 0.005.
  • "NightWeightDecayTime" - The time scale on which the priority decay from NightWeightHigh to NightWeightLow. Default is -100.
  • "MaxNightN" - Max. number of times to observe the target per night. Default is 8.

Additional constraints:

  • "MinMoonDist" - Min. Moon angular distance. If -1, then use MoonConstraints property. Default is -1.
  • "MinVisibility" - Minumum time of visibility from first obseravtion of the night. I.e., the target need to be observable for at least this time. Default is 2./24.

For the first observation during the night, you can increase the priority above the calculated weight if the target is in the HA range of MinHA1 and MaxHA1. This allow the user to maximize the obsevations of minimum airmass targets.

  • "ExtraPriorityHA" - Default is 0.2.
  • "MinHA1" - Default is -2./24.
  • "MaxHA1" - Default is -1./24.

Methods

Important high level methods

Generate target lists, load and save:

  • generateRegularGrid - Generate a regular grid of targets using tile_the_sky.
  • loadTable - Read file (mat, csv) or data, and merge it into an existing telescope.Scheduler object.
  • populateMountAltConstraints - populate MountAltConstraints.
  • save - save the Targets object as a MAT file.

Running LAST scheduler demon:

  • demon - (Static method) Execute scheduler in listening mode. This method executes the telescope.Scheduler in an infinite loop. In each loop, check if a new ToO file exists, and if so load it. Look for new target for mount and send it to mount. The communication with mounts is done using a user provided functions.

  • Visibility:

  • isVisible - Check if targets are visible given all their specified criteria

  • leftVisibilityTime - Left visibility time for all targets

Target selecttion:

  • increaseCounter - Increase Global/Night counters for target
  • initNightCounter - Set NightCounter to 0 for all targets
  • getTarget - Get properties of selected targets by index or target name
  • selectTarget - Select best target for observation

Targets search:

  • searchFieldName - Search target list by FieldName (exact or substring).
  • coneSearch - Search indices of targets in list by coordinates
  • cooInField - Search for fields that contain a list of coordinates
  • fieldsCoverHealpix - Given a list of healpix pixels, return the indices of target fields that contains the healpix pixels.

Visibility plots

  • dailyObservability - Daily observability plot for target
  • yearlyObservability - Yearly observability plot for target
  • plot - plot a sky map with fields position in Aitoff projection.

Simulations:

  • simulate - Simulate scheduler and target selection.

Check Status:

  • sunAlt - Return Sun geometric Alt and Az [no refraction] (Static)
  • earthShadow - Calculate the J2000.0 equatorial coordinates of the Earth shadow at a given height

Additional (mostly internal) methods

  • injectDefaultColumns - Inject or replace the column in List with the default values.
  • serviceTargetRequests - Treat target requests posted (currently, only via the redis Mailbox)
  • unitsAskingTargets - poll the Mailbox (here the Redis cache on localhost by default), and return the number of the units which have aske for a target, together with the JD of their request. The results are sorted from oldest to newest
  • dispatchTargetToUnit - Aux fun.
  • radec2deg - (Static) convert RA,Dec to deg.
  • getHA - (Static) Calculate Hour Angle.
  • read2table - (Static) Read file (mat, csv) or data into a table object
  • popNightVisibility - Populate the NightVisibility matrix indicating the visibility of each source as a function of time from SunSet to SunRise
  • nextSunHorizon - look for next Sun horizon crossing (including refraction)

Constraints related functions

  • checkAltConstraints - Check Alt of targets agains the AltConstraints property.
  • checkMoonConstraints - Check Moon distance of targets against the MoonConstraints property (distance/illumination).
  • applyColumnConstraints - Apply for each column in List, its appropriate constraints
  • timeSinceSunSet - Time (days) since last Sunset.
  • isNewNight - Check if new night

Weight-related functions:

  • weight - Calculate priority weight (without visibility) for periodic cadence
  • fermiExpWeight - Fermi-rise exp-decay weight function for cadence priority

Aux:

  • radec2name - given RA/Dec [deg] generate names in cell array %03d+%02d

Examples

Running LAST pipeline

To run the LAST pipeline you need to execute on last0. This is done automatically, so under normal circumstances you are not suppose to execute this command:

telescope.Scheduler.demon;

In order to inject a ToO, create a ToO file an put it in: last0:/home/ocs/Scheduler/

Use the ToO template file.

Looking for a target

Looking for target by name:

Ind=S.searchFieldName(1000)
Ind=S.searchFieldName('1000') 
Ind=S.searchFieldName('1000','Exact',true)

Looking for target by coordinates

Ind=S.coneSearch(100,-20,1e4)
Ind=S.coneSearch('10:10:10','-20:10:30',1e4)

Looking fir field IDs that covers a specific coordinate:

find(S.cooInField(352.59,1.88))

Looking for field IDs that cover specific healpix pixels:

F=find(S.fieldsCoverHealpix(2.^16,[100;101;200]))

How to schedule a target: Regular cadence observations

To change the default cadence property of a target, first load the targets table mat file

S = telescope.Scheduler;
S.loadTable('TargetList.mat');

Now you can edit the list. First, identify the target index you are interested in (using e.g., coneSearch, or searchFiledName). Next, change the parameters of interests. For example, to increase the BasePriority:

Ind = S.searchFieldName(1000);
S.List.Catalog.BasePriority(Ind) = 0.3;

To change the minimum visibility at the time of first observation: Next, change the parameters of interests. For example, to increase the BasePriority:

Ind = S.searchFieldName(1000);
S.List.Catalog.MinVisibility(Ind) = 1./24;

etc.

After done save the modified target list:

S.save('TargetList.mat');

How to schedule a target: Critical time observations

To schedule a critical time observations:

  1. Create your target or use the existing target:
  2. Set the StartJD and StopJD to be in the needed JD range.
  3. If needed, change other parameters like the cadence parameters and BasePriority.

Simulate observations

Given the target list you can simulate observations using:

TS=S.simulate;

Targets visibility

Given a target in the target list. First look for the target index.

Ind=S.searchFieldName(1000)

Plot nightly visibility for today:

S.dailyObservability(1000)

Plot nightly visibility for user-defined date:

S.dailyObservability(1000,[1 1 2000])

The output is something like this:

Plot yearly observability:

S.yearlyObservability(1000)

The output is something like this: