Exporting as RTML for ACP Scheduler

ACP Planner can be used to generate input to ACP Scheduler, which requires observing requests in Robotic Telescope Markup Language (RTML) V2.3. You don't have to know anything about RTML itself because Planner generates it for you. The important thing to know is that you cannot tell Scheduler when to do an observation! It picks the time based on the constraints you specify for each observation. Where does that leave Planner, which is all about picking the best time to observe each target in your plan? Despite this apparent disconnect, we've provided tools in Planner to export your plans in RTML for scheduler input.

Since Scheduler doesn't need timing inputs, your plan is simply exported as a set of targets which become Observations in Scheduler. This can still be very useful, as Planner provides a more convenient way to get observing requests into Scheduler than the Schedule Browser. The timing in your plan can still be used, in an indirect way. Here's how it works:

When you capture a target from TheSky or Starry Night, Planner not only captures the time (which is not directly used) but also the altitude of your target at the time of capture. When exporting to Scheduler, the altitude becomes the minimum altitude constraint for that target's Observation. Thus, Scheduler will consider the Observation eligible any time your target is above that minimum elevation in the sky. Thus, the time of capture is used to determine the altitude of the target, and Scheduler is told that it can acquire images for that target any time it is above that altitude.

You can change the captured minimum altitude by right clicking on the target in the list and selecting Edit... In the Add/edit Target window, change the minimum altitude and click OK.

When you create a target in Planner by right-clicking and selecting Add New Target... the Add/Edit Target window will appear. Fill in your target type and other information, which includes the minimum altitude. The time is ignored for RTML exporting. Note that manual and deep sky target types are not supported for RTML exporting.

Constraints Created for Scheduler

Each target in your Planner plan will be turned into an Observation in Scheduler. The basis on which Scheduler decides whether an observation is eligible to run is its constraints. If you are unfamiliar with how Scheduler does its work, don't worry. Once you become familiar with how Scheduler works, it will make more sense to you.

As briefly described above (and in more detail below) RTML exporting creates a minimum altitude constraint for each of your targets. This translates into a scheduler Horizon constraint. In addition, two other constraints are created for all exported targets:

1. Moon Avoidance: This implements the Moon-Avoidance Lorentzian, which varies the avoidance distance from the Moon based on its phase. At full moon the target will need to be at its farthest from the Moon. As the brightness decreases (with phase), the Observation can be done closer. MoonAvoid takes two parameters: distance (degrees) and width (days). Observations will not be scheduled if the target is within distance/(1+(age/width)^2) of the moon. This means at full moon the avoidance will be distance, and width days before (or after) the avoidance will be one half distance. Planner's RTML export sets distance to 15 degrees and width to 6 days. You can adjust this in the Schedule Browser after importing the RTML.
2. Sky condition: This constrains the Observation to be taken at or better than the given sky condition. ACP Scheduler implements a simple 4-value sky condition (Excellent, Good, Fair, Poor). Planner's RTML export sets the sky condition to good. You can adjust this in the Schedule Browser after importing the RTML.

Exporting a Plan for Scheduler Input

Once you've completed your plan in Planner, you can export it to RTML for input to Scheduler. To do this, select File/Save As (as usual) but in the file-save window select RTML (.rtml) as the exported file type, then give your export file a name. After this, the Export RTML to Scheduler window appears.

1. Observer: Enter the name of the observer in the Scheduler to whom the observing request will belong. Depending on the type of scheduler license at the observatory:
   1. Multi-Observer license: If the observer name exists, the request will be assigned to that observer. Otherwise, a new observer with the given name will be created during RTML import and the request will be assigned to the newly created observer.
   2. Single-Observer license: The Observer name must be identical to the single observer name in the scheduler database. If not, the RTML import will fail.
2. Project: Enter the name for the Project under which the observing request will be entered. If the project does not exist, a new project with that name will be created during RTML import.
3. Plan Structure: You have two choices here:
   1. Separate plans: Each target in your Planner plan will be assigned a separate plan in Scheduler. This allows Scheduler to schedule each of your targets independently. This option gives scheduler the most flexibility. It also allows the minimum altitudes for your targets to be preserved. Just be aware that your Planner plan will not run as a unit, instead each target will be acquired at a time (and order) chosen by Scheduler, and this may be over a span of days or even weeks unless the schedule is lightly loaded. Use this option unless you have a very good reason to choose the other.
   2. Single plan: (caution) The targets in your Planner plan are assigned to a single Scheduler plan. Thus your entire Planner plan will run as a unit, with your targets being acquired in the order in which they appear in Planner. Use this option only with due care since your entire plan may require a large block of time, effectively preventing Scheduler from responding to higher priority plans that might be added after your (long-running) plan has been started. Also, it is easy to create an impossible-to-run plan. All of your targets must be above the (master) minimum altitude at their expected start time and throughout their acquisition cycle. If you aren't careful, Scheduler could decide that the entire set of targets and their constraints can never be met, and it will never get run. If you do select this option, your individual targets' minimum altitudes cannot be preserved. Instead you must assign a single master minimum altitude for the entire set of targets. Also, you must give a name for the master plan in Scheduler. Do not use this option except for short-running plans whose targets must be acquired together (for example, a supernova search mosaic with single short exposures for each mosaic frame).

Once you have completed the form, click OK to export. Notepad will appear with your RTML. Do not modify this unless you are brave. The RTML file is ready for importing into Scheduler, using the Schedule Browser. After importing into Scheduler, you can adjust the constraints of the Observations as needed. Most of the work will have been done for you.

Limitations

ACP Scheduler does not support observing requests for calibration (dark/bias) images. In addition, cooler and dome control commands are not supported as observing requests. Therefore, your plans cannot contain these things if exporting to RTML. If you accedentally include one, Planner will alert you and give you a chance to remove those items.