Progress Info: A Proposal

Rappture has a simple function for reporting progress during simulation. For example, in C language, the call would be:

rpUtilsProgress(25, "Solving sparse matrix...");

This brings up a progress bar showing 25% and the message Solving sparse matrix... beneath it. Your program should call this again and again during a long simulation to update the percentage and the message displayed to the user.

Users of some simulators need to see more than a simple status message. For example, suppose a simulator spends a while trying to achieve convergence for an initial solution, and then computes solutions at a series of time points. During the initial solution, the user might want to see a plot of convergence, so if the solution is wandering, the simulation can be aborted. After the initial solution, the user may want to see a plot for each time point, or perhaps a 2D image at each time point, to get a feeling of how the simulation is progressing.

These advanced scenarios could be handled by defining Rappture objects within a <progress> section of the tool.xml file:

<?xml version="1.0"?>
<run>
<tool>...</tool>
<input>...</input>
<progress>
  <phase id="init">
    <curve id="converge">
      <about><label>Convergence of Initial Solution</label></about>
      <xaxis><label>Iteration</label></xaxis>
      <yaxis><label>Error</label><scale>log</scale></yaxis>
    </curve>
  </phase>
  <phase id="solve">
    <image id="2D">
      <about><label>2D Solution</label></about>
    </image>
  </phase>
</progress>
<output>...</output>
</run>

This example has two phases of progress. The first phase is used during the initial solution and shows a plot of error (on a log scale) versus iteration number. The second phase is used when computing solutions at each time point and it shows a 2D image of the solution for each time point.

Progress would be reported within the simulation program as follows:

import Rappture
import sys

# open the XML file containing the run parameters
driver = Rappture.library(sys.argv[1])

Tstr = driver.get('input.number(temperature).current')
T = Rappture.Units.convert(Tstr, to="K", units="off")
...

# phase 1 - initial solution
iter = 0
while !converged:
    ...do the computation...
    Rappture.Utils.progressData(driver, 'progress.phase(init).curve(convergence).component.xy', '%d %g\n' % (iter,err), op='append');

# phase 2 - solution for each time point
t = 0.0
while t < tmax:
    ...do the computation...
    str = Rappture.encoding.encode(imgdata)
    Rappture.Utils.progressData(driver, 'progress.phase(solve).image(2D).current', str, op='overwrite');
    Rappture.Utils.progress(t/tmax*100, 'Solving at t = %g' % t);

Rappture.result(driver)
sys.exit()

When data is sent to a particular phase, it appears on the screen. Note that separate progress() calls can be used in addition to the progressData() calls to indicate overall progress.