One of the most requested features for Rappture is a ''service'', a short calculation which runs independently of the '''Simulate''' button.  A service could be an ''input service'', which runs automatically in response to user input, before '''Simulate''' is clicked, or an ''output service'', which runs as the user analyzes results of the main simulation, launched when the user clicks '''Simulate'''.

== Input service example: MaterialDB ==

As an example, consider the following tool: 
[[BR]]
[[Image(pic1.png)]]
[[BR]]
This tool needs 3 inputs, a lattice constant, a dielectric constant, and a band gap, which are properties of the material chosen in the selector at the top.  Using the current capabilities of Rappture, the user would need to input each of the 3 values separately (obviating the need for the Material selector).


The MaterialDB (an entirely separate project) calculates these material properties (and many others) from functional expressions.  For example, the dielectric constant for !GaAs is 
{{{
12.40*(1.0+1.20E-4*T)
}}}
where T is the temperature.  The details of the MaterialDB are not relevant to this proposal, except to say that by using it material parameters can be calculated on the fly.  Running MaterialDB as an ''input service'' then, Rappture could populate the lattice constant, dielectric constant, and band gap inputs of the tool above 
based solely on the value of the Material selector.


The core idea of this proposal is a method of connecting the input and output of tools with Rappture interfaces; to that end, we also need a Rappture GUI for the MaterialDB, like the following:
[[BR]]
[[Image(pic2.png)]]
[[BR]]
This tool takes a material name and parameter name and returns the requested material parameter from the MaterialDB.  The tool.xml file for this tool is very simple.
{{{
<?xml version="1.0"?>
<run>
   <tool>
      <title>MaterialDB Service</title>
      <about>Rappture service interface to the Purdue MaterialDB</about>
      <command>tclsh @tool/matdb_service.tcl @driver</command>
      <layout>wizard</layout>
   </tool>
   <input>
      <!-- ================================================================= -->
      <string id="material_name">
         <about>
            <label>Material name</label>
            <description></description>
         </about>
         <size>30x1</size>
         <default>Enter material name here</default>
      </string>
      <!-- ================================================================= -->
      <string id="parameter">
         <about>
            <label>Parameter</label>
            <description></description>
         </about>
         <size>30x1</size>
         <default>Enter parameter name here</default>
      </string>
   </input>
   <!-- ==================================================================== -->
   <output>
      <string id="result">
         <about>
            <label>Result</label>
            <description>Value returned from MaterialDB</description>
         </about>
      </string>
   </output>
   <!-- ==================================================================== -->
</run>
}}}


