Transient Astronomy - Customizing Observing Strategies

For background, you should at least skim-read the paper Transient Astronomy with ACP Scheduler (PDF), as well as the RTML Programmer's Guide, which gives details on the meaning of the RTML tags, and finally RTML Mapping, which gives details on how RTML elements map to Scheduler observing requests. Constructing RTML templates is complex, however it offers considerable flexibility.

You have complete control over the observing request that is generated for each type of VOEvent that is passed by the filter for observing. As described in Customizing the Event Filter, the filter passes back the name of an RTML template to use for constructing the observing request for the event. The templates must be located in the Scheduler\ReceiverData folder (or a sub-folder). The standard templates are named XXXObsRequest.rtml, where XXX is the three letter code for the event type (SWF, INT, CAT, etc.). You can modify these as well as make your own and alter the filter to pass back the template name of your own template. If this is confusing, feel free to contact DC-3 Dreams, SP for help in understanding how all of this works.

Before trying to make your own template, have a look at the ones that come with Scheduler, in the ReceiverData folder. Try to understand what's going on with the RTML. Refer to RTML Mapping and the RTML Programmer's Guide (the schema diagram there is very useful).

iAn RTML tester is located in the ReceiverData folder. Drag and drop your RTML on to the TestRTML icon and you'll either get a report on the error or a message that it's OK.

Making Templates with ACP Planner

For all but the most advanced uses, you can use ACP Planner to make your RTML templates. Here's how:

  1. Make sure your preferences are set for the observatory, namely that the filter names are correct.
  2. In your preferences, select Disable Timing Features.
  3. Create a new target by right-clicking in the target list
  4. Set the Target Name to something meaningful, it will become the Observation name in the observing request. Note the Plan will be given a name by the receiver, so the <Request>/<ID> is replaced.
  5. Set the RA and Dec to 0, they will be replaced. If your system has a rotator, set the PA to 0. It is not replaced.
  6. Fill in the specs for the images you want and click Update (or use a preset).
  7. Save the plan as RTML. You'll see the Export RTML to Scheduler window.
  8. Make sure your name is in the Observer field.
  9. In the Project field, put ##PROJ##. Be careful, this must be exact!
  10. Optionally, you can add a Moon Avoidance constraint, but be aware that it may cause your Plan to fail if the target is "too close" to the Moon. But you may decide that it's not worth observing that close anyway, so this constraint may be useful.
  11. Optionally, set a minimum sky condition, for example if you don't want to bother in less than excellent skies.
  12. Save the RTML and rename is to XXXObsRequest.rtml, where XXX is the three letter code for the event type (SWF, INT, CAT, etc.), then put it into the scheduler's ReceiverData folder.

Advanced Technique - Multiple Targets

If you put multiple targets into the Planner, it will either produce RTML for multiple Plans with One Observation each (the most useful), or one Plan with multiple Observations. The selection of one Plan or multiple Plans is made in the Export RTML to Scheduler window. Note the receiver will replace the RA and Dec with the position of the object in the incoming VOEvent message, so this isn't really multiple targets. It can be useful, however, if you want to make a template with multiple Plans then hand-patch the generated RTML so that the Plans are run at different times by adding <TimeRange> elements with differential times.

Request Hierarchy

Each VOEvent results in a separate Project being created. The project name is the "target name" returned by the filter. This allows observing requests for the event to contain multiple Plans, each of which is scheduled separately, providing great flexibility.

Template Processing

The receiver creates observing requests from the specified template as follows:

  1. Read in the template and perform substitution for placeholders in the template
  2. Import the resulting RTML into the schedule database
  3. Fix up the created Plans/Observations/Images in the database as needed.

The third step is needed because there are some things that can't be expressed in RTML and some things that are more conveniently set after import.

Timing Specification Processing

If you include a <Schedule> section in the RTML, besides specifying constraints, you can give hints on timing of the observation or force the observations to be acquired immediately, or at a certain time delay after a Plan is started. Remember that multiple Plans can be specified by putting multiple <Requests>s in the RTML. Thus you can have, for example, one Plan that starts immediately, interrupting the dispatcher and killing all running plans, plus more plans that run normally with or without time hints. There is considerable flexibility in laying out your observing request(s) in the RTML template!

The <Schedule>/<TimeRange> Element

The <TimeRange> element, and its children <Earliest> and <Latest>, control timing hints and/or forced times. Normally, the date/times in this element are complete date-time strings (in XML/ISO format):

 <TimeRange>
     <Earliest>2009-03-16T04:23:00</Earliest>
     <Latest>2009-03-16T05:23:00</Latest>
 </TimeRange>

The problem with using these in a template is that the template is re-used over and over, at different times on different days.

Differential Time Specification

