ITAC Command-Line Interface
This is the repository for the Gemini Observatory ITAC application.
Installing ITAC is straightforward but you may require a bit of assistance if you're not comfortable using the command line. Anyone from ITS or the software group can help you if you get stuck.
Open a command shell (Terminal.app on the Mac) and continue with Step 2.
2. Install Coursier
First install the Coursier native launcher. This will let you set up ITAC as well as the Java Virtual Machine, if necessary. Follow the instructions here.
Depending on how you installed it, you may need to move
cs into a directory that's on your executable path, such as
On success you will be able to do:
$ cs --help Coursier 2.0.0-RC6-10 Usage: cs [options] [command] [command-options] Available commands: bootstrap, complete, fetch, install, java, java-home, launch, publish, resolve, setup, uninstall, update Type cs command --help for help on an individual command
3. Install ITAC
cs setup to set up Java, configure your path, and install ITAC.
cs setup --yes --channel edu.gemini:itac-channel --apps itac
Close and re-open your terminal window and
itac --help should now run and print a help message.
4. Update ITAC
Once ITAC is installed you can update to the latest version thus:
cs update itac
cs uninstall itac
ITAC is a command-line application that reads proposal XML files along with some configuration information stored in YAML files, and produces an observing queue. The main workflow is:
- Initialize a workspace directory to contain all your input files, and copy proposal XML files into the
- Customize configuration files as necessary to specify partner times, shutdown blocks, target changes, and so on.
- Create queues and examine the output, tweaking configuration until you're satisfied.
- Send emails and ingest the proposals into the ODB.
Keep in mind the following big ideas:
- All the input files are just normal text files. You can rename them, make backups, store them in source control, manage them however you like.
- All proposal "edits" are specified as part of configuration and occur as proposals are loaded from disk. The XML files are never touched. This means you undo or change edits simply by updating the contents of the
- The input files completely specify the Queue. If you want to have several queues that you can compare, you can have several sets of input files.
Now let's examine these steps in more detail.
Initialize and Configure an ITAC Workspace
Note: this step requires a connection to the internal Gemini network, so if you're working off-site you need to have the VPN turned on.
Create a new directory, move into it, and initialize the ITAC workspace for next semester.
$ mkdir itac-example $ cd itac-example $ itac init 2020B [INFO ] Creating folder: email_templates [INFO ] Creating folder: proposals [INFO ] Creating folder: edits [INFO ] Writing: ./email_templates/ngo_classical.vm [INFO ] Writing: ./email_templates/ngo_exchange.vm [INFO ] Writing: ./email_templates/ngo_joint_classical.vm [INFO ] Writing: ./email_templates/ngo_joint_exchange.vm [INFO ] Writing: ./email_templates/ngo_joint_poor_weather.vm [INFO ] Writing: ./email_templates/ngo_joint_queue.vm [INFO ] Writing: ./email_templates/ngo_poor_weather.vm [INFO ] Writing: ./email_templates/ngo_queue.vm [INFO ] Writing: ./email_templates/pi_successful.vm [INFO ] Writing: ./email_templates/unsuccessful.vm [INFO ] Writing: ./common.yaml [INFO ] Writing: ./gn-queue.yaml [INFO ] Writing: ./gs-queue.yaml [INFO ] Fetching current rollover report from Gemini North... [INFO ] Got rollover information for 2020A [INFO ] Writing: ./gn-rollovers.yaml [INFO ] Fetching current rollover report from Gemini South... [INFO ] Got rollover information for 2020A [INFO ] Writing: ./gs-rollovers.yaml [INFO ] init: initialized ITAC workspace in .
itac has created a bunch of files. Let's look at them.
$ tree . ├── common.yaml ├── email_templates │ ├── ngo_classical.vm │ ├── ngo_exchange.vm │ ├── ngo_joint_classical.vm │ ├── ngo_joint_exchange.vm │ ├── ngo_joint_poor_weather.vm │ ├── ngo_joint_queue.vm │ ├── ngo_poor_weather.vm │ ├── ngo_queue.vm │ ├── pi_successful.vm │ └── unsuccessful.vm ├── gn-queue.yaml ├── gn-rollovers.yaml ├── gs-queue.yaml ├── gs-rollovers.yaml └── proposals
common.yamlcontains configuration that applies to all queues and is unlikely to change much. You will need to edit this file to specify shutdown times and partner contact emails. The rest is probably ok.
email_templates/contains the default email templates which are used to generate emails that are sent to partners and PIs. You can change these if you wish (and if you do, let us know so we can change the defaults) but they're probably ok.
gs-queue.yamlspecify site-specific queue configurations. The most important part here is
hourswhich specifies per-partner hours in bands 1, 2, and 3. Remaining configuration is probably ok.
gn-rollovers.yamlcontain rollover reports fetched from the ODBs at GN and GS. You may wish to adjust the times here. To re-fetch a rollover report you can say
itac --force rollover --south(or
--north). Note that you must have an internal or VPN connection to do this.
proposals/is where your proposal XML files (from Jared's system) need to go.
edits/is where you define edits that are applied to the XML files as they are read.
You can get detailed help about
itac commands and options with the
||Show top-level help.|
||Show help for a specific command. For example,
You can also ask for help on the
#itac channel on the Gemini Software Slack (ask Arturo if you need access).
Look at Proposals
The following commands display information about the proposals in your workspace's
||Show a list of all proposals in the workspace.|
||Display a summary of a proposal and its observations. For example,
Construct a Queue
Once your workspace is set up you can run a queue, but if you want to play with this software it's likely you don't have any proposals for the current semester. So to do this we can turn back time and run a previous semester's queue again. Let's use 2020A.
- Put the 2020A proposal XMLs in
common.yamland change the semester to
- Replace the rollover files if desired (Rob can send you 20A rollovers).
You should now be able to run a queue and see output that includes rejection messages, bin usage, and band assignments.
itac queue --south
itac allows you to define edits that are applied to proposals as the XML files are read. Here is the workflow.
itac summarize <ref>to look at the proposal you wish to edit.
itac summarize --edit <ref>to write a copy of the summary into the
edits/folder, with the name
- Edit the file in the
edits/folder, making changes as instructed in the comment at the top of the file.
- Changes will be applied each time the proposal is loaded from disk. The original XML file is never touched. You can verify changes by running
itac summarize <ref>again.
- To undo your edits, delete the edit file.
- It is not possible to update ToO or nonsidereal targets using
itac. Such edits will be ignored.
- It is not possible to add observations. This must be done in the PIT.