First you should set up a directory to use just for your proposal. This directory will be used both as the input and output directory for RPS2. Note that RPS2 generates a large number of intermediate files. (The amount of room you will need in this directory depends on the size of your proposal, but only very large proposals will require more that one megabyte for these intermediate files.)
Start RPS2 by typing the following at the Unix prompt:
For example, if RPS2 was installed in directory /user/local/bin/rps2, you would type:
At first you will see the servers start (as described in See Bring the servers up and down ) and then a small graphical window will appear on your screen. This window has buttons along the top row that invoke the tools and options for RPS2. Simply place the mouse pointer on top of a button to see a short explanation of its function.
The first step is to write at least a partial draft of your Phase II proposal. General Observers (GOs) will start with a template which has been supplied by their Program Coordinator. This template has most of the text sections already filled in from their original Phase I proposal. The rest of the template is a single visit and single exposure skeleton with all the keywords and special requirements available.
If you have been given a partially completed template by your PC, save the template (without any mail header) to a file named <#> .prop where <#> is the proposal ID number that was supplied by your PC.
If you do not have a partially completed template, you can obtain a completely blank template by clicking on the "File..." button at the top of the RPS2 window and selecting the "Create New File" option.
The next step is to choose an editor. RPS2's proposal editor (PED) is a graphical proposal writing tool with menus of options and as-you-go syntax checking. The first-time HST user will find this tool to be helpful in preparing a syntactically correct first draft of the proposal. For more information on PED, see See Writing Your Proposal: How to use the Proposal Editor (PED) You can also use the regular text editors available on your system.
The appropriate instrument handbooks provide the guidelines for instrument use, and the Phase II Proposal Instructions (Version 8.0G) provides the proper syntax to write a proposal. Before writing the entire proposal, you may wish to try out a small subset of the proposal (i.e., one visit with a few exposures) to become accustomed to proposal writing and get immediate feedback from the RPS2 system.
You are encouraged to contact your PC at any time with questions about writing your proposal.
Once a draft of the proposal (or partial draft) has been written, RPS2 can be used to check for syntax problems, evaluate potential implementation problems, and determine schedulability. If you haven't already done so, choose the "Select Existing File" option from the "File..." button at the top of the window and use the resulting dialog box to select your proposal from your proposal directory. Then click on "Process." In a few seconds, a progress meter will appear appended to the bottom of the existing RPS2 window. This will indicate about how far along the processing is. A proposal with one target and one visit will generally take about 10 minutes to process fully the first time. (If you find RPS2 runs too slowly, refer to the list of tips in See How can I make RPS2 run faster? )
Processing a proposal will put many small files in your working directory. In general, you should not delete these files as they store the intermediate results and final output. Many of the files are recalculated each time you process, but if you need to view the current output again later, you can do so without reprocessing the proposal. Note that there is a target file created by the Schedulability subsystem which is created on the first run and reused in subsequent runs (the file is simply updated as you change targets in the proposal). If you delete all the files (or move the proposal to a new directory) that target file will need to be recreated (which takes time).
When processing is complete, a new screen will automatically appear called "RPS2 Description Generator", which is a separate interface used to display the processing results. This interface also has the options displayed at the top. A short explanation of each option appears just below the top row if the cursor is placed over each button. Note that the main progress meter on the RPS2 User Interface remains at the step "Creating Visit Analysis Reports" until you use the Description Generator. Once you click on something in the display, the progress meter will say "Activating Description Generator Buttons". The option to have the Description Generator come up automatically after processing can be turned off by clicking off the red button next to the words "Display Output" on the main panel of RPS2.
If you need to process many proposals in batch, this can be done using the command line version of RPS2 and a shell script. Contact your PC if you need help. Here is an example shell script:
Some proposals will be large enough that they will take a long time to process through all the subsystems. If a proposal has started processing and you wish to stop it (e.g., you forgot to change something), the processing can be halted. Click on "Halt" beside the progress meter for the process you would like to stop. This aborts all subsequent processing on that proposal. If you are processing and/or displaying multiple proposals and would like to stop everything, use the "Halt All" button at the top of the User Interface. (If the progress meter fails to go away completely after performing these steps, there probably has been a communications error. Quit RPS2 and start over again.)
The descriptive and diagnostic information generated during RPS2 processing is summarized into two types of graphical reports. The first is the Proposal Summary Report, and the other is the Visit Analysis Report. Reports are created automatically after processing (if desired) or by clicking on "Display Output" at the top of the window. The resulting interface will only display the output of a single proposal.
Each section of a report has a help window which is brought up by clicking on the "HELP" button to the right of the section. Click on "Dismiss" at the bottom of the small window when you are finished reading the help message. If the font of the report is too small, click on "Zoom+" at the top of the window to increase the font size. The report can also be made smaller by clicking on "Zoom-." If the initial display of the Structure section of the Visit Analysis report is hard to read because it is crowded with lots of labels and arrows, use the "More/Less Arrows" button at the top of the window to toggle on the fewer arrows option. This should only be needed when many exposures are done in rapid succession. (Zoom is a configurable options. See See Change default aspects of the display for more details.)
Select this report by clicking on "Proposal Summary" at the top of the Description Generator window. This report lists much of the general proposal level information as well as high level information about all the visits in a proposal along with their target(s), science instrument(s) used, number of HST orbits used, and whether there are outstanding diagnostics. Next is a list of proposal-level diagnostics (which affect the whole proposal, not an individual visit). At the bottom of the report is a graphical summary of each visit's schedulability (identical to the ones that appear at the bottom of each Visit Analysis Report).
There is one report for each visit in the proposal. Select a particular visit's report by clicking on "Visit Analysis" at the top of the window, and pulling down to the visit of interest. (The "Visit+" and "Visit-" buttons at the top of the window can be used to go through the visits in numerical order.) Each visit report is composed of several sections:
The visit section lists the number of orbits used, science instruments, visit-level special requirements, visit-level comments, and whether there are any diagnostics.
This section is a summary of all outstanding diagnostics in the visit. They are broken down into Syntax, Feasibility, and Schedulability. These messages are generally short; longer, more detailed explanations are available by clicking on the message of interest. A small window will appear on the screen with both the short and long explanations. Click on "Dismiss" at the bottom of the small window when you are finished reading the message.
It should be noted that output from Feasibility and Schedulability depend on correct proposal syntax. It is therefore a good idea to try to resolve Syntax problems before considering the stated Feasibility and Schedulability problems.
The exposures section is a listing of the exposures given for the visit. In addition to reflecting what was specified in the proposal, this section also indicates the allocation of exposures to orbits and whether any exposures have been lengthened or shortened by RPS2 in order to use orbits more efficiently.
To save space on the display, the target for each exposure is referred to only by its number in the target list. If you have more than one target in the target list for that visit, you should check to make sure you are observing the right target in each exposure.
This section is generated by the Feasibility subsystem. The structure section is a graphical representation of the exposure section, complete with helpful comments. A key to the color and hatching scheme is available by clicking on the "HELP" button to the right. In this section, each orbit is represented by a 96-minute orbital timeline, and the major events of the orbit are noted separately (e.g., guide star acquisition, target acquisition, exposures, unused target visibility, and occultation). Note that each exposure is shown with all associated overhead included. The actual on-target exposure time is displayed in brackets next to the total time.
This section assists the user in deciding how to design the visit to fit into the number of orbits allocated. There are exposure-level special requirements which allow you to specify which exposures can be lengthened or shortened and by how much.
If you are iterating on how to best fill your orbits, you should probably turn off the Schedulability subsystem to save processing time.
This section is generated by the Schedulability subsystem. The scheduling section contains a timeline of when the visit could be scheduled. All constraints which were calculated are indicated at the top of this section. They are divided into three categories: physical constraints (e.g., Sun, Moon), absolute constraints due to special requirements, and relative constraints due to special requirements.
All user-imposed constraints are plotted, but only those physical constraints which actually affect scheduling are plotted. For example, if the target is within 50 degrees of the Sun at some point during the year, the Sun constraint graph will appear and will have a dashed line during the time that the target is too close to the Sun for observation with HST. If the target is never within 50 degrees of the Sun, no Sun constraint graph will appear.
The resulting Total Scheduling Windows which are the intersection of the individual constraint plots, are plotted at the bottom. You can click on the name next to each constraint time line to see a report which contains all the schedulable date spans.
Hard copy versions of the reports are available as PostScript files. Click on "Write PS Files" at the top of the RPS2 User Interface window. This will create the Proposal Summary Report as well as Visit Analysis Reports for all the visits. If any of the reports contain diagnostics, a separate file for each report containing the long explanation of each diagnostic will be generated. All the files have the extension .ps . A file named help.ps is also generated which contains all the help panels concatenated together. You can then print these files to a local PostScript printer.
Changes can be made to the proposal while still in RPS2. Clicking on "Edit" at the top of the window will bring up an editing session on the proposal. If you choose the proposal editor (PED) to be your editor, the proposal will be loaded into PED and initial syntax checking will be performed automatically. Otherwise the editor will be the one indicated in your EDITOR environment variable. If your EDITOR environment variable has not been set, the internal RPS2 text editor will be used. When editing is complete, just save the file and you can reprocess the proposal. You need not quit the editor.
The following unix command will set the EDITOR environment variable on most unix systems:
You may wish to add this to your shell setup file (for example in the C shell, place this command in your .cshrc file). If you are unsure of the editors available on your system or where they are located, talk to your system manager.
If you would like to save a copy of the current version of a proposal before making changes, you can do this from the "Backup..." option available from the "File..." menu. When you click on "Backup..." you will be given a sub menu with the options: "Backup Current Version," "Restore Backup Version," and "Remove Backup." All options prompt you for a name for your backup. This name can be any alphanumeric text string (including periods, dashes and underscores) but should not include characters that would be unacceptable in a file name (such as blanks or slashes).
The advantage of using this method for backing up your work, is that all the cached files and other output files that have been created so far are archived with the proposal. This will save processing time when you restore the backup. You also have all the cached files and output files in your current working directory so incremental changes will take less time. Avoid creating new directories or proposals numbers to try new things - this will cause unnecessary reprocessing and slow your work.
Each proposal that you work on with RPS2 has a history file. This file is maintained across different RPS2 sessions and contains time and date stamps. To view the history file, select the "History..." option from the "File..." menu. The two choices are "View History" and "Add To History." "View History" will bring up a screen with the most recent activity listed at the top. This screen can be left up if desired and will update as new steps are done. "Add To History" will allow you to add a line of free text to the log to help you keep track of when something happened.
When RPS2 detects a system error, it displays a window to the screen. The text in the box should be self-explanatory. For example if you click on the "Submit" option, but have not first "Select"ed a proposal, you will get a small window which says "No Proposal Selected." Click on "Dismiss" at the bottom of the small window when you are finished reading the error message.
Less straightforward error conditions may yield system messages that are hard to understand. If you encounter an cryptic error message, contact your Program Coordinator; be sure to include the text of the error message in your message to the PC. This is easy to do since each session of RPS2 keeps a log of all system errors. The rps2-error file can be found in the directory RPS2 was started in, and can be copied directly into an e-mail message. Along with the error message, please include the version of the proposal that had the problem and the history of your session (this is stored in the file ####.log ).
RPS2 has quite a bit of built-in, on-line help:
A short description of each main option at the top of the interface is displayed just below the row of buttons when the cursor is place over the button.
The "Help" button will bring up a World Wide Web client (such as Netscape) in order to display the RPS2 Help Page. This page contains the RPS2 User's Manual as well as an up-to-date advisories list of known RPS2 problems and suggested workarounds.
The Description Generator has help buttons throughout the report which describe each section of the report.
Command line users (as well as any user who prefers to view their output in PostScript form) can print out the file help.ps in order to have a hard copy of all the Description Generator section help panels.
If the RPS2 User's Manual and the various help facilities are not sufficient for resolving any problems running RPS2 or understanding the output, contact your Program Coordinator.
The default World Wide Web client which the RPS2 "Help" button invokes can be set. Simply type:
at the Unix prompt before running RPS2. You may wish to add this to your shell setup file (for example in the C shell, place this command in your .cshrc file).
There are several aspects of RPS2 for which you can change the default configurations. When you choose an option it goes into effect right away. When you "Quit" RPS2, these defaults are saved to a file in your home directory named .rps2-init . The next time you bring up RPS2 those options will still be in effect. Many of the options have to do with the subsystem servers. If you need to know more about the client/server nature of RPS2, refer to See RPS2: A client-server system
Selecting which subsystems to run when you click on "Process" is such an important function that the switches appear on the front panel of the RPS2 User Interface instead of in the Configure menu. They look like this:
When you bring up RPS2 for the first time, all three selectable subsystems will be selected (the button in front of them will be green). Click on the green button to turn off the selection of a subsystem.
Most observers encounter syntax problems during the initial processing of their proposals. During this early stage, you should run only the Syntax subsystem function to save time. In order to perform just Syntax checking, turn off the Feasibility and Schedulability subsystems.
Syntax checking is required before Feasibility and Schedulability; it cannot be turned off. It is possible, however, to turn off Feasibility or Schedulability. For more information on the interdependencies of these subsystems, refer to See The components of RPS2 Note that Feasibility cannot be turned off if Schedulability is on. This prevents a user from trying to run Schedulability before Feasibility has been run on a visit. Feasibility will be run on only those visits that have changed, even if the button is on (green).
The third selectable item is Display Output. This runs the subsystem which compiles the raw output from the other subsystems into the on-screen reports. Most people want to review the output immediately after processing, but if you prefer to wait (or use the "Write PS Files" option instead) you can turn off the Display Output button.
If you cannot run some (or all) of the servers on your own computer and servers exist on a computer which is more convenient to you than the one at STScI, a preference for this computer can be specified using the "Configure Routing" option from the "Configure" menu. Click on the word "Machine," type in the Internet Protocol (IP) address or IP name (e.g., 130.167.107.14 or anarky.stsci.edu) of the computer desired, and click on "Apply."
When RPS2 comes up, it will by default attempt to start all the servers in your installed configuration. If they are already up from a previous session, RPS2 will detect this and will not attempt to start new ones. This behavior can be changed using the "Configure Servers" option from the "Configure" menu. The five servers of RPS2 are listed, and each one can be configured not to start when RPS2 is started. You can also stop and restart the servers in real time from this menu. This can be useful if you want to experiment with which servers you want to run locally and which you want to run at STScI through the Internet. (Note, however that it takes approximately 5 minutes for the operating system to clear the server connection. So if you bring the servers down and try to bring them back up immediately, they will not come up because they already appear to be running.)
When you first bring up RPS2 and click the "Edit" button, you are asked to select a default editor (text editor or PED). You can change the default editor later by selecting the "Configure Editor" option from the "Configure" menu.
In order to set the default font size for reports created by the Description Generator, select the "Configure Description_Generator" option from the "Configure" menu. Next to the word "zoom" enter an integer between 0 and 2 (0 for 10 point, 1 for 14 point - the default, and 2 for 18 point). After you have entered 0, 1, or 2, click on "Apply."
By default RPS2 will only process the visits in a proposal that have changed since the last time it was processed. Additionally RPS2 will only run the subsystems that have not been run yet on a version of the proposal. (So if you run syntax checking and then decide to finish processing, the syntax checking step will not run the second time.) There are no known problems with these time saving features, but as a safety measure, there is a way to turn this off. Select the "Configure Processing" option from the "Configure" menu and click on "Entire Proposal." Then click on "Apply" to commit the change.
Once you have written your Phase II proposal, processed it using RPS2, examined the output products -- confirming that there are no errors and you are within your orbit allocation -- and are confident that the proposal will obtain the data you need, it is time to submit your proposal. Completed Phase II proposals should be submitted to STScI using the "Submit" option of RPS2. There is a button on this panel that you can click on if you would like to include feedback or comments with your submission.
It is important that you first "Select" the proposal file that you wish to submit and that the proposal file ( <#>.prop ) uses your assigned proposal ID number.
The diagnostic files in the proposal directory from the most recent processing of the proposal will be checked before the submission is made. If there are outstanding diagnostics, a red warning message will appear to remind you that there are still problems with the proposal. If there is a bug or limitation in RPS2 that makes it impossible for you to submit the proposal without diagnostics, you must discuss this problem with your Program Coordinator before the proposal is submitted. If the problem cannot be resolved, the proposal can be submitted, but it will be flagged as having problems and your PC will tell you how to proceed.
If you submit a proposal with errors that have not been reviewed with your PC, it will no t be accepted for processing and scheduling until these errors have been discussed with the PC.
The submission software returns an automatic electronic acknowledgment to you via e-mail that your proposal has been received. Both your Program Coordinator and your Contact Scientist will be notified of your submission, and you should receive a message from your PC regarding the acceptance of your proposal in a few days.