Wavefront User's Manual

Last Updated February 2010

Wavefront( array R[x,0], array R[0,y], function F(x,y,d) )
returns matrix R where
R[i,j] = F( R[i-1,j], R[i,j-1], R[i-1,j-1] )

The Wavefront abstraction computes a two dimensional recurrence relation. You provide a function F that accepts the left (x), right (y), and diagonal (d) values and initial values for the edges of the matrix. You may optionally provide additional parameters for each cell, given by a matrix P. The abstraction then runs each of the functions in the order of dependency, handling load balancing, data movement, fault tolerance, and so on.

To use Wavefront, install the Cooperative Computing Tools and run the program named wavefront. Create files named R.0.0 through R.0.n and R.0.0 through R.n.0. Then run wavefront, specifying the program that computes each cell, and the number of cells in each dimension:

wavefront ./func.exe 10 10

The program func.exe may be written in any language that you like. For each cell of the result, the program will be invoked like this:

./func.exe R.3.2 R.2.3 R.2.2 > R.3.3

Wavefront will check for a few error conditions, and then start to run, showing progress on the console like this:

# elapsed time : waiting jobs / running jobs / complete jobs (percent complete)
0 : 0 / 1 / 0 (%0.00)
5 : 0 / 2 / 1 (%1.23)
10 : 0 / 3 / 3 (%3.70)
16 : 0 / 4 / 6 (%7.41)
21 : 0 / 4 / 8 (%9.88)
...

When complete, your outputs will be stored in files named R.i.j, once for each cell computed. If you have parameters for each function, then place them in files named P.i.j and give the -P option to Wavefront.

If you run Wavefront on a single-CPU machine, then exactly one process will run at once. If you run it on a multi-core machine, it will employ all available processors. If you have a Condor or SGE batch system, give the -T condor or -T sge option, and and up to 1000 jobs will run at once on Condor. You may also explicitly control the maximum number using the -n option. For example, here is a graph of a 100 by 100 problem run on a 64-core machine, where each F takes about five seconds to execute:

The -B option will write a bitmap progress image every five seconds. Each pixel represents the state of one cell in the matrix: green indicates complete, blue currently running, yellow ready to run, and red not ready. Here is an example of the progress of a small ten by ten job using five CPUs:

Note that at the broadest part of the workload, there are not enough CPUs to run all cells at once, so some must wait. Also note that the wave does not need to run synchronously: cells may begin to compute as soon as their dependencies are satisfied.

For More Information

For the latest information about Wavefront, please visit our web site and subscribe to our mailing list.