Now we have two Rappture tools, the top level tool which needs material parameters and the MaterialDB tool which provides the parameters.  The following tool.xml for the top level tool illustrates some ideas about how to describe calling the MaterialDB tool as an ''input service''.
{{{
<?xml version="1.0"?>
<run>
   <tool>
      <title>Material Parameter Lookup</title>
      <about>Quick reference for material parameters</about>
      <command>ruby @tool/matref.rb @driver</command>
      <layout>wizard</layout>
   </tool>
   <input>
      <!-- ================================================================= -->
      <choice id="material">
         <about>
            <label>Material</label>
            <description>Choose a semiconductor material</description>
         </about>
         <option><about><label>GaAs</label></about></option>
         <option><about><label>Si</label></about></option>
         <option><about><label>SiGe</label></about></option>
         <default>GaAs</default>
         <service id="MaterialDB">
            <!-- A service is activated by a specific GUI action.  In this
                 case, any selection of the this choice activates the 
                 MaterialDB service. -->
            <activate>select</activate>
            <!-- When the service is activated, all the following call elements
                 are executed. -->
            <!-- =========================================================== -->
            <call>
               <map>
                  <!-- The map input tags specify how to send values to the 
                    service's driver.xml.  These values might be the current
                    values of elements in this driver.xml or simple strings. -->
                  <input>
                     <value>
                        <!-- Send the material name (from the above choice in
                             this driver.xml) to the material_name string in 
                             the service's driver.xml. -->
                        <send>input.choice(material).current</send>
                        <receive>input.string(material_name).current</receive>
                     </value>
                     <value>
                        <!-- Send the material parameter name; this is a 
                             string, the name of a MaterialDB entry, unique to 
                             each call -->
                        <send>PhysChem:a_lattice</send>
                        <receive>input.string(parameter).current</receive>
                     </value>
                  </input>
                  <output>
                     <!-- The map output tags specify how to get values from 
                          the service's run.xml back to elements in this 
                          driver.xml -->
                     <value>
                        <!-- Send the output result, a number, from the 
                             service's run.xml to the lattice_constant number,
                             below -->
                        <send>output.string(result).current</send>
                        <receive>input.number(lattice_constant).current</receive>
                     </value>
                  </output>
               </map>
            </call>
            <!-- =========================================================== -->
            <call>
               <map>
                  <input>
                     <value>
                        <send>input.choice(material).current</send>
                        <receive>input.string(material_name).current</receive>
                     </value>
                     <value>
                        <send>PhysChem:epsilon_dc</send>
                        <receive>input.string(parameter).current</receive>
                     </value>
                  </input>
                  <output>
                     <value>
                        <send>output.string(result).current</send>
                        <receive>input.number(dielectric_constant).current</receive>
                     </value>
                  </output>
               </map>
            </call>
            <!-- =========================================================== -->
            <call>
               <map>
                  <input>
                     <value>
                        <send>input.choice(material).current</send>
                        <receive>input.string(material_name).current</receive>
                     </value>
                     <value>
                        <send>BandEdge:C_Gamma:Eg</send>
                        <receive>input.string(parameter).current</receive>
                     </value>
                  </input>
                  <output>
                     <value>
                        <send>output.string(result).current</send>
                        <receive>input.number(band_gap).current</receive>
                     </value>
                  </output>
               </map>
            </call>
         </service>
      </choice>
      <!-- ================================================================= -->
      <number id="lattice_constant">
         <about>
            <label>Lattice constant</label>
            <description>Length of conventional unit cell edge, in Angstroms</description>
         </about>
         <units>A</units>
         <default>1.0</default>
      </number>
      <!-- ================================================================= -->
      <number id="dielectric_constant">
         <about>
            <label>Dielectric constant</label>
            <description>Relative permittivity of a material (dimensionless)</description>
         </about>
         <default>1.0</default>
      </number>
      <!-- ================================================================= -->
      <number id="band_gap">
         <about>
            <label>Band gap</label>
            <description>Band gap at the gamma point (eV)</description>
         </about>
         <units>eV</units>
         <default>1.0</default>
      </number>
   </input>
</run>
}}}
[[BR]]
The <activate> tag specifies which GUI actions launch the ''input service''.  The <call> tags delimit a specific, automatic invocation of the MaterialDB tool; each time the ''input service'' runs, it invokes the MaterialDB service once for each <call> tag.


The <map> tags describe the connections between GUI elements in the two tools.  In some cases, the value of a Rappture GUI element in one tool is mapped to a Rappture GUI element in another tool (the GUI element in the second tool takes the current value of the GUI element in the first tool).  In other cases, a GUI element in the second tool may require a literal value, like 
{{{
BandEdge:C_Gamma:Eg
}}}
in the syntax of the MaterialDB.


=== Issues ===
 * Multiple <call> tags per service invocation vs. a single call
   * Having multiple <call> tags adds complexity to the tool.xml which invokes the ''service''; the ''service'' tool Rappture interface could be customized to take only the material name and calculate the specific parameters (lattice constant, dielectric constant, and band gap in this example) in one calculation.
   * The tradeoff is the cost of changing the call to the ''service'' tool (e.g. requesting a fourth parameter, such as effective mass), which would involve changes to both the top level tool.xml and the ''service'' tool.
 * The proposal above does not distinguish between Rappture GUI element paths (e.g. input.number(band_gap).current) and literal strings (e.g. the BandEdge:C_Gamma:Eg above).  Both could be sent to or received from the ''service'' tool.
 * Conversion: mapping Rappture GUI elements between two tools would require checking the type of each element to prevent nonsensical conversions (e.g. string to sequence) but allow sensible conversions (e.g. number to string).