2.5 Visualization of Process Networks

When large process networks are created is is difficult to obtain a good overview of the network. In such a case a graphical output of the network, made via the dotty tools can be useful.

2.5.1 What is Dotty?

Figure 2.4: Dotty Output

The dotty format is a textual format that can be used to represent graphs. The dotty tools can then be used to create a layout of the graph and output it as a postscript file. The postscript file can then be used for documentation purposes. An example process network that is visualized via dotty is shown in Figure 2.4. Dotty is a part of the Graphviz tools, and can be obtained from http://www.research.att.com/sw/tools/graphviz. Note that dotty is available for users at the Nat.Lab. through the cadappl tree (cadenv graphviz).

2.5.2 How to Use Dotty

The function printDotty is used to print a process network in dotty format.

void printDotty(const ProcessNetwork& p, 
                std::ostream& o = std::cout);

To generate a dotty file one can add a printDotty call to the main program, as shown in the example below. In this example the process network nw of type MyNetwork is created, which is then printed in dotty format in the file nw.dot.

Program 2.5.1   Dotty Output

#include "mynetwork.h"
#include "dotty.h"
#include <fstream>

main()
{
        // create the network
        MyNetwork nw(id("nw"));

        // create output file nw.dot
        std::ofstream f("nw.dot");

        // print network in dotty format
        printDotty(nw, f);
}

After creating the .dot file by running the program, the graphviz tools can be used to visualize the .dot file. The program dotty can be used to view the graph via the X environment, or the program dot can be used to convert the graph into postscript format, with the following command:

dot -Tps nw.dot -o nw.ps

For output in other formats we refer to the graphviz manual pages.

2.5.3 Options

The YAPI to dotty conversion has various options to control the formatting of the graph. These options are specified via a configuration file named dotty.cfg that must be present in the current directory or in your home directory. The configuration file is a text file in which the options are specified as name = value pairs. Below, the default option settings are listed.

Program 2.5.2   Default Option Settings

InitLevel                      = 10
PageSize                       = A4p
Ratio                          = fill
Fifo                           = false
Decorate                       = false

ProcessNetworkColor            = white
ProcessColor                   = white
PortColor                      = white
FifoColor                      = white

ProcessNetworkClusterFontColor = black
ProcessNetworkFontColor        = black
ProcessFontColor               = black
PortFontColor                  = black
FifoFontColor                  = black

ProcessNetworkClusterFontName  = Helvetica
ProcessNetworkFontName         = Helvetica
ProcessFontName                = Helvetica
PortFontName                   = Helvetica
FifoFontName                   = Helvetica

ProcessNetworkClusterFontSize  = 20
ProcessNetworkFontSize         = 16
ProcessFontSize                = 16
PortFontSize                   = 16
FifoFontSize                   = 16

The options can be chosen from the following values:

• InitLevel: integer.
  The number of hierarchical levels that is shown. When set to 1, only the top level prosess network is shown, and all sub-networks are shown as simple nodes. When set to 2, the contents of the top level network and its sub-networks are shown.
• PageSize: A4p, A4l, A3p, A3l, A2p, A2l, A1p, A1l, A0p or A0l.
  Specifies the page size and orientation. For example, A4p represents A4 portrait, A2l represents A2 landscape, etc.
• Ratio: fill, compress, or auto.
  Fill stretches the drawing, whereas compress compresses the drawing to fit it in the given pagesize.
• Fifo: true, or false.
  If set to true, fifos are shown as diamond-shaped nodes, otherwise as normal edges.
• Decorate: true, or false.
  If set to true, a line is drawn that connects the fifo label with the edges. These lines are only visible in the postscript output, not in X (dotty).
• Color: white, lavender, gray, black, red, pink, brown, beige, orange, yellow, gold, green, cyan, blue, navy, magenta, purple, or violet.
• Font: Times-Roman, Helvetica, or Courier.