[ Home | What's New | Contents | Overview | Contributors | Distribution | Examples | Documentation | Manual | Publications | Mailing List Archive | Problems ] This page was last updated by Axel Belinfante on 2006-06-30
TorX Test Tool Information
Prev   Next

anifsm(1) - animate, construct or edit graphs in dot format

Table of Contents

Name

anifsm - animate, construct or edit graphs in dot format

Synopsis

anifsm [ -r ] [ -m mcastid ] [ -t title ] [ -k key ] [ dotfiles ]
anifsm [ -r ] [ -m mcastid ] [ -t title ] [ -k key ] -
anifsmsrv
anifsm -exit

Description

anifsm uses tcldot(1) to animate, construct or edit graphs in dot format. In TorX it is used to animate the automaton (RFSM) file(s) generated by jararaca(1), autexp(1), or any other explorer, and to on-the-fly construct the automaton of the test run. The automaton represented by the graph can be written out to file in Aldebaran (.aut) format. This allows anifsm to be used as a graphical editor to construct simple automata in Aldebaran (.aut) format.

After start up, anifsm creates a window (with the given title) for each file in dotfiles (or just a single window if no dotfiles was given, or if dotfiles consists only of the special name ``-'') in which it draws the automaton for that file and then for the last (or only) window waits for commands (for animation or layout) on standard input. The animation and layout commands are discussed below in COMMANDS. On end of file on standard input, or when the user removes the window (or presses the Quit button which tells anifsmsrv to stop running) anifsm exits.
Note: the special treatment of ``-'' is deprecated and may disappear is future versions.

In each anifsm window the graph can be edited (constructed, changed) using the mouse. The left mouse button is used to create nodes and edges; the right mouse button is used to delete them, to edit their attributes, and to post a pop-up menu which includes entries to save the graph to file in dot, Aldebaran (.aut), and Postscript format. For further details see EDITING below. Details of the transformation to Aldebaran (.aut) format are discussed below in AUTOMATON.

The middle mouse button can be used to scroll the canvas in its window by moving the mouse with the middle button pressed. When the middle button is clicked without moving the mouse the canvas of all clones of that window is scrolled to show the positition at which the mouse was clicked. When the Control key is pressed while the mouse is moved with the middle button pressed the canvases of all clones of the window are continuously scrolled to show the item under mouse.

Actually, anifsm is a shell-level command that uses a running anifsmsrv to load the named dot file, and animate it using animation commands on standard input. The connection between anifsm and a running anifsmsrv will not be closed until the complete standard input of the anifsm command has been processed by anifsmsrv. If anifsm cannot find a running anifsmsrv, it will start a new one. To display the new dot file, anifsm will reuse windows, but only those that contain a completed animation, and have the Reuse toggle activated. To choose which window to reuse, anifsm uses the -k key command line option. If there are reusable windows with the same key, one of those will be used. Otherwise, if anifsm was invoked without -k key option, it will look for reusable windows with a non-empty key. If anifsm was invoked with a non-empty -k key option, it will look for reusable windows with an empty key. If none of the above is succesful, a new window will be created.
In general, it should not be necessary to start anifsmsrv by hand.

The -r command line option of anifsm will activate the Reuse toggle button for the window that will contain the dotfile given on the same command line.

The -k key command line option of anifsm will associate key with the window in which the given dotfile is animated. The key will be displayed to the right of the Reuse button. The key is used to guide the reuse of windows in which the animation is finished, as discussed above.

To make a running anifsmsrv go away invoke anifsm with the -exit command line option.

The animation in the window will follow the animation commands read from standard input. The animation can be stepped through manually using the Step up and down arrow buttons (as discussed below in BUTTONS).

In addition, the animation can be remotely controlled. If the -m mcastid command line option is given, or environment variable TORXMCASTID was set, anifsm will attempt to make a remote control connection to the tcp address in mcastid. If it succeeds, it will then interpret lines of text read from the remote control connection consisting of a single number as commands to show the corresponding step in the animation. Additionally, whenever the user uses mouse button and/or navigation commands to show a different step, its step number is written to the remote control connection. The remote control connection allows multiple viewers to show the same test step.

Commands

Each animation or dot layout command consists of a single line of text. The animation and layout commands can appear interspersed, see EXAMPLES below. The display is updated after execution of each individual command (unless the Render button is disabled, in which case the display is not updated for dot layout commands).

The animation commands are expected to be generated using log2jararacy(1) and jararacy2anifsm(1), e.g. using a unix command as

log2jararacy < logfile | jararacy2anifsm | anifsm dotfile
or
tail -f logfile | log2jararacy | jararacy2anifsm | anifsm dotfile
Make sure that the logfile contains a run of the automaton present in dotfile.

A mix of animation and layout (graph operation) commands is expected to be generated by log2anifsm(1) e.g. using a unix command as

log2anifsm < logfile | anifsm -
or
tail -f logfile | log2anifsm | anifsm -

Of course, layout and animation commands can also be generated by other programs, or even be written by hand.

Layout Commands

The dot layout (graph operation) commands start with the word dot, followed by the command (either subgraph, node, edge, delnode, or deledge), followed by the argument to the command, followed by optional attributes. The items in a dot layout command are separated by whitespace. For each optional attribute its name and its value are given, separated by whitespace. The general form is:
dot command argument aname avalue aname avalue ...

Known layout commands and their arguments are:

dot subgraph subgraphname aname avalue aname avalue ...
Create a subgraph named subgraphname. Each group of aname and avalue defines an attribute of the subgraph. The usual dot subgraph attributes can be specified. An attribute with name subgraph is treated special, to allow definition of nested subgraphs. The subgraphname can be used in subsequent subgraph or node commands, as value of an attribute named subgraph to add the a new subgraph or node to the subgraph specified earlier. See EXAMPLES below.
dot node nodename aname avalue aname avalue ...
Create a node named nodename. Each group of aname and avalue defines an attribute of the node. The usual dot node attributes can be specified. An attribute with name subgraph is treated special: it indicates that the node should be created in the subgraph with the name given in the value of the attribute. This subgraph should have been defined earlier. (Apart from the special treatment of the subgraph attribute) this commands corresponds to a dot file line of
nodename [ aname=avalue, aname=avalue, ... ]
The nodename can be used in subsequent dot edge dot layout commands. It is not necessary to define all nodes using this command: if no attributes need to be given, nodes can be implicitly defined in the dot edge commands. The nodename will also be used as the label of the node in the animation, unless a label attribute is specified among the aname and avalue. In this respect it is very much like a node definition in an ordinary dot input file.
dot edge edgelist aname avalue aname avalue ...
Create one or more edges (and, implicitly nodes, for those nodes listed in edgelist that do not yet exist) as specified by edgelist which consists of a list of node names separated by -> (without any whitspace). So edgelist is of the form src->dst or n1->n2->n3 etc. Such a dot edge command specifies an edge from node src to node dst, or from n1 to n2 to n3, and each group of aname and avalue defines an attribute of the edge. It corresponds to a dot file line of
src -> dst [ aname=avalue, aname=avalue, ... ]
The usual dot edge attributes can be specified.
dot delnode nodename
Delete the node or nodes specified by nodename, together with their (incoming or outgoing) edges, from the graph.
dot deledge edge
Delete the edge or edges specified by edge (a list of nodenames separated by -> or the value of a name attribute specified for an edge) from the graph.

Color Animation Commands

The animation commands consist of alternating commands and arguments:
command arguments command arguments ...
Known commands and their arguments are:
-c color
where color should be a color known by tcl/tk.
-n nodes
where nodes consists of a whitespace separated list of node identifiers.
-e edges
where edges consists of a whitespace separated list of edge identifiers.
-- word
do not try to interpret word as a command, but use it literally.

The node identifiers should be present in the dotfile or given in dot node or dot edge commands. The edge identifiers should be given in the dotfile as the value of a name attribute of an edge, as for example e42 is given in

src -> dst [label=action, name=e42 , ...];
Alternatively, an edge identifier can be of the form
src->dst
(note: no whitespace between src, -> and dst) where src and dst are node identifiers. Note, however, that if src and dst are linked by multiple edges, an arbitrary one will be chosen! It is much safer to rely on name attributes in the dotfile.
During animation, the given states and edges will be colored as indicated by the -c color command preceding it (reading from left to right). The initial color is red. An initial -n command is implied and may be omitted. Nodes and edges that are not mentioned in a command will have their initial color, as specified in the dotfile. If a node or edge is mentioned multiple times on a single command line, it will be colored according to the color specified for its last (rightmost) occurence.

Buttons

At the bottom of an anifsm window there are several buttons. The Zoom up and down arrow buttons zoom out resp. in. When zooming, the font size is adjusted accordingly. When the fontsize becomes too small to be usable, only the nodes and edges are drawn and the node and edge labels are omitted. When, as a consequence of zooming in, the fontsize increases again sufficiently, the node and edge labels are shown again.
The Fit button zooms the animation to fit in the window. If the Auto toggle button is enabled, the animation is automatically zoomed to fit the window when the window is resized.
If the Render toggle button is enabled (which is the default) dot layout commands read from standard input have immediate effect. Otherwise, the layout displayed will not be updated until the Render toggle button is enabled again.
The step number of the animation step in the trace is shown in the Step field. Step numbers start at 0, for the initial state. To visualize the animation step for a known step, enter the step number in the Step entry field, and hit the return key. If a step number is present in the Step field, the down and up arrow buttons can be used to step backwards resp. forwards in the animation.
The Reuse toggle button indicates that its window may be reused for a new dotfile, when end-of-input has been seen for the dotfile currently displayed in it. While an animation is in progress (so, when end-of-input has not yet been seen) the Reuse button is disabled. (default value: unset, except when overridden by a -r command line option of anifsm).
To the right of the Reuse button, a menu button displays the current key value. The key value is used to guide the reuse of the window. Pressing the key menu button pops up a menu that offers the choice between all ``known'' keys. While an animation is in progress (so, when end-of-input has not yet been seen) the key menu button is disabled. (default value: empty, except when overridden by a -k key command line option of anifsm ).
The Clone button creates a new anifsm window, showing the same animated dot file. As described above the canvas of the clone(s) can be made to scroll simultaneously to show the same item.
The Close button closes the window, and, if this was the last remaining anifsm window, exits the anifsmsrv program.
The Quit button closes all anifsm windows and exits the anifsmsrv program.

Editing

The mouse can be used to edit the graph in an anifsm window. The left mouse button is used to create nodes and edges, the right mouse button is used to delete them, to edit their attributes, and to post a pop-up menu.

Clicking the left mouse button on the background of the canvas creates a new node.

Pressing the left mouse button on (in) a node and (while keeping the mouse button pressed) moving the mouse slightly starts the creation of an edge, as indicated by the red arrow which then appears. If the left mouse button is then released with the mouse cursor on (in) a node, an edge is created from the originating node to the destination node. If these nodes are the same a self-loop is created. If the mouse was released while the mouse cursor was not in a node, no edge is created (this can be used to cancel the creation of an edge). Just clicking the left mouse button on a node without moving the mouse at all does nothing (to avoid having to remove lots of unwanted self-loops).

Pressing the right mouse button on a node or edge pops up an attribute edit box, which allows editing of node or edge attributes, and deletion of the node or edge. The top part of the edit box contains attribute names (on the left) with their current values (on the right). The values that can be changed appear in entry fields. To change a value, edit it in the entry field, and press the return key to 'commit' the change. To add an attribute not yet present, enter its name in the empty entry field on the left (under the 'known' attribute names), and its value in its corresponding entry field on the right, and press the return key.
At the bottom of the edit box there are two buttons: Delete, which deletes the node or edge from the graph, and Dismiss, which makes the edit box disappear.

Pressing the right mouse button on a the background of the canvas pops up a menu that contains commands to create a new (inititially empty) window, to open (read) a dot file, to show some information, to connect to an mcast session, to write the graph in the window in dot, Aldebaran (.aut), or postscript format, and to pop up an edit box to edit global graph, node or edge attributes.

Automaton

The graph in the window can be interpreted as an automaton. Special node attributes are used to indicate the start state, and to indicate those graph nodes that are not part of the automaton (those graph nodes will not be present in the automaton written in Aldebaran (.aut) format). Initial values of these attributes are set when the dot file is read, or, if no dot file was given, when the graph is constructed.
autstart
when set to 1, indicates that this node is to be the start state of the (Aldebaran, .aut) automaton represented by the graph. At most one node in the graph can have this attribute with a non-zero and/or non-empty value.
autexclude
when set to 1, indicates that this node should not appear in the (Aldebaran, .aut) automaton. When reading an automaton or graph from file, nodes of which either the node name or the value of the label attribute starts with an underscore will have this attribute set to 1.

When a graph is read or constructed, the start state will be determined as follows. Initially, the first node created in a graph will be the start state. Then, the nodes are inspected and where applicable autexclude attributes will be set. Finally the edges are inspected. If there is an edge from an aut-excluded node to a non-aut-excluded node, the non-aut-excluded will be the start state of the automaton. If there are multiple such edges, the 'last' one 'wins'.

When the Aldebaran (.aut) file is written, the transition names are taken from the label attributes of the edges. The state names are determined as follows. If a graph node has a label attribute, it is used to determine the state name, otherwise the node name is used. If all such names (of all non-autexcluded graph nodes) consist of the same string prefix followed by a number, the numbers are used as state numbers in the Aldebaran file. Otherwise the complete names are used (which make them just be numbers).

Attributes

A number of node and edge attributes have direct effect on the appearance of the graph in anifsm (even though they (mostly) have no effect on the automaton). The definitive reference for these is the dot(1) manual page; we only list a number of them here for convenience.

In addition to the attribute names understood by dot there are a few node and edge attribute names that dot does not care about, but that are special for anifsm.

Attributes that have no value yet (that have the empty value) appear with {} as value in the edit box.

Dot Node Attributes

label
the text that appears in a node. The value {\\N} is special: it indicates that the node name should be used as label.
color
the color of the node
fillcolor
the fill color of the node, if its style is set to filled (if fillcolor is not set the value of color will be used)
style
for example, filled
shape
the shape of the node.

Dot Edge Attributes

label
the text that appears with an edge.
color
the color of the edge and its accompanying text

Anifsm Node Attributes

autstart
when set to 1, indicates that this node is to be the start state of the (Aldebaran, .aut) automaton represented by the graph. At most one node in the graph can have this attribute with a non-zero and/or non-empty value.
autexclude
when set to 1, indicates that this node should not appear in the (Aldebaran, .aut) automaton.
subgraph
gives the name of the subgraph to which the node belongs.

Anifsm Edge Attributes

name
identifies the edge. This name can be used, for example, during animation to hightlight the edge. The same name may be assigned to multiple edges (which all will be highlighted when the name is used in an animation command).

Examples

Valid commands are:
S0
-n S0
-c red -n S0
-c #f00 -n S0
to color node S0 red; the commands are equivalent, the first uses the defaults. The last shows that in addition to color names also the #rgb color specifications of tcl/tk can be used.
-c green S0
to color node S0 green;
-c green S0 S1 -e e0 -c blue e1 -n S2 S3 S4 -e e2
to color nodes S0 and S1 and edge e0 green and nodes S2, S3 and S4 and edges e1 and e2 blue;
-e e0
to color edge e0 red.

Example of mix of dot layout and animation commands (note that we do not have to use dot node commands if we do not need to specify attributes for the nodes, and we do not have multiple nodes with the same name). We specify edges between nodes a, b, and c, with name attributes that we use in subsequent animation commands, and for the edge from a to c we specify a ``backwards'' direction, equivalent to dir=back in a dot file. We then specify some additional edges, without name attribute, so we use the src->dst notation to refer to them in the subsequent animation commands.


dot edge a->b name e0
dot edge b->c name e1
dot edge a->c name e2 dir back
-e e0
-e e1
-e e2
dot edge a->d
dot edge d->c
-e a->d
-e d->c
-e e2

Example of the creation of subgraphs. With the subgraph definition and subgraph attribute in the definition of both nodes a and d both nodes will be at the top, having the same rank. Without the subgraph definition node d would be next to node b.


dot subgraph g1 rank same
dot node a subgraph g1
dot node b
dot node c
dot node d subgraph g1
dot edge a->b
dot edge b->c
dot edge d->c
The three dot edge lines above can be combined into two:

dot edge a->b->c
dot edge d->c

Diagnostics

Error messages and navigation diagnostics appear on standard error.

Bugs

The environment variable TORX_ROOT is not supported.

Because the animation commands are read from standard input, it is not possible to read the dotfile from standard input. However, the (new) dot layout commands that can be given on standard input compensate for that to a certain extent.

The window does not automatically scroll to follow the colored states.

After an syntax error has been encountered in an input dotfile, tcldot(1) (at least the version in GraphViz 1.8.5) seems to be unable to recover sufficiently to be able to read more (syntactly correct) dotfiles.

After the revision of the syntax of the commands accepted on standard input to make it more general and take out the TorX specific features, the language accepted by anifsm differs from the one accepted by jararacy(1). The difference between the two is bridged by jararacy2anifsm(1). However, the fact that we have this difference breaks the fall-back to jararacy(1) that used to be present in anifsm, because if this fall-back would be used, jararacy(1) would be given the revised commands which it will not understand. As a consequence, the fall-back has been removed: if anifsm can not find tcl package Tcldot it will just give up.

The usage of autstart and autexclude attributes to indicate automaton features of the graph is clumsy.

When the attribute edit box is popped up, it tries to position itself under the mouse cursor, in an attempt to reduce the necessary mouse movements. We added this in the hope that it would be benificial, but it works not as benificial as intended: the fact that the box is moving all the time is very annoying. To be fixed.

There is no indication that a graph that was read in from a dot file has been altered using mouse commands.

There are no distinct view and edit modes (editing is always enabled). There is not enough experience (yet) with anifsm to tell whether such modes are actually needed, though.

See Also

torx-intro(1), jararaca(1), jararacy2anifsm(1), log2jararacy(1), dot(1), doted(1), tcldot(1), jararacy(1), torx-logclient(1), tmcs(1), anifsm(1), aniwait(1), mscviewer(1), environ(5)

Acknowledgements

Parts of anifsm (in particular the zooming and graph editing code) have been lifted and adapted from:
doted - dot graph editor - John Ellson (ellson@graphviz.org)

Contact

By Email: <torx_support@cs.utwente.nl>

Version

This manual page documents version 3.9.0 of torx.


Table of Contents


Prev Table of Contents Next
Appendix D: TorX Manual Pages: adaptsim(1) - torx program to interface to a TorX primer used as SUT Valid HTML 4.01! Appendix D: TorX Manual Pages: anifsmsrv(1)