wiki:rappture_xml_elements

Version 32 (modified by mmc, 12 years ago) (diff)

Add info about the tool directory and other information stamped into the tool.xml file

Zoo of Inputs/Outputs?

Welcome to the zoo of Rappture elements! This page shows the various snippets of XML code needed to create a Rappture tool.xml file.

NOTE: There are lots of examples included in the Rappture code distribution. You can browse the examples online, or copy them into your working directory within a nanoHUB workspace from /apps/rappture/current/examples.

Overall Structure

Each tool is described by a tool.xml file, which has the following structure: 

<?xml version="1.0"?>
<run>
  <tool>
    <title>Name of the tool</title>
    <about>Description and credits</about>
    <command>
      @tool/path/to/executable @driver
    </command>
    <limits>
      <cputime>900</cputime>
    </limits>
    <action><label>Simulate</label></action>
    <layout>xxx</layout>
    <control>xxx</control>
    <analyzer>xxx</analyzer>
    <reportJobFailures>1</reportJobFailures>
  </tool>
  <input>
    ...see Element Index below...
  </input>
  <output>
    ...see Element Index below...
  </output>
</run>

The <tool> section describes the underlying compute engine and includes the <command> needed to run it. This can be any Unix-style command line. The @tool keyword gets replaced with the name of the directory containing the tool.xml file. The executable for the compute engine is usually located relative to that. The @driver keyword gets replaced with the name of the driver XML file that the Rappture GUI creates for a particular run. It is usually the first argument to the executable for the compute engine.

This command is invoked whenever the user presses the run button, which says Simulate by default. The text of this button can be changed by setting the <action><label> property.

The optional <limits> section can be used to set limits on the amount of CPU time or the size of files that a simulator produces. This keeps runaway programs in check. By default, each simulator is allowed 900 seconds (15 mins) of CPU time and 1MB for each file produced. You can increase or decrease either of these limits. You can also set either value to unlimited to remove the limits. (Please use that feature sparingly! ) Note: filesize limits have been deprecated and are no longer in effect.

The optional <layout> attribute can be set to wizard to avoid the normal side-by-side layout of inputs and outputs. In "wizard" layout, the input takes the entire first screen, and the Simulate > button appears at the bottom like a Next > button. Clicking this button takes you to the output page. Spice3F4 is an example of a tool using this.

The optional <control> attribute is manual by default. This means that you must push the Simulate button to trigger simulation. It can also be set to automatic, so a change to any input value will trigger simulation. (This was thought to be a good idea early on, but people hated it, so it is rarely used.) It can also be set to manual-resim to allow the same set of input parameters to be simulated again. Normally, when you set inputs back to an earlier set of parameters, the Simulate button is disabled, indicating that you don't have to simulate this combination because you already have results. The manual-resim setting overrides this behavior and lets you simulate again.

The optional <analyzer> attribute can be set to last to automatically clear after each run. Normally, Rappture keeps all results so you can compare them side-by-side. For some tools, it is better to clear before each new simulation. Spice3F4 is an example of a tool using this.

The optional <reportJobFailures> attribute can be used to turn off automatic reporting of failures during job launch. If a tool is likely to fail based on user input (i.e., user may enter improperly syntax into the input deck area), then automatic reporting of job failures should be turned off. When in doubt, leave this out. It is on by default so that the hub team can be notified of problems. If it becomes a problem and they think it should be turned off, they can add this attribute to your tool. Spice3F4 is an example of a tool using this.

The <input> and <output> sections contain descriptions of the inputs and outputs for the underlying compute engine. See the Element Index below for details.

Element Index

This is the list of all input/output elements in Rappture. Look in the rappture/examples/zoo directory for the various snippets of code shown here.

Tool Version Inforation

Whenever Rappture invokes a tool, it updates the information in the tool.xml to make note of the directory containing the tool.xml. This isn't stored back in the original tool.xml, but rather, propagated along to the driver file and the eventual run.xml file. When a run is complete, it's good to know exactly what tool.xml it came from, and it's also useful during tool execution. A tool may be looking for libraries or other files relative to the tool.xml file. That information is stored at the following location and can therefore be queried like any other input value via a simple Rappture "get" call:

tool.version.application.directory(tool) => directory containing the tool.xml file

When your tool is installed on a hub, additional information is stamped into the tool.xml file during the publication process. That information is useful for tracking the provenance of the tool, since they are propagated through the driver to the eventual run.xml file. Like the directory mentioned above, those values can be see in the final output, or queried like any other input value via a simple Rappture "get" call. The values are as follows:

tool.id => short (alphanumeric) name of the tool on the hub (e.g., qdot)
tool.name => official title of the tool publication on the hub (e.g., "Quantum Dot Lab")
tool.version.identifier => version number of the tool as published on the hub (e.g., 1.0b2)
tool.version.application.revision => revision ID for this tool version from the source code control system
tool.version.application.modified => date of last modification from the source code control system
tool.version.application.installed => date that this software was installed/published
tool.version.application.directory(top) => top-level directory for the entire tool
tool.version.application.directory(tool) => directory containing the tool.xml file for Rappture-based tools


Other Notes

Here are some other notes that apply to the various elements above.