= 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 [source:trunk/examples/ browse the examples online], or copy them into your working directory within a nanoHUB workspace from {{{/apps/share64/debian7/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>
    <uq>true</uq>
    <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 {{{<uq>}}} attribute sets the default UQ (Uncertainty Quantification) state for the tool.  If set to false, no UQ buttons will appear next to Number controls, unless a Number control specifically enables it.

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.
 * [wiki:rp_xml_ele_boolean boolean]
 * [wiki:rp_xml_ele_choice choice]
 * [wiki:rp_xml_ele_curve curve]
 * [wiki:rp_xml_ele_drawing drawing (input)]
 * [wiki:rp_xml_ele_drawing_output drawing (output)]
 * [wiki:rp_xml_ele_field field]
 * [wiki:rp_xml_ele_flow flow]
 * [wiki:rp_xml_ele_group group]
 * [wiki:rp_xml_ele_histogram histogram]
 * [wiki:rp_xml_ele_image image]
 * [wiki:rp_xml_ele_integer integer]
 * [wiki:rp_xml_ele_loader loader]
 * [wiki:rp_xml_ele_log log]
 * [wiki:MapObjectXML map]
 * [wiki:rp_xml_ele_mesh mesh]
 * [wiki:rp_xml_ele_note note]
 * [wiki:rp_xml_ele_number number]
 * [wiki:rp_xml_ele_periodicelement periodicelement]
 * [wiki:rp_xml_ele_phase phase]
 * [wiki:rp_xml_ele_sequence sequence]
 * [wiki:rp_xml_ele_string string]
 * [wiki:rp_xml_ele_structure structure]
 * [wiki:rp_xml_ele_table table]

== Tool Version Information ==
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 ||

== Tool Execution Info ==
Information about each tool run is added to the run.xml file as it is moved into the "results" directory.  This info is used by the '''rptimes''' script as the execution times are extracted and stored for predicting future run times.
|| {{{output.cputime}}} || => total CPU time in seconds ||
|| {{{output.walltime}}} || => total wall time (overall real time of execution) in seconds ||
|| {{{output.time}}} || => time stamp representing the end of execution ||
|| {{{output.venue.name}}} || => name of the venue where the computation ran (local exec host, if not specified) ||
|| {{{output.venue.ncpus}}} || => number of CPUs used during the computation ran (assume 1, if not specified) ||

[[BR]]
== Other Notes ==
Here are some other notes that apply to the various elements above.
 * [wiki:rp_xml_enable enable/disable one element based on another]
 * [wiki:rp_progress show progress during long-running simulations]