This document describes how to:
There are three ways to obtain the latest development version of APT:
1. Use the nightly developers' build that's installed on the Science network.
The nightly developers' build can be run on the Science network with:
/usr/local/APT/nightly-develop-build/APT_Installation/runAPT
2. Install your own copy of the night developer's build.
The nightly developers' build can be installed from this link.
3. Checkout the code and build your own APT run-time.
(One major drawback to using this option is that there is currently no good way to specify APT command line options when running from your own APT run-time. Hopefully this will be addressed soon.)
APT's source code is stored in CVS. The CVSROOT for APT development on the science net is /usr/ra/cvsroot. If you have rsh access to the science net from a non-science net computer, then use CVSROOT :ext:ra.stsci.edu:/usr/ra/cvsroot from that computer.
Using the above mentioned CVSROOT, checkout the module APT to get the APT source code. In general, you won't need to commit anything from these checked-out APT's, but if you do, please accompany the commit with a brief e-mail to apt-developer.
Sample checkout from science net computer:
cd $mydir
cvs -d /usr/ra/cvsroot co APTThat creates the directory $mydir/APT. If the module APT had been checked out, $mydir/APT would've been created. From now on, I'll refer to $mydir/APT as $APT.
Before running APT, the source code must be compiled, with the resulting .class files being bundled into .jar files. APT builds use 'ant' which is installed on the Science network (/usr/local/bin/ant). When using ant with APT, it is important to tell ant to use the correct version of Java via the JAVA_HOME environment variable. Currently we are using Java 1.4, so something like this would be appropriate:
setenv JAVA_HOME /usr/local/j2sdk1.4.2To build APT from scratch,
cd $APT
ant redeliverThe latest code can always be obtained then with:
cd $APT
cvs update -dAfter updating, APT can be built from scratch, as above, or can be built more quickly by just building what's changed:
cd $APT
ant deliver
When using option (1)
above, APT is installed in /usr/local/APT/nightly-develop-build/APT_Installation
(which we'll call $APT). APT can then be run with:
$APT/runAPT [command arguments - see
below]
When using option (2)
above, let $APT be the directory where you installed APT. APT can then be
run with:
$APT/runAPT [command arguments - see
below]
When using option (3)
above, APT can be invoked using ant, but no command options can be specified:
cd $APT
ant runAPT
On some machines, APT takes a long time to come up. To reduce this initialization time, one can remove some of the plug-in tools that are run with APT. When APT starts, it loads plug-in tools from the jar files in $APT/Plug-Ins. Moving or removing a jar file from $APT/Plug-Ins will cause the corresponding tool not to be loaded. For example, one can decied not to use the VTT or VisitPlanner tools, and thereby substantially reduce the start-up time of APT, by getting rid of the files $APT/Plug-Ins/VTT.jar and $APT/Plug-ins/VisitPlanner.jar.
APT Command Line Argument Documentation
Configuring APT to Run with a Developer's Trans Image
Orbit Planner preferences determine how the OrbitPlanner tool interacts with Trans. The internal defaults for those preferences are fine for basic runs of the Orbit Planner. Some defaults need to be overridden to have the Orbit Planner run with a non-default Trans image, or to direct various Orbit Planner output files to go to non-default locations.
Orbit Planner preferences can be specified using -Properties on the APT command line, or in a Java properties file. Preferences specified on the command line override those in the Java properties file.
By default, the startTransServer property is set to true. This tells the OrbitPlanner to try to start a trans image every time it starts. Since developers start their own Trans image (with lt, for example), startTransServer should be set to false when running with a developer's trans image. All other default preference values are sufficient.
Here, all the Orbit Planner preferences are defined:
op.properties.file - string with no default value. This preference can only be specified on the APT command line. This property names a file which, if it exists, will be read by the Orbit Planner as a Java properties file assumed to contain any selection of the properties listed below. If the specified file does not exist, the Orbit Planner will create it as a valid Java properties file containing the default values of all the properties listed below.
writeTVDesc - boolean with default value of false. Controls whether or not APT will write out it's notion of tv-desc files for the visit after each "update" action.
useGUI - boolean with default value of true. Controls whether or not the OrbitPlanner tool runs in GUI mode. This option is only effective when the OrbitPlanner is started as a stand-alone tool and is not actively supported.
outputDir - string with default value of $HOME/.OrbitPlanner. Controls to which directory the OrbitPlanner will write output. Mostly this refers to the optional tv-desc output files.
verbose - boolean with default value of false. Controls whether or not the OrbitPlanner will write lots of extra info and junk to stdout and stderr.
tdfFile - string with default value of "". Controls which tdf file will be read when the "Run Trans" action is selected from the OrbitPlanner pull-down.
startTransServer - boolean with default value of true. Controls whether or not the OrbitPlanner tries to start a trans image when it's activated.
useTransServer - boolean with default value of true. Controls whether or not the OrbitPlanner tries to use trans for OrbitPlanning. If it doesn't use Trans, no orbit planning is done.
useOrbtrace - boolean with default value of false. Enables certain features in the Orbtrace package. This is used for monitoring, logging and debugging the APT/Trans communications.
transImage - string with default value of trans-apt/trans-apt. Specifies the pathname (full or relative to $APT) of the executable trans image which will be invoked if startTransServer=true.
useFullSearch - boolean with default value of true. Deprecated. Will be removed at some point.
transOutputDir - string with default value of $HOME/.OrbitPlanner. Specifies the directory to which Trans should write any output files. Only effective when startTransServer=true.
transIORFile - string with default value of $HOME/.OrbitPlanner/optrans.ior. Specifies the pathname (full or relative to $APT) of the IOR file which will be read by APT to find how to connect with Trans. This file is created by Trans automatically when startTransServer=true. When startTransServer=false, the developer who starts Trans must ensure that trans creates the ior file, and that it's written or moved to the location specified by this property before the OrbitPlanner is activated.
transOutputLog - string with default value of $HOME/.OrbitPlanner/transOutput.log. Specifies the pathname (full or relative to $APT) of the file to which trans will write it's stdout and stderr. Only used when startTransServer=true.
Initializing a Developer's Trans Image to Interact with APT
To interact with APT, a trans image must create a TransServer object and publish it's location in an IOR file. APT will read the IOR file from the location specified by the transIORFile property. The TransServer object and IOR file can be created by calling start-TransServer with two optional arguments. The first arg specifies the name of the IOR file, the second specifies the Trans output directory. For example, if I were running on the science net, and I were using the default value for transIORFile, I could evaluate the following form in trans:
(trans::start-TransServer "~/.OrbitPlanner/optrans.ior" "~/.OrbitPlanner/transOutput")
If the Trans output directory is unspecified, Trans will use the default Trans output directory for that image. If the IOR file is unspecified, Trans will use the value of the TRANS_IOR environment variable, if set. If TRANS_IOR is not set, the IOR file will be optrans.ior in the default Trans output directory.
By default, Orbtrace recording will be done to the orbtrace subdirectory of the Trans output directory.
Note that there's no need to restart the trans image or the TransServer object when APT is restarted. A single TransServer can serve repeated invocations of APT, even when run-time errors were encountered. (Though it may be good to :pop or :cont out of a debug situation before restarting APT.)
Configuring APT to Run with Stand-alone Trans and Casm Images
By default, APT will look for Trans to be in the executable file $APT/LispPrograms/trans-apt/trans-apt. On Windows, the file extension will be ".exe". If your environment was set up to use a Trans development image, then your $HOME/.OrbitPlanner/OrbitPlanner.prop file will need to be changed to get APT to use the stand-alone image. Edit OrbitPlanner.prop to specify startTransServer=true, or simply delete the file, and APT will recreate it with that default the next time it runs.
APT will look for Casm to be in the executable file $APT/LispPrograms/casm/casm.exe. For Casm, the ".exe" file extension is present on all platforms.
Prebuilt, ready to use, Trans and Casm stand-alone images are available for all supported platforms on the Solaris Science Net. In /project/ra5/apt/lispPrograms, there are linux, solarisand windowsdirectories. Each of those directories contains a LispPrograms directory that can be copied to your $APT for your use.
Using the OrbitPlanner with APT's Editor
The normal (and only fully supported) use case of the Orbit Planner will be to use APT's proposal editing capabilities to define the proposals which are sent to Trans. This section doesn't give a complete description of how APT's editor works, but touches on how the APT editor interacts with the OrbitPlanner tool.
In APT, the left-most panel contains the hierarchical browser representation of the proposals which are loaded. Clicking on an item in the hierarchical browser makes it the "lead selection" (an important notion in APT).
The upper panel on the right contains the view for the active tool. The active tool is selected by pressing the tool's button on the toolbar or by selecting the tool from the "Tools" pull-down menu. The Orbit Planner is the most relevant tool for this discussion.
When the OrbitPlanner is selected as the active tool, it infers what visit is being worked on from the lead selection. For example, if the lead selection is an exposure, the OrbitPlanner infers that the user is working on the visit containing that exposure. If the lead selection is not in a visit (a target, for example), then the OrbitPlanner doesn't know which visit is being worked on.
If the OrbitPlanner can determine the current visit, it immediately begins sending all the specifications for the visit to trans (if useTransServer=true). It also sets up the spreadsheet editor (in the lower right panel) to include all the items in the visit. The spreadsheet editor will be (for the time being) the most convenient place to edit the specifications for all the different things in the visit. Editing proposal properties in the spreadsheet editor is mostly straightforward. Note, however, that after typing a new value for exposure time, you must hit "Enter" and select another spreadsheet box before the change will be detected.
The OrbitPlanner's "Update Display" button will be sensitive whenever trans has some specification data on which it hasn't run a full search. Pressing the "Update Display" button causes trans to run a full search and display the results in the orbit planner window. For now, APT will wait quite a while (indefinitely?) for Trans to do an update, so various debugging can be done in the Trans image without messing up APT's state.
Running the preprocessor on a .prop file generates a corresponding xml version of that proposal. This prop to xml conversion is a good mechanism for generating APT test data.
Notes about other quirky behavior may be found in the release notes
for prior test releases. These notes, along with other possibly useful
info can be found off the Orbit Planner Development
page.