Tutorial on Creating Solar System Observations in APT

A walk-through on how to create a Solar System observation in the JWST Astronomer's Proposal Tool (APT) is presented in this article.

On this page

See also: JWST Astronomers Proposal Tool Overview

In this article, we walk through an example for creating new Solar System observations in the JWST Astronomer's Proposal Tool (APT). This is a very basic example; the article Solar System Special Requirements describes in greater detail the options for constraining moving target observations.

To learn how to download APT and start a JWST proposal, see Moving Target APT Instructions. Before this tutorial you may want to read Tutorial on Creating Solar System Targets in APT, and after, Tutorial on Visualizing Dithers of a Solar System Observation in APT. If you have questions please contact the help desk

Getting started creating a Solar System observation

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

You must first create targets before creating observations.

The workflow for creating an observation is:

  • Pick a target

  • Pick an instrument (MIRI, NIRCam, NIRISS, NIRSpec)

  • Pick a science template (Imaging, IFU Spectroscopy, etc.)

Moving targets can be observed with any instrument and any observing template, but some observing modes are better suited for moving target observations than others.

To create observations for your targets, click on the Observations folder and then on the New Observation Folder button. An empty Observation Folder will be created in the left sidebar, containing an empty Observation 1. Inside Observation 1 is a blank form where you can select the target, instrument, template, etc.

The article APT Observations describes APT observations more generally and JWST APT Observation Templates describes the available instrument templates. An example for setting up a NIRCam Imaging observation is provided below; other modes, of course, have their own unique parameters.

A NIRCam imaging example

To create a NIRCam imaging observation, select NIRCAM from the Instrument drop-down choices, NIRCam Imaging from the Template drop-down choices, and one of the previously defined targets from the Target drop-down choices. After you have selected the template, a new form will appear at the bottom, where you can define the template's parameters such as the subarray, dither pattern, and filters. Notice how the estimated time in the Duration box changes as you tweak the parameters.

Figure 1. Selecting the observing template

Click on the figure for a larger view.

In the other tabs on the template form you can, for example, modify observation constraints such as timing and position angle under Special Requirements. These can differ between observing templates; more general information can be found in APT Special Requirements.

Keep in mind that defining constraints depends on the circumstances of your observation. Using either the Special Requirements (Figure 2) or Solar System Target Window (Figure 3) tabs can significantly restrict the scheduling period for the observation, and may incur a Direct Scheduling Overhead. Note that if you were to create a constraint requiring that the observation be made in a window of less than 1 hour (to observe a particular longitude on an object, for example), your program will be charged an additional overhead. See Moving Target Overheads and Time Constrained Observations for additional information.

Figure 2. Special Requirements

Click on the figure for a larger view.

Figure 3. Solar System Target Windows

Click on the figure for a larger view.

Let's add a solar phase constraint. In the Solar System Target Windows tab click on the Add Observing Window button and select New Solar Phase Observing Window from the drop-down choices.

Figure 4. Adding a Solar System Target Window

Click on the figure for a larger view.

You will get a pop-up window as shown in Figure 5. For Object, select from a list of any of your defined targets or solar system standard target, and likewise from the Observer drop-down choices.
Figure 5. Adding a Solar Phase Observing Window

Click on the figure for a larger view.

Solar System Target Windows

The Solar System Special Requirements article has a full list of available Solar System target windows, with descriptions. A few notes about specific ones are provided below.

  • Separation of ... vs. Distance ... special requirements:
    The Separation of <object1> <object2> from <observer> <condition> <angle> observing window allows you to define the separation between 2 objects in angular units. The DISTANCE <object1> <object2> <condition> <distance> observing window allows you to specify that an observation should occur at a particular separation between 2 objects in distance units (AU). There are no specific target windows for defining a heliocentric or observer-centric distance; either can be specified using the Distance observing window and choosing the appropriate object (SUN or JWST) for <object 2>.

  • Central Meridian Longitude of ... special requirement:
    This observing window allows the user to specify a longitude on a rotating Solar System object. This is similar to the Phase constraint available under the Special Requirements tab, except that the Central Meridian Longitude observing window only applies to a handful of standard targets: Mars, Jupiter, Saturn, Uranus, Neptune, Io, Europa, Ganymede, Callisto, Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Iapetus, Ariel, Umbriel, Titania, Oberon, Miranda, Triton, Pluto, and Charon. Specifying a Central Meridian Longitude constraint on an object not in this list will result in a warning when running the Visit Planner. Rotational constraints for other objects not in this list should be specified instead with the Phase constraint.

    The Phase Special Requirement and Central Meridian Longitude Solar System Window can be used interchangeably for any targets with defined coordinate systems. However, keep in mind that the entire observation must occur within the window specified by a Central Meridian Longitude constraint, whereas the Phase constraint only specifies when the observation should begin. In other words, the schedulability window for the start time of an observation with a Central Meridian Longitude constraint will be reduced by the length of the observation; if the observation is longer than the specified window, it will not be schedulable. The Phase constraint thus increases schedulability, but there is a possibility that the observations will not actually occur between the desired rotational phases.

  • Transit of ... vs. Occultation of ... special requirements:
    A transit begins when the entire disk of the transiting body is in front of the transited body and ends when the limb of the transiting body first crosses over the limb of the transited body. In other words, the transit duration covers only the time when the entire disk of the transiting body is on the disk of the transited body. An occultation begins when the limb of the transiting body first touches the limb of the transited body and ends when the two bodies are no longer in contact. The duration of an occultation is therefore always longer than the duration of a transit.

  • Eclipse ... special requirement:
    An eclipse begins when the limb of the eclipsed sphere first touches the umbra or penumbra (depending on which is specified) and ends when the limb of the eclipsed sphere touches the umbra or penumbra for the last time. In other words, the eclipse duration covers the entire time that any part of the eclipsed sphere is in the shadow.

You should be aware that drop-down choices for choosing Solar System objects, available in a few of the Solar System Target Windows, will list targets you defined in the APT file first, followed by standard targets, satellites of standard targets, and JWST at the bottom. (There is a second instance of JWST between the standard targets and their satellites, and either can be used.)


Download the Astronomer's Proposal Tool

Notable updates
    Wording changes.
Originally published