Tcl programming interface

Right after shell start, the Tcl wrapper provides a single object command, goblin. This library root object serves as as a factory of graph objects and mixed integer programs. And generating a library object implies generating the respective Tcl object command.

For the time being, this Tcl command reference is not complete but, at least, covers all graph object commands. Descriptions for the missing LP / MIP commands will be added after some necessary interface cleanup steps.

Object instanciation

Objects are instanciated by sending one of the following messages to the goblin root object:

The general command structure is goblin <class_name> <options> <object_name>. The results are a GOBLIN library object and a new Tcl command <object_name> to address the library object. Example:

    goblin regularTree -depth 5 -deg 2 myTree
generates a regular tree named myTree. A regular tree is a special case of a sparseDiGraph object, and the respective Tcl command accepts the same command options as if it was generated like goblin sparseDiGraph <options> myTree.

Object classification

To obtain the inherent type of a data object, use the command structure <object_name> info -<class_specifier>:

By the same syntax, graph object can be classified more detailed:

The preceding commands only evaluate the type of the C++ core library object. For example, if a graph object has been instanciated as a mixedGraph, both <object_name> info -directed and <object_name> info -undirected return false, irrespective of the actual arc orientations.

The following options are different in that a high-level recognition method is called:

Default values

Many object commands allow to explicitly pass default, undefined or infinite values instead of concrete parameter values. In all such cases, an asterisk * applies. For example,
    goblin polarGrid -rows 4 -columns 4 myGraph
    myGraph spanningTree -rootNode *
    goblin polarGrid -rows 4 -columns 4 myGraph
    myGraph spanningTree
are equivalent codes, as specifying an undefined root node explicitly instructs the spanning tree method to select a root node by the a certain default rule: The immediate results of
    myGraph configure -rootNode $r
    myGraph spanningTree
    myGraph spanningTree -rootNode $r
    myGraph configure -rootNode $r
    myGraph spanningTree -rootNode [myGraph info -rootNode]
are the same, but the configure command makes the root node selection persistent. That is, subsequent vertex routing method calls apply the configured root node, even if the graph object is written to and reread from file.

With a few exceptions, this substitution of missing -rootNode, -sourceNode and -targetNode parameters applies to all optimization and layout commands:

The default rules and its exceptions even apply when the C++ interface is used.

Graph Composition

To construct a graph object from another, the general command structure <original_object> <derived_class> <options> <derived_object> and some of the following options apply:

For undirected graphs only:

For digraphs only:

Graph Optimization

For digraphs only:

For undirected graphs only:

For balanced digraphs only:

Graph Layout

Graph visualization is controlled with messages like <object_name> layout ... and the following options:

As an example,

    goblin polarGrid -rows 4 -columns 4 myGraph
    myGraph layout orthogonal -small
generates a 4-planar, face-regular graph and determines an orthogonal plane drawing with small nodes for it.

Retrieving information about graph objects

The following problem dimensions can be queried from graph objects:

For bigraphs objects only:

Most attributes are associated with graph nodes and edges, and the access to particular attribute values is described later. What follows is a list of commands which refer to node or arc attributes, but not to a specific node or arc entity:

Retrieving arc attribute values

Graph arc retrieval messages all start like <object_name> arc <arc index> info .... Most messages do not actually depend on the arc direction, but all expect arc indices including the direction bit:

Retrieving node attribute values

Graph node retrieval messages start like <object_name> node <node index> info ...:

Retrieving layout point attribute values

Layout point retrieval messages start like <object_name> layout point <point index> info ...:

Graph Manipulation

For sparse graph objects only:

Setting Arc Attribute Values

Graph arc manipulation messages all start like <object_name> arc <arc index> .... Most messages do not actually depend on the arc direction, but all expect arc indices including the direction bit.

Setting Node Attribute Values

Graph node manipulation messages all start like <object_name> node <node index> ...

For sparse bigraphs objects only:

Manipulating layout points

Layout point manipulation messages all start like <object_name> layout point <point index> ...

Writing graph objects to file

The message write <file name> applies to all library data objects. The output depends, however, on the concrete data object type. For the time being, only the proprietary formats are supported.