The TikZ and PGF Packages
Manual for version 3.1.10

\usepgflibrary{graphdrawing} % LaTeX and plain TeX
\usepgflibrary[graphdrawing] % ConTeXt

This package provides the core support for graph drawing inside pgf. It does so by providing pgf macros for controlling the graph drawing system, but also implements the binding to the graph drawing system (see Section 39 for details on bindings).

This macro starts a TeX scope inside which the following things happen:

• 1. The display layer method beginGraphDrawingScope is called, which created a new graph drawing scope inside the graph drawing system and places it on top of an internal stack. From now on, all subsequent interface calls will refer to this scope until \pgfgdendscope is called, which will pop the scope once more.

• 2. Inside the TeX scope, nodes are not placed immediately. Rather, \pgfpositionnodelater, see Section 106.2.3, is used to call InterfaceToDisplay.createVertex for all nodes created inside the scope. This will cause them to be put inside some internal table.

• 3. Some additional ⟨code⟩ is executed, which has been set using the following command:

  \pgfgdaddspecificationhook{⟨code⟩} ¶

  This command adds the ⟨code⟩ to the code that is executed whenever a graph drawing scope starts. For instance, the TikZ library graphdrawing uses this macro to add some ⟨code⟩ that will redirect the edge and edge from parent path commands to \pgfgdedge.

• 4. \pgftransformreset is called.

• 5. The following TeX-if is set to true:

  \ifpgfgdgraphdrawingscopeactive ¶

  Will be true inside a graph drawing scope.

The above has a number of consequences for what can happen inside a graph drawing scope:

• • Since nodes are not actually created before the end of the scope, you cannot reference these nodes. Thus, you cannot write

  copy
\tikz [spring layout] {
\node (a) {a};
\node (b) {b};
\draw (a) -- (b);
}


  The problem is that we cannot connect (a) and (b) via a straight line since these nodes do not exist at that point (they are available only deeply inside the Lua).

• • In order to create edges between nodes inside a graph drawing scope, you need to call the \pgfgdedge command, described below.

Additionally, when TikZ is used, the following things also happen:

