= What Is Rappture? =

The Rappture toolkit provides the basic infrastructure for a large class of scientific applications, letting scientists focus on their core algorithm when developing new simulators.  Here's a [http://www.nanohub.org/images/tool/molctoy/molctoy.swf demo] of a Rappture interface for a Matlab script which simulates conduction through a molecule.  This interface was generated automatically by Rappture, based on a description of the tool inputs and outputs.

Rappture also makes it easy to put a friendly, interactive interface on existing legacy applications, without having to rewrite the code.  For example, the [http://bwrc.eecs.berkeley.edu/Classes/IcBook/SPICE/ SPICE circuit simulator] has been around since 1972.  You can now run [http://nanohub.org/tools/spice3f4 SPICE on the nanoHUB] via a simple Rappture interface.  This shows the power of taking a powerful, batch-processing tool, and making it more interactive and accessible.

== Tutorial ==

The following tutorials teach the basic concepts behind Rappture and take you through several examples in Python, Fortran, and other languages:
 * [http://hubzero.org/resources/381 HUBbub 2011: Creating and Deploying Scientific Tools] (short course)
 * [http://nanohub.org/resources/14671 NCN Software Boot Camp 2012] (longer version)

== Licensing ==

Rappture is Open Source software.  See the [wiki:LicenseTerms license terms] for details.

== How does it work? ==

Instead of inventing your own input/output, you declare the parameters associated with your tool by describing Rappture objects in the Extensible Markup Language (XML).  For example, the figure below shows the XML description of a simple plotting tool.

[[rpimage(graphxml.gif)]]

The <input> section contains three elements:  a <string> representing the mathematical formula that the user will enter, a <number> for the x-axis minimum, and another <number> for the x-axis maximum.  The <output> section for this tool contains a <curve> plotting the value of the function versus x.  This is the complete set of parameters for this simple tool.  The are many other types of Rappture elements which can be used to describe other input/output data, including simple elements such as <boolean> and <choice>, and more complex elements, such as <structure>, <mesh>, <field>, and <molecule>.  For details, see [wiki:rappture_xml_elements Rappture XML Elements].

Rappture reads the XML description for a tool and generates the GUI automatically.  The XML description shown on the left-hand side of the figure above produces the screen shot on the right-hand side.  Note that the three input parameters appear on the left side of the screen, and the output curve appears on the right.  The user can enter a formula along with the x-axis min/max values, and press the ''Simulate'' button to see the graph on the right-hand side.  Rappture has a fairly sophisticated analysis environment for viewing results.  The user can enter additional formulas and compare the results, or plot them all on the same graph, as shown in the figure.

Describing the inputs and outputs is the first half of the development process.  The second half is writing the code within a simulator to access these elements.  Rappture has bindings for a variety of programming languages, including [wiki:rappture_ccpp_api C/C++], [wiki:rappture_fortran_api Fortran], [wiki:rappture_python_api Python], and a variety of other [wiki:Documentation languages].  So you can use the Rappture Application Programming Interface (API) naturally within your favorite programming environment.

To continue our example, here is the Python code needed to implement the simple graphical calculator tool shown above:

[[rpimage(graphsrc.gif)]]

The lines in bold face emphasize the code needed for Rappture; the rest of the code is needed for the core simulator, regardless of how the input/output is handled.  A typical simulator might read values from standard input, compute the results, and write them to standard output.  Instead, a Rappture simulator gets inputs from the <input> elements in its tool description, and puts outputs into the <output> elements.  In Python, this is accomplished as follows.  The {{{import}}} statement loads the Rappture package into the Python interpreter, providing access to elements in the API, such as {{{Rappture.library}}} and {{{Rappture.result}}}.  The {{{Rappture.library}}} call loads what we refer to as the ''driver file'', which is normally passed as the first argument to the simulator program.  The driver file is the same as the XML tool description shown above, but with {{{<current>}}} values for each of the input elements.  The {{{io.get()}}} command gets the current value for each of the input parameters.  Each parameter is uniquely identified by a simple path syntax.  The path {{{input.number(min).current}}} means "find the <input> tag, then the <number id="min"> within it, then the <current> tag within that."

Once our simulator has all of its inputs, it begins evaluating the formula for each value of x.  The {{{io.put()}}} command stores each computed (x,y) point in the output <curve> element; the {{{append=1}}} flag indicates that each point should be appended to the previous results, instead of overwriting them.  When the simulation is complete, the {{{Rappture.result()}}} call reports the results back to the Rappture GUI.

The Rappture GUI drives the whole interaction.  There is one generic GUI program called {{{rappture}}} that can be used for all Rappture tools.  This program reads the XML description for a tool and produces the interface automatically, on-the-fly.  The user interacts with the GUI, entering values, and eventually presses the ''Simulate'' button.  At that point, Rappture substitutes the current value for each input parameter into the XML description, and launches the simulator with this XML description as the "driver" file.  The simulator reads the inputs, computes the outputs, and sends the results back to the Rappture GUI, as described above.  The GUI then loads the results into the output analyzer for the user to explore.

It is easy to add new parameters to a simulator.  First, update the XML description of the simulator; then, update the code for the simulator itself to access the new parameters.  Rappture generates the GUI dynamically, each time you run a tool, based on the information available at that point.  So as you make changes to a program, Rappture will detect the changes and adjust the GUI accordingly the very next time you run the tool.

The tool shown here is a fairly simple example.  Rappture is capable of supporting real scientific simulators with much more complexity.  [http://www.nanohub.org/images/tool/molctoy/molctoy.swf This demo] shows an educational tool with a little more complexity running within a web page on the nanoHUB.  If you have a nanoHUB account, you can launch the tool yourself from [http://www.nanohub.org/resources/225 this page].  This tool simulates electronic conduction through a molecule sandwiched between two gold contacts.  In addition to the various number parameters, this tool has a <structure> with <field>'s describing the energy levels within it.  Rappture renders the structure and its fields, giving the user a graphical overview of the device under test.  This graphical input, coupled closely with immediate output, provides an intuitive environment for education and scientific discovery.

== Getting Started ==

Ready to get started with Rappture?  Follow the instructions on [wiki:GettingStarted this page] to install the Rappture development environment and get the examples up and running.  Then, start building your own tool with Rappture!