Designing programs in APT for Roman is different than using APT for HST or JWST. This article provides example workflows to implement some typical survey programs in Roman. APT users should be able to follow this guide to get started building their program.

Get the Astronomer's Proposal Tool (APT) Software 

APT is a standalone tool that can be used on Linux, macOS, and Windows systems. The software is regularly upgraded to stay up-to-date with HST, JWST, and Roman functionality; updates are described in the release notes. 

Download APT

Download and install the latest version of APT. Not all versions of APT will have Roman enabled automatically, and the version advertised on the main APT distribution website (apt.stsci.edu) may not have Roman features enabled. APT version 2024.2 is the most current release that has Roman features enabled.

What is the most recent APT version with Roman features enabled?

Having Trouble Accessing Roman features?

If you have issues, please contact the Roman Help Desk at STScI.

Load a Program

The first step is to ensure that you have the ability to edit Roman programs. If the features below are not accessible, see the Get the Astronomer's Proposal Tool section.

New Programs

A new proposal is created by selecting the New Roman Proposal option from the New Document pull-down menu at upper left of the APT window, just below the top tool bar. After selecting a Roman Proposal, the user will only see the Roman-related options in APT. 

More information can be found in the Astronomers Proposal Tool (APT) overview article.

Existing Programs

Existing programs can also be opened via the File menu for APT and this provides options to upload from a local directory or using the ID number to retrieve accepted programs from the Roman Science Operations Center at STScI. Once a program has started its observations, changes will be made by creating new Execution Plans. After loading a Roman Proposal, the user will only see the Roman-related options in APT. 

More information can be found in the Astronomers Proposal Tool (APT) overview article.

Define Targets 

The most optimal method to input targets depends on your survey design. Some surveys will have a modest number of targets, while others will have a large number of targets, and others will cover such large areas of sky that the traditional meaning of the term "target" for HST and JWST is not appropriate. The methods to enter the desired observing coordinates for these three scenarios are given below.

A Modest Number of Fixed Targets

Fixed Targets are defined by a single coordinate on the sky around which various observational setups can be attached, including mosaic and dither patterns that can be used cover the desired sky area. 

Learn how to input Fixed Targets. 

A Large Number of Fixed Targets

Long lists of targets can also be quickly uploaded with the Import Targets tool. The Target Importer Tool can read an input file prepared by the user and a GUI will help assign the input columns to the data that APT requires. Each input line in the file becomes a Fixed Target around which various observational setups can be attached, including mosaic and dither patterns that can be used cover the desired sky area. 

Learn how to use the Target Importer. 

A Large Area on the Sky 

Region Targets are a means of covering a large area on the sky without determining the coordinates of individual Fixed Targets by hand. The sky coordinates of a polygon are input into the Region Target Planner. The user can then input how they want to partition the overall region into smaller blocks and APT will then determine how to fill the sky region with the Segments required by the user The central coordinates of each Segment, effectively, operate as a Fixed Target around which various observational setups can be attached, including mosaic and dither patterns that can be used cover the segment area. The benefit of the Region Target is that the user is able to modify the size and shape of segments en masse and all other observational components are updated automatically. In terms of planning, a very large region is also broken down into units that can be scheduled to build large surveys effectively.

Learn how to define Region Targets. 

Verify Targets 

The Aladin viewer in APT can be used to examine the results of the various forms inputting Targets. Currently, APT can only verify the central coordinates of Fixed Targets – either input manually, imported from a file, or as Segments of a Region that were generated from the Region Planner Tool.

Set up Observation Sequences 

Most Roman programs will want more coverage than is provided by the footprint of the Wide Field Instrument and will need to use Region Targets, Mosaic Patterns, Dither Patterns, or a combination of these to provide full coverage of their desired sky area. Some of the options to cover the desired sky area are given below. 

Covering the Largest Areas

The largest areas that Roman surveys are capable of observing should be implemented as Region Targets. The Region Targets are broken into smaller units for scheduling called Segments using the Region Planner. Each Segment can then be covered by nesting a Mosaic Pattern and Dither Patterns. 

Learn how to define Region Targets. 

Cover a Large Area

Mosaic Patterns are a means of planning sky areas as large as 100 x 100 Tiles of the Wide Field Instrument. A Tile corresponds to the filled area of the Wide Field Instrument footprint which is approximately 0.7 deg by 0.4 deg (see the Tiles article). The largest allowed Mosaic Pattern approximately 70 deg by 40 deg and the smallest would be larger than what is feasible with the permitted Dither Patterns (note that Dithers can be executed for each Tile to fill gaps).
Mosaic Patterns are first defined by the number of Tiles on either axis of the Mosaic grid and then can be modified using overlaps and shifts. Individual Tiles in a Mosaic Pattern can be excluded to create more complex shapes to create the desired sky area. 

Learn how to define Mosaic Patterns.

Fill Gaps Between Detectors

Learn about Gap Fill patterns in Dither Patterns. 

Pass Plans

On the Pass Plans screen, the user will connect their targets inputs to their the observation sequences they designed and to other observation parameters to build Pass Plans. More specifically, the form editor will allow one to select Targets alongside Optical Elements, user-defined Mosaic Patterns, Dither Patterns, Subpixel Dither Patterns, Multi Accumulation Tables, and set Special Requirements. On the Pass Plans Form Editor, the number of visits will be shown and this is computed by APT for Roman using the selections.

Learn about observation parameters to select for Pass Plans.

Survey Plans

The Pass Plans  contain nearly all of elements necessary for the observation. The Survey Plan adds specificity to when and how a Pass Plan should be observed. At this part of the process, Special Requirements for orientation and timing can be specified for each Pass Plan or for repeats of the Pass Plan. Each line in the Survey Plan is a Pass and the Survey Plan is, thus, composed of this set of Passes. To build a specific scientific program, for example, a single Pass Plan can be entered multiple times to build a Survey Plan for time domain science using timing-related Special Requirements or for spectroscopic science using orientation-related Special Requirements. 

Learn about observation parameters to select to build the Survey Plan.

Determine if Observations can be Scheduled

The Visit Planner shows the visibility windows where the Pass Plans could be scheduled. The Visit Planner will use Special Requirements placed on the Survey Step to determine if observations can be scheduled based on the field visibility; this combines field orientation and timing constraints that are entered to order Pass Plans in the process of building a Survey Plan. APT will determine if these constraints can be accommodated given the visibility of the Fixed Target or Region.

Optimize your Program

Many of the steps outlined above will require iteration to obtain an optimized Program that meets the needs of a user's scientific goal. To be submitted, a Program must resolve any observations that cannot be scheduled in principle, which may require changing constraints entered as Special Requirements. 

Execution Plans 

Execution Plans are constructed for approved Programs and break the program into the individual units that are scheduled. If Programs require changes once some of its observations have begun, those changes will be implemented through modifications to the Passes and Segments in the Execution Plans. These options in APT are only available for Programs that have started their observations. 

Learn how to modify Execution Plans. 

Submission 

The last phase of building a Program in APT is the submission of the Program for the next steps in its process. This is different for Proposed Investigations and for Approved Investigations as described below. 

Submit Proposed Investigations

Proposed investigations will be submitted via the Roman Telescope Proposal System (RTPS) to the Science Support Center (SSC) at IPAC. For investigations requesting new observations, the file generated by APT will be submitted alongside other proposal requirements.

Learn more about Submission. 

Submit Approved Observations

Observations that have been approved can be submitted, and resubmitted when changes are required, to the Science Operations Center (SOC) at STScI through APT.

Learn more about Submission.