In order to make <TimeRange> useful in a templated environment, the VOEvent Receiver inspects the date/time strings and constructs the Earliest and Latest times for the scheduled request based on the current date/time. In order to activate this feature, the date/time string must specify date of 0001-01-01. If the VOEvent receiver sees this, it interprets the rest of the date/time as a differential time. It calculates the amount of time from 0001-01-01T00:00:00 to the given differential time, and adds that time interval to the current time to get the actual date/time for that field in the scheduler request.

To make this clearer, here is an example:

Current date time: 2009-03-16T04:23:32
<Earliest>: 0001-01-01T00:30:00
Actual Earliest time in request: 2009-03-16T04:53:32

The differential time in the RTML <Earliest> tag is 30 minutes, thus the Plan containing this <Earliest> will not start for at least 30 minutes after the VOEvent is received and the request is submitted. Note that you can specify Earliest and Latest differential times a day in the future to cause a Plan in your template to have a time restriction for the same times on the night after the event, etc.

Forcing a Plan to Run at a Given Time

In your RTML template, if you specify the exact same <Earliest> and <Latest> date/times, the RTML importer will turn on the Run At Time flag. This will force the Plan to be started at the given time. Combined with a differential time specification, you can force a Plan to start immediately or force it to start at some delta-time after the VOEvent. You can see this in the Swift template SWFObsRequest.rtml, which wants observing to start immediately:

 <TimeRange>
     <Earliest>0001-01-01T00:00:00</Earliest>  <!-- Special value: "immediately" -->
     <Latest>0001-01-01T00:00:00</Latest>      <!-- Special value: equal to Earliest -> Run Now! See Scheduler docs! -->
 </TimeRange>

Note that the standard filter script DefaultEventFilter.js also returns the "timecrit" flag, telling the receiver to interrupt the dispatcher. The net effect of all of this is to interrupt the dispatcher, kill all running Plans, and start the Swift follow up request immediately.

Specifying Constraints

If your follow up observations are not time-critical, and/or may extend over multiple nights, you can put some constraints into the Observations via the RTML <Request>/<Schedule> element. See RTML Mapping, Application of Constraints.

Pre-Import Substitutions

Before importing the RTML into the database, the following substitutions are made:

  1. ##PROJ## is replaced with the target name returned from the filter. This must be a unique name, so the filter must return a unique name for each accepted VOEvent!
  2. If the Scheduler is running under a single-user license, the <UserName> tag under <Request> is forced to be the Observer Name of the one allowed observer. This assures that the new Project is created for that one observer.

Post-Import Substitutions and Adjustments

Many of these things can be overridden in the template itself. For example, you might want different Contact info for different types of event observations. After importing, the receiver does the following:

  1. If the Project's Contact Name is empty, fill it in with the receiver configured Author Name.
  2. If the Project's Contact Email is empty, fill it in with the receiver configured Author Email.
  3. If the Project's Contact Organization is empty, fill it in with the receiver configured Author Organization.
  4. The Project's Description field is filled in with the event IVORN.
  5. If the Alerter is enabled, the Project's External ID field is set to "VOEvent". This causes the acquisition process to place images and logs into the special web-accessible area. See Alert Data Locations.
  6. For each Plan created by the RTML:
    1. The Plan name is set to the target name returned by the filter. If there is more than one Plan, an index number is added in parentheses.
    2. The Plan TimeStamp is set to the Date of the VOEvent.
    3. The Plan Description is set to show the time of observation in the VOEvent and other descriptive info.
    4. The Plan Earliest and Latest times are processed per Timing Specification Processing above.
  7. For each Observation in each Plan, the RA and Dec are set to the J2000 coordinates derived from the data in the VOEvent. This may involve conversion from local topocentric to J2000 depending on the type of coordinate in the VOEvent message.

At this point the Project is enabled to run, and if indicated the dispatcher is interrupted, allowing the new Project to come into contention. If the special "run now" values of Earliest and Latest were set, the receiver kills all running plans, guaranteeing that the time-critical VOEvent Project's Plan(s) will be immediately started.

Advanced Technique - Dynamic Template Generation

Sometimes, a static template just isn't good enough. You may want to alter the number of images, exposure intervals, and/or filter sequence based on the data in the incoming VOEvent message. Therefore, the VOEvent Receiver provides support for dynamic template creation. This is done in the event filter. The filter command line includes a named argument //rxdata which is the full path to the ReceiverData folder. This is the location into which the filter can write a dynamically created RTML template. After writing the template file into ReceiverData, the filter can return the name of the template to the receiver as usual, and the receiver will use the dynamic template to make the followup observing request.

ACP Scheduler includes an example of this for the User-Defined 1 (US1) event type. Look at DefaultEventFilter.js, where it handles the US1 events, and you'll see code that generates a template named US1ObsTemplate.rtml, then passes that name back to the receiver.

Copyright © 2005-2016 Robert B. Denny, Mesa, AZ