3.3.10 The latex_vis backend

The latex_vis backend visualizes a program’s communication pattern as an Encapsulated PostScript time-space diagram. The backend thereby provides a static counterpart to the animated visualizations made possible by the picl and paraver backends and the ParaGraph and Paraver trace visualizers (see The picl backend, and The paraver backend). latex_vis outputs LaTeX code with calls to the PSTricks package (available from http://www.tug.org/applications/PSTricks/ but shipped with most LaTeX distributions) to draw the figure, then runs latex (or whatever the LATEX environment variable is set to) to convert the .tex file to DVI format and dvips (or whatever the DVIPS environment variable is set to) to convert the .dvi file into EPS format. Finally, latex_vis runs the graphic through Ghostscript ( gs or whatever the GS environment variable is set to) to tighten the graphic’s bounding box.⁴ latex_vis requires that LaTeX and PSTricks be installed in order to produce its visualizations. However, it can still run with --no-compile (see Compiling coNCePTuaL programs) to produce a .tex file that can later be run manually through latex.

As an example, the following is the default latex_vis output from the coNCePTuaL program ‘TASK 0 SENDS A 1 MEGABYTE MESSAGE TO TASK 1 THEN ALL TASKS SYNCHRONIZE THEN TASK 1 SENDS A 3 KILOBYTE MESSAGE TO TASK 0’ when run with three tasks:

Currently, the output diagram does not indicate message size but this may change in a future release of latex_vis.

The latex_vis backend has a number of uses. First, it can be used to illustrate a nontraditional communication pattern for a presentation, research paper, or technical report. Second, it can be used as a teaching aid to demonstrate common communication patterns (e.g., a butterfly pattern) to students. Third, it can be used as a debugging aid to ensure that a coNCePTuaL program is, in fact, performing the expected communication operations.

latex_vis is derived from interpret (see The interpret backend) and therefore supports the interpret backend’s --tasks and --mcastsync options as well as the standard options described in Running coNCePTuaL programs. (The interpret backend’s --kill-reps option can be handy for reducing the picture’s size by showing only a single iteration of each loop.) Because latex_vis does not produce log files, the --logfile option is absent. latex_vis additionally supports the following command-line options:

-A, --annotate=<string>         Annotation level (0=no annotations;
                                  1=annotate communication events;
                                  2=annotate all events;
                                  "<event>..."=annotate only the
                                  specified events) [default: "0"]
  -B, --binary-tasks=<number>     Display task numbers in binary rather
                                  than decimal (0=decimal; 1=binary)
                                  [default: 0]
  -E, --every-event=<number>      Events requiring nonzero time to complete
                                  (0=only communication events;
                                  1=every event) [default: 0]
  -G, --stagger=<number>          Number of points by which to stagger
                                  overlapping arrows [default: 2]
  -L, --source-lines=<number>     Associate source-code line numbers with
                                  each event annotation (0=no; 1=yes)
                                  [default: 0]
  -R, --arrow-width=<string>      Python expression to map m, representing
                                  a message size in bytes, to an arrow
                                  width in points [default: "1"]
  -Z, --zero-latency=<number>     Depict communication as having zero
                                  latency (0=unit latency; 1=zero
                                  latency) [default: 0]

In the preceding list a “point” refers to a PostScript point. TeX calls these “big points” and defines 1bp = 1/72")

The --annotate option places adjacent to appropriate nodes in the output diagram a list of textual annotations that indicate the communication operations that were posted or completed and the non-communication operations that were executed by the corresponding task at the corresponding time. Some sample annotations are ‘Post SEND’, ‘Complete SEND’, and ‘Execute OUTPUT’. With --annotate=1, only communication events are annotated; with --annotate=2, all events are annotated;⁵; otherwise, a list of specific events can be annotated. For example, --annotate=SYNC,MCAST causes only the ‘SYNC’ and ‘MCAST’ events to be annotated. Compiling a coNCePTuaL program with the latex_vis backend and the --keep-ints options (see Compiling coNCePTuaL programs) produces a .tex file that contains in the prologue comments a list of all events used by a program that were and were not annotated.

Task numbers are normally shown in base ten. The --binary-tasks option causes task numbers to be output in base two and using the same number of bits for each task. For example, a 3-task visualization with --binary-tasks would number the tasks ‘00’, ‘01’, and ‘11’.

Because latex_vis is intended primarily for visualizing communication patterns, by default only communication operations take nonzero time to complete. The --every-event option indicates that all events—including local events such as ‘SLEEP’, ‘COMPUTE’, ‘LOG’, and ‘OUTPUT’—should be deemed to complete in unit time.

latex_vis output distinguishes coincident arrows (consider the phrase ‘TASK 0 ASYNCHRONOUSLY SENDS 5 MESSAGES TO TASK 1’) by staggering them slightly. The --stagger option specifies the number of PostScript points by which to stagger each overlapping arrow with a default of 2 points. Large stagger values are more visually distinctive while small stagger values allow arrows to drift less from their associated nodes.

The --source-lines option, when used with --annotate, augments each event annotation with the corresponding line(s) of source code that produced that event. This feature improves the utility of latex_vis as a debugging aid for coNCePTuaL programs.

By default, all arrows that indicate message transmissions are drawn with equally thick line widths. The --arrow-width option lets you specify a Python function to map a message size in bytes, m, to a line width in PostScript points, with the default being 1 point. As a simple example, --arrow-width=2 doubles the arrow width for all message (i.e., it represents the constant function f: m --> 2). A more typical example would be --arrow-width="log10(m)" (representing f: m --> log10(m)), which causes a tenfold increase in message size to yield a unit increase in line width. The argument to --arrow-width can be any Python expression using either built-in functions or functions from the Python math module. See the Python library reference for details.

Normally, messages are considered to require one time unit to travel from source to destination. The --zero-latency option shows messages as being received in the same timestep as they were sent. Some communication patterns are more aesthetically pleasing when drawn this way.