wiki:rappture_xml_elements

Version 20 (modified by mmc, 17 years ago) (diff)

added <control> parameter

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.

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>
      <filesize>1000000</filesize>
    </limits>
    <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.

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'')

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.


Other Notes

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