• • If the graphs library has been loaded, the default positioning mechanisms of this library are switched off, leaving the positioning to the graph drawing engine. Also, when an edge is created by the graphs library, this is signalled to the graphdrawing library. (To be more precise: The keys new -> and so on are redefined so that they call \pgfgdedge instead of creating an edge.

• • The edge path command is modified so that it also calls \pgfgdedge instead of immediately creating any edges.

• • The edge from parent path command is modified so that is also calls \pgfgdedge.

• • The keys append after command and prefix after command keys are modified so that they are executed only via late options when the node has “reached its final parking position”.

Note that inside a graph drawing scope you first have to open a (main) layout scope (using the \pgfgdbeginlayout command described later on) before you can add nodes and edges to the scope.

This macro is used to end a graph drawing scope. It must be given on the same TeX grouping level as the corresponding \pgfgdbeginscope. When the macro is called, it triggers a lot of new calls:

• 1. The special treatment of newly created boxes is ended. Nodes are once more created normally.

• 2. The effects of the ⟨code⟩ that was inserted via the specification hook command also ends (provided it had no global effects).

• 3. We call InterfaceToDisplay.runGraphDrawingAlgorithm. This will cause the algorithm(s) for the graph to be executed (since a graph can have sublayouts, several algorithms may be run). See Section 29.3 below.

• 4. Next, we call InterfaceToDisplay.endGraphDrawingScope. This causes all nodes that were intercepted during the graph drawing scope to be reinserted into the output stream at the positions that were computed for them. Also, for each edge that was requested via \pgfgdedge, the callback macro is called (see below).

This command is used to tell the graph drawing engine that there is an edge between ⟨first node⟩ and ⟨second node⟩ in your graph. The “kind” of connection is indicated by ⟨direction⟩, which may be one of the following:

• • -> indicates a directed edge (also known as an arc) from ⟨first node⟩ to ⟨second node⟩.

• • -- indicates an undirected edge between ⟨first node⟩ and ⟨second node⟩,

• • <- indicates a directed edge from ⟨second node⟩ to ⟨first node⟩, but with the “additional hint” that this is a “backward” edge. A graph drawing algorithm may or may not take this hint into account.

• • <-> indicates a bi-directed edge between ⟨first node⟩ and ⟨second node⟩.

• • -!- indicates that the edge from ⟨first node⟩ to ⟨second node⟩ is “missing”.

Note that in all cases, the syntactic digraph will contain an arc from ⟨first node⟩ to ⟨second node⟩, regardless of the value of ⟨direction⟩. The ⟨direction⟩ is “just” a “semantic annotation”.

The parameters ⟨edge options⟩ and ⟨edge nodes⟩ are a bit more tricky. When an edge between two vertices of a graph is created via \pgfgdedge, nothing is actually done immediately. After all, without knowing the final positions of the nodes ⟨first node⟩ and ⟨second node⟩, there is no way of creating the actual drawing commands for the edge. Thus, the actual drawing of the edge is done only when the graph drawing algorithm is done (namely in the macro \pgfgdedgecallback, see later).

Because of this “delayed” drawing of edges, options that influence the edge must be retained until the moment when the edge is actually drawn. Parameters ⟨edge options⟩ and ⟨edge nodes⟩ store such options.

Let us start with ⟨edge options⟩. This parameter should be set to a list of key–value pairs like

Some of these options may be of interest to the graph drawing algorithm (like the last option) while others will only be important during the drawing of edge (like the first option). The options that are important for the graph drawing algorithm must be pushed onto the graph drawing system’s option stack.

The tricky part is that options that are of interest to the graph drawing algorithm must be executed before the algorithm starts, but the options as a whole are usually only executed during the drawing of the edges, which is after the algorithm has finished. To overcome this problem, the following happens:

The options in ⟨edge options⟩ are executed “tentatively” inside \pgfgdedge. However, this execution is done in a “heavily guarded sandbox” where all effects of the options (like changing the color or the line width) do not propagate beyond the sandbox. Only the changes of the graph drawing edge parameters leave the sandbox. These parameters are then passed down to the graph drawing system.

Later, when the edge is drawn using \pgfgdedgecallback, the options ⟨edge options⟩ are available once more and then they are executed normally.

Note that when the options in ⟨edge options⟩ are executed, no path is preset. Thus, you typically need to start it with, say, /tikz/.cd. Also note that the sandbox is not perfect and changing global values will have an effect outside the sandbox. Indeed, “putting things in a sandbox” just means that the options are executed inside a TeX scope inside an interrupted path inside a TeX box that is thrown away immediately.

The text in ⟨edge nodes⟩ is some “auxiliary” text that is simply stored away and later directed to \pgfgdedgecallback. This is used for instance by TikZ to store its node labels.

This command allows you to change the ⟨macro⟩ that gets called form inside the graph drawing system at the end of the creation of a graph, when the nodes have been positioned. The ⟨macro⟩ will be called once for each edge with the following parameters:

⟨macro⟩{⟨first node⟩}{⟨second node⟩}{⟨direction⟩}{⟨edge options⟩}{⟨edge nodes⟩}
{⟨algorithm-generated options⟩}{⟨bend information⟩}{⟨animations⟩}

The first five parameters are the original values that were passed down to the \pgfgdedge command.

The ⟨algorithm-generated options⟩ have been “computed by the algorithm”. For instance, an algorithm might have determined, say, flow capacities for edges and it might now wish to communicate this information back to the upper layers. These options should be executed with the path /graph drawing.

The parameter ⟨bend information⟩ contains algorithmically-computed information concerning how the edge should bend. This will be a text like (10pt,20pt)--(30pt,40pt) in TikZ-syntax and may include the path commands --, .. (followed by Bézier coordinates), and --cycle.

The last parameter ⟨animations⟩ contains algorithmically-generated animation commands (calls to \pgfanimateattribute). The whom will be set to pgf@gd.

The default ⟨macro⟩ simply draws a line between the nodes. When the graphdrawing library of the TikZ layer is loaded, a more fancy ⟨macro⟩ is used that takes all of the parameters into account.

This command first starts a new TeX scope and then informs the display layer that a new (sub)layout should be started. For each graph there may be a hierarchy of layouts, each of which contains a certain number of vertices and edges. This hierarchy is created through calls to this macros and the corresponding calls of \pgfgdendlayout. For each graph drawing scope there has to be exactly one main layout that encompasses all nodes and edges and also all sublayouts. Thus, after a graph drawing scope has been opened, a layout scope also needs to be opened almost immediately.

For each layout created via this macro, a graph drawing algorithm will be run later on the subgraph of all nodes that make up the layout. Which algorithm is run for the layout is dictated by which layout key (one of the ... layout keys) is “in force” when the macro is called. Thus, using a layout key for selecting an algorithm must always be done before the layout is started. (However, see the discussion of layout keys in the next subsection for more details on what really happens.)

A vertex can be part of several layouts, either because they are nested or because they overlap (this happens when a node is later on added to another layout by calling \pgfgdsetlatenodeoption). This means that it is not immediately obvious how conflicts arising from the different ways different algorithms “would like to place nodes” should be resolved. The method for this resolving is detailed in Section 28.10.3.

This command ends the TeX scope of the current layout. Once closed, no nodes or edges can be added to a layout.

This command can only be called when the node named ⟨node name⟩ has already been created inside the current graph drawing scope. The effect of calling this macro will be that all options currently on the graph drawing system’s option stack will be added to the node’s option, possibly overwriting the original option settings. Furthermore, the node will become part of all layouts currently on the option stack. This means that you can use this command to add a node to several layouts that are not included in one another.

This command sets up ⟨macro⟩ as the macro that is called whenever a layout key “requests” that a layout and, possibly, a graph drawing scope is opened. When ⟨macro⟩ is called, it gets two parameters, the ⟨begin code⟩ and the ⟨end code⟩. In addition to whatever setup the ⟨macro⟩ would like to do, it should execute the ⟨begin code⟩ at the beginning of a TeX scope (the code will open graph drawing and layout scopes) and the ⟨end code⟩ at the end of the same TeX scope.

The need for this slightly strange macro arises from the fact that in TikZ we often write things like [spring layout,node sep=2cm]. The point is that when the spring layout key is executed, we do not wish to open a layout scope immediately. Rather, this should happen only after the option nodes sep=2cm has been executed. For this reason, TikZ sets up a special ⟨macro⟩ that “delays” the execution of the ⟨begin code⟩ until the end of the opening of the next scope.

Because of this, in TikZ layout keys can only be used as an option when a TikZ scope is started. Thus, you can pass them to \tikz, to {tikzpicture}, to \scoped, to {scope}, to graph, and to {graph}. For instance, the tree layout option can be used in the following ways:

You can not use layout keys with a single node or on a path. In particular, to typeset a tree given in the child syntax somewhere inside a {tikzpicture}, you must prefix it with the \scoped command:

Naturally, the above could have been written more succinctly as

Or even more succinctly:

Calls createEvent of the graph drawing system’s interface class. This creates a new Event object on the Lua layer whose kind field is set to ⟨kind⟩ and the parameters field to ⟨parameter⟩. You must be inside a graph drawing scope to use this command.

Starts an event group. This just means that an Event of kind begin is created with the given ⟨parameter⟩.

Ends an event group. This is done by adding an event of kind end without any parameters to the event string.

Starts an event group just like \pgfgdbegineventgroup, but adds a corresponding closing end event at the end of the current TeX group (using \aftergroup).

A subgraph node is a node that “surrounds” the nodes of a subgraph. The special property of a subgraph node opposed to a normal node is that it is created only after the subgraph has been laid out. However, the difference to a collection like hyper is that the node is available immediately as a normal node in the sense that you can connect edges to it.

What happens internally is that subgraph nodes get “registered” immediately both on the pgf level and on the Lua level, but the actual node is only created inside the layout pipeline using a callback. The actual node creation happens when the innermost layout in which the subgraph node is declared has finished.

When you create a subgraph node using this macro, you also start a collection (of an internal kind) that stores the subgraph. All following nodes in the current TeX scope will become part of this collection.

The ⟨name⟩ is the node name by which you can refer to this node in the following. The ⟨node options⟩ are normal pgf options (like red or draw or circle) that will influence the appearance when it is created later on. The ⟨node text⟩ is the text that will be passed to \pgfnode upon creation of the node.

See InterfaceToDisplay.pushSubgraphVertex for more details.