| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% Copyright 2019 by Jannis Pohlmann |
| 3 |
% |
| 4 |
% This file may be distributed and/or modified |
| 5 |
% |
| 6 |
% 1. under the LaTeX Project Public License and/or |
| 7 |
% 2. under the GNU Free Documentation License. |
| 8 |
% |
| 9 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 10 |
|
| 11 |
|
| 12 |
\section{Specifying Graphs} |
| 13 |
\label{section-library-graphs} |
| 14 |
|
| 15 |
\subsection{Overview} |
| 16 |
|
| 17 |
\tikzname\ offers a powerful path command for specifying how the nodes in a |
| 18 |
graph are connected by edges and arcs: The |graph| path command, which becomes |
| 19 |
available when you load the |graphs| library. |
| 20 |
|
| 21 |
\begin{tikzlibrary}{graphs} |
| 22 |
The package must be loaded to use the |graph| path command. |
| 23 |
\end{tikzlibrary} |
| 24 |
|
| 25 |
In this section, by \emph{graph} we refer to a set of nodes together with some |
| 26 |
edges (sometimes also called arcs, in case they are directed) such as the |
| 27 |
following: |
| 28 |
% |
| 29 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 30 |
\tikz \graph { a -> {b, c} -> d }; |
| 31 |
\end{codeexample} |
| 32 |
|
| 33 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 34 |
\tikz \graph { |
| 35 |
subgraph I_nm [V={a, b, c}, W={1,...,4}]; |
| 36 |
|
| 37 |
a -> { 1, 2, 3 }; |
| 38 |
b -> { 1, 4 }; |
| 39 |
c -> { 2 [>green!75!black], 3, 4 [>red]} |
| 40 |
}; |
| 41 |
\end{codeexample} |
| 42 |
|
| 43 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 44 |
\tikz |
| 45 |
\graph [nodes={draw, circle}, clockwise, radius=.5cm, empty nodes, n=5] { |
| 46 |
subgraph I_n [name=inner] --[complete bipartite] |
| 47 |
subgraph I_n [name=outer] |
| 48 |
}; |
| 49 |
\end{codeexample} |
| 50 |
|
| 51 |
\begin{codeexample}[ |
| 52 |
preamble={\usetikzlibrary{graphs}}, |
| 53 |
pre={\definecolor{graphicbackground}{rgb}{0.96,0.96,0.8}}, |
| 54 |
] |
| 55 |
\tikz |
| 56 |
\graph [nodes={draw, circle}, clockwise, radius=.75cm, empty nodes, n=8] { |
| 57 |
subgraph C_n [name=inner] <->[shorten <=1pt, shorten >=1pt] |
| 58 |
subgraph C_n [name=outer] |
| 59 |
}; |
| 60 |
\end{codeexample} |
| 61 |
|
| 62 |
\begin{codeexample}[width=6.6cm,preamble={\usetikzlibrary{graphs}}] |
| 63 |
\tikz [>={To[sep]}, rotate=90, xscale=-1, |
| 64 |
mark/.style={fill=black!50}, mark/.default=] |
| 65 |
\graph [trie, simple, |
| 66 |
nodes={circle,draw}, |
| 67 |
edges={nodes={ |
| 68 |
inner sep=1pt, anchor=mid, |
| 69 |
fill=graphicbackground}}, % yellowish background |
| 70 |
put node text on incoming edges] |
| 71 |
{ |
| 72 |
root[mark] -> { |
| 73 |
a -> n -> { |
| 74 |
g [mark], |
| 75 |
f -> a -> n -> g [mark] |
| 76 |
}, |
| 77 |
f -> a -> n -> g [mark], |
| 78 |
g[mark], |
| 79 |
n -> { |
| 80 |
g[mark], |
| 81 |
f -> a -> n -> g[mark] |
| 82 |
} |
| 83 |
}, |
| 84 |
{ [edges=red] % highlight one path |
| 85 |
root -> f -> a -> n |
| 86 |
} |
| 87 |
}; |
| 88 |
\end{codeexample} |
| 89 |
|
| 90 |
The nodes of a graph are normal \tikzname\ nodes, the edges are normal lines |
| 91 |
drawn between nodes. There is nothing in the |graphs| library that you cannot |
| 92 |
do using the normal |\node| and the |edge| commands. Rather, its purpose is to |
| 93 |
offer a concise and powerful way of \emph{specifying} which nodes are present |
| 94 |
and how they are connected. The |graphs| library only offers simple methods for |
| 95 |
specifying \emph{where} the nodes should be shown, its main strength is in |
| 96 |
specifying which nodes and edges are present in principle. The problem of |
| 97 |
finding ``good positions on the canvas'' for the nodes of a graph is left to |
| 98 |
\emph{graph drawing algorithms}, which are covered in Part~\ref{part-gd} of |
| 99 |
this manual and which are not part of the |graphs| library; indeed, these |
| 100 |
algorithms can be used also with graphs specified using |node| and |edge| |
| 101 |
commands. |
| 102 |
% |
| 103 |
\ifluatex |
| 104 |
As an example, consider the above drawing of a trie, which is drawn without |
| 105 |
using the graph drawing libraries. Its layout can be somewhat improved by |
| 106 |
loading the |layered| graph drawing library, saying |\tikz[layered layout,...|, |
| 107 |
and then using Lua\TeX, resulting in the following drawing of the same graph: |
| 108 |
\medskip |
| 109 |
|
| 110 |
\tikz [layered layout, >={To[sep]}, rotate=90, xscale=-1, |
| 111 |
mark/.style={fill=black!50}, mark/.default=] |
| 112 |
\graph [trie, simple, sibling distance=8mm, |
| 113 |
nodes={circle,draw}, |
| 114 |
edges={nodes={ |
| 115 |
inner sep=1pt, anchor=mid, fill=white}}, |
| 116 |
put node text on incoming edges] |
| 117 |
{ |
| 118 |
root[mark] -> { |
| 119 |
a -> n -> { |
| 120 |
g [mark], |
| 121 |
f -> a -> n -> g [mark] |
| 122 |
}, |
| 123 |
f -> a -> n -> g [mark], |
| 124 |
g[mark], |
| 125 |
n -> { |
| 126 |
g[mark], |
| 127 |
f -> a -> n -> g[mark] |
| 128 |
} |
| 129 |
}, |
| 130 |
{ [edges=red] % highlight one path |
| 131 |
root -> f -> a -> n |
| 132 |
} |
| 133 |
}; |
| 134 |
\medskip |
| 135 |
\fi |
| 136 |
|
| 137 |
The |graphs| library uses a syntax that is quite different from the normal |
| 138 |
\tikzname\ syntax for specifying nodes. The reason for this is that for many |
| 139 |
medium-sized graphs it can become quite cumbersome to specify all the nodes |
| 140 |
using |\node| repeatedly and then using a great number of |edge| command; |
| 141 |
possibly with complicated |\foreach| statements. Instead, the syntax of the |
| 142 |
|graphs| library is loosely inspired by the \textsc{dot} format, which is quite |
| 143 |
useful for specifying medium-sized graphs, with some extensions on top. |
| 144 |
|
| 145 |
|
| 146 |
\subsection{Concepts} |
| 147 |
|
| 148 |
The present section aims at giving a quick overview of the main concepts behind |
| 149 |
the |graph| command. The exact syntax is explained in more detail in later |
| 150 |
sections. |
| 151 |
|
| 152 |
|
| 153 |
\subsubsection{Concept: Node Chains} |
| 154 |
|
| 155 |
The basic way of specifying a graph is to write down a \emph{node chain} as in |
| 156 |
the following example: |
| 157 |
% |
| 158 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 159 |
\tikz [every node/.style = draw] |
| 160 |
\graph { foo -> bar -> blub }; |
| 161 |
\end{codeexample} |
| 162 |
|
| 163 |
As can be seen, the text |foo -> bar -> blub| creates three nodes, one with |
| 164 |
the text |foo|, one with |bar| and one with the text |blub|. These nodes are |
| 165 |
connected by arrows, which are caused by the |->| between the node texts. Such |
| 166 |
a sequence of node texts and arrows between them is called a \emph{chain} in |
| 167 |
the following. |
| 168 |
|
| 169 |
Inside a graph there can be more than one chain: |
| 170 |
% |
| 171 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 172 |
\tikz \graph { |
| 173 |
a -> b -> c; |
| 174 |
d -> e -> f; |
| 175 |
g -> f; |
| 176 |
}; |
| 177 |
\end{codeexample} |
| 178 |
|
| 179 |
Multiple chains are separated by a semicolon or a comma (both have exactly the |
| 180 |
same effect). As the example shows, when a node text is seen for the second |
| 181 |
time, instead of creating a new node, a connection is created to the already |
| 182 |
existing node. |
| 183 |
|
| 184 |
When a node like |f| is created, both the node name and the node text are |
| 185 |
identical by default. This is not always desirable and can be changed by using |
| 186 |
the |as| key or by providing another text after a slash: |
| 187 |
% |
| 188 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 189 |
\tikz \graph { |
| 190 |
x1/$x_1$ -> x2 [as=$x_2$, red] -> x34/{$x_3,x_4$}; |
| 191 |
x1 -> [bend left] x34; |
| 192 |
}; |
| 193 |
\end{codeexample} |
| 194 |
|
| 195 |
When you wish to use a node name that contains special symbols like commas or |
| 196 |
dashes, you must surround the node name by quotes. This allows you to use quite |
| 197 |
arbitrary text as a ``node name'': |
| 198 |
% |
| 199 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 200 |
\tikz \graph { |
| 201 |
"$x_1$" -> "$x_2$"[red] -> "$x_3,x_4$"; |
| 202 |
"$x_1$" ->[bend left] "$x_3,x_4$"; |
| 203 |
}; |
| 204 |
\end{codeexample} |
| 205 |
|
| 206 |
|
| 207 |
\subsubsection{Concept: Chain Groups} |
| 208 |
|
| 209 |
Multiple chains that are separated by a semicolon or a comma and that are |
| 210 |
surrounded by curly braces form what will be called a \emph{chain group} or |
| 211 |
just a \emph{group}. A group in itself has no special effect. However, things |
| 212 |
get interesting when you write down a node or even a whole group and connect it |
| 213 |
to another group. In this case, the ``exit points'' of the first node or group |
| 214 |
get connected to the ``entry points'' of the second node or group: |
| 215 |
% |
| 216 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 217 |
\tikz \graph { |
| 218 |
a -> { |
| 219 |
b -> c, |
| 220 |
d -> e |
| 221 |
} -> f |
| 222 |
}; |
| 223 |
\end{codeexample} |
| 224 |
|
| 225 |
Chain groups make it easy to create tree structures: |
| 226 |
% |
| 227 |
\begin{codeexample}[width=10cm,preamble={\usetikzlibrary{graphs}}] |
| 228 |
\tikz |
| 229 |
\graph [grow down, |
| 230 |
branch right=2.5cm] { |
| 231 |
root -> { |
| 232 |
child 1, |
| 233 |
child 2 -> { |
| 234 |
grand child 1, |
| 235 |
grand child 2 |
| 236 |
}, |
| 237 |
child 3 -> { |
| 238 |
grand child 3 |
| 239 |
} |
| 240 |
} |
| 241 |
}; |
| 242 |
\end{codeexample} |
| 243 |
|
| 244 |
As can be seen, the placement is not particularly nice by default, use the |
| 245 |
algorithms from the graph drawing libraries to get a better layout. For |
| 246 |
instance, adding |tree layout| to the above code (and |
| 247 |
|\usetikzlibrary{graphdrawing}| as well as |\usegdlibrary{trees}| to the |
| 248 |
preamble) results in the following somewhat more pleasing rendering: |
| 249 |
% |
| 250 |
\ifluatex |
| 251 |
\medskip |
| 252 |
|
| 253 |
\tikz \graph [grow down, branch right=2.5cm, tree layout] { |
| 254 |
root -> { |
| 255 |
child 1, |
| 256 |
child 2 -> { |
| 257 |
grand child 1, |
| 258 |
grand child 2 |
| 259 |
}, |
| 260 |
child 3 -> { |
| 261 |
grand child 3 |
| 262 |
} |
| 263 |
} |
| 264 |
}; |
| 265 |
\else |
| 266 |
(You need to use Lua\TeX\ to typeset this graphic.) |
| 267 |
\fi |
| 268 |
|
| 269 |
|
| 270 |
\subsubsection{Concept: Edge Labels and Styles} |
| 271 |
|
| 272 |
When connectors like |->| or |--| are used to connect nodes or whole chain |
| 273 |
groups, one or more edges will typically be created. These edges can be styled |
| 274 |
easily by providing options in square brackets directly after these connectors: |
| 275 |
% |
| 276 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 277 |
\tikz \graph { |
| 278 |
a ->[red] b --[thick] {c, d}; |
| 279 |
}; |
| 280 |
\end{codeexample} |
| 281 |
|
| 282 |
Using the quotes syntax, see Section~\ref{section-label-quotes}, you can even |
| 283 |
add labels to the edges easily by putting the labels in quotes: |
| 284 |
% |
| 285 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 286 |
\tikz \graph { |
| 287 |
a ->[red, "foo"] b --[thick, "bar"] {c, d}; |
| 288 |
}; |
| 289 |
\end{codeexample} |
| 290 |
|
| 291 |
For the first edge, the effect is as desired, however between |b| and the group |
| 292 |
|{c,d}| two edges are inserted and the options |thick| and the label option |
| 293 |
|"bar"| is applied to both of them. While this is the correct and consistent |
| 294 |
behavior, we typically might wish to specify different labels for the edge |
| 295 |
going from |b| to |c| and the edge going from |b| to |d|. To achieve this |
| 296 |
effect, we can no longer specify the label as part of the options of |--|. |
| 297 |
Rather, we must pass the desired label to the nodes |c| and |d|, but we must |
| 298 |
somehow also indicate that these options actually ``belong'' to the edge |
| 299 |
``leading'' to nodes. This is achieved by preceding the options with a |
| 300 |
greater-than sign: |
| 301 |
% |
| 302 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 303 |
\tikz \graph { |
| 304 |
a -> b -- {c [> "foo"], d [> "bar"']}; |
| 305 |
}; |
| 306 |
\end{codeexample} |
| 307 |
|
| 308 |
Symmetrically, preceding the options by |<| causes the options and labels to |
| 309 |
apply to the ``outgoing'' edges of the node: |
| 310 |
% |
| 311 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 312 |
\tikz \graph { |
| 313 |
a [< red] -> b -- {c [> blue], d [> "bar"']}; |
| 314 |
}; |
| 315 |
\end{codeexample} |
| 316 |
|
| 317 |
This syntax allows you to easily create trees with special edge labels as in |
| 318 |
the following example of a treap: |
| 319 |
% |
| 320 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 321 |
\tikz |
| 322 |
\graph [edge quotes={fill=white,inner sep=1pt}, |
| 323 |
grow down, branch right, nodes={circle,draw}] { |
| 324 |
"" -> h [>"9"] -> { |
| 325 |
c [>"4"] -> { |
| 326 |
a [>"2"], |
| 327 |
e [>"0"] |
| 328 |
}, |
| 329 |
j [>"7"] |
| 330 |
} |
| 331 |
}; |
| 332 |
\end{codeexample} |
| 333 |
|
| 334 |
|
| 335 |
\subsubsection{Concept: Node Sets} |
| 336 |
|
| 337 |
When you write down some node text inside a |graph| command, a new node is |
| 338 |
created by default unless this node has already been created inside the same |
| 339 |
|graph| command. In particular, if a node has already been declared outside of |
| 340 |
the current |graph| command, a new node of the same name gets created. |
| 341 |
|
| 342 |
This is not always the desired behavior. Often, you may wish to make nodes part |
| 343 |
of a graph than have already been defined prior to the use of the |graph| |
| 344 |
command. For this, simply surround a node name by parentheses. This will cause |
| 345 |
a reference to be created to an already existing node: |
| 346 |
% |
| 347 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 348 |
\tikz { |
| 349 |
\node (a) at (0,0) {A}; |
| 350 |
\node (b) at (1,0) {B}; |
| 351 |
\node (c) at (2,0) {C}; |
| 352 |
|
| 353 |
\graph { (a) -> (b) -> (c) }; |
| 354 |
} |
| 355 |
\end{codeexample} |
| 356 |
|
| 357 |
You can even go a step further: A whole collection of nodes can all be flagged |
| 358 |
to belong to a \emph{node set} by adding the option |set=|\meta{node set name}. |
| 359 |
Then, inside a |graph| command, you can collectively refer to these nodes by |
| 360 |
surrounding the node set name in parentheses: |
| 361 |
% |
| 362 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,shapes.geometric}}] |
| 363 |
\tikz [new set=my nodes] { |
| 364 |
\node [set=my nodes, circle, draw] at (1,1) {A}; |
| 365 |
\node [set=my nodes, rectangle, draw] at (1.5,0) {B}; |
| 366 |
\node [set=my nodes, diamond, draw] at (1,-1) {C}; |
| 367 |
\node (d) [star, draw] at (3,0) {D}; |
| 368 |
|
| 369 |
\graph { X -> (my nodes) -> (d) }; |
| 370 |
} |
| 371 |
\end{codeexample} |
| 372 |
|
| 373 |
|
| 374 |
\subsubsection{Concept: Graph Macros} |
| 375 |
|
| 376 |
Often, a graph will consist -- at least in parts -- of standard parts. For |
| 377 |
instance, a graph might contain a cycle of certain size or a path or a clique. |
| 378 |
To facilitate specifying such graphs, you can define a \emph{graph macro}. Once |
| 379 |
a graph macro has been defined, you can use the name of the graph to make a |
| 380 |
copy of the graph part of the graph currently being specified: |
| 381 |
% |
| 382 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 383 |
\tikz \graph { subgraph K_n [n=6, clockwise] }; |
| 384 |
\end{codeexample} |
| 385 |
|
| 386 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 387 |
\tikz \graph { subgraph C_n [n=5, clockwise] -> mid }; |
| 388 |
\end{codeexample} |
| 389 |
|
| 390 |
The library |graphs.standard| defines a number of such graphs, including the |
| 391 |
complete clique $K_n$ on $n$ nodes, the complete bipartite graph $K_{n,m}$ with |
| 392 |
shores sized $n$ and $m$, the cycle $C_n$ on $n$ nodes, the path $P_n$ on $n$ |
| 393 |
nodes, and the independent set $I_n$ on $n$ nodes. |
| 394 |
|
| 395 |
|
| 396 |
\subsubsection{Concept: Graph Expressions and Color Classes} |
| 397 |
|
| 398 |
When a graph is being constructed using the |graph| command, it is constructed |
| 399 |
recursively by uniting smaller graphs to larger graphs. During this recursive |
| 400 |
union process the nodes of the graph get implicitly \emph{colored} |
| 401 |
(conceptually) and you can also explicitly assign colors to individual nodes |
| 402 |
and even change the colors as the graph is being specified. All nodes having |
| 403 |
the same color form what is called a \emph{color class}. |
| 404 |
|
| 405 |
The power of color class is that special \emph{connector operators} allow you |
| 406 |
to add edges between nodes having certain colors. For instance, saying |
| 407 |
|clique=red| at the beginning of a group will cause all nodes that have been |
| 408 |
flagged as being (conceptually) ``red'' to be connected as a clique. Similarly, |
| 409 |
saying |complete bipartite={red}{green}| will cause edges to be added between |
| 410 |
all red and all green nodes. More advanced connectors, like the |butterfly| |
| 411 |
connector, allow you to add edges between color classes in a fancy manner. |
| 412 |
% |
| 413 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 414 |
\tikz [x=8mm, y=6mm, circle] |
| 415 |
\graph [nodes={fill=blue!70}, empty nodes, n=8] { |
| 416 |
subgraph I_n [name=A] --[butterfly={level=4}] |
| 417 |
subgraph I_n [name=B] --[butterfly={level=2}] |
| 418 |
subgraph I_n [name=C] --[butterfly] |
| 419 |
subgraph I_n [name=D] -- |
| 420 |
subgraph I_n [name=E] |
| 421 |
}; |
| 422 |
\end{codeexample} |
| 423 |
|
| 424 |
|
| 425 |
\subsection{Syntax of the Graph Path Command} |
| 426 |
|
| 427 |
\subsubsection{The Graph Command} |
| 428 |
|
| 429 |
In order to construct a graph, you should use the |graph| path command, which |
| 430 |
can be used anywhere on a path at any place where you could also use a command |
| 431 |
like, say, |plot| or |--|. |
| 432 |
|
| 433 |
\begin{command}{\graph} |
| 434 |
Inside a |{tikzpicture}| this is an abbreviation for |\path graph|. |
| 435 |
\end{command} |
| 436 |
|
| 437 |
\begin{pathoperation}{graph}{\opt{\oarg{options}}\meta{group specification}} |
| 438 |
When this command is encountered on a path, the construction of the current |
| 439 |
path is suspended (similarly to an |edge| command or a |node| command). In |
| 440 |
a local scope, the \meta{options} are first executed with the key path |
| 441 |
|/tikz/graphs| using the following command: |
| 442 |
% |
| 443 |
\begin{command}{\tikzgraphsset\marg{options}} |
| 444 |
Executes the \meta{options} with the path prefix |/tikz/graphs|. |
| 445 |
\end{command} |
| 446 |
% |
| 447 |
Apart from the keys explained in the following, further permissible keys |
| 448 |
will be listed during the course of the rest of this section. |
| 449 |
|
| 450 |
\begin{stylekey}{/tikz/graphs/every graph} |
| 451 |
This style is executed at the beginning of every |graph| path command |
| 452 |
prior to the \meta{options}. |
| 453 |
\end{stylekey} |
| 454 |
|
| 455 |
Once the scope has been set up and once the \meta{options} have been |
| 456 |
executed, a parser starts to parse the \meta{group specification}. The |
| 457 |
exact syntax of such a group specification in explained in detail in |
| 458 |
Section~\ref{section-library-graphs-group-spec}. Basically, a group |
| 459 |
specification is a list of chain specifications, separated by commas or |
| 460 |
semicolons. |
| 461 |
|
| 462 |
Depending on the content of the \meta{group specification}, two things will |
| 463 |
happen: |
| 464 |
% |
| 465 |
\begin{enumerate} |
| 466 |
\item A number of new nodes may be created. These will be inserted into |
| 467 |
the picture in the same order as if they had been created using |
| 468 |
multiple |node| path commands at the place where the |graph| path |
| 469 |
command was used. In other words, all nodes created in a |graph| |
| 470 |
path command will be painted on top of any nodes created earlier in |
| 471 |
the path and behind any nodes created later in the path. Like |
| 472 |
normal nodes, the newly created nodes always lie on top of the path |
| 473 |
that is currently being created (which is often empty, for instance |
| 474 |
when the |\graph| command is used). |
| 475 |
\item Edges between the nodes may be added. They are added in the same |
| 476 |
order as if the |edge| command had been used at the position where |
| 477 |
the |graph| command is being used. |
| 478 |
\end{enumerate} |
| 479 |
|
| 480 |
Let us now have a look at some common keys that may be used inside the |
| 481 |
\meta{options}: |
| 482 |
% |
| 483 |
\begin{key}{/tikz/graphs/nodes=\meta{options}} |
| 484 |
This option causes the \meta{options} to be applied to each newly |
| 485 |
created node inside the \meta{group specification}. |
| 486 |
% |
| 487 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 488 |
\tikz \graph [nodes=red] { a -> b -> c }; |
| 489 |
\end{codeexample} |
| 490 |
% |
| 491 |
Multiple uses of this key accumulate. |
| 492 |
\end{key} |
| 493 |
% |
| 494 |
\begin{key}{/tikz/graphs/edges=\meta{options}} |
| 495 |
This option causes the \meta{options} to be applied to each newly |
| 496 |
created edge inside the \meta{group specification}. |
| 497 |
% |
| 498 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 499 |
\tikz \graph [edges={red,thick}] { a -> b -> c }; |
| 500 |
\end{codeexample} |
| 501 |
% |
| 502 |
Again, multiple uses of this key accumulate. |
| 503 |
\end{key} |
| 504 |
% |
| 505 |
\begin{key}{/tikz/graphs/edge=\meta{options}} |
| 506 |
This is an alias for |edges|. |
| 507 |
\end{key} |
| 508 |
|
| 509 |
\begin{key}{/tikz/graphs/edge node=\meta{node specification}} |
| 510 |
This key specifies that the \meta{node specification} should be added |
| 511 |
to each newly created edge as an implicitly placed node. |
| 512 |
% |
| 513 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 514 |
\tikz \graph [edge node={node [red, near end] {X}}] { a -> b -> c }; |
| 515 |
\end{codeexample} |
| 516 |
% |
| 517 |
Again, multiple uses of this key accumulate. |
| 518 |
% |
| 519 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 520 |
\tikz \graph [edge node={node [near end] {X}}, |
| 521 |
edge node={node [near start] {Y}}] { a -> b -> c }; |
| 522 |
\end{codeexample} |
| 523 |
\end{key} |
| 524 |
|
| 525 |
\begin{key}{/tikz/graphs/edge label=\meta{text}} |
| 526 |
This key is an abbreviation for |edge node=node[auto]{|\meta{text}|}|. |
| 527 |
The net effect is that the |text| is placed next to the newly created |
| 528 |
edges. |
| 529 |
% |
| 530 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 531 |
\tikz \graph [edge label=x] { a -> b -> {c,d} }; |
| 532 |
\end{codeexample} |
| 533 |
\end{key} |
| 534 |
|
| 535 |
\begin{key}{/tikz/graphs/edge label'=\meta{text}} |
| 536 |
This key is an abbreviation for |edge node=node[auto,swap]{|\meta{text}|}|. |
| 537 |
% |
| 538 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 539 |
\tikz \graph [edge label=out, edge label'=in] |
| 540 |
{ subgraph C_n [clockwise, n=5] }; |
| 541 |
\end{codeexample} |
| 542 |
\end{key} |
| 543 |
\end{pathoperation} |
| 544 |
|
| 545 |
|
| 546 |
\subsubsection{Syntax of Group Specifications} |
| 547 |
\label{section-library-graphs-group-spec} |
| 548 |
|
| 549 |
A \meta{group specification} inside a |graph| path command has the following |
| 550 |
syntax: |
| 551 |
% |
| 552 |
\begin{quote} |
| 553 |
|{|\opt{\oarg{options}}\meta{list of chain specifications}|}| |
| 554 |
\end{quote} |
| 555 |
% |
| 556 |
The \meta{chain specifications} must contain chain specifications, whose syntax |
| 557 |
is detailed in the next section, separated by either commas or semicolons; you |
| 558 |
can freely mix them. It is permissible to use empty lines (which are mapped to |
| 559 |
|\par| commands internally) to structure the chains visually, they are simply |
| 560 |
ignored by the parser. |
| 561 |
|
| 562 |
In the following example, the group specification consists of three chain |
| 563 |
specifications, namely of |a -> b|, then |c| alone, and finally |d -> e -> f|: |
| 564 |
% |
| 565 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 566 |
\tikz \graph { |
| 567 |
a -> b, |
| 568 |
c; |
| 569 |
|
| 570 |
d -> e -> f |
| 571 |
}; |
| 572 |
\end{codeexample} |
| 573 |
% |
| 574 |
The above has the same effect as the more compact group specification |
| 575 |
|{a->b,c,d->e->f}|. |
| 576 |
|
| 577 |
Commas are used to detect where chain specifications end. However, you will |
| 578 |
often wish to use a comma also inside the options of a single node like in the |
| 579 |
following example: |
| 580 |
% |
| 581 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 582 |
\tikz \graph { |
| 583 |
a [red, draw] -> b [blue, draw], |
| 584 |
c [brown, draw, circle] |
| 585 |
}; |
| 586 |
\end{codeexample} |
| 587 |
|
| 588 |
Note that the above example works as expected: The first comma inside the |
| 589 |
option list of |a| is \emph{not} interpreted as the end of the chain |
| 590 |
specification ``|a [red|''. Rather, commas inside square brackets are |
| 591 |
``protected'' against being interpreted as separators of group specifications. |
| 592 |
|
| 593 |
The \meta{options} that can be given at the beginning of a group specification |
| 594 |
are local to the group. They are executed with the path prefix |/tikz/graphs|. |
| 595 |
Note that for the outermost group specification of a graph it makes no |
| 596 |
difference whether the options are passed to the |graph| command or whether |
| 597 |
they are given at the beginning of this group. However, for groups nested |
| 598 |
inside other groups, it does make a difference: |
| 599 |
% |
| 600 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 601 |
\tikz \graph { |
| 602 |
a -> { [nodes=red] % the option is local to these nodes: |
| 603 |
b, c |
| 604 |
} -> |
| 605 |
d |
| 606 |
}; |
| 607 |
\end{codeexample} |
| 608 |
|
| 609 |
\medskip |
| 610 |
\textbf{Using foreach.} |
| 611 |
There is special support for the |\foreach| statement inside groups: You may |
| 612 |
use the statement inside a group specification at any place where a \meta{chain |
| 613 |
specification} would normally go. In this case, the |\foreach| statement is |
| 614 |
executed and for each iteration the content of the statement's body is treated |
| 615 |
and parsed as a new chain specification. |
| 616 |
% |
| 617 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 618 |
\tikz \graph [math nodes, branch down=5mm] { |
| 619 |
a -> { |
| 620 |
\foreach \i in {1,2,3} { |
| 621 |
a_\i -> { x_\i, y_\i } |
| 622 |
}, |
| 623 |
b |
| 624 |
} |
| 625 |
}; |
| 626 |
\end{codeexample} |
| 627 |
|
| 628 |
\medskip |
| 629 |
\textbf{Using macros.} |
| 630 |
In some cases you may wish to use macros and \TeX\ code to compute which nodes |
| 631 |
and edges are present in a group. You cannot use macros in the normal way |
| 632 |
inside a graph specification since the parser does not expand macros as it |
| 633 |
scans for the start and end of groups and node names. Rather, only after |
| 634 |
commas, semicolons, and hyphens have already been detected and only after all |
| 635 |
other parsing decisions have been made will macros be expanded. At this point, |
| 636 |
when a macro expands to, say |a,b|, this will not result in two nodes to be |
| 637 |
created since the parsing is already done. For these reasons, a special key is |
| 638 |
needed to make it possible to ``compute'' which nodes should be present in a |
| 639 |
group. |
| 640 |
|
| 641 |
\begin{key}{/tikz/graph/parse=\meta{text}} |
| 642 |
This key can only be used inside the \meta{options} of a \meta{group |
| 643 |
specification}. Its effect is that the \meta{text} is inserted at the |
| 644 |
beginning of the current group as if you had entered it there. Naturally, |
| 645 |
it makes little sense to just write down some static \meta{text} since you |
| 646 |
could just as well directly place it at the beginning of the group. The |
| 647 |
real power of this command stems from the fact that the keys mechanism |
| 648 |
allows you to say, for instance, |parse/.expand once| to insert the text |
| 649 |
stored in some macro into the group. |
| 650 |
% |
| 651 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 652 |
\def\mychain{ a -> b -> c; } |
| 653 |
\tikz \graph { [parse/.expand once=\mychain] d -> e }; |
| 654 |
\end{codeexample} |
| 655 |
% |
| 656 |
In the following, more fancy example we use a loop to create a chain of |
| 657 |
dynamic length. |
| 658 |
% |
| 659 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 660 |
\def\mychain#1{ |
| 661 |
\def\mytext{1} |
| 662 |
\foreach \i in {2,...,#1} { |
| 663 |
\xdef\mytext{\mytext -> \i} |
| 664 |
} |
| 665 |
} |
| 666 |
\tikzgraphsset{my chain/.style={ |
| 667 |
/utils/exec=\mychain{#1}, |
| 668 |
parse/.expand once=\mytext} |
| 669 |
} |
| 670 |
\tikz \graph { [my chain=4] }; |
| 671 |
\end{codeexample} |
| 672 |
% |
| 673 |
Multiple uses of this key accumulate, that is, all the \text{text}s given |
| 674 |
in the different uses is inserted in the order it is given. |
| 675 |
\end{key} |
| 676 |
|
| 677 |
|
| 678 |
\subsubsection{Syntax of Chain Specifications} |
| 679 |
|
| 680 |
A \meta{chain specification} has the following syntax: It consists of a |
| 681 |
sequence of \meta{node specifications}, where subsequent node specifications |
| 682 |
are separated by \meta{edge specifications}. Node specifications, which |
| 683 |
typically consist of some text, are discussed in the next section in more |
| 684 |
detail. They normally represent a single node that is either newly created or |
| 685 |
exists already, but they may also specify a whole set of nodes. |
| 686 |
|
| 687 |
An \meta{edge specification} specifies \emph{which} of the node(s) to the left |
| 688 |
of the edge specification should be connected to which node(s) to the right of |
| 689 |
it and it also specifies in which direction the connections go. In the |
| 690 |
following, we only discuss how the direction is chosen, the powerful mechanism |
| 691 |
behind choosing which nodes should be connect is detailed in |
| 692 |
Section~\ref{section-library-graphs-color-classes}. |
| 693 |
|
| 694 |
The syntax of an edge specification is always one of the following five |
| 695 |
possibilities: |
| 696 |
% |
| 697 |
\begin{quote} |
| 698 |
|->| \opt{\oarg{options}}\\ |
| 699 |
|--| \opt{\oarg{options}}\\ |
| 700 |
|<-| \opt{\oarg{options}}\\ |
| 701 |
|<->| \opt{\oarg{options}}\\ |
| 702 |
|-!-| \opt{\oarg{options}} |
| 703 |
\end{quote} |
| 704 |
|
| 705 |
The first four correspond to a directed edge, an undirected edge, a |
| 706 |
``backward'' directed edge, and a bidirected edge, respectively. The fifth edge |
| 707 |
specification means that there should be no edge (this specification can be |
| 708 |
used together with the |simple| option to remove edges that have previously |
| 709 |
been added, see Section~\ref{section-library-graphs-simple}). |
| 710 |
|
| 711 |
Suppose the nodes \meta{left nodes} are to the left of the \meta{edge |
| 712 |
specification} and \meta{right nodes} are to the right and suppose we have |
| 713 |
written |->| between them. Then the following happens: |
| 714 |
% |
| 715 |
\begin{enumerate} |
| 716 |
\item The \meta{options} are executed (inside a local scope) with the path |
| 717 |
|/tikz/graphs|. These options may setup the connector algorithm (see |
| 718 |
below) and may also use keys like |edge| or |edge label| to specify how |
| 719 |
the edge should look like. As a convenience, whenever an unknown key is |
| 720 |
encountered for the path |/tikz/graphs|, the key is passed to the |
| 721 |
|edge| key. This means that you can directly use options like |thick| |
| 722 |
or |red| inside the \meta{options} and they will apply to the edge as |
| 723 |
expected. |
| 724 |
\item The chosen connector algorithm, see |
| 725 |
Section~\ref{section-library-graphs-color-classes}, is used to compute |
| 726 |
from which of the \meta{left nodes} an edge should lead to which of the |
| 727 |
\meta{right nodes}. Suppose that $(l_1,r_1)$, \dots, $(l_n,r_n)$ is the |
| 728 |
list of node pairs that result (so there should be an edge between |
| 729 |
$l_1$ and $r_1$ and another edge between $l_2$ and $r_2$ and so on). |
| 730 |
\item For each pair $(l_i,r_i)$ an edge is created. This is done by calling |
| 731 |
the following key (for the edge specification |->|, other keys are |
| 732 |
executed for the other kinds of specifications): |
| 733 |
% |
| 734 |
\begin{key}{/tikz/graphs/new ->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} |
| 735 |
This key will be called for a |->| edge specification with the |
| 736 |
following four parameters: |
| 737 |
% |
| 738 |
\begin{enumerate} |
| 739 |
\item \meta{left node} is the name of the ``left'' node, that |
| 740 |
is, the name of $l_i$. |
| 741 |
\item \meta{right node} is the name of the right node. |
| 742 |
\item \meta{edge options} are the accumulated options from all |
| 743 |
calls of |/tikz/graph/edges| in groups that surround the |
| 744 |
edge specification. |
| 745 |
\item \meta{edge nodes} is text like |node {A} node {B}| that |
| 746 |
specifies some nodes that should be put as labels on the |
| 747 |
edge using \tikzname's implicit positioning mechanism. |
| 748 |
\end{enumerate} |
| 749 |
% |
| 750 |
By default, the key executes the following code: |
| 751 |
% |
| 752 |
\begin{quote} |
| 753 |
|\path [->,every new ->]|\\ |
| 754 |
\hbox{}\quad|(|\meta{left node}|\tikzgraphleftanchor) edge [|% |
| 755 |
\meta{edge options}|]| \meta{edge nodes}||\\ |
| 756 |
\hbox{}\quad|(|\meta{right node}|\tikzgraphrightanchor);| |
| 757 |
\end{quote} |
| 758 |
% |
| 759 |
You are welcome to change the code underlying the key. |
| 760 |
% |
| 761 |
\begin{stylekey}{/tikz/every new ->} |
| 762 |
This key gets executed by default for a |new ->|. |
| 763 |
\end{stylekey} |
| 764 |
\end{key} |
| 765 |
% |
| 766 |
\begin{key}{/tikz/graphs/left anchor=\meta{anchor}} |
| 767 |
This anchor is used for the node that is to the left of an edge |
| 768 |
specification. Setting this anchor to the empty string means that |
| 769 |
no special anchor is used (which is the default). The \meta{anchor} |
| 770 |
is stored in the macro |\tikzgraphleftanchor| with a leading dot. |
| 771 |
% |
| 772 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 773 |
\tikz \graph { |
| 774 |
{a,b,c} -> [complete bipartite] {e,f,g} |
| 775 |
}; |
| 776 |
\end{codeexample} |
| 777 |
% |
| 778 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 779 |
\tikz \graph [left anchor=east, right anchor=west] { |
| 780 |
{a,b,c} -- [complete bipartite] {e,f,g} |
| 781 |
}; |
| 782 |
\end{codeexample} |
| 783 |
\end{key} |
| 784 |
% |
| 785 |
\begin{key}{/tikz/graphs/right anchor=\meta{anchor}} |
| 786 |
Works like |left anchor|, only for |\tikzgraphrightanchor|. |
| 787 |
\end{key} |
| 788 |
% |
| 789 |
For the other three kinds of edge specifications, the following keys |
| 790 |
will be called: |
| 791 |
% |
| 792 |
\begin{key}{/tikz/graphs/new --=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} |
| 793 |
This key is called for |--| with the same parameters as above. The |
| 794 |
only difference in the definition is that in the |\path| command |
| 795 |
the |->| gets replaced by |-|. |
| 796 |
% |
| 797 |
\begin{stylekey}{/tikz/every new --} |
| 798 |
\end{stylekey} |
| 799 |
\end{key} |
| 800 |
% |
| 801 |
\begin{key}{/tikz/graphs/new <->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} |
| 802 |
Called for |<->| with the same parameters as above. The |->| is |
| 803 |
replaced by |<-| |
| 804 |
% |
| 805 |
\begin{stylekey}{/tikz/every new <->} |
| 806 |
\end{stylekey} |
| 807 |
\end{key} |
| 808 |
% |
| 809 |
\begin{key}{/tikz/graphs/new <-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} |
| 810 |
Called for |<-| with the same parameters as above.% |
| 811 |
\footnote{% |
| 812 |
You might wonder why this key is needed: It seems more logical |
| 813 |
at first sight to just call |new edge directed| with swapped |
| 814 |
first parameters. However, a positioning algorithm might wish |
| 815 |
to take the fact into account that an edge is ``backward'' |
| 816 |
rather than ``forward'' in order to improve the layout. Also, |
| 817 |
different arrow heads might be used. |
| 818 |
} |
| 819 |
% |
| 820 |
\begin{stylekey}{/tikz/every new <-} |
| 821 |
\end{stylekey} |
| 822 |
\end{key} |
| 823 |
% |
| 824 |
\begin{key}{/tikz/graphs/new -\protect\exclamationmarktext-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} |
| 825 |
Called for |-!-| with the same parameters as above. Does nothing by |
| 826 |
default. |
| 827 |
\end{key} |
| 828 |
\end{enumerate} |
| 829 |
|
| 830 |
Here is an example that shows the default rendering of the different edge |
| 831 |
specifications: |
| 832 |
% |
| 833 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 834 |
\tikz \graph [branch down=5mm] { |
| 835 |
a -> b; |
| 836 |
c -- d; |
| 837 |
e <- f; |
| 838 |
g <-> h; |
| 839 |
i -!- j; |
| 840 |
}; |
| 841 |
\end{codeexample} |
| 842 |
|
| 843 |
|
| 844 |
\subsubsection{Syntax of Node Specifications} |
| 845 |
\label{section-library-graphs-node-spec} |
| 846 |
|
| 847 |
Node specifications are the basic building blocks of a graph specification. |
| 848 |
There are three different possible kinds of node specifications, each of which |
| 849 |
has a different syntax: |
| 850 |
% |
| 851 |
\begin{description} |
| 852 |
\item[Direct Node Specification] |
| 853 |
\ \\ |
| 854 |
\opt{|"|}\meta{node name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}} \opt{\oarg{options}}\\ |
| 855 |
(note that the quotation marks are optional and only needed when the |
| 856 |
\meta{node name} contains special symbols) |
| 857 |
\item[Reference Node Specification] |
| 858 |
\ \\ |
| 859 |
|(|\meta{node name or node set name}|)| |
| 860 |
\item[Group Node Specification] |
| 861 |
\ \\ |
| 862 |
\meta{group specification} |
| 863 |
\end{description} |
| 864 |
|
| 865 |
The rule for determining which of the possible kinds is meant is as follows: If |
| 866 |
the node specification starts with an opening parenthesis, a reference node |
| 867 |
specification is meant; if it starts with an opening curly brace, a group |
| 868 |
specification is meant; and in all other cases a direct node specification is |
| 869 |
meant. |
| 870 |
|
| 871 |
\medskip |
| 872 |
\textbf{Direct Node Specifications.} If after reading the first symbol of a |
| 873 |
node specification is has been detected to be \emph{direct}, \tikzname\ will |
| 874 |
collect all text up to the next edge specification and store it as the |
| 875 |
\meta{node name}; however, square brackets are used to indicate options and a |
| 876 |
slash ends the \meta{node name} and start a special \meta{text} that is used as |
| 877 |
a rendering text instead of the original \meta{node name}. |
| 878 |
|
| 879 |
Due to the way the parsing works and due to the restrictions on node names, |
| 880 |
most special characters are forbidding inside the \meta{node name}, including |
| 881 |
commas, semicolons, hyphens, braces, dots, parentheses, slashes, dashes, and |
| 882 |
more (but spaces, single underscores, and the hat character \emph{are} |
| 883 |
allowed). To use special characters in the name of a node, you can optionally |
| 884 |
surround the \meta{node name} and/or the \meta{text} by quotation marks. In |
| 885 |
this case, you can use all of the special symbols once more. The details of |
| 886 |
what happens, exactly, when the \meta{node name} is surrounded by quotation |
| 887 |
marks is explained later; surrounding the \meta{text} by quotation marks has |
| 888 |
essentially the same effect as surrounding it by curly braces. |
| 889 |
|
| 890 |
Once the node name has been determined, it is checked whether the same node |
| 891 |
name was already used inside the current graph. If this is the case, then we |
| 892 |
say that the already existing node is \emph{referenced}; otherwise we say that |
| 893 |
the node is \emph{fresh}. |
| 894 |
% |
| 895 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 896 |
\tikz \graph { |
| 897 |
a -> b; % both are fresh |
| 898 |
c -> a; % only c is fresh, a is referenced |
| 899 |
}; |
| 900 |
\end{codeexample} |
| 901 |
|
| 902 |
This behavior of deciding whether a node is fresh or referenced can, however, |
| 903 |
be modified by using the following keys: |
| 904 |
% |
| 905 |
\begin{key}{/tikz/graphs/use existing nodes=\opt{\meta{true or false}} (default true)} |
| 906 |
When this key is set to |true|, all nodes will be considered to the |
| 907 |
referenced, no node will be fresh. This option is useful if you have |
| 908 |
already created all the nodes of a graph prior to using the |graph| command |
| 909 |
and you now only wish to connect the nodes. It also implies that an error |
| 910 |
is raised if you reference a node which has not been defined previously. |
| 911 |
\end{key} |
| 912 |
|
| 913 |
\begin{key}{/tikz/graphs/fresh nodes=\opt{\meta{true or false}} (default true)} |
| 914 |
When this key is set to |true|, all nodes will be considered to be fresh. |
| 915 |
This option is useful when you create for instance a tree with many |
| 916 |
identical nodes. |
| 917 |
|
| 918 |
When a node name is encountered that was already used previously, a new |
| 919 |
name is chosen is follows: An apostrophe (|'|) is appended repeatedly until |
| 920 |
a node name is found that has not yet been used: |
| 921 |
% |
| 922 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 923 |
\tikz \graph [branch down=5mm] { |
| 924 |
{ [fresh nodes] |
| 925 |
a -> { |
| 926 |
b -> {c, c}, |
| 927 |
b -> {c, c}, |
| 928 |
b -> {c, c}, |
| 929 |
} |
| 930 |
}, |
| 931 |
b' -- b'' |
| 932 |
}; |
| 933 |
\end{codeexample} |
| 934 |
% |
| 935 |
\end{key} |
| 936 |
|
| 937 |
\begin{key}{/tikz/graphs/number nodes=\opt{\meta{start number}} (default 1)} |
| 938 |
When this key is used in a scope, each encountered node name will get |
| 939 |
appended a new number, starting with \meta{start}. Typically, this ensures |
| 940 |
that all node names are different. Between the original node name and the |
| 941 |
appended number, the setting of the following will be inserted: |
| 942 |
% |
| 943 |
\begin{key}{/tikz/graphs/number nodes sep=\meta{text} (initially \normalfont space)} |
| 944 |
\end{key} |
| 945 |
% |
| 946 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 947 |
\tikz \graph [branch down=5mm] { |
| 948 |
{ [number nodes] |
| 949 |
a -> { |
| 950 |
b -> {c, c}, |
| 951 |
b -> {c, c}, |
| 952 |
b -> {c, c}, |
| 953 |
} |
| 954 |
}, |
| 955 |
b 2 -- b 5 |
| 956 |
}; |
| 957 |
\end{codeexample} |
| 958 |
% |
| 959 |
\end{key} |
| 960 |
|
| 961 |
When a fresh node has been detected, a new node is created in the inside a |
| 962 |
protecting scope. For this, the current placement strategy is asked to compute |
| 963 |
a default position for the node, see |
| 964 |
Section~\ref{section-library-graphs-placement} for details. Then, the command |
| 965 |
% |
| 966 |
\begin{quote} |
| 967 |
|\node (|\meta{full node name}|) [|\meta{node options}|] {|\meta{text}|};| |
| 968 |
\end{quote} |
| 969 |
% |
| 970 |
is called. The different parameters are as follows: |
| 971 |
% |
| 972 |
\begin{itemize} |
| 973 |
\item The \meta{full node name} is normally the \meta{node name} that has |
| 974 |
been determined as described before. However, there are two exceptions: |
| 975 |
|
| 976 |
First, if the \meta{node name} is empty (which happens when there is no |
| 977 |
\meta{node name} before the slash), then a fresh internal node name is |
| 978 |
created and used as \meta{full node name}. This name is guaranteed to |
| 979 |
be different from all node names used in this or any other graph. Thus, |
| 980 |
a direct node starting with a slash represents an anonymous fresh node. |
| 981 |
|
| 982 |
Second, you can use the following key to prefix the \meta{node name} |
| 983 |
inside the \meta{full node name}: |
| 984 |
|
| 985 |
\begin{key}{/tikz/graphs/name=\meta{text}} |
| 986 |
This key prepends the \meta{text}, followed by a separating symbol |
| 987 |
(a space by default), to all \meta{node name}s inside a \meta{full |
| 988 |
node name}. Repeated calls of this key accumulate, leading to |
| 989 |
ever-longer ``name paths'': |
| 990 |
% |
| 991 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 992 |
\begin{tikzpicture} |
| 993 |
\graph { |
| 994 |
{ [name=first] 1, 2, 3} -- |
| 995 |
{ [name=second] 1, 2, 3} |
| 996 |
}; |
| 997 |
\draw [red] (second 1) circle [radius=3mm]; |
| 998 |
\end{tikzpicture} |
| 999 |
\end{codeexample} |
| 1000 |
% |
| 1001 |
Note that, indeed, in the above example six nodes are created even |
| 1002 |
though the first and second set of nodes have the same \meta{node |
| 1003 |
name}. The reason is that the full names of the six nodes are all |
| 1004 |
different. Also note that only the \meta{node name} is used as the |
| 1005 |
node text, not the full name. This can be changed as described |
| 1006 |
later on. |
| 1007 |
|
| 1008 |
This key can be used repeatedly, leading to ever longer node names. |
| 1009 |
\end{key} |
| 1010 |
|
| 1011 |
\begin{key}{/tikz/graphs/name separator=\meta{symbols} (initially \string\space)} |
| 1012 |
Changes the symbol that is used to separate the \meta{text} from |
| 1013 |
the \meta{node name}. The default is |\space|, resulting in a |
| 1014 |
space. |
| 1015 |
% |
| 1016 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1017 |
\begin{tikzpicture} |
| 1018 |
\graph [name separator=] { % no separator |
| 1019 |
{ [name=first] 1, 2, 3} -- |
| 1020 |
{ [name=second] 1, 2, 3} |
| 1021 |
}; |
| 1022 |
\draw [red] (second1) circle [radius=3mm]; |
| 1023 |
\end{tikzpicture} |
| 1024 |
\end{codeexample} |
| 1025 |
% |
| 1026 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1027 |
\begin{tikzpicture} |
| 1028 |
\graph [name separator=-] { |
| 1029 |
{ [name=first] 1, 2, 3} -- |
| 1030 |
{ [name=second] 1, 2, 3} |
| 1031 |
}; |
| 1032 |
\draw [red] (second-1) circle [radius=3mm]; |
| 1033 |
\end{tikzpicture} |
| 1034 |
\end{codeexample} |
| 1035 |
\end{key} |
| 1036 |
\item The \meta{node options} are |
| 1037 |
% |
| 1038 |
\begin{enumerate} |
| 1039 |
\item The options that have accumulated in calls to |nodes| from |
| 1040 |
the surrounding scopes. |
| 1041 |
\item The local \meta{options}. |
| 1042 |
\end{enumerate} |
| 1043 |
% |
| 1044 |
The options are executed with the path prefix |/tikz/graphs|, but any |
| 1045 |
unknown key is executed with the prefix |/tikz|. This means, in |
| 1046 |
essence, that some esoteric keys are more difficult to use inside the |
| 1047 |
options and that any key with the prefix |/tikz/graphs| will take |
| 1048 |
precedence over a key with the prefix |/tikz|. |
| 1049 |
\item The \meta{text} that is passed to the |\node| command is computed as |
| 1050 |
follows: First, you can use the following key to directly set the |
| 1051 |
\meta{text}: |
| 1052 |
% |
| 1053 |
\begin{key}{/tikz/graphs/as=\meta{text}} |
| 1054 |
The \meta{text} is used as the text of the node. This allows you to |
| 1055 |
provide a text for the node that differs arbitrarily from the name |
| 1056 |
of the node. |
| 1057 |
% |
| 1058 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1059 |
\tikz \graph { a [as=$x$] -- b [as=$y_5$] -> c [red, as={a--b}] }; |
| 1060 |
\end{codeexample} |
| 1061 |
% |
| 1062 |
This key always takes precedence over all of the mechanisms |
| 1063 |
described below. |
| 1064 |
\end{key} |
| 1065 |
% |
| 1066 |
In case the |as| key is not used, a default text is chosen as follows: |
| 1067 |
First, when a direct node specification contains a slash (or, for |
| 1068 |
historical reasons, a double underscore), the text to the right of the |
| 1069 |
slash (or double underscore) is stored in the macro |
| 1070 |
|\tikzgraphnodetext|; if there is no slash, the \meta{node name} is |
| 1071 |
stored in |\tikzgraphnodetext|, instead. Then, the current value of the |
| 1072 |
following key is used as \meta{text}: |
| 1073 |
% |
| 1074 |
\begin{key}{/tikz/graphs/typeset=\meta{code}} |
| 1075 |
The macro or code stored in this key is used as the \meta{text} of |
| 1076 |
the node. Inside the \meta{code}, the following macros are |
| 1077 |
available: |
| 1078 |
% |
| 1079 |
\begin{command}{\tikzgraphnodetext} |
| 1080 |
This macro expands to the \meta{text} to the right of the |
| 1081 |
double underscore or slash in a direct node specification or, |
| 1082 |
if there is no slash, to the \meta{node name}. |
| 1083 |
\end{command} |
| 1084 |
% |
| 1085 |
\begin{command}{\tikzgraphnodename} |
| 1086 |
This macro expands to the name of the current node without the |
| 1087 |
path. |
| 1088 |
\end{command} |
| 1089 |
% |
| 1090 |
\begin{command}{\tikzgraphnodepath} |
| 1091 |
This macro expands to the current path of the node. These paths |
| 1092 |
result from the use of the |name| key as described above. |
| 1093 |
\end{command} |
| 1094 |
% |
| 1095 |
\begin{command}{\tikzgraphnodefullname} |
| 1096 |
This macro contains the concatenation of the above two. |
| 1097 |
\end{command} |
| 1098 |
\end{key} |
| 1099 |
% |
| 1100 |
By default, the typesetter is just set to |\tikzgraphnodetext|, which |
| 1101 |
means that the default text of a node is its name. However, it may be |
| 1102 |
useful to change this: For instance, you might wish that the text of |
| 1103 |
all graph nodes is, say, surrounded by parentheses: |
| 1104 |
% |
| 1105 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1106 |
\tikz \graph [typeset=(\tikzgraphnodetext)] |
| 1107 |
{ a -> b -> c }; |
| 1108 |
\end{codeexample} |
| 1109 |
% |
| 1110 |
A more advanced macro might take apart the node text and render it |
| 1111 |
differently: |
| 1112 |
% |
| 1113 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1114 |
\def\mytypesetter{\expandafter\myparser\tikzgraphnodetext\relax} |
| 1115 |
\def\myparser#1 #2 #3\relax{% |
| 1116 |
$#1_{#2,\dots,#3}$ |
| 1117 |
} |
| 1118 |
\tikz \graph [typeset=\mytypesetter, grow down] |
| 1119 |
{ a 1 n -> b 2 m -> c 4 nm }; |
| 1120 |
\end{codeexample} |
| 1121 |
% |
| 1122 |
The following styles install useful predefined typesetting macros: |
| 1123 |
% |
| 1124 |
\begin{key}{/tikz/graphs/empty nodes} |
| 1125 |
Just sets |typeset| to nothing, which causes all nodes to have an |
| 1126 |
empty text (unless, of course, the |as| option is used): |
| 1127 |
% |
| 1128 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1129 |
\tikz \graph [empty nodes, nodes={circle, draw}] { a -> {b, c} }; |
| 1130 |
\end{codeexample} |
| 1131 |
\end{key} |
| 1132 |
% |
| 1133 |
\begin{key}{/tikz/graphs/math nodes} |
| 1134 |
Sets |typeset| to |$\tikzgraphnodetext$|, which causes all nodes |
| 1135 |
names to be typeset in math mode: |
| 1136 |
% |
| 1137 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1138 |
\tikz \graph [math nodes, nodes={circle, draw}] { a_1 -> {b^2, c_3^n} }; |
| 1139 |
\end{codeexample} |
| 1140 |
\end{key} |
| 1141 |
\end{itemize} |
| 1142 |
|
| 1143 |
If a node is referenced instead of fresh, then this node becomes the node that |
| 1144 |
will be connected by the preceding or following edge specification to other |
| 1145 |
nodes. The \meta{options} are executed even for a referenced node, but they |
| 1146 |
cannot be used to change the appearance of the node (because the node exists |
| 1147 |
already). Rather, the \meta{options} can only be used to change the logical |
| 1148 |
coloring of the node, see Section~\ref{section-library-graphs-color-classes} |
| 1149 |
for details. |
| 1150 |
|
| 1151 |
\medskip |
| 1152 |
\textbf{Quoted Node Names.} When the \meta{node name} and/or the \meta{text} of |
| 1153 |
a node is surrounded by quotation marks, you can use all sorts of special |
| 1154 |
symbols as part of the text that are normally forbidden: |
| 1155 |
% |
| 1156 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1157 |
\begin{tikzpicture} |
| 1158 |
\graph [grow right=2cm] { |
| 1159 |
"Hi, World!" -> "It's \emph{important}!"[red,rotate=-45]; |
| 1160 |
"name"/actual text -> "It's \emph{important}!"; |
| 1161 |
}; |
| 1162 |
\draw (name) circle [radius=3pt]; |
| 1163 |
\end{tikzpicture} |
| 1164 |
\end{codeexample} |
| 1165 |
|
| 1166 |
In detail, for the following happens when quotation marks are encountered at |
| 1167 |
the beginning of a node name or its text: |
| 1168 |
% |
| 1169 |
\begin{itemize} |
| 1170 |
\item Everything following the quotation mark up to the next single |
| 1171 |
quotation mark is collected into a macro \meta{collected}. All sorts of |
| 1172 |
special characters, including commas, square brackets, dashes, and even |
| 1173 |
backslashes are allowed here. Basically, the only restriction is that |
| 1174 |
braces must be balanced. |
| 1175 |
\item A double quotation mark (|""|) does not count as the ``next single |
| 1176 |
quotation mark''. Rather, it is replaced by a single quotation mark. |
| 1177 |
For instance, |"He said, ""Hello world."""| would be stored inside |
| 1178 |
\meta{collected} as |He said, "Hello world."| However, this rule |
| 1179 |
applies only on the outer-most level of braces. Thus, in |
| 1180 |
% |
| 1181 |
\begin{codeexample}[code only] |
| 1182 |
"He {said, ""Hello world.""}" |
| 1183 |
\end{codeexample} |
| 1184 |
% |
| 1185 |
we would get |He {said, ""Hello world.""}| as \meta{collected}. |
| 1186 |
\item ``The next single quotation mark'' refers to the next quotation mark |
| 1187 |
on the current level of braces, so in |"hello {"} world"|, the next |
| 1188 |
quotation mark would be the one following |world|. |
| 1189 |
\end{itemize} |
| 1190 |
|
| 1191 |
Now, once the \meta{collected} text has been gather, it is used as follows: |
| 1192 |
When used as \meta{text} (what is actually displayed), it is just used ``as |
| 1193 |
is''. When it is used as \meta{node name}, however, the following happens: |
| 1194 |
Every ``special character'' in \meta{collected} is replaced by its Unicode |
| 1195 |
name, surrounded by |@|-signs. For instance, if \meta{collected} is |
| 1196 |
|Hello, world!|, the \meta{node name} is the somewhat longer text |
| 1197 |
|Hello@COMMA@ world@EXCLAMATION MARK@|. Admittedly, referencing such a node |
| 1198 |
from outside the graph is cumbersome, but when you use exactly the same |
| 1199 |
\meta{collected} text once more, the same \meta{node name} will result. The |
| 1200 |
following characters are considered ``special'': |
| 1201 |
% |
| 1202 |
\begin{quote} |
| 1203 |
\texttt{\char`\|}|$&^~_[](){}/.-,+*'`!":;<=>?@#%\{}|%$ |
| 1204 |
\end{quote} |
| 1205 |
% |
| 1206 |
These are exactly the Unicode character with a decimal code number between 33 |
| 1207 |
and 126 that are neither digits nor letters. |
| 1208 |
|
| 1209 |
\medskip |
| 1210 |
\textbf{Reference Node Specifications.} A reference node specification is a |
| 1211 |
node specification that starts with an opening parenthesis. In this case, |
| 1212 |
parentheses must surround a \meta{name} as in |(foo)|, where |foo| is the |
| 1213 |
\meta{name}. The following will now happen: |
| 1214 |
% |
| 1215 |
\begin{enumerate} |
| 1216 |
\item It is tested whether \meta{name} is the name of a currently active |
| 1217 |
\emph{node set}. This case will be discussed in a moment. |
| 1218 |
\item Otherwise, the \meta{name} is interpreted and treated as a referenced |
| 1219 |
node, but independently of whether the node has already been fresh in |
| 1220 |
the current graph or not. In other words, the node must have been |
| 1221 |
defined either already inside the graph (in which case the parenthesis |
| 1222 |
are more or less superfluous) or it must have been defined outside the |
| 1223 |
current picture. |
| 1224 |
|
| 1225 |
The way the referenced node is handled is the same way as for a direct |
| 1226 |
node that is a referenced node. |
| 1227 |
|
| 1228 |
If the node does not already exist, an error message is printed. |
| 1229 |
\end{enumerate} |
| 1230 |
|
| 1231 |
Let us now have a look at node sets. Inside a |{tikzpicture}| you can locally |
| 1232 |
define a \emph{node set} by using the following key: |
| 1233 |
% |
| 1234 |
\begin{key}{/tikz/new set=\meta{set name}} |
| 1235 |
This will setup a node set named \meta{set name} within the current scope. |
| 1236 |
Inside the scope, you can add nodes to the node set using the |set| key. If |
| 1237 |
a node set of the same name already exists in the current scope, it will be |
| 1238 |
reset and made empty for the current scope. |
| 1239 |
|
| 1240 |
Note that this command has the path |/tikz| and is normally used |
| 1241 |
\emph{outside} the |graph| command. |
| 1242 |
\end{key} |
| 1243 |
% |
| 1244 |
\begin{key}{/tikz/set=\meta{set name}} |
| 1245 |
This key can be used as an option with a |node| command. The \meta{set |
| 1246 |
name} must be the name of a node set that has previously been created |
| 1247 |
inside some enclosing scope via the |new set| key. The effect is that the |
| 1248 |
current node is added to the node set. |
| 1249 |
\end{key} |
| 1250 |
|
| 1251 |
When you use a |graph| command inside a scope where some node set called |
| 1252 |
\meta{set name} is defined, then inside this |graph| command you use |
| 1253 |
|(|\meta{set name}|)| to reference \emph{all} of the nodes in the node set. The |
| 1254 |
effect is the same as if instead of the reference to the set name you had |
| 1255 |
created a group specification containing a list of references to all the nodes |
| 1256 |
that are part of the node set. |
| 1257 |
% |
| 1258 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1259 |
\begin{tikzpicture}[new set=red, new set=green, shorten >=2pt] |
| 1260 |
\foreach \i in {1,2,3} { |
| 1261 |
\node [draw, red!80, set=red] (r\i) at (\i,1) {$r_\i$}; |
| 1262 |
\node [draw, green!50!black, set=green] (g\i) at (\i,2) {$g_\i$}; |
| 1263 |
} |
| 1264 |
\graph { |
| 1265 |
root [xshift=2cm] -> |
| 1266 |
(red) -> [complete bipartite, right anchor=south] |
| 1267 |
(green) |
| 1268 |
}; |
| 1269 |
\end{tikzpicture} |
| 1270 |
\end{codeexample} |
| 1271 |
|
| 1272 |
There is an interesting caveat with referencing node sets: Suppose that at the |
| 1273 |
beginning of a graph you just say |(foo);| where |foo| is a set name. Unless |
| 1274 |
you have specified special options, this will cause the following to happen: A |
| 1275 |
group is created whose members are all the nodes of the node set |foo|. These |
| 1276 |
nodes become referenced nodes, but otherwise nothing happens since, by default, |
| 1277 |
the nodes of a group are not connected automatically. However, the referenced |
| 1278 |
nodes have now been referenced inside the graph, you can thus subsequently |
| 1279 |
access them as if they had been defined inside the graph. Here is an example |
| 1280 |
showing how you can create nodes outside a |graph| command and then connect |
| 1281 |
them inside as if they had been declared inside: |
| 1282 |
% |
| 1283 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1284 |
\begin{tikzpicture}[new set=import nodes] |
| 1285 |
\begin{scope}[nodes={set=import nodes}] % make all nodes part of this set |
| 1286 |
\node [red] (a) at (0,1) {$a$}; |
| 1287 |
\node [red] (b) at (1,1) {$b$}; |
| 1288 |
\node [red] (d) at (2,1) {$d$}; |
| 1289 |
\end{scope} |
| 1290 |
|
| 1291 |
\graph { |
| 1292 |
(import nodes); % "import" the nodes |
| 1293 |
|
| 1294 |
a -> b -> c -> d -> e; % only c and e are new |
| 1295 |
}; |
| 1296 |
\end{tikzpicture} |
| 1297 |
\end{codeexample} |
| 1298 |
|
| 1299 |
\medskip |
| 1300 |
\textbf{Group Node Specifications.} At a place where a node specification |
| 1301 |
should go, you can also instead provide a group specification. Since nodes |
| 1302 |
specifications are part of chain specifications, which in turn are part of |
| 1303 |
group specifications, this is a recursive definition. |
| 1304 |
% |
| 1305 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1306 |
\tikz \graph { a -> {b,c,d} -> {e -> {f,g}, h} }; |
| 1307 |
\end{codeexample} |
| 1308 |
|
| 1309 |
As can be seen in the above example, when two groups of nodes are connected via |
| 1310 |
an edge specification, it is not immediately obvious which connecting edges are |
| 1311 |
added. This is detailed in Section~\ref{section-library-graphs-color-classes}. |
| 1312 |
|
| 1313 |
|
| 1314 |
\subsubsection{Specifying Tries} |
| 1315 |
|
| 1316 |
In computer science, a \emph{trie} is a special kind of tree, where for each |
| 1317 |
node and each symbol of an alphabet, there is at most one child of the node |
| 1318 |
labeled with this symbol. |
| 1319 |
|
| 1320 |
The |trie| key is useful for drawing tries, but it can also be used in other |
| 1321 |
situations. What it does, essentially, is to prepend the node names of all |
| 1322 |
nodes \emph{before} the current node of the current chain to the node's name. |
| 1323 |
This will often make it easier or more natural to specify graphs in which |
| 1324 |
several nodes have the same label. |
| 1325 |
|
| 1326 |
\begin{key}{/tikz/graphs/trie=\opt{\meta{true or false}} (default true, initially false)} |
| 1327 |
If this key is set to |true|, after a node has been created on a chain, the |
| 1328 |
|name| key is executed with the node's \meta{node name}. Thus, all nodes |
| 1329 |
later on this chain have the ``path'' of nodes leading to this node as |
| 1330 |
their name. This means, in particular, that |
| 1331 |
% |
| 1332 |
\begin{enumerate} |
| 1333 |
\item two nodes of the same name but in different parts of a chain will |
| 1334 |
be different, |
| 1335 |
\item while if another chain starts with the same nodes, no new nodes |
| 1336 |
get created. |
| 1337 |
\end{enumerate} |
| 1338 |
% |
| 1339 |
In total, this is exactly the behavior you would expect of a trie: |
| 1340 |
% |
| 1341 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1342 |
\tikz \graph [trie] { |
| 1343 |
a -> { |
| 1344 |
a, |
| 1345 |
c -> {a, b}, |
| 1346 |
b |
| 1347 |
} |
| 1348 |
}; |
| 1349 |
\end{codeexample} |
| 1350 |
% |
| 1351 |
You can even ``reiterate'' over a path in conjunction with the |simple| |
| 1352 |
option. However, in this case, the default placement strategies will not |
| 1353 |
work and you will need options like |layered layout| from the graph drawing |
| 1354 |
libraries, which need Lua\TeX. |
| 1355 |
% |
| 1356 |
\ifluatex |
| 1357 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}\usegdlibrary{layered}}] |
| 1358 |
\tikz \graph [trie, simple, layered layout] { |
| 1359 |
a -> b -> a, |
| 1360 |
a -> b -> c, |
| 1361 |
a -> {d,a} |
| 1362 |
}; |
| 1363 |
\end{codeexample} |
| 1364 |
% |
| 1365 |
In the following example, we setup the |typeset| key so that it shows the |
| 1366 |
complete names of the nodes: |
| 1367 |
% |
| 1368 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}\usegdlibrary{layered}}] |
| 1369 |
\tikz \graph [trie, simple, layered layout, |
| 1370 |
typeset=\tikzgraphnodefullname] { |
| 1371 |
a -> b -> a, |
| 1372 |
a -> b -> c, |
| 1373 |
a -> {d,a} |
| 1374 |
}; |
| 1375 |
\end{codeexample} |
| 1376 |
\fi |
| 1377 |
% |
| 1378 |
You can also use the |trie| key locally and later reference nodes using |
| 1379 |
their full name: |
| 1380 |
% |
| 1381 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1382 |
\tikz \graph { |
| 1383 |
{ [trie, simple] |
| 1384 |
a -> { |
| 1385 |
b, |
| 1386 |
c -> a |
| 1387 |
} |
| 1388 |
}, |
| 1389 |
a b ->[red] a c a |
| 1390 |
}; |
| 1391 |
\end{codeexample} |
| 1392 |
% |
| 1393 |
\end{key} |
| 1394 |
|
| 1395 |
|
| 1396 |
\subsection{Quick Graphs} |
| 1397 |
\label{section-library-graphs-quick} |
| 1398 |
|
| 1399 |
The graph syntax is powerful, but this power comes at a price: parsing the |
| 1400 |
graph syntax, which is done by \TeX, can take some time. Normally, the parsing |
| 1401 |
is fast enough that you will not notice it, but it can be bothersome when you |
| 1402 |
have graphs with hundreds of nodes as happens frequently when nodes are |
| 1403 |
generated algorithmically by some other program. Fortunately, when another |
| 1404 |
program generated a graph specification, we typically do not need the full |
| 1405 |
power of the graph syntax. Rather, a small subset of the graph syntax would |
| 1406 |
suffice that allows to specify nodes and edges. For these reasons, the is a |
| 1407 |
special ``quick'' version of the graph syntax. |
| 1408 |
|
| 1409 |
Note, however, that using this syntax will usually at most halve the time |
| 1410 |
needed to parse a graph. Thus, it really mostly makes sense in conjunction with |
| 1411 |
large, algorithmically generated graphs. |
| 1412 |
|
| 1413 |
\begin{key}{/tikz/graphs/quick} |
| 1414 |
When you provide this key with a graph, the syntax of graph specifications |
| 1415 |
gets restricted. You are no longer allowed to use certain features of the |
| 1416 |
graph syntax; but all features that are still allowed are also allowed in |
| 1417 |
the same way when you do not provide the |quick| option. Thus, leaving out |
| 1418 |
the |quick| option will never hurt. |
| 1419 |
|
| 1420 |
Since the syntax is so severely restricted, it is easier to explain which |
| 1421 |
aspects of the graph syntax \emph{will} still work: |
| 1422 |
% |
| 1423 |
\begin{enumerate} |
| 1424 |
\item A quick graph consists of a sequence of either nodes, edges |
| 1425 |
sequences, or groups. These are separated by commas or semicolons. |
| 1426 |
\item Every node is of the form |
| 1427 |
% |
| 1428 |
\begin{quote} |
| 1429 |
|"|\meta{node name}|"|\opt{|/"|\meta{node text}|"[|\meta{options}|]|} |
| 1430 |
\end{quote} |
| 1431 |
|
| 1432 |
The quotation marks are mandatory. The part |/"|\meta{node text}|"| |
| 1433 |
may be missing, in which case the node name is used as the node |
| 1434 |
text. The \meta{options} may also be missing. The \meta{node name} |
| 1435 |
may not contain any ``funny'' characters (unlike in the normal |
| 1436 |
graph command). |
| 1437 |
\item Every chain is of the form |
| 1438 |
% |
| 1439 |
\begin{quote} |
| 1440 |
\meta{node spec} \meta{connector} \meta{node spec} |
| 1441 |
\meta{connector} \dots \meta{connector} \meta{node spec}|;| |
| 1442 |
\end{quote} |
| 1443 |
|
| 1444 |
Here, the \meta{node spec} are node specifications as described |
| 1445 |
above, the \meta{connector} is one of the four connectors |->|, |
| 1446 |
|<-|, |--|, and |<->| (the connector |-!-| is not allowed since the |
| 1447 |
|simple| option is also not allowed). Each connector may be |
| 1448 |
followed by options in square brackets. The semicolon may be |
| 1449 |
replaced by a comma. |
| 1450 |
\item Every group is of the form |
| 1451 |
% |
| 1452 |
\begin{quote} |
| 1453 |
|{ [|\meta{options}|]| \meta{chains and groups} |};| |
| 1454 |
\end{quote} |
| 1455 |
% |
| 1456 |
The \meta{options} are compulsory. The semicolon can, again, be |
| 1457 |
replaced by a comma. |
| 1458 |
\item The |number nodes| option will work as expected. |
| 1459 |
\end{enumerate} |
| 1460 |
|
| 1461 |
Here is a typical way this syntax might be used: |
| 1462 |
% |
| 1463 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1464 |
\tikz \graph [quick] { "a" --["foo"] "b"[x=1] }; |
| 1465 |
\end{codeexample} |
| 1466 |
|
| 1467 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1468 |
\tikz \graph [quick] { |
| 1469 |
"a"/"$a$" -- "b"[x=1] --[red] "c"[x=2]; |
| 1470 |
{ [nodes=blue] "a" -- "d"[y=1]; }; |
| 1471 |
}; |
| 1472 |
\end{codeexample} |
| 1473 |
|
| 1474 |
Let us now have a look at the most important things that will \emph{not} |
| 1475 |
work when the |quick| option is used: |
| 1476 |
|
| 1477 |
\begin{itemize} |
| 1478 |
\item Connecting a node and a group as in |a->{b,c}|. |
| 1479 |
\item Node names without quotation marks as in |a--b|. |
| 1480 |
\item Everything described in subsequent subsections, which includes |
| 1481 |
subgraphs (graph macros), graph sets, graph color classes, |
| 1482 |
anonymous nodes, the |fresh nodes| option, sublayouts, simple |
| 1483 |
graphs, edge annotations. |
| 1484 |
\item Placement strategies -- you either have to define all node |
| 1485 |
positions explicitly using |at=| or |x=| and |y=| or you must use a |
| 1486 |
graph drawing algorithm like |layered layout|. |
| 1487 |
\end{itemize} |
| 1488 |
\end{key} |
| 1489 |
|
| 1490 |
|
| 1491 |
\subsection{Simple Versus Multi-Graphs} |
| 1492 |
\label{section-library-graphs-simple} |
| 1493 |
|
| 1494 |
The |graphs| library allows you to construct both simple graphs and |
| 1495 |
multi-graphs. In a simple graph there can be at most one edge between any two |
| 1496 |
vertices, while in a multi-graph there can be multiple edges (hence the name). |
| 1497 |
The two keys |multi| and |simple| allow you to switch (even locally inside on |
| 1498 |
of the graph's scopes) between which kind of graph is being constructed. By |
| 1499 |
default, the |graph| command produces a multi-graph since these are faster to |
| 1500 |
construct. |
| 1501 |
|
| 1502 |
\begin{key}{/tikz/graphs/multi} |
| 1503 |
When this edge is set for a whole graph (which is the default) or just for |
| 1504 |
a group (which is useful if the whole graph is simple in general, but a |
| 1505 |
part is a multi-graph), then when you specify an edge between two nodes |
| 1506 |
several times, several such edges get created: |
| 1507 |
% |
| 1508 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1509 |
\tikz \graph [multi] { % "multi" is not really necessary here |
| 1510 |
a ->[bend left, red] b; |
| 1511 |
a ->[bend right, blue] b; |
| 1512 |
}; |
| 1513 |
\end{codeexample} |
| 1514 |
% |
| 1515 |
In case |multi| is used for a scope inside a larger scope where the |
| 1516 |
|simple| option is specified, then inside the local |multi| scope edges are |
| 1517 |
immediately created and they are completely ignored when it comes to |
| 1518 |
deciding which kind of edges should be present in the surrounding simple |
| 1519 |
graph. From the surrounding scope's point of view it is as if the local |
| 1520 |
|multi| graph contained no edges at all. |
| 1521 |
|
| 1522 |
This means, in particular, that you can use the |multi| option with a |
| 1523 |
single edge to ``enforce'' this edge to be present in a simple graph. |
| 1524 |
\end{key} |
| 1525 |
|
| 1526 |
\begin{key}{/tikz/graphs/simple} |
| 1527 |
In contrast a multi-graph, in a simple graph, at most one edge gets created |
| 1528 |
for every pair of vertices: |
| 1529 |
% |
| 1530 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1531 |
\tikz \graph [simple]{ |
| 1532 |
a ->[bend left, red] b; |
| 1533 |
a ->[bend right, blue] b; |
| 1534 |
}; |
| 1535 |
\end{codeexample} |
| 1536 |
% |
| 1537 |
As can be seen, the second edge ``wins'' over the first edge. The general |
| 1538 |
rule is as follows: In a simple graph, whenever an edge between two |
| 1539 |
vertices is specified multiple times, only the very last specification and |
| 1540 |
its options will actually be executed. |
| 1541 |
|
| 1542 |
The real power of the |simple| option lies in the fact that you can first |
| 1543 |
create a complicated graph and then later redirect and otherwise modify |
| 1544 |
edges easily: |
| 1545 |
% |
| 1546 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1547 |
\tikz \graph [simple, grow right=2cm] { |
| 1548 |
{a,b,c,d} ->[complete bipartite] {e,f,g,h}; |
| 1549 |
|
| 1550 |
{ [edges={red,thick}] a -> e -> d -> g -> a }; |
| 1551 |
}; |
| 1552 |
\end{codeexample} |
| 1553 |
|
| 1554 |
One particularly interesting kind of edge specification for a simple graph |
| 1555 |
is |-!-|. Recall that this is used to indicate that ``no edge'' should be |
| 1556 |
added between certain nodes. In a multi-graph, this key usually has no |
| 1557 |
effect (unless the key |new -!-| has been redefined) and is pretty |
| 1558 |
superfluous. In a simple graph, however, it counts as an edge kind and you |
| 1559 |
can thus use it to remove an edge that been added previously: |
| 1560 |
% |
| 1561 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 1562 |
\tikz \graph [simple] { |
| 1563 |
subgraph K_n [n=8, clockwise]; |
| 1564 |
% Get rid of the following edges: |
| 1565 |
1 -!- 2; |
| 1566 |
3 -!- 4; |
| 1567 |
6 -!- 8; |
| 1568 |
% And make one edge red: |
| 1569 |
1 --[red] 3; |
| 1570 |
}; |
| 1571 |
\end{codeexample} |
| 1572 |
|
| 1573 |
Creating a graph such as the above in other fashions is pretty awkward. |
| 1574 |
|
| 1575 |
For every unordered pair $\{u,v\}$ of vertices at most one edge will be |
| 1576 |
created in a simple graph. In particular, when you say |a -> b| and later |
| 1577 |
also |a <- b|, then only the edge |a <- b| will be created. Similarly, when |
| 1578 |
you say |a -> b| and later |b -> a|, then only the edge |b -> a| will be |
| 1579 |
created. |
| 1580 |
|
| 1581 |
The power of the |simple| command comes at a certain cost: As the graph is |
| 1582 |
being constructed, a (sparse) array is created that keeps track for each |
| 1583 |
edge of the last edge being specified. Then, at the end of the scope |
| 1584 |
containing the |simple| command, for every pair of vertices the edge is |
| 1585 |
created. This is implemented by two nested loops iterating over all |
| 1586 |
possible pairs of vertices -- which may take quite a while in a graph of, |
| 1587 |
say, 1000 vertices. Internally, the |simple| command is implemented as an |
| 1588 |
operator that adds the edges when it is called, but this should be |
| 1589 |
unimportant in normal situations. |
| 1590 |
\end{key} |
| 1591 |
|
| 1592 |
|
| 1593 |
\subsection{Graph Edges: Labeling and Styling} |
| 1594 |
|
| 1595 |
When the |graphs| library creates an edge between two nodes in a graph, the |
| 1596 |
appearance (called ``styling'' in \tikzname) can be specified in different |
| 1597 |
ways. Sometimes you will simply wish to say ``the edges between these two |
| 1598 |
groups of node should be red'', but sometimes you may wish to say ``this |
| 1599 |
particular edge going into this node should be red''. In the following, |
| 1600 |
different ways of specifying such styling requirements are discussed. Note that |
| 1601 |
adding labels to edges is, from \tikzname's point of view, almost the same as |
| 1602 |
styling edges, since they are also specified using options. |
| 1603 |
|
| 1604 |
|
| 1605 |
\subsubsection{Options For All Edges Between Two Groups} |
| 1606 |
|
| 1607 |
When you write |... ->[options] ...| somewhere inside your graph specification, |
| 1608 |
this typically cause one or more edges to be created between the nodes in the |
| 1609 |
chain group before the |->| and the nodes in the chain group following it. The |
| 1610 |
|options| are applied to all of them. In particular, if you use the |quotes| |
| 1611 |
library and you write some text in quotes inside the |options|, this text will |
| 1612 |
be added as a label to each edge: |
| 1613 |
% |
| 1614 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1615 |
\tikz |
| 1616 |
\graph [edge quotes=near start] { |
| 1617 |
{ a, b } -> [red, "x", complete bipartite] { c, d }; |
| 1618 |
}; |
| 1619 |
\end{codeexample} |
| 1620 |
|
| 1621 |
As documented in the |quotes| library in more detail, you can easily modify the |
| 1622 |
appearance of edge labels created using the quotes syntax by adding options |
| 1623 |
after the closing quotes: |
| 1624 |
% |
| 1625 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1626 |
\tikz \graph { |
| 1627 |
a ->["x"] b ->["y"'] c ->["z" red] d; |
| 1628 |
}; |
| 1629 |
\end{codeexample} |
| 1630 |
|
| 1631 |
The following options make it easy to setup the styling of nodes created in |
| 1632 |
this way: |
| 1633 |
% |
| 1634 |
\begin{key}{/tikz/graphs/edge quotes=\opt{\meta{options}}} |
| 1635 |
A shorthand for setting the style |every edge quotes| to \meta{options}. |
| 1636 |
% |
| 1637 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1638 |
\tikz \graph [edge quotes={blue,auto}] { |
| 1639 |
a ->["x"] b ->["y"'] c ->["b" red] d; |
| 1640 |
}; |
| 1641 |
\end{codeexample} |
| 1642 |
% |
| 1643 |
\end{key} |
| 1644 |
|
| 1645 |
\begin{key}{/tikz/graphs/edge quotes center} |
| 1646 |
A shorthand for |edge quotes| to |anchor=center|. |
| 1647 |
% |
| 1648 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1649 |
\tikz \graph [edge quotes center] { |
| 1650 |
a ->["x"] b ->["y"] c ->["z" red] d; |
| 1651 |
}; |
| 1652 |
\end{codeexample} |
| 1653 |
% |
| 1654 |
\end{key} |
| 1655 |
|
| 1656 |
\begin{key}{/tikz/graphs/edge quotes mid} |
| 1657 |
A shorthand for |edge quotes| to |anchor=mid|. |
| 1658 |
% |
| 1659 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1660 |
\tikz \graph [edge quotes mid] { |
| 1661 |
a ->["x"] b ->["y"] c ->["z" red] d; |
| 1662 |
}; |
| 1663 |
\end{codeexample} |
| 1664 |
% |
| 1665 |
\end{key} |
| 1666 |
|
| 1667 |
|
| 1668 |
\subsubsection{Changing Options For Certain Edges} |
| 1669 |
|
| 1670 |
Consider the following tree-like graph: |
| 1671 |
% |
| 1672 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1673 |
\tikz \graph { a -> {b,c} }; |
| 1674 |
\end{codeexample} |
| 1675 |
|
| 1676 |
Suppose we wish to specify that the edge from |a| to |b| should be red, while |
| 1677 |
the edge from |a| to |c| should be blue. The difficulty lies in the fact that |
| 1678 |
\emph{both} edges are created by the single |->| operator and we can only add |
| 1679 |
one of these option |red| or |blue| to the operator. |
| 1680 |
|
| 1681 |
There are several ways to solve this problem. First, we can simply split up the |
| 1682 |
specification and specify the two edges separately: |
| 1683 |
% |
| 1684 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1685 |
\tikz \graph { |
| 1686 |
a -> [red] b; |
| 1687 |
a -> [blue] c; |
| 1688 |
}; |
| 1689 |
\end{codeexample} |
| 1690 |
% |
| 1691 |
While this works quite well, we can no longer use the nice chain group syntax |
| 1692 |
of the |graphs| library. For the rather simple graph |a->{b,c}| this is not a |
| 1693 |
big problem, but if you specify a tree with, say, 30 nodes it is really |
| 1694 |
worthwhile being able to specify the tree ``in its natural form in the \TeX\ |
| 1695 |
code'' rather than having to list all of the edges explicitly. Also, as can be |
| 1696 |
seen in the above example, the node placement is changed, which is not always |
| 1697 |
desirable. |
| 1698 |
|
| 1699 |
One can sidestep this problem using the |simple| option: This option allows you |
| 1700 |
to first specify a graph and then, later on, replace edges by other edges and, |
| 1701 |
thereby, provide new options: |
| 1702 |
% |
| 1703 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1704 |
\tikz \graph [simple] { |
| 1705 |
a -> {b,c}; |
| 1706 |
a -> [red] b; |
| 1707 |
a -> [blue] c; |
| 1708 |
}; |
| 1709 |
\end{codeexample} |
| 1710 |
|
| 1711 |
The first line is the original specification of the tree, while the following |
| 1712 |
two lines replace some edges of the tree (in this case, all of them) by edges |
| 1713 |
with special options. While this method is slower and in the above example |
| 1714 |
creates even longer code, it is very useful if you wish to, say, highlight a |
| 1715 |
path in a larger tree: First specify the tree normally and, then, ``respecify'' |
| 1716 |
the path or paths with some other edge options in force. In the following |
| 1717 |
example, we use this to highlight a whole subtree of a larger tree: |
| 1718 |
% |
| 1719 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1720 |
\tikz \graph [simple] { |
| 1721 |
% The larger tree, no special options in force |
| 1722 |
a -> { |
| 1723 |
b -> {c,d}, |
| 1724 |
e -> {f,g}, |
| 1725 |
h |
| 1726 |
}, |
| 1727 |
{ [edges=red] % Now highlight a part of the tree |
| 1728 |
a -> e -> {f,g} |
| 1729 |
} |
| 1730 |
}; |
| 1731 |
\end{codeexample} |
| 1732 |
|
| 1733 |
|
| 1734 |
\subsubsection{Options For Incoming and Outgoing Edges} |
| 1735 |
|
| 1736 |
When you use the syntax |... ->[options] ...| to specify options, you specify |
| 1737 |
options for the ``connections between two sets of nodes''. In many cases, |
| 1738 |
however, it will be more natural to specify options ``for the edges lead to or |
| 1739 |
coming from a certain node'' and you will want to specify these options ``at |
| 1740 |
the node''. Returning to the example of the graph |a->{b,c}| where we want a |
| 1741 |
red edge between |a| and |b| and a blue edge between |a| and |c|, this could |
| 1742 |
also be phrased as follows: ``Make the edge leading to |b| red and make the |
| 1743 |
edge leading to |c| blue''. |
| 1744 |
|
| 1745 |
For this situation, the |graphs| library offers a number of special keys, which |
| 1746 |
are documented in the following. However, most of the time you will not use |
| 1747 |
these keys directly, but, rather, use a special syntax explained in |
| 1748 |
Section~\ref{section-syntax-outgoing-incoming}. |
| 1749 |
|
| 1750 |
\begin{key}{/tikz/graphs/target edge style=\meta{options}} |
| 1751 |
This key can (only) be used with a \emph{node} inside a graph |
| 1752 |
specification. When used, the \meta{options} will be added to every edge |
| 1753 |
that is created by a connector like |->| in which the node is a |
| 1754 |
\emph{target}. Consider the following example: |
| 1755 |
% |
| 1756 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1757 |
\tikz \graph { |
| 1758 |
{ a, b } -> |
| 1759 |
{ c [target edge style=red], d } -> |
| 1760 |
{ e, f } |
| 1761 |
}; |
| 1762 |
\end{codeexample} |
| 1763 |
% |
| 1764 |
In the example, only when the edge from |a| to |c| is created, |c| is the |
| 1765 |
``target'' of the edge. Thus, only this edge becomes red. |
| 1766 |
|
| 1767 |
When an edge already has options set directly, the \meta{options} are |
| 1768 |
executed after these direct options, thus, they ``overrule'' them: |
| 1769 |
% |
| 1770 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1771 |
\tikz \graph { |
| 1772 |
{ a, b } -> [blue, thick] |
| 1773 |
{ c [target edge style=red], d } -> |
| 1774 |
{ e, f } |
| 1775 |
}; |
| 1776 |
\end{codeexample} |
| 1777 |
|
| 1778 |
The \meta{options} set in this way will stay attached to the node, so also |
| 1779 |
for edges created later on that lead to the node will have these options |
| 1780 |
set: |
| 1781 |
% |
| 1782 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1783 |
\tikz \graph { |
| 1784 |
{ a, b } -> |
| 1785 |
{ c [target edge style=red], d } -> |
| 1786 |
{ e, f }, |
| 1787 |
b -> c |
| 1788 |
}; |
| 1789 |
\end{codeexample} |
| 1790 |
|
| 1791 |
Multiple uses of this key accumulate. However, you may sometimes also wish |
| 1792 |
to ``clear'' these options for a key since at some later point you no |
| 1793 |
longer wish the \meta{options} to be added when some further edges are |
| 1794 |
added. This can be achieved using the following key: |
| 1795 |
% |
| 1796 |
\begin{key}{/tikz/graphs/target edge clear} |
| 1797 |
Clears all \meta{options} for edges with the node as a target and |
| 1798 |
also edge labels (see below) for this node. |
| 1799 |
\end{key} |
| 1800 |
% |
| 1801 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1802 |
\tikz \graph { |
| 1803 |
{ a, b } -> |
| 1804 |
{ c [target edge style=red], d }, |
| 1805 |
b -> c[target edge clear] |
| 1806 |
}; |
| 1807 |
\end{codeexample} |
| 1808 |
% |
| 1809 |
\end{key} |
| 1810 |
|
| 1811 |
\begin{key}{/tikz/graphs/target edge node=\meta{node specification}} |
| 1812 |
This key works like |target edge style|, only the \meta{node specification} |
| 1813 |
will not be added as options to any newly created edges with the current |
| 1814 |
node as their target, but rather it will be added as a node specification. |
| 1815 |
% |
| 1816 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1817 |
\tikz \graph { |
| 1818 |
{ a, b } -> |
| 1819 |
{ c [target edge node=node{X}], d } -> |
| 1820 |
{ e, f } |
| 1821 |
}; |
| 1822 |
\end{codeexample} |
| 1823 |
% |
| 1824 |
As for |target edge style| multiple uses of this key accumulate and the key |
| 1825 |
|target edge clear| will (also) clear all target edge nodes that have been |
| 1826 |
set for a node earlier on. |
| 1827 |
\end{key} |
| 1828 |
|
| 1829 |
\begin{key}{/tikz/graphs/source edge style=\meta{options}} |
| 1830 |
Works exactly like |target edge style|, only now the \meta{options} are |
| 1831 |
only added when the node is a source of a newly created edge: |
| 1832 |
% |
| 1833 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1834 |
\tikz \graph { |
| 1835 |
{ a, b } -> |
| 1836 |
{ c [source edge style=red], d } -> |
| 1837 |
{ e, f } |
| 1838 |
}; |
| 1839 |
\end{codeexample} |
| 1840 |
% |
| 1841 |
If both for the source and also for the target of an edge \meta{options} |
| 1842 |
have been specified, the options are applied in the following order: |
| 1843 |
% |
| 1844 |
\begin{enumerate} |
| 1845 |
\item First come the options from the edge itself. |
| 1846 |
\item Then come the options contributed by the source node using this |
| 1847 |
key. |
| 1848 |
\item Then come the options contributed by the target node using |
| 1849 |
|target node style|. |
| 1850 |
\end{enumerate} |
| 1851 |
% |
| 1852 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1853 |
\tikz \graph { |
| 1854 |
a [source edge style=red] ->[green] |
| 1855 |
b [target edge style=blue] % blue wins |
| 1856 |
}; |
| 1857 |
\end{codeexample} |
| 1858 |
% |
| 1859 |
\end{key} |
| 1860 |
|
| 1861 |
\begin{key}{/tikz/graphs/source edge node=\meta{node specification}} |
| 1862 |
Works like |source edge style| and |target edge node|. |
| 1863 |
\end{key} |
| 1864 |
|
| 1865 |
\begin{key}{/tikz/graphs/source edge clear=\meta{node specification}} |
| 1866 |
Works like |target edge clear|. |
| 1867 |
\end{key} |
| 1868 |
|
| 1869 |
|
| 1870 |
\subsubsection{Special Syntax for Options For Incoming and Outgoing Edges} |
| 1871 |
\label{section-syntax-outgoing-incoming} |
| 1872 |
|
| 1873 |
The keys |target node style| and its friends are powerful, but a bit cumbersome |
| 1874 |
to write down. For this reason, the |graphs| library introduces a special |
| 1875 |
syntax that is based on what I call the ``first-char syntax'' of keys. Inside |
| 1876 |
the options of a node inside a graph, the following special rules apply: |
| 1877 |
% |
| 1878 |
\begin{enumerate} |
| 1879 |
\item Whenever an option starts with |>|, the rest of the options are |
| 1880 |
passed to |target edge style|. For instance, when you write |a[>red]|, |
| 1881 |
then this has the same effect as if you had written |
| 1882 |
% |
| 1883 |
\begin{codeexample}[code only] |
| 1884 |
a[target edge style={red}] |
| 1885 |
\end{codeexample} |
| 1886 |
% |
| 1887 |
\item Whenever an options starts with |<|, the rest of the options are |
| 1888 |
passed to |source edge style|. |
| 1889 |
\item In both of the above case, in case the options following the |>| or |
| 1890 |
|<| sign start with a quote, the created edge label is passed to |
| 1891 |
|source edge node| or |target edge node|, respectively. |
| 1892 |
|
| 1893 |
This is exactly what you want to happen. |
| 1894 |
\end{enumerate} |
| 1895 |
% |
| 1896 |
Additionally, the following styles provide shorthands for ``clearing'' the |
| 1897 |
target and source options: |
| 1898 |
% |
| 1899 |
\begin{key}{/tikz/graphs/clear >} |
| 1900 |
A more easy-to-remember shorthand for |target edge clear|. |
| 1901 |
\end{key} |
| 1902 |
% |
| 1903 |
\begin{key}{/tikz/graphs/clear <} |
| 1904 |
A more easy-to-remember shorthand for |source edge clear|. |
| 1905 |
\end{key} |
| 1906 |
|
| 1907 |
These mechanisms make it especially easy to create trees in which the edges are |
| 1908 |
labeled in some special way: |
| 1909 |
% |
| 1910 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1911 |
\tikz |
| 1912 |
\graph [edge quotes={fill=white,inner sep=1pt}, |
| 1913 |
grow down, branch right] { |
| 1914 |
/ -> h [>"9"] -> { |
| 1915 |
c [>"4" text=red,] -> { |
| 1916 |
a [>"2", >thick], |
| 1917 |
e [>"0"] |
| 1918 |
}, |
| 1919 |
j [>"7"] |
| 1920 |
} |
| 1921 |
}; |
| 1922 |
\end{codeexample} |
| 1923 |
|
| 1924 |
|
| 1925 |
\subsubsection{Placing Node Texts on Incoming Edges} |
| 1926 |
|
| 1927 |
Normally, the text of a node is shown (only) inside the node. In some case, for |
| 1928 |
instance when drawing certain kind of trees, the nodes themselves should not |
| 1929 |
get any text, but rather the edge leading to the node should be labeled as in |
| 1930 |
the following example: |
| 1931 |
% |
| 1932 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 1933 |
\tikz \graph [empty nodes] |
| 1934 |
{ |
| 1935 |
root -> { |
| 1936 |
a [>"a"], |
| 1937 |
b [>"b"] -> { |
| 1938 |
c [>"c"], |
| 1939 |
d [>"d"] |
| 1940 |
} |
| 1941 |
} |
| 1942 |
}; |
| 1943 |
\end{codeexample} |
| 1944 |
% |
| 1945 |
As the example shows, it is a bit cumbersome that we have to label the nodes |
| 1946 |
and then specify the same text once more using the incoming edge syntax. |
| 1947 |
|
| 1948 |
For these cases, it would be better if the text of the node where not used with |
| 1949 |
the node but, rather, be passed directly to the incoming or the outgoing edge. |
| 1950 |
The following styles do exactly this: |
| 1951 |
|
| 1952 |
\begin{key}{/tikz/graphs/put node text on incoming edges=\opt{\meta{options}}} |
| 1953 |
When this key is used with a node or a group, the following happens: |
| 1954 |
% |
| 1955 |
\begin{enumerate} |
| 1956 |
\item The command |
| 1957 |
|target edge node={node[|\meta{options}|]{\tikzgraphnodetext}}| is |
| 1958 |
executed. This means that all incoming edges of the node get a |
| 1959 |
label with the text that would usually be displayed in the node. |
| 1960 |
You can use keys like |math nodes| normally. |
| 1961 |
\item The command |as={}| is executed. This means that the node itself |
| 1962 |
will display nothing. |
| 1963 |
\end{enumerate} |
| 1964 |
% |
| 1965 |
Here is an example that show how this command is used. |
| 1966 |
% |
| 1967 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 1968 |
\tikz \graph [put node text on incoming edges, |
| 1969 |
math nodes, nodes={circle,draw}] |
| 1970 |
{ a -> b -> {c, d} }; |
| 1971 |
\end{codeexample} |
| 1972 |
% |
| 1973 |
\end{key} |
| 1974 |
|
| 1975 |
\begin{key}{/tikz/graphs/put node text on outgoing edges=\opt{\meta{options}}} |
| 1976 |
Works like the previous key, only with |target| replaced by |source|. |
| 1977 |
\end{key} |
| 1978 |
|
| 1979 |
|
| 1980 |
\subsection{Graph Operators, Color Classes, and Graph Expressions} |
| 1981 |
\label{section-library-graphs-color-classes} |
| 1982 |
|
| 1983 |
\tikzname's |graph| command employs a powerful mechanism for adding edges |
| 1984 |
between nodes and sets of nodes. To a graph theorist, this mechanism may be |
| 1985 |
known as a \emph{graph expression}: A graph is specified by starting with small |
| 1986 |
graphs and then applying \emph{operators} to them that form larger graphs and |
| 1987 |
that connect and recolor colored subsets of the graph's node in different ways. |
| 1988 |
|
| 1989 |
|
| 1990 |
\subsubsection{Color Classes} |
| 1991 |
\label{section-library-graph-coloring} |
| 1992 |
|
| 1993 |
\tikzname\ keeps track of a \emph{(multi)coloring} of the graph as it is being |
| 1994 |
constructed. This does not mean that the actual color of the nodes on the page |
| 1995 |
will be different, rather, in the following we refer to ``logical'' colors in |
| 1996 |
the way graph theoreticians do. These ``logical'' colors are only important |
| 1997 |
while the graph is being constructed and they are ``thrown away'' at the end of |
| 1998 |
the construction. The actual (``physical'') colors of the nodes are set |
| 1999 |
independently of these logical colors. |
| 2000 |
|
| 2001 |
As a graph is being constructed, each node can be part of one or more |
| 2002 |
overlapping \emph{color classes}. So, unlike what is sometimes called a |
| 2003 |
\emph{legal coloring}, the logical colorings that \tikzname\ keeps track of may |
| 2004 |
assign multiple colors to the same node and two nodes connected by an edge may |
| 2005 |
well have the same color. |
| 2006 |
|
| 2007 |
Color classes must be declared prior to use. This is done using the following |
| 2008 |
key: |
| 2009 |
% |
| 2010 |
\begin{key}{/tikz/graphs/color class=\meta{color class name}} |
| 2011 |
This sets up a new color class called \meta{color class name}. Nodes and |
| 2012 |
whole groups of nodes can now be colored with \meta{color class name}. This |
| 2013 |
is done using the following keys, which become |
| 2014 |
available inside the current scope: |
| 2015 |
% |
| 2016 |
\begin{key}{/tikz/graphs/\meta{color class name}} |
| 2017 |
This key internally uses the |operator| command to setup an operator |
| 2018 |
that will cause all nodes of the current group to get the ``logical |
| 2019 |
color'' \meta{color class name}. Nodes retain this color in all |
| 2020 |
encompassing scopes, unless it is explicitly changed (see below) or |
| 2021 |
unset (again, see below). |
| 2022 |
% |
| 2023 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2024 |
\tikz \graph [color class=red] { |
| 2025 |
[cycle=red] % causes all "logically" red nodes to be connected in |
| 2026 |
% a cycle |
| 2027 |
a, |
| 2028 |
b [red], |
| 2029 |
{ [red] c ->[bend right] d }, |
| 2030 |
e |
| 2031 |
}; |
| 2032 |
\end{codeexample} |
| 2033 |
% |
| 2034 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2035 |
\tikz \graph [color class=red, color class=green, |
| 2036 |
math nodes, clockwise, n=5] { |
| 2037 |
[complete bipartite={red}{green}] |
| 2038 |
{ [red] r_1, r_2 }, |
| 2039 |
{ [green] g_1, g_2, g_3 } |
| 2040 |
}; |
| 2041 |
\end{codeexample} |
| 2042 |
\end{key} |
| 2043 |
% |
| 2044 |
\begin{key}{/tikz/graphs/not \meta{color class name}} |
| 2045 |
Sets up an operator for the current scope so that all nodes in it loose |
| 2046 |
the color \meta{color class name}. You can also use |!|\meta{color |
| 2047 |
class name} as an alias for this key. |
| 2048 |
% |
| 2049 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2050 |
\tikz \graph [color class=red, color class=green, |
| 2051 |
math nodes, clockwise, n=5] { |
| 2052 |
[complete bipartite={red}{green}] |
| 2053 |
{ [red] r_1, r_2 }, |
| 2054 |
{ [green] g_1, g_2, g_3 }, |
| 2055 |
g_2 [not green] |
| 2056 |
}; |
| 2057 |
\end{codeexample} |
| 2058 |
\end{key} |
| 2059 |
% |
| 2060 |
\begin{key}{/tikz/graphs/recolor \meta{color class name} by=\meta{new color}} |
| 2061 |
Causes all keys having color \meta{color class name} to get \meta{new |
| 2062 |
color} instead. They loose having color \meta{color class name}, but |
| 2063 |
other colors are not affected. |
| 2064 |
% |
| 2065 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2066 |
\tikz \graph [color class=red, color class=green, |
| 2067 |
math nodes, clockwise, n=5] { |
| 2068 |
[complete bipartite={red}{green}] |
| 2069 |
{ [red] r_1, r_2 }, |
| 2070 |
{ [green] g_1, g_2, g_3 }, |
| 2071 |
g_2 [recolor green by=red] |
| 2072 |
}; |
| 2073 |
\end{codeexample} |
| 2074 |
\end{key} |
| 2075 |
\end{key} |
| 2076 |
|
| 2077 |
The following color classes are available by default: |
| 2078 |
% |
| 2079 |
\begin{itemize} |
| 2080 |
\item Color class |all|. Every node is part of this class by default. This |
| 2081 |
is useful to access all nodes of a (sub)graph, since you can simply |
| 2082 |
access all nodes of this color class. |
| 2083 |
\item Color classes |source| and |target|. These classes are used to |
| 2084 |
identify nodes that lead ``into'' a group of nodes and nodes from which |
| 2085 |
paths should ``leave'' the group. Details on how these colors are |
| 2086 |
assigned are explained in Section~\ref{section-library-graphs-join}. By |
| 2087 |
saying |not source| or |not target| with a node, you can influence how |
| 2088 |
it is connected: |
| 2089 |
% |
| 2090 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2091 |
\tikz \graph { a -> { b, c, d } -> e }; |
| 2092 |
\end{codeexample} |
| 2093 |
% |
| 2094 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2095 |
\tikz \graph { a -> { b[not source], c, d[not target] } -> e }; |
| 2096 |
\end{codeexample} |
| 2097 |
% |
| 2098 |
\item Color classes |source'| and |target'|. These are temporary colors |
| 2099 |
that are also explained in Section~\ref{section-library-graphs-join}. |
| 2100 |
\end{itemize} |
| 2101 |
|
| 2102 |
|
| 2103 |
\subsubsection{Graph Operators on Groups of Nodes} |
| 2104 |
|
| 2105 |
Recall that the |graph| command constructs graphs recursively from nested |
| 2106 |
\meta{group specifications}. Each such \meta{group specification} describes a |
| 2107 |
subset of the nodes of the final graph. A \emph{graph operator} is an algorithm |
| 2108 |
that gets the nodes of a group as input and (typically) adds edges between |
| 2109 |
these nodes in some sensible way. For instance, the |clique| operator will |
| 2110 |
simply add edges between all nodes of the group. |
| 2111 |
|
| 2112 |
\begin{key}{/tikz/graphs/operator=\meta{code}} |
| 2113 |
This key has an effect in three places: |
| 2114 |
% |
| 2115 |
\begin{enumerate} |
| 2116 |
\item It can be used in the \meta{options} of a \meta{direct node |
| 2117 |
specification}. |
| 2118 |
\item It can be used in the \meta{options} of a \meta{group |
| 2119 |
specification}. |
| 2120 |
\item It can be used in the \meta{options} of an \meta{edge |
| 2121 |
specification}. |
| 2122 |
\end{enumerate} |
| 2123 |
% |
| 2124 |
The first case is a special case of the second, since it is treated like a |
| 2125 |
group specification containing a single node. The last case is more |
| 2126 |
complicated and discussed in the next section. So, let us focus on the |
| 2127 |
second case. |
| 2128 |
|
| 2129 |
Even though the \meta{options} of a group are given at the beginning of the |
| 2130 |
\meta{group specification}, the \meta{code} is only executed when the group |
| 2131 |
has been parsed completely and all its nodes have been identified. If you |
| 2132 |
use the |operator| multiple times in the \meta{options}, the effect |
| 2133 |
accumulates, that is, all code passed to the different calls of |operator| |
| 2134 |
gets executed in the order it is encountered. |
| 2135 |
|
| 2136 |
The \meta{code} can do ``whatever it wants'', but it will typically add |
| 2137 |
edges between certain nodes. You can configure what kind of edges |
| 2138 |
(directed, undirected, etc.) are created by using the following keys: |
| 2139 |
% |
| 2140 |
\begin{key}{/tikz/graphs/default edge kind=\meta{value} (initially -\/-)} |
| 2141 |
This key stores one of the five edge kinds |--|, |<-|, |->|, |<->|, and |
| 2142 |
|-!-|. When an operator wishes to create a new edge, it should |
| 2143 |
typically set |
| 2144 |
% |
| 2145 |
\begin{codeexample}[code only] |
| 2146 |
\tikzgraphsset{new \pfkeysvalueof{/tikz/graphs/default edge kind}=...} |
| 2147 |
\end{codeexample} |
| 2148 |
% |
| 2149 |
While this key can be set explicitly, it may be more convenient to use |
| 2150 |
the abbreviating keys listed below. Also, this key is automatically set |
| 2151 |
to the current value of \meta{edge specification} when a joining |
| 2152 |
operator is called, see the discussion of joining operators in |
| 2153 |
Section~\ref{section-library-graphs-join}. |
| 2154 |
\end{key} |
| 2155 |
% |
| 2156 |
\begin{key}{/tikz/graphs/--} |
| 2157 |
Sets the |default edge kind| to |--|. |
| 2158 |
% |
| 2159 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2160 |
\tikz \graph { subgraph K_n [--, n=5, clockwise, radius=6mm] }; |
| 2161 |
\end{codeexample} |
| 2162 |
\end{key} |
| 2163 |
% |
| 2164 |
\begin{key}{/tikz/graphs/->} |
| 2165 |
Sets the |default edge kind| to |->|. |
| 2166 |
% |
| 2167 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2168 |
\tikz \graph { subgraph K_n [->, n=5, clockwise, radius=6mm] }; |
| 2169 |
\end{codeexample} |
| 2170 |
\end{key} |
| 2171 |
% |
| 2172 |
\begin{key}{/tikz/graphs/<-} |
| 2173 |
Sets the |default edge kind| to |<-|. |
| 2174 |
% |
| 2175 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2176 |
\tikz \graph { subgraph K_n [<-, n=5, clockwise, radius=6mm] }; |
| 2177 |
\end{codeexample} |
| 2178 |
\end{key} |
| 2179 |
% |
| 2180 |
\begin{key}{/tikz/graphs/<->} |
| 2181 |
Sets the |default edge kind| to |<->|. |
| 2182 |
% |
| 2183 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2184 |
\tikz \graph { subgraph K_n [<->, n=5, clockwise, radius=6mm] }; |
| 2185 |
\end{codeexample} |
| 2186 |
\end{key} |
| 2187 |
% |
| 2188 |
\begin{key}{/tikz/graphs/-\protect\exclamationmarktext-} |
| 2189 |
Sets the |default edge kind| to |-!-|. |
| 2190 |
\end{key} |
| 2191 |
|
| 2192 |
When the \meta{code} of an operator is executed, the following commands can |
| 2193 |
be used to find the nodes that should be connected: |
| 2194 |
% |
| 2195 |
\begin{command}{\tikzgraphforeachcolorednode\marg{color name}\marg{macro}} |
| 2196 |
When this command is called inside \meta{code}, the following will |
| 2197 |
happen: \tikzname\ will iterate over all nodes inside the |
| 2198 |
just-specified group that have the color \meta{color name}. The order |
| 2199 |
in which they are iterated over is the order in which they appear |
| 2200 |
inside the group specification (if a node is encountered several times |
| 2201 |
inside the specification, only the first occurrence counts). Then, for |
| 2202 |
each node the \meta{macro} is executed with the node's name as the only |
| 2203 |
argument. |
| 2204 |
|
| 2205 |
In the following example we use an operator to connect every node |
| 2206 |
colored |all| inside the subgroup to he node |root|. |
| 2207 |
% |
| 2208 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2209 |
\def\myconnect#1{\tikzset{graphs/new ->={root}{#1}{}{}}} |
| 2210 |
|
| 2211 |
\begin{tikzpicture} |
| 2212 |
\node (root) at (-1,-1) {root}; |
| 2213 |
|
| 2214 |
\graph { |
| 2215 |
x, |
| 2216 |
{ |
| 2217 |
[operator=\tikzgraphforeachcolorednode{all}{\myconnect}] |
| 2218 |
a, b, c |
| 2219 |
} |
| 2220 |
}; |
| 2221 |
\end{tikzpicture} |
| 2222 |
\end{codeexample} |
| 2223 |
\end{command} |
| 2224 |
|
| 2225 |
\begin{command}{\tikzgraphpreparecolor\marg{color name}\marg{counter}\marg{prefix}} |
| 2226 |
This command is used to ``prepare'' the nodes of a certain color for |
| 2227 |
random access. The effect is the following: It is counted how many |
| 2228 |
nodes there are having color \meta{color name} in the current group and |
| 2229 |
the result is stored in \meta{counter}. Next, macros named |
| 2230 |
\meta{prefix}|1|, \meta{prefix}|2|, and so on are defined, that store |
| 2231 |
the names of the first, second, third, and so on node having the color |
| 2232 |
\meta{color name}. |
| 2233 |
|
| 2234 |
The net effect is that after you have prepared a color, you can quickly |
| 2235 |
iterate over them. This is especially useful when you iterate over |
| 2236 |
several color at the same time. |
| 2237 |
|
| 2238 |
As an example, let us create an operator then adds a zig-zag path |
| 2239 |
between two color classes: |
| 2240 |
% |
| 2241 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2242 |
\newcount\leftshorecount \newcount\rightshorecount |
| 2243 |
\newcount\mycount \newcount\myothercount |
| 2244 |
\def\zigzag{ |
| 2245 |
\tikzgraphpreparecolor{left shore}\leftshorecount{left shore prefix} |
| 2246 |
\tikzgraphpreparecolor{right shore}\rightshorecount{right shore prefix} |
| 2247 |
\mycount=0\relax |
| 2248 |
\loop |
| 2249 |
\advance\mycount by 1\relax% |
| 2250 |
% Add the "forward" edge |
| 2251 |
\tikzgraphsset{new ->= |
| 2252 |
{\csname left shore prefix\the\mycount\endcsname} |
| 2253 |
{\csname right shore prefix\the\mycount\endcsname}{}{}} |
| 2254 |
\myothercount=\mycount\relax% |
| 2255 |
\advance\myothercount by1\relax% |
| 2256 |
\tikzgraphsset{new <-= |
| 2257 |
{\csname left shore prefix\the\myothercount\endcsname} |
| 2258 |
{\csname right shore prefix\the\mycount\endcsname}{}{}} |
| 2259 |
\ifnum\myothercount<\leftshorecount\relax |
| 2260 |
\repeat |
| 2261 |
} |
| 2262 |
\begin{tikzpicture} |
| 2263 |
\graph [color class=left shore, color class=right shore] |
| 2264 |
{ [operator=\zigzag] |
| 2265 |
{ [left shore, Cartesian placement] a, b, c }, |
| 2266 |
{ [right shore, Cartesian placement, nodes={xshift=1cm}] d, e, f } |
| 2267 |
}; |
| 2268 |
\end{tikzpicture} |
| 2269 |
\end{codeexample} |
| 2270 |
% |
| 2271 |
Naturally, in order to turn the above code into a usable operator, some |
| 2272 |
more code would be needed (like default values and taking care of |
| 2273 |
shores of different sizes). |
| 2274 |
\end{command} |
| 2275 |
\end{key} |
| 2276 |
|
| 2277 |
There are a number of predefined operators, like |clique| or |cycle|, see the |
| 2278 |
reference Section~\ref{section-library-graphs-reference} for a complete list. |
| 2279 |
|
| 2280 |
|
| 2281 |
\subsubsection{Graph Operators for Joining Groups} |
| 2282 |
\label{section-library-graphs-join} |
| 2283 |
|
| 2284 |
When you join two nodes |foo| and |bar| by the edge specification |->|, it is |
| 2285 |
fairly obvious, what should happen: An edge from |(foo)| to |(bar)| should be |
| 2286 |
created. However, suppose we use an edge specification between two node sets |
| 2287 |
like |{a,b,c}| and |{d,e,f}|. In this case, it is not so clear which edges |
| 2288 |
should be created. One might argue that all possible edges from any node in the |
| 2289 |
first set to any node in the second set should be added. On the other hand, one |
| 2290 |
might also argue that only a matching between these two sets should be created. |
| 2291 |
Things get even more muddy when a longer chain of node sets are joined. |
| 2292 |
|
| 2293 |
Instead of fixing how edges are created between two node sets, \tikzname\ takes |
| 2294 |
a somewhat more general, but also more complicated approach, which can be |
| 2295 |
broken into two parts. In the following, assume that the following chain |
| 2296 |
specification is given: |
| 2297 |
% |
| 2298 |
\begin{quote} |
| 2299 |
\meta{spec$_1$} \meta{edge specification} \meta{spec$_2$} |
| 2300 |
\end{quote} |
| 2301 |
% |
| 2302 |
An example might be |{a,b,c} -> {d, e->f}|. |
| 2303 |
|
| 2304 |
\medskip |
| 2305 |
\textbf{The source and target vertices.} Let us start with the question of |
| 2306 |
which vertices of the first node set should be connected to vertices in the |
| 2307 |
second node set. |
| 2308 |
|
| 2309 |
There are two predefined special color classes that are used for this: |source| |
| 2310 |
and |target|. For every group specification, some vertices are colored as |
| 2311 |
|source| vertices and some vertices are |target| vertices (a node can both be a |
| 2312 |
target and a source). Initially, every vertex is both a source and a target, |
| 2313 |
but that can change as we will see in a moment. |
| 2314 |
|
| 2315 |
The intuition behind source and target vertices is that, in some sense, edges |
| 2316 |
``from the outside'' lead into the group via the source vertices and lead out |
| 2317 |
of the group via the target vertices. To be more precise, the following |
| 2318 |
happens: |
| 2319 |
% |
| 2320 |
\begin{enumerate} |
| 2321 |
\item The target vertices of the first group are connected to the source |
| 2322 |
vertices of the second group. |
| 2323 |
\item In the group resulting from the union of the nodes from |
| 2324 |
\meta{spec$_1$} and \meta{spec$_2$}, the source vertices are only those |
| 2325 |
from the first group, and the target vertices are only those from the |
| 2326 |
second group. |
| 2327 |
\end{enumerate} |
| 2328 |
|
| 2329 |
Let us go over the effect of these rules for the example |
| 2330 |
|{a,b,c} -> {d, e->f}|. First, each individual node is initially both a |
| 2331 |
|source| and a |target| vertex. Then, in |{a,b,c}| all nodes are still both |
| 2332 |
source and target vertices since just grouping vertices does not change their |
| 2333 |
colors. Now, in |e->f| something interesting happens for the first time: the |
| 2334 |
target vertices of the ``group'' |e| (which is just the node |e|) are connected |
| 2335 |
to the source vertices of the ``group'' |f|. This means, that an edge is added |
| 2336 |
from |e| to |f|. Then, in the resulting group |e->f| the only source vertex is |
| 2337 |
|e| and the only target vertex is |f|. This implies that in the group |
| 2338 |
|{d,e->f}| the sources are |d| and |e| and the targets are |d| and~|f|. |
| 2339 |
|
| 2340 |
Now, in |{a,b,c} -> {d,e->f}| the targets of |{a,b,c}| (which are all three of |
| 2341 |
them) are connected to the sources of |{d,e->f}| (which are just |d| and~|e|). |
| 2342 |
Finally, in the whole graph only |a|, |b|, and |c| are sources while only |d| |
| 2343 |
and |f| are targets. |
| 2344 |
% |
| 2345 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2346 |
\def\hilightsource#1{\fill [green, opacity=.25] (#1) circle [radius=2mm]; } |
| 2347 |
\def\hilighttarget#1{\fill [red, opacity=.25] (#1) circle [radius=2mm]; } |
| 2348 |
\tikz \graph |
| 2349 |
[operator=\tikzgraphforeachcolorednode{source}{\hilightsource}, |
| 2350 |
operator=\tikzgraphforeachcolorednode{target}{\hilighttarget}] |
| 2351 |
{ {a,b,c} -> {d, e->f} }; |
| 2352 |
\end{codeexample} |
| 2353 |
|
| 2354 |
The next objective is to make more precise what it means that ``the targets of |
| 2355 |
the first graph'' and the ``sources of the second graph'' should be connected. |
| 2356 |
We know already of a general way of connecting nodes of a graph: operators! |
| 2357 |
Thus, we use an operator for this job. For instance, the |complete bipartite| |
| 2358 |
operator adds an edge from every node having a certain color to every node have |
| 2359 |
a certain other color. This is exactly what we need here: The first color is |
| 2360 |
``the color |target| restricted to the nodes of the first graph'' and the |
| 2361 |
second color is ``the color |source| restricted to the nodes of the second |
| 2362 |
graph''. |
| 2363 |
|
| 2364 |
However, we cannot really specify that only nodes from a certain subgraph are |
| 2365 |
meant -- the |operator| machinery only operates on all nodes of the current |
| 2366 |
graph. For this reason, what really happens is the following: When the |graph| |
| 2367 |
command encounters \meta{spec$_1$} \meta{edge specification} \meta{spec$_2$}, |
| 2368 |
it first computes and colors the nodes of the first and the second |
| 2369 |
specification independently. Then, the |target| nodes of the first graph are |
| 2370 |
recolored to |target'| and the |source| nodes of the second graph are recolored |
| 2371 |
to |source'|. Then, the two graphs are united into one graph and a |
| 2372 |
\emph{joining operator} is executed, which should add edges between |target'| |
| 2373 |
and |source'|. Once this is done, the colors |target'| and |source'| get |
| 2374 |
erased. Note that in the resulting graph only the |source| nodes from the first |
| 2375 |
graph are still |source| nodes and likewise for the |target| nodes of the |
| 2376 |
second graph. |
| 2377 |
|
| 2378 |
\medskip |
| 2379 |
\textbf{The joining operators.} The job of a joining operator is to add edges |
| 2380 |
between nodes colored |target'| and |source'|. The following rule is used to |
| 2381 |
determine which operator should be chosen for performing this job: |
| 2382 |
% |
| 2383 |
\begin{enumerate} |
| 2384 |
\item If the \meta{edge specification} explicitly sets the |operator| key |
| 2385 |
to something non-empty (and also not to |\relax|), then the \meta{code} |
| 2386 |
of this |operator| call is used. |
| 2387 |
\item Otherwise, the current value of the following key is used: |
| 2388 |
% |
| 2389 |
\begin{key}{/tikz/graphs/default edge operator=\meta{key} (initially matching and star)} |
| 2390 |
This key stores the name of a \meta{key} that is executed for every |
| 2391 |
\meta{edge specification} whose \meta{options} do not contain the |
| 2392 |
|operator| key. |
| 2393 |
% |
| 2394 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2395 |
\tikz \graph [default edge operator=matching] { |
| 2396 |
{a, b} ->[matching and star] |
| 2397 |
{c, d, e} --[complete bipartite] |
| 2398 |
{f, g, h} -- |
| 2399 |
{i, j, k} |
| 2400 |
}; |
| 2401 |
\end{codeexample} |
| 2402 |
\end{key} |
| 2403 |
\end{enumerate} |
| 2404 |
|
| 2405 |
A typical joining operator is |complete bipartite|. It takes the names of two |
| 2406 |
color classes as input and adds edges from all vertices of the first class to |
| 2407 |
all vertices of the second class. Now, the trick is that the default value for |
| 2408 |
the |complete bipartite| key is |{target'}{source'}|. Thus, if you just write |
| 2409 |
|->[complete bipartite]|, the same happens as if you had written |
| 2410 |
% |
| 2411 |
\begin{quote} |
| 2412 |
|->[complete bipartite={target'}{source'}]| |
| 2413 |
\end{quote} |
| 2414 |
% |
| 2415 |
This is exactly what we want to happen. The same default values are also set |
| 2416 |
for other joining operators like |matching| or |butterfly|. |
| 2417 |
|
| 2418 |
Even though an operator like |complete bipartite| is typically used together |
| 2419 |
with an edge specification, it can also be used as a normal operator together |
| 2420 |
with a group specification. In this case, however, the color classes must be |
| 2421 |
named explicitly: |
| 2422 |
% |
| 2423 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2424 |
\begin{tikzpicture} |
| 2425 |
\graph [color class=red, color class=green, math nodes] |
| 2426 |
{ [complete bipartite={red}{green}] |
| 2427 |
{ [red, Cartesian placement] r_1, r_2, r_3 }, |
| 2428 |
{ [green, Cartesian placement, nodes={xshift=1cm}] g_1, g_2, g_3 } |
| 2429 |
}; |
| 2430 |
\end{tikzpicture} |
| 2431 |
\end{codeexample} |
| 2432 |
|
| 2433 |
A list of predefined joining operators can be found in the reference |
| 2434 |
Section~\ref{section-library-graphs-reference}. |
| 2435 |
|
| 2436 |
The fact that joining operators can also be used as normal operators leads to a |
| 2437 |
subtle problem: A normal operator will typically use the current value of |
| 2438 |
|default edge kind| to decide which kind of edges should be put between the |
| 2439 |
identified vertices, while a joining operator should, naturally, use the kind |
| 2440 |
of edge specified by the \meta{edge specification}. This problem is solved as |
| 2441 |
follows: Like a normal operator, a joining operator should also use the current |
| 2442 |
value of |default edge kind| for the edges it produces. The trick is that this |
| 2443 |
will automatically be set to the current \meta{edge specification} when the |
| 2444 |
operator explicitly in the \meta{options} of the edge specification or |
| 2445 |
implicitly in the |default edge operator|. |
| 2446 |
|
| 2447 |
|
| 2448 |
\subsection{Graph Macros} |
| 2449 |
\label{section-library-graphs-macros} |
| 2450 |
|
| 2451 |
A \emph{graph macro} is a small graph that is inserted at some point into the |
| 2452 |
graph that is currently being constructed. There is special support for such |
| 2453 |
graph macros in \tikzname. You might wonder why this is necessary -- can't one |
| 2454 |
use \TeX's normal macro mechanism? The answer is ``no'': one cannot insert new |
| 2455 |
nodes into a graph using normal macros because the chains, groups, and nodes |
| 2456 |
are determined prior to macro expansion. Thus, any macro encountered where some |
| 2457 |
node text should go will only be expanded when this node is being named and |
| 2458 |
typeset. |
| 2459 |
|
| 2460 |
A graph macro is declared using the following key: |
| 2461 |
|
| 2462 |
\begin{key}{/tikz/graphs/declare=\marg{graph name}\marg{specification}} |
| 2463 |
This key declares that \meta{graph name} can subsequently be used as a |
| 2464 |
replacement for a \meta{node name}. Whenever the \meta{graph name} is used |
| 2465 |
in the following, a graph group will be inserted instead whose content is |
| 2466 |
exactly \meta{specification}. In case \meta{graph name} is used together |
| 2467 |
with some \meta{options}, they are executed prior to inserting the |
| 2468 |
\meta{specification}. |
| 2469 |
% |
| 2470 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2471 |
\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] { |
| 2472 |
a; |
| 2473 |
claw; |
| 2474 |
b; |
| 2475 |
}; |
| 2476 |
\end{codeexample} |
| 2477 |
% |
| 2478 |
In the next example, we use a key to configure a subgraph: |
| 2479 |
% |
| 2480 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2481 |
\tikz \graph [ n/.code=\def\n{#1}, branch down=4mm, |
| 2482 |
declare={star}{root -- { \foreach \i in {1,...,\n} {\i} }}] |
| 2483 |
{ star [n=5]; }; |
| 2484 |
\end{codeexample} |
| 2485 |
% |
| 2486 |
Actually, the |n| key is already defined internally for a similar purpose. |
| 2487 |
|
| 2488 |
As a last example, let us define a somewhat more complicated graph macro. |
| 2489 |
% |
| 2490 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2491 |
\newcount\mycount |
| 2492 |
\tikzgraphsset{ |
| 2493 |
levels/.store in=\tikzgraphlevel, |
| 2494 |
levels=1, |
| 2495 |
declare={bintree}{% |
| 2496 |
[/utils/exec={% |
| 2497 |
\ifnum\tikzgraphlevel=1\relax% |
| 2498 |
\def\childtrees{ / }% |
| 2499 |
\else% |
| 2500 |
\mycount=\tikzgraphlevel% |
| 2501 |
\advance\mycount by-1\relax% |
| 2502 |
\edef\childtrees{ |
| 2503 |
/ -> { |
| 2504 |
bintree[levels=\the\mycount], |
| 2505 |
bintree[levels=\the\mycount] |
| 2506 |
}} |
| 2507 |
\fi% |
| 2508 |
}, |
| 2509 |
parse/.expand once=\childtrees |
| 2510 |
] |
| 2511 |
% Everything is inside the \childtrees... |
| 2512 |
} |
| 2513 |
} |
| 2514 |
\tikz \graph [grow down=5mm, branch right=5mm] { bintree [levels=5] }; |
| 2515 |
\end{codeexample} |
| 2516 |
% |
| 2517 |
\end{key} |
| 2518 |
|
| 2519 |
Note that when you use a graph macro several time inside the same graph, you |
| 2520 |
will typically have to use the |name| option so that different copies of the |
| 2521 |
subgraph are created: |
| 2522 |
% |
| 2523 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2524 |
\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] { |
| 2525 |
claw [name=left], |
| 2526 |
claw [name=right] |
| 2527 |
}; |
| 2528 |
\end{codeexample} |
| 2529 |
|
| 2530 |
You will find a list of useful graph macros in the reference section, |
| 2531 |
Section~\ref{section-library-graphs-reference-macros}. |
| 2532 |
|
| 2533 |
|
| 2534 |
\subsection{Online Placement Strategies} |
| 2535 |
\label{section-library-graphs-placement} |
| 2536 |
|
| 2537 |
The main job of the |graphs| library is to make it easy to specify which nodes |
| 2538 |
are present in a graph and how they are connected. In contrast, it is |
| 2539 |
\emph{not} the primary job of the library to compute good positions for nodes |
| 2540 |
in a graph -- use for instance a |\matrix|, specify good positions ``by hand'' |
| 2541 |
or use the graph drawing facilities. Nevertheless, some basic support for |
| 2542 |
automatic node placement is provided for simple cases. The |graphs| library |
| 2543 |
will provide you with information about the position of nodes inside their |
| 2544 |
groups and chains. |
| 2545 |
|
| 2546 |
As a graph is being constructed, a \emph{placement strategy} is used to |
| 2547 |
determine a (reasonably good) position for the nodes as they are created. These |
| 2548 |
placement strategies get some information about what \tikzname\ has already |
| 2549 |
seen concerning the already constructed nodes, but it gets no information |
| 2550 |
concerning the upcoming nodes. Because of this lack of information concerning |
| 2551 |
the future, the strategies need to be what is called an \emph{online strategy} |
| 2552 |
in computer science. (The opposite are \emph{offline strategies}, which get |
| 2553 |
information about the whole graph and all the sizes of the nodes in it. The |
| 2554 |
graph drawing libraries employ such offline strategies.) |
| 2555 |
|
| 2556 |
Strategies are selected using keys like |no placement| or |
| 2557 |
|Cartesian placement|. It is permissible to use different strategies inside |
| 2558 |
different parts of a graph, even though the different strategies do not always |
| 2559 |
work together in perfect harmony. |
| 2560 |
|
| 2561 |
|
| 2562 |
\subsubsection{Manual Placement} |
| 2563 |
\label{section-graphs-xy} |
| 2564 |
|
| 2565 |
\begin{key}{/tikz/graphs/no placement} |
| 2566 |
This strategy simply ``switches off'' the whole placement mechanism, |
| 2567 |
causing all nodes to be placed at the origin by default. You need to use |
| 2568 |
this strategy if you position nodes ``by hand''. For this, you can use the |
| 2569 |
|at| key, the |shift| keys: |
| 2570 |
% |
| 2571 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2572 |
\tikz \graph [no placement] |
| 2573 |
{ |
| 2574 |
a[at={(0:0)}] -> b[at={(1,0)}] -> c[yshift=1cm]; |
| 2575 |
}; |
| 2576 |
\end{codeexample} |
| 2577 |
% |
| 2578 |
Since the syntax and the many braces and parentheses are a bit cumbersome, |
| 2579 |
the following two keys might also be useful: |
| 2580 |
% |
| 2581 |
\begin{key}{/tikz/graphs/x=\meta{x dimension}} |
| 2582 |
When you use this key, it will have the same effect as if you had |
| 2583 |
written |at={(|\meta{x dimension}|,|\meta{y dimension}|)}|, where |
| 2584 |
\meta{y dimension} is a value set using the |y| key: |
| 2585 |
% |
| 2586 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2587 |
\tikz \graph [no placement] |
| 2588 |
{ |
| 2589 |
a[x=0,y=0] -> b[x=1,y=0] -> c[x=0,y=1]; |
| 2590 |
}; |
| 2591 |
\end{codeexample} |
| 2592 |
% |
| 2593 |
Note that you can specify an |x| or a |y| key for a whole scope and |
| 2594 |
then vary only the other key: |
| 2595 |
% |
| 2596 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2597 |
\tikz \graph [no placement] |
| 2598 |
{ |
| 2599 |
a -> |
| 2600 |
{ [x=1] % group option |
| 2601 |
b [y=0] -> c[y=1] |
| 2602 |
}; |
| 2603 |
}; |
| 2604 |
\end{codeexample} |
| 2605 |
% |
| 2606 |
Note that these keys have the path |/tikz/graphs/|, so they will be |
| 2607 |
available inside |graph|s and will not clash with the usual |x| and |y| |
| 2608 |
keys of \tikzname, which are used to specify the basic lengths of |
| 2609 |
vectors. |
| 2610 |
\end{key} |
| 2611 |
% |
| 2612 |
\begin{key}{/tikz/graphs/y=\meta{y dimension}} |
| 2613 |
See above. |
| 2614 |
\end{key} |
| 2615 |
\end{key} |
| 2616 |
|
| 2617 |
|
| 2618 |
\subsubsection{Placement on a Grid} |
| 2619 |
|
| 2620 |
\begin{key}{/tikz/graphs/Cartesian placement} |
| 2621 |
This strategy is the default strategy. It works, roughly, as follows: For |
| 2622 |
each new node on a chain, advance a ``logical width'' counter and for each |
| 2623 |
new node in a group, advance a ``logical depth'' counter. When a chain |
| 2624 |
contains a whole group, then the ``logical width'' taken up by the group is |
| 2625 |
the maximum over the logical widths taken up by the chains inside the |
| 2626 |
group; and symmetrically the logical depth of a chain is the maximum of the |
| 2627 |
depths of the groups inside it. |
| 2628 |
|
| 2629 |
This slightly confusing explanation is perhaps best exemplified. In the |
| 2630 |
below example, the two numbers indicate the two logical width and depth of |
| 2631 |
each node as computed by the |graphs| library. Just ignore the arcane code |
| 2632 |
that is used to print these numbers. |
| 2633 |
% |
| 2634 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2635 |
\tikz |
| 2636 |
\graph [nodes={align=center, inner sep=1pt}, grow right=7mm, |
| 2637 |
typeset={\tikzgraphnodetext\\[-4pt] |
| 2638 |
\tiny\mywidth\\[-6pt]\tiny\mydepth}, |
| 2639 |
placement/compute position/.append code= |
| 2640 |
\pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth} |
| 2641 |
\pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}] |
| 2642 |
{ |
| 2643 |
a, |
| 2644 |
b, |
| 2645 |
c -> d -> { |
| 2646 |
e -> f -> g, |
| 2647 |
h -> i |
| 2648 |
} -> j, |
| 2649 |
k -> l |
| 2650 |
}; |
| 2651 |
\end{codeexample} |
| 2652 |
% |
| 2653 |
You will find a detailed description of how these logical units are |
| 2654 |
computed, exactly, in Section~\ref{section-library-graphs-new-online}. |
| 2655 |
|
| 2656 |
Now, even though we talk about ``widths'' and ``depths'' and even though by |
| 2657 |
default a graph ``grows'' to the right and down, this is by no means fixed. |
| 2658 |
Instead, you can use the following keys to change how widths and heights |
| 2659 |
are interpreted: |
| 2660 |
% |
| 2661 |
\begin{key}{/tikz/graphs/chain shift=\meta{coordinate} (initially {(1,0)})} |
| 2662 |
Under the regime of the |Cartesian placement| strategy, each node is |
| 2663 |
shifted by the current logical width times this \meta{coordinate}. |
| 2664 |
% |
| 2665 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2666 |
\tikz \graph [chain shift=(45:1)] { |
| 2667 |
a -> b -> c; |
| 2668 |
d -> e; |
| 2669 |
f -> g -> h; |
| 2670 |
}; |
| 2671 |
\end{codeexample} |
| 2672 |
\end{key} |
| 2673 |
% |
| 2674 |
\begin{key}{/tikz/graphs/group shift=\meta{coordinate} (initially {(0,-1)})} |
| 2675 |
Like for |chain shift|, each node is shifted by the current logical |
| 2676 |
depth times this \meta{coordinate}. |
| 2677 |
% |
| 2678 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2679 |
\tikz \graph [chain shift=(45:7mm), group shift=(-45:7mm)] { |
| 2680 |
a -> b -> c; |
| 2681 |
d -> e; |
| 2682 |
f -> g -> h; |
| 2683 |
}; |
| 2684 |
\end{codeexample} |
| 2685 |
\end{key} |
| 2686 |
\end{key} |
| 2687 |
|
| 2688 |
\begin{key}{/tikz/graphs/grow up=\meta{distance} (default 1)} |
| 2689 |
Sets the |chain shift| to |(0,|\meta{distance}|)|, so that chains ``grow |
| 2690 |
upward''. The distance by which the center of each new element is removed |
| 2691 |
from the center of the previous one is \meta{distance}. |
| 2692 |
% |
| 2693 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2694 |
\tikz \graph [grow up=7mm] { a -> b -> c}; |
| 2695 |
\end{codeexample} |
| 2696 |
% |
| 2697 |
\end{key} |
| 2698 |
|
| 2699 |
\begin{key}{/tikz/graphs/grow down=\meta{distance} (default 1)} |
| 2700 |
Like |grow up|. |
| 2701 |
% |
| 2702 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2703 |
\tikz \graph [grow down=7mm] { a -> b -> c}; |
| 2704 |
\end{codeexample} |
| 2705 |
% |
| 2706 |
\end{key} |
| 2707 |
|
| 2708 |
\begin{key}{/tikz/graphs/grow left=\meta{distance} (default 1)} |
| 2709 |
Like |grow up|. |
| 2710 |
% |
| 2711 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2712 |
\tikz \graph [grow left=7mm] { a -> b -> c}; |
| 2713 |
\end{codeexample} |
| 2714 |
% |
| 2715 |
\end{key} |
| 2716 |
|
| 2717 |
\begin{key}{/tikz/graphs/grow right=\meta{distance} (default 1)} |
| 2718 |
Like |grow up|. |
| 2719 |
% |
| 2720 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2721 |
\tikz \graph [grow right=7mm] { a -> b -> c}; |
| 2722 |
\end{codeexample} |
| 2723 |
% |
| 2724 |
\end{key} |
| 2725 |
|
| 2726 |
\begin{key}{/tikz/graphs/branch up=\meta{distance} (default 1)} |
| 2727 |
Sets the |group shift| so that groups ``branch upward''. The distance by |
| 2728 |
which the center of each new element is removed from the center of the |
| 2729 |
previous one is \meta{distance}. |
| 2730 |
% |
| 2731 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2732 |
\tikz \graph [branch up=7mm] { a -> b -> {c, d, e} }; |
| 2733 |
\end{codeexample} |
| 2734 |
% |
| 2735 |
Note that when you draw a tree, the |branch ...| keys specify how siblings |
| 2736 |
(or adjacent branches) are arranged, while the |grow ...| keys specify in |
| 2737 |
which direction the branches ``grow''. |
| 2738 |
\end{key} |
| 2739 |
|
| 2740 |
\begin{key}{/tikz/graphs/branch down=\meta{distance} (default 1)} |
| 2741 |
% |
| 2742 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2743 |
\tikz \graph [branch down=7mm] { a -> b -> {c, d, e}}; |
| 2744 |
\end{codeexample} |
| 2745 |
% |
| 2746 |
\end{key} |
| 2747 |
|
| 2748 |
\begin{key}{/tikz/graphs/branch left=\meta{distance} (default 1)} |
| 2749 |
% |
| 2750 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2751 |
\tikz \graph [branch left=7mm, grow down=7mm] { a -> b -> {c, d, e}}; |
| 2752 |
\end{codeexample} |
| 2753 |
% |
| 2754 |
\end{key} |
| 2755 |
|
| 2756 |
\begin{key}{/tikz/graphs/branch right=\meta{distance} (default 1)} |
| 2757 |
% |
| 2758 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2759 |
\tikz \graph [branch right=7mm, grow down=7mm] { a -> b -> {c, d, e}}; |
| 2760 |
\end{codeexample} |
| 2761 |
% |
| 2762 |
\end{key} |
| 2763 |
|
| 2764 |
The following keys place nodes in a $N\times M$ grid. |
| 2765 |
% |
| 2766 |
\begin{key}{/tikz/graphs/grid placement} |
| 2767 |
This key works similar to |Cartesian placement|. As for that placement |
| 2768 |
strategy, a node has logical width and depth 1. However, the computed total |
| 2769 |
width and depth are mapped to a $N\times M$ grid. The values of $N$ and $M$ |
| 2770 |
depend on the size of the graph and the value of |wrap after|. The number |
| 2771 |
of columns $M$ is either set to |wrap after| explicitly or computed |
| 2772 |
automatically as $\sqrt{\texttt{\string|V\string|}}$. $N$ is the number of |
| 2773 |
rows needed to lay out the graph in a grid with $M$ columns. |
| 2774 |
% |
| 2775 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2776 |
% An example with 6 nodes, 3 columns and therefore 2 rows |
| 2777 |
\tikz \graph [grid placement] { subgraph I_n[n=6, wrap after=3] }; |
| 2778 |
\end{codeexample} |
| 2779 |
% |
| 2780 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2781 |
% An example with 9 nodes with columns and rows computed automatically |
| 2782 |
\tikz \graph [grid placement] { subgraph Grid_n [n=9] }; |
| 2783 |
\end{codeexample} |
| 2784 |
% |
| 2785 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2786 |
% Directions can be changed |
| 2787 |
\tikz \graph [grid placement, branch up, grow left] { subgraph Grid_n [n=9] }; |
| 2788 |
\end{codeexample} |
| 2789 |
% |
| 2790 |
In case a user-defined graph instead of a pre-defined |subgraph| is to be |
| 2791 |
laid out using |grid placement|, |n| has to be specified explicitly: |
| 2792 |
% |
| 2793 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2794 |
\tikz \graph [grid placement] { |
| 2795 |
[n=6, wrap after=3] |
| 2796 |
a -- b -- c -- d -- e -- f |
| 2797 |
}; |
| 2798 |
\end{codeexample} |
| 2799 |
% |
| 2800 |
\end{key} |
| 2801 |
|
| 2802 |
|
| 2803 |
\subsubsection{Placement Taking Node Sizes Into Account} |
| 2804 |
|
| 2805 |
Options like |grow up| or |branch right| do not take the sizes of the |
| 2806 |
to-be-positioned nodes into account -- all nodes are placed quite ``dumbly'' at |
| 2807 |
grid positions. It turns out that the |Cartesian placement| can also be used to |
| 2808 |
place nodes in such a way that their height and/or width is taken into account. |
| 2809 |
Note, however, that while the following options may yield an adequate placement |
| 2810 |
in many situations, when you need advanced alignments you should use a |matrix| |
| 2811 |
or advanced offline strategies to place the nodes. |
| 2812 |
|
| 2813 |
\begin{key}{/tikz/graphs/grow right sep=\meta{distance} (default 1em)} |
| 2814 |
This key has several effects, but let us start with the bottom line: Nodes |
| 2815 |
along a chain are placed in such a way that the left end of a new node is |
| 2816 |
\meta{distance} from the right end of the previous node: |
| 2817 |
% |
| 2818 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2819 |
\tikz \graph [grow right sep, left anchor=east, right anchor=west] { |
| 2820 |
start -- { |
| 2821 |
long text -- {short, very long text} -- more text, |
| 2822 |
long -- longer -- longest |
| 2823 |
} -- end |
| 2824 |
}; |
| 2825 |
\end{codeexample} |
| 2826 |
% |
| 2827 |
What happens internally is the following: First, the |anchor| of the nodes |
| 2828 |
is set to |west| (or |north west| or |south west|, see below). Second, the |
| 2829 |
logical width of a node is no longer |1|, but set to the actual width of |
| 2830 |
the node (which we define as the horizontal difference between the |west| |
| 2831 |
anchor and the |east| anchor) in points. Third, the |chain shift| is set to |
| 2832 |
|(1pt,0pt)|. |
| 2833 |
\end{key} |
| 2834 |
|
| 2835 |
\begin{key}{/tikz/graphs/grow left sep=\meta{distance} (default 1em)} |
| 2836 |
% |
| 2837 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2838 |
\tikz \graph [grow left sep] { long -- longer -- longest }; |
| 2839 |
\end{codeexample} |
| 2840 |
% |
| 2841 |
\end{key} |
| 2842 |
|
| 2843 |
\begin{key}{/tikz/graphs/grow up sep=\meta{distance} (default 1em)} |
| 2844 |
% |
| 2845 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2846 |
\tikz \graph [grow up sep] { |
| 2847 |
a / $a=x$ -- |
| 2848 |
b / {$b=\displaystyle \int_0^1 x dx$} -- |
| 2849 |
c [draw, circle, inner sep=7mm] |
| 2850 |
}; |
| 2851 |
\end{codeexample} |
| 2852 |
% |
| 2853 |
\end{key} |
| 2854 |
|
| 2855 |
\begin{key}{/tikz/graphs/grow down sep=\meta{distance} (default 1em)} |
| 2856 |
As above. |
| 2857 |
\end{key} |
| 2858 |
|
| 2859 |
\begin{key}{/tikz/graphs/branch right sep=\meta{distance} (default 1em)} |
| 2860 |
This key works like |grow right sep|, only it affects groups rather than |
| 2861 |
chains. |
| 2862 |
% |
| 2863 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2864 |
\tikz \graph [grow down, branch right sep] { |
| 2865 |
start -- { |
| 2866 |
an even longer text -- {short, very long text} -- more text, |
| 2867 |
long -- longer -- longest, |
| 2868 |
some text -- a -- b |
| 2869 |
} -- end |
| 2870 |
}; |
| 2871 |
\end{codeexample} |
| 2872 |
% |
| 2873 |
When both this key and, say, |grow down sep| are set, instead of the |west| |
| 2874 |
anchor, the |north west| anchor will be selected automatically. |
| 2875 |
\end{key} |
| 2876 |
|
| 2877 |
\begin{key}{/tikz/graphs/branch left sep=\meta{distance} (default 1em)} |
| 2878 |
% |
| 2879 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2880 |
\tikz \graph [grow down sep, branch left sep] { |
| 2881 |
start -- { |
| 2882 |
an even longer text -- {short, very long text} -- more text, |
| 2883 |
long -- longer, |
| 2884 |
some text -- a -- b |
| 2885 |
} -- end |
| 2886 |
}; |
| 2887 |
\end{codeexample} |
| 2888 |
% |
| 2889 |
\end{key} |
| 2890 |
|
| 2891 |
\begin{key}{/tikz/graphs/branch up sep=\meta{distance} (default 1em)} |
| 2892 |
% |
| 2893 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2894 |
\tikz \graph [branch up sep] { a, b, c[draw, circle, inner sep=7mm] }; |
| 2895 |
\end{codeexample} |
| 2896 |
% |
| 2897 |
\end{key} |
| 2898 |
|
| 2899 |
\begin{key}{/tikz/graphs/branch down sep=\meta{distance} (default 1em)} |
| 2900 |
\end{key} |
| 2901 |
|
| 2902 |
|
| 2903 |
\subsubsection{Placement On a Circle} |
| 2904 |
|
| 2905 |
The following keys place nodes on circles. Note that, typically, you do not use |
| 2906 |
|circular placement| directly, but rather use one of the two keys |clockwise| |
| 2907 |
or |counterclockwise|. |
| 2908 |
|
| 2909 |
\begin{key}{/tikz/graphs/circular placement} |
| 2910 |
This key works quite similar to |Cartesian placement|. As for that |
| 2911 |
placement strategy, a node has logical width and depth |1|. However, the |
| 2912 |
computed total width and depth are mapped to polar coordinates rather than |
| 2913 |
Cartesian coordinates. |
| 2914 |
|
| 2915 |
\begin{key}{/tikz/graphs/chain polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(0:1)})} |
| 2916 |
Under the regime of the |circular placement| strategy, each node on a |
| 2917 |
chain is shifted by |
| 2918 |
|(|\meta{logical width}\meta{angle}|:|\meta{logical width}\meta{angle}|)|. |
| 2919 |
% |
| 2920 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2921 |
\tikz \graph [circular placement] { |
| 2922 |
a -> b -> c; |
| 2923 |
d -> e; |
| 2924 |
f -> g -> h; |
| 2925 |
}; |
| 2926 |
\end{codeexample} |
| 2927 |
% |
| 2928 |
\end{key} |
| 2929 |
% |
| 2930 |
\begin{key}{/tikz/graphs/group polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(45:0)})} |
| 2931 |
Like for |group shift|, each node on a chain is shifted by |
| 2932 |
|(|\meta{logical depth}\meta{angle}|:|\meta{logical depth}\meta{angle}|)|. |
| 2933 |
% |
| 2934 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2935 |
\tikz \graph [circular placement, group polar shift=(30:0)] { |
| 2936 |
a -> b -> c; |
| 2937 |
d -> e; |
| 2938 |
f -> g -> h; |
| 2939 |
}; |
| 2940 |
\end{codeexample} |
| 2941 |
% |
| 2942 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2943 |
\tikz \graph [circular placement, |
| 2944 |
chain polar shift=(30:0), |
| 2945 |
group polar shift=(0:1cm)] { |
| 2946 |
a -- b -- c; |
| 2947 |
d -- e; |
| 2948 |
f -- g -- h; |
| 2949 |
}; |
| 2950 |
\end{codeexample} |
| 2951 |
\end{key} |
| 2952 |
% |
| 2953 |
\begin{key}{/tikz/graphs/radius=\meta{dimension} (initially 1cm)} |
| 2954 |
This is an initial value that is added to the total computed radius |
| 2955 |
when the polar shift of a node has been calculated. Essentially, this |
| 2956 |
key allows you to set the \meta{radius} of the innermost circle. |
| 2957 |
% |
| 2958 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2959 |
\tikz \graph [circular placement, radius=5mm] { a, b, c, d }; |
| 2960 |
\end{codeexample} |
| 2961 |
% |
| 2962 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2963 |
\tikz \graph [circular placement, radius=1cm] { a, b, c, d }; |
| 2964 |
\end{codeexample} |
| 2965 |
\end{key} |
| 2966 |
% |
| 2967 |
\begin{key}{/tikz/graphs/phase=\meta{angle} (initially 90)} |
| 2968 |
This is an initial value that is added to the total computed angle when |
| 2969 |
the polar shift of a node has been calculated. |
| 2970 |
% |
| 2971 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2972 |
\tikz \graph [circular placement] { a, b, c, d }; |
| 2973 |
\end{codeexample} |
| 2974 |
% |
| 2975 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2976 |
\tikz \graph [circular placement, phase=0] { a, b, c, d }; |
| 2977 |
\end{codeexample} |
| 2978 |
\end{key} |
| 2979 |
\end{key} |
| 2980 |
|
| 2981 |
\label{key-graphs-clockwise}% |
| 2982 |
\begin{key}{/tikz/graphs/clockwise=\meta{number} (default \string\tikzgraphVnum)} |
| 2983 |
This key sets the |group shift| so that if there are exactly \meta{number} |
| 2984 |
many nodes in a group, they will form a complete circle. If you do not |
| 2985 |
provide a \meta{number}, the current value of |\tikzgraphVnum| is used, |
| 2986 |
which is exactly what you want when you use predefined graph macros like |
| 2987 |
|subgraph K_n|. |
| 2988 |
% |
| 2989 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 2990 |
\tikz \graph [clockwise=4] { a, b, c, d }; |
| 2991 |
\end{codeexample} |
| 2992 |
% |
| 2993 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 2994 |
\tikz \graph [clockwise] { subgraph K_n [n=5] }; |
| 2995 |
\end{codeexample} |
| 2996 |
% |
| 2997 |
\end{key} |
| 2998 |
|
| 2999 |
\label{key-graphs-counterclockwise}% |
| 3000 |
\begin{key}{/tikz/graphs/counterclockwise=\meta{number} (default \string\tikzgraphVnum)} |
| 3001 |
Works like |clockwise|, only the direction is inverted. |
| 3002 |
\end{key} |
| 3003 |
|
| 3004 |
|
| 3005 |
\subsubsection{Levels and Level Styles} |
| 3006 |
|
| 3007 |
As a graph is being parsed, the |graph| command keeps track of a parameter |
| 3008 |
called the \emph{level} of a node. Provided that the graph is actually |
| 3009 |
constructed in a tree-like manner, the level is exactly equal to the level of |
| 3010 |
the node inside this tree. |
| 3011 |
|
| 3012 |
\begin{key}{/tikz/graphs/placement/level} |
| 3013 |
This key stores a number that is increased for each element on a chain, but |
| 3014 |
gets reset at the end of a group: |
| 3015 |
% |
| 3016 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3017 |
\tikz \graph [ branch down=5mm, typeset= |
| 3018 |
\tikzgraphnodetext:\pgfkeysvalueof{/tikz/graphs/placement/level}] |
| 3019 |
{ |
| 3020 |
a -> { |
| 3021 |
b, |
| 3022 |
c -> { |
| 3023 |
d, |
| 3024 |
e -> {f,g}, |
| 3025 |
h |
| 3026 |
}, |
| 3027 |
j |
| 3028 |
} |
| 3029 |
}; |
| 3030 |
\end{codeexample} |
| 3031 |
% |
| 3032 |
Unlike the parameters |depth| and |width| described in the next section, |
| 3033 |
the key |level| is always available. |
| 3034 |
\end{key} |
| 3035 |
|
| 3036 |
In addition to keeping track of the value of the |level| key, the |graph| |
| 3037 |
command also executes the following keys whenever it creates a node: |
| 3038 |
|
| 3039 |
\begin{stylekey}{/tikz/graph/level=\meta{level}} |
| 3040 |
This key gets executed for each newly created node with \meta{level} set to |
| 3041 |
the current level of the node. You can use this key to, say, reconfigure |
| 3042 |
the node distance or the node color. |
| 3043 |
\end{stylekey} |
| 3044 |
|
| 3045 |
\begin{stylekey}{/tikz/graph/level \meta{level}} |
| 3046 |
This key also gets executed for each newly created node with \meta{level} |
| 3047 |
set to the current level of the node. |
| 3048 |
% |
| 3049 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3050 |
\tikz \graph [ |
| 3051 |
branch down=5mm, |
| 3052 |
level 1/.style={nodes=red}, |
| 3053 |
level 2/.style={nodes=green!50!black}, |
| 3054 |
level 3/.style={nodes=blue}] |
| 3055 |
{ |
| 3056 |
a -> { |
| 3057 |
b, |
| 3058 |
c -> { |
| 3059 |
d, |
| 3060 |
e -> {f,g}, |
| 3061 |
h |
| 3062 |
}, |
| 3063 |
j |
| 3064 |
} |
| 3065 |
}; |
| 3066 |
\end{codeexample} |
| 3067 |
% |
| 3068 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3069 |
\tikz \graph [ |
| 3070 |
branch down=5mm, |
| 3071 |
level 1/.style={grow right=2cm}, |
| 3072 |
level 2/.style={grow right=1cm}, |
| 3073 |
level 3/.style={grow right=5mm}] |
| 3074 |
{ |
| 3075 |
a -> { |
| 3076 |
b, |
| 3077 |
c -> { |
| 3078 |
d, |
| 3079 |
e -> {f,g}, |
| 3080 |
h |
| 3081 |
}, |
| 3082 |
j |
| 3083 |
} |
| 3084 |
}; |
| 3085 |
\end{codeexample} |
| 3086 |
% |
| 3087 |
\end{stylekey} |
| 3088 |
|
| 3089 |
|
| 3090 |
\subsubsection{Defining New Online Placement Strategies} |
| 3091 |
\label{section-library-graphs-new-online} |
| 3092 |
|
| 3093 |
In the following the details of how to define a new placement strategy are |
| 3094 |
explained. Most readers may wish to skip this section. |
| 3095 |
|
| 3096 |
As a graph specification is being parsed, the |graphs| library will keep track |
| 3097 |
of different numbers that identify the positions of the nodes. Let us start |
| 3098 |
with what happens on a chain. First, the following counter is increased for |
| 3099 |
each element of the chain: |
| 3100 |
% |
| 3101 |
\begin{key}{/tikz/graphs/placement/element count} |
| 3102 |
This key stores a number that tells us the position of the node on the |
| 3103 |
current chain. However, you only have access to this value inside the code |
| 3104 |
passed to the macro |compute position|, explained later on. |
| 3105 |
% |
| 3106 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3107 |
\tikz \graph [ |
| 3108 |
grow right sep, typeset=\tikzgraphnodetext:\mynum, |
| 3109 |
placement/compute position/.append code= |
| 3110 |
\pgfkeysgetvalue{/tikz/graphs/placement/element count}{\mynum}] |
| 3111 |
{ |
| 3112 |
a -> b -> c, |
| 3113 |
d -> {e, f->h} -> j |
| 3114 |
}; |
| 3115 |
\end{codeexample} |
| 3116 |
% |
| 3117 |
As can be seen, each group resets the element counter. |
| 3118 |
\end{key} |
| 3119 |
|
| 3120 |
The second value that is computed is more complicated to explain, but it also |
| 3121 |
gives more interesting information: |
| 3122 |
% |
| 3123 |
\begin{key}{/tikz/graphs/placement/width} |
| 3124 |
This key stores the ``logical width'' of the nodes parsed up to now in the |
| 3125 |
current group or chain (more precisely, parsed since the last call of |
| 3126 |
|place| in an enclosing group). This is not necessarily the ``total |
| 3127 |
physical width'' of the nodes, but rather a number representing how ``big'' |
| 3128 |
the elements prior to the current element were. This \emph{may} be their |
| 3129 |
width, but it may also be their height or even their number (which, |
| 3130 |
incidentally, is the default). You can use the |width| to perform shifts or |
| 3131 |
rotations of to-be-created nodes (to be explained later). |
| 3132 |
|
| 3133 |
The logical width is defined recursively as follows. First, the width of a |
| 3134 |
single node is computed by calling the following key: |
| 3135 |
% |
| 3136 |
\begin{key}{/tikz/graphs/placement/logical node width=\meta{full node name}} |
| 3137 |
This key is called to compute a physical or logical width of the node |
| 3138 |
\meta{full node name}. You can change the code of this key. The code |
| 3139 |
should return the computed value in the macro |\pgfmathresult|. By |
| 3140 |
default, this key returns |1|. |
| 3141 |
\end{key} |
| 3142 |
% |
| 3143 |
The width of a chain is the sum of the widths of its elements. The width of |
| 3144 |
a group is the maximum of the widths of its elements. |
| 3145 |
|
| 3146 |
To get a feeling what the above rules imply in practice, let us first have |
| 3147 |
a look at an example where each node has logical width and height |1| |
| 3148 |
(which is the default). The arcane options at the beginning of the code |
| 3149 |
just setup things so that the computed width and depth of each node is |
| 3150 |
displayed at the bottom of each node. |
| 3151 |
% |
| 3152 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3153 |
\tikz |
| 3154 |
\graph [nodes={align=center, inner sep=1pt}, grow right=7mm, |
| 3155 |
typeset={\tikzgraphnodetext\\[-4pt] |
| 3156 |
\tiny\mywidth\\[-6pt]\tiny\mydepth}, |
| 3157 |
placement/compute position/.append code= |
| 3158 |
\pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth} |
| 3159 |
\pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}] |
| 3160 |
{ |
| 3161 |
a, |
| 3162 |
b, |
| 3163 |
c -> d -> { |
| 3164 |
e -> f -> g, |
| 3165 |
h -> i |
| 3166 |
} -> j, |
| 3167 |
k -> l |
| 3168 |
}; |
| 3169 |
\end{codeexample} |
| 3170 |
% |
| 3171 |
In the next example the ``logical'' width and depth actually match the |
| 3172 |
``physical'' width and height. This is caused by the |grow right sep| |
| 3173 |
option, which internally sets the |logical node width| key so that it |
| 3174 |
returns the width of its parameter in points. |
| 3175 |
% |
| 3176 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3177 |
\tikz |
| 3178 |
\graph [grow right sep, branch down sep, nodes={align=left, inner sep=1pt}, |
| 3179 |
typeset={\tikzgraphnodetext\\[-4pt] \tiny Width: \mywidth\\[-6pt] \tiny Depth: \mydepth}, |
| 3180 |
placement/compute position/.append code= |
| 3181 |
\pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth} |
| 3182 |
\pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}] |
| 3183 |
{ |
| 3184 |
a, |
| 3185 |
b, |
| 3186 |
c -> d -> { |
| 3187 |
e -> f -> g, |
| 3188 |
h -> i |
| 3189 |
} -> j, |
| 3190 |
k -> l |
| 3191 |
}; |
| 3192 |
\end{codeexample} |
| 3193 |
% |
| 3194 |
\end{key} |
| 3195 |
|
| 3196 |
Symmetrically to chains, as a group is being constructed, counters are |
| 3197 |
available for the number of chains encountered so far in the current group and |
| 3198 |
for the logical depth of the current group: |
| 3199 |
% |
| 3200 |
\begin{key}{/tikz/graphs/placement/chain count} |
| 3201 |
This key stores a number that tells us the sequence number of the |
| 3202 |
chain in the current group. |
| 3203 |
% |
| 3204 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3205 |
\tikz \graph [ |
| 3206 |
grow right sep, branch down=5mm, typeset=\tikzgraphnodetext:\mynum, |
| 3207 |
placement/compute position/.append code= |
| 3208 |
\pgfkeysgetvalue{/tikz/graphs/placement/chain count}{\mynum}] |
| 3209 |
{ |
| 3210 |
a -> b -> {c,d,e}, |
| 3211 |
f, |
| 3212 |
g -> h |
| 3213 |
}; |
| 3214 |
\end{codeexample} |
| 3215 |
% |
| 3216 |
\end{key} |
| 3217 |
|
| 3218 |
\begin{key}{/tikz/graphs/placement/depth} |
| 3219 |
Similarly to the |width| key, this key stores the ``logical depth'' of the |
| 3220 |
nodes parsed up to now in the current group or chain and, also similarly, |
| 3221 |
this key may or may not be related to the actual depth/height of the |
| 3222 |
current node. As for the |width|, the exact definition is as follows: For a |
| 3223 |
single node, the depth is computed by the following key: |
| 3224 |
% |
| 3225 |
\begin{key}{/tikz/graphs/placement/logical node depth=\meta{full node name}} |
| 3226 |
The code behind this key should return the ``logical height'' of the |
| 3227 |
node \meta{full node name} in the macro |\pgfmathresult|. |
| 3228 |
\end{key} |
| 3229 |
% |
| 3230 |
Second, the depth of a group is the sum of the depths of its elements. |
| 3231 |
Third, the depth of a chain is the maximum of the depth of its elements. |
| 3232 |
\end{key} |
| 3233 |
|
| 3234 |
The |width|, |depth|, |element count|, and |chain count| keys get updated |
| 3235 |
automatically, but do not have an effect by themselves. This is to the |
| 3236 |
following two keys: |
| 3237 |
|
| 3238 |
\begin{key}{/tikz/graphs/placement/compute position=\meta{code}} |
| 3239 |
The \meta{code} is called by the |graph| command just prior to creating a |
| 3240 |
new node (the exact moment when this key is called is detailed in the |
| 3241 |
description of the |place| key). When the \meta{code} is called, all of the |
| 3242 |
keys described above will hold numbers computed in the way described above. |
| 3243 |
|
| 3244 |
The job of the \meta{code} is to setup node options appropriately so that |
| 3245 |
the to-be-created node will be placed correctly. Thus, the \meta{code} |
| 3246 |
should typically set the key |nodes={shift=|\meta{coordinate}|}| where |
| 3247 |
\meta{coordinate} is the computed position for the node. The \meta{code} |
| 3248 |
could also set other options like, say, the color of a node depending on |
| 3249 |
its depth. |
| 3250 |
|
| 3251 |
The following example appends some code to the standard code of |
| 3252 |
|compute position| so that ``deeper'' nodes of a tree are lighter. |
| 3253 |
(Naturally, the same effect could be achieved much more easily using the |
| 3254 |
|level| key.) |
| 3255 |
% |
| 3256 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3257 |
\newcount\mycount |
| 3258 |
\def\lightendeepernodes{ |
| 3259 |
\pgfmathsetcount{\mycount}{ |
| 3260 |
100-20*\pgfkeysvalueof{/tikz/graphs/placement/width} |
| 3261 |
} |
| 3262 |
\edef\mydepth{\the\mycount} |
| 3263 |
\tikzset{nodes={fill=red!\mydepth,circle,text=white}} |
| 3264 |
} |
| 3265 |
\tikz |
| 3266 |
\graph [placement/compute position/.append code=\lightendeepernodes] |
| 3267 |
{ |
| 3268 |
a -> { |
| 3269 |
b -> c -> d, |
| 3270 |
e -> { |
| 3271 |
f, |
| 3272 |
g |
| 3273 |
}, |
| 3274 |
h |
| 3275 |
} |
| 3276 |
}; |
| 3277 |
\end{codeexample} |
| 3278 |
% |
| 3279 |
\end{key} |
| 3280 |
|
| 3281 |
\begin{key}{/tikz/graphs/placement/place} |
| 3282 |
Executing this key has two effects: First, the key |compute position| is |
| 3283 |
called to compute a good position for future nodes (usually, these ``future |
| 3284 |
nodes'' are just a single node that is created immediately). Second, all of |
| 3285 |
the above counters like |depth| or |width| are reset (but not |level|). |
| 3286 |
|
| 3287 |
There are two places where this key is sensibly called: First, just prior |
| 3288 |
to creating a node, which happens automatically. Second, when you change |
| 3289 |
the online strategy. In this case, the computed width and depth values from |
| 3290 |
one strategy typically make no sense in the other strategy, which is why |
| 3291 |
the new strategy should proceed ``from a fresh start''. In this case, the |
| 3292 |
implicit call of |compute position| ensures that the new strategy gets the |
| 3293 |
last place the old strategy would have used as its starting point, while |
| 3294 |
the computation of its positions is now relative to this new starting |
| 3295 |
point. |
| 3296 |
|
| 3297 |
For these reasons, when an online strategy like |Cartesian placement| is |
| 3298 |
called, this key gets called implicitly. You will rarely need to call this |
| 3299 |
key directly, except when you define a new online strategy. |
| 3300 |
\end{key} |
| 3301 |
|
| 3302 |
|
| 3303 |
\subsection{Reference: Predefined Elements} |
| 3304 |
\label{section-library-graphs-reference} |
| 3305 |
|
| 3306 |
\subsubsection{Graph Macros} |
| 3307 |
\label{section-library-graphs-reference-macros} |
| 3308 |
|
| 3309 |
\begin{tikzlibrary}{graphs.standard} |
| 3310 |
This library defines a number of graph macros that are often used in the |
| 3311 |
literature. When new graphs are added to this collection, they will follow |
| 3312 |
the definitions in the Mathematica program, see |
| 3313 |
\url{mathworld.wolfram.com/topics/SimpleGraphs.html}. |
| 3314 |
\end{tikzlibrary} |
| 3315 |
|
| 3316 |
\begin{graph}{subgraph I\_n} |
| 3317 |
This graph consists just of $n$ unconnected vertices. The following key is |
| 3318 |
used to specify the set of these vertices: |
| 3319 |
% |
| 3320 |
\begin{key}{/tikz/graphs/V=\marg{list of vertices}} |
| 3321 |
Sets a list of vertex names for use with graphs like |subgraph I_n| and |
| 3322 |
also other graphs. This list is available in the macro |\tikzgraphV|. |
| 3323 |
The number of elements of this list is available in |\tikzgraphVnum|. |
| 3324 |
\end{key} |
| 3325 |
% |
| 3326 |
\begin{key}{/tikz/graphs/n=\meta{number}} |
| 3327 |
This is an abbreviation for |
| 3328 |
|V={1,...,|\meta{number}|}, name shore V/.style={name=V}|. |
| 3329 |
\end{key} |
| 3330 |
% |
| 3331 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3332 |
\tikz \graph [branch right, nodes={draw, circle}] |
| 3333 |
{ subgraph I_n [V={a,b,c}] }; |
| 3334 |
\end{codeexample} |
| 3335 |
% |
| 3336 |
This graph is not particularly exciting by itself. However, it is often |
| 3337 |
used to introduce nodes into a graph that are then connected as in the |
| 3338 |
following example: |
| 3339 |
% |
| 3340 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3341 |
\tikz \graph [clockwise, clique] { subgraph I_n [n=4] }; |
| 3342 |
\end{codeexample} |
| 3343 |
% |
| 3344 |
\end{graph} |
| 3345 |
|
| 3346 |
\begin{graph}{subgraph I\_nm} |
| 3347 |
This graph consists of two sets of once $n$ unconnected vertices and then |
| 3348 |
$m$ unconnected vertices. The first set consists of the vertices set by the |
| 3349 |
key |V|, the other set consists of the vertices set by the key |W|. |
| 3350 |
% |
| 3351 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3352 |
\tikz \graph { subgraph I_nm [V={1,2,3}, W={a,b,c}] }; |
| 3353 |
\end{codeexample} |
| 3354 |
% |
| 3355 |
In order to set the graph path name of the two sets, the following keys get |
| 3356 |
executed: |
| 3357 |
% |
| 3358 |
\begin{stylekey}{/tikz/graphs/name shore V (initially \normalfont empty)} |
| 3359 |
Set this style to, say, |name=my V set| in order to set a name for the |
| 3360 |
|V| set. |
| 3361 |
\end{stylekey} |
| 3362 |
% |
| 3363 |
\begin{stylekey}{/tikz/graphs/name shore W (initially \normalfont empty)} |
| 3364 |
Same as for |name shore V|. |
| 3365 |
\end{stylekey} |
| 3366 |
% |
| 3367 |
\begin{key}{/tikz/graphs/W=\marg{list of vertices}} |
| 3368 |
Sets the list of vertices for the |W| set. The elements and their |
| 3369 |
number are available in the macros |\tikzgraphW| and |\tikzgraphWnum|, |
| 3370 |
respectively. |
| 3371 |
\end{key} |
| 3372 |
% |
| 3373 |
\begin{key}{/tikz/graphs/m=\meta{number}} |
| 3374 |
This is an abbreviation for |
| 3375 |
|W={1,...,|\meta{number}|}, name shore W/.style={name=W}|. |
| 3376 |
\end{key} |
| 3377 |
% |
| 3378 |
The main purpose of this subgraph is to setup the nodes in a bipartite |
| 3379 |
graph: |
| 3380 |
% |
| 3381 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3382 |
\tikz \graph { |
| 3383 |
subgraph I_nm [n=3, m=4]; |
| 3384 |
|
| 3385 |
V 1 -- { W 2, W 3 }; |
| 3386 |
V 2 -- { W 1, W 3 }; |
| 3387 |
V 3 -- { W 1, W 4 }; |
| 3388 |
}; |
| 3389 |
\end{codeexample} |
| 3390 |
% |
| 3391 |
\end{graph} |
| 3392 |
|
| 3393 |
\begin{graph}{subgraph K\_n} |
| 3394 |
This graph is the complete clique on the vertices from the |V| key. |
| 3395 |
% |
| 3396 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3397 |
\tikz \graph [clockwise] { subgraph K_n [n=7] }; |
| 3398 |
\end{codeexample} |
| 3399 |
% |
| 3400 |
\end{graph} |
| 3401 |
|
| 3402 |
\begin{graph}{subgraph K\_nm} |
| 3403 |
This graph is the complete bipartite graph with the two shores |V| and |W| |
| 3404 |
as in |subgraph I_nm|. |
| 3405 |
% |
| 3406 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3407 |
\tikz \graph [branch right, grow down] |
| 3408 |
{ subgraph K_nm [V={6,...,9}, W={b,...,e}] }; |
| 3409 |
\end{codeexample} |
| 3410 |
% |
| 3411 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3412 |
\tikz \graph [simple, branch right, grow down] |
| 3413 |
{ |
| 3414 |
subgraph K_nm [V={1,2,3}, W={a,b,c,d}, ->]; |
| 3415 |
subgraph K_nm [V={2,3}, W={b,c}, <-]; |
| 3416 |
}; |
| 3417 |
\end{codeexample} |
| 3418 |
% |
| 3419 |
\end{graph} |
| 3420 |
|
| 3421 |
\begin{graph}{subgraph P\_n} |
| 3422 |
This graph is the path on the vertices in |V|. |
| 3423 |
% |
| 3424 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3425 |
\tikz \graph [branch right] { subgraph P_n [n=3] }; |
| 3426 |
\end{codeexample} |
| 3427 |
% |
| 3428 |
\end{graph} |
| 3429 |
|
| 3430 |
\begin{graph}{subgraph C\_n} |
| 3431 |
This graph is the cycle on the vertices in |V|. |
| 3432 |
% |
| 3433 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3434 |
\tikz \graph [clockwise] { subgraph C_n [n=7, ->] }; |
| 3435 |
\end{codeexample} |
| 3436 |
% |
| 3437 |
\end{graph} |
| 3438 |
|
| 3439 |
\begin{graph}{subgraph Grid\_n} |
| 3440 |
This graph is a grid of the vertices in |V|. |
| 3441 |
% |
| 3442 |
\begin{key}{/tikz/graphs/wrap after=\meta{number}} |
| 3443 |
Defines the number of nodes placed in a single row of the grid. This |
| 3444 |
value implicitly defines the number of grid columns as well. In the |
| 3445 |
following example a |grid placement| is used to visualize the edges |
| 3446 |
created between the nodes of a |Grid_n| |subgraph| using different |
| 3447 |
values for |wrap after|. |
| 3448 |
% |
| 3449 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3450 |
\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=1] }; |
| 3451 |
\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=3] }; |
| 3452 |
\end{codeexample} |
| 3453 |
% |
| 3454 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3455 |
\tikz \graph [grid placement] { subgraph Grid_n [n=4,wrap after=2] }; |
| 3456 |
\tikz \graph [grid placement] { subgraph Grid_n [n=4] }; |
| 3457 |
\end{codeexample} |
| 3458 |
\end{key} |
| 3459 |
\end{graph} |
| 3460 |
|
| 3461 |
% TODO: Implement the Grid_nm subgraph described here: |
| 3462 |
% |
| 3463 |
%\begin{graph}{subgraph Grid\_nm} |
| 3464 |
% This graph is a grid built from the cartesian product of the two node |
| 3465 |
% sets |V| and |W| which are either defined using the keys |
| 3466 |
% |/tikz/graphs/V| and |/tikz/graphs/W| or |/tikz/graphs/n| and |
| 3467 |
% |/tikz/graphs/m| or a mixture of both. |
| 3468 |
% |
| 3469 |
% The resulting |Grid_nm| subgraph has $n$ ``rows'' and $m$ ``columns'' and |
| 3470 |
% the nodes are named |V i W j| with $1\le i\le n$ and $1\le j\le n$. |
| 3471 |
% The names of the two shores |V| and |W| can be changed as described in |
| 3472 |
% the documentation of the keys |/tikz/graphs/name shore V| and |
| 3473 |
% |/tikz/graphs/name shore W|. |
| 3474 |
% \begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3475 |
%\tikz \graph [grid placement] { subgraph Grid_nm [V={1,2,3}, W={4, 5, 6}] }; |
| 3476 |
% \end{codeexample} |
| 3477 |
%\end{graph} |
| 3478 |
|
| 3479 |
|
| 3480 |
\subsubsection{Group Operators} |
| 3481 |
|
| 3482 |
The following keys use the |operator| key to setup operators that connect the |
| 3483 |
vertices of the current group having a certain color in a specific way. |
| 3484 |
|
| 3485 |
\begin{key}{/tikz/graphs/clique=\meta{color} (default all)} |
| 3486 |
Adds an edge between all vertices of the current group having the (logical) |
| 3487 |
color \meta{color}. Since, by default, this color is set to |all|, which is |
| 3488 |
a color that all nodes get by default, when you do not specify anything, |
| 3489 |
all nodes will be connected. |
| 3490 |
% |
| 3491 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3492 |
\tikz \graph [clockwise, n=5] { |
| 3493 |
a, |
| 3494 |
b, |
| 3495 |
{ |
| 3496 |
[clique] |
| 3497 |
c, d, e |
| 3498 |
} |
| 3499 |
}; |
| 3500 |
\end{codeexample} |
| 3501 |
% |
| 3502 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3503 |
\tikz \graph [color class=red, clockwise, n=5] { |
| 3504 |
[clique=red, ->] |
| 3505 |
a, b[red], c[red], d, e[red] |
| 3506 |
}; |
| 3507 |
\end{codeexample} |
| 3508 |
% |
| 3509 |
\end{key} |
| 3510 |
|
| 3511 |
\begin{key}{/tikz/graphs/induced independent set=\meta{color} (default all)} |
| 3512 |
This key is the ``opposite'' of a |clique|: It removes all edges in the |
| 3513 |
current group having belonging to color class \meta{color}. More precisely, |
| 3514 |
an edge of kind |-!-| is added for each pair of vertices. This means that |
| 3515 |
edge only get removed if you specify the |simple| option. |
| 3516 |
% |
| 3517 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3518 |
\tikz \graph [simple] { |
| 3519 |
subgraph K_n [<->, n=7, clockwise]; % create lots of edges |
| 3520 |
|
| 3521 |
{ [induced independent set] 1, 3, 4, 5, 6 } |
| 3522 |
}; |
| 3523 |
\end{codeexample} |
| 3524 |
% |
| 3525 |
\end{key} |
| 3526 |
|
| 3527 |
\begin{key}{/tikz/graphs/cycle=\meta{color} (default all)} |
| 3528 |
Connects the nodes colored \meta{color} is a cyclic fashion. The ordering |
| 3529 |
is the ordering in which they appear in the whole graph specification. |
| 3530 |
% |
| 3531 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3532 |
\tikz \graph [clockwise, n=6, phase=60] { |
| 3533 |
{ [cycle, ->] a, b, c }, |
| 3534 |
{ [cycle, <-] d, e, f } |
| 3535 |
}; |
| 3536 |
\end{codeexample} |
| 3537 |
% |
| 3538 |
\end{key} |
| 3539 |
|
| 3540 |
\begin{key}{/tikz/graphs/induced cycle=\meta{color} (default all)} |
| 3541 |
While the |cycle| command will only add edges, this key will also remove |
| 3542 |
all other edges between the nodes of the cycle, provided we are |
| 3543 |
constructing a |simple| graph. |
| 3544 |
% |
| 3545 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3546 |
\tikz \graph [simple] { |
| 3547 |
subgraph K_n [n=7, clockwise]; % create lots of edges |
| 3548 |
|
| 3549 |
{ [induced cycle, ->, edge=red] 2, 3, 4, 6, 7 }, |
| 3550 |
}; |
| 3551 |
\end{codeexample} |
| 3552 |
% |
| 3553 |
\end{key} |
| 3554 |
|
| 3555 |
\begin{key}{/tikz/graphs/path=\meta{color} (default all)} |
| 3556 |
Works like |cycle|, only there is no edge from the last to the first |
| 3557 |
vertex. |
| 3558 |
% |
| 3559 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3560 |
\tikz \graph [clockwise, n=6] { |
| 3561 |
{ [path, ->] a, b, c }, |
| 3562 |
{ [path, <-] d, e, f } |
| 3563 |
}; |
| 3564 |
\end{codeexample} |
| 3565 |
% |
| 3566 |
\end{key} |
| 3567 |
|
| 3568 |
\begin{key}{/tikz/graphs/induced path=\meta{color} (default all)} |
| 3569 |
Works like |induced cycle|, only there is no edge from the last to the |
| 3570 |
first vertex. |
| 3571 |
% |
| 3572 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3573 |
\tikz \graph [simple] { |
| 3574 |
subgraph K_n [n=7, clockwise]; % create lots of edges |
| 3575 |
|
| 3576 |
{ [induced path, ->, edges=red] 2, 3, 4, 6, 7 }, |
| 3577 |
}; |
| 3578 |
\end{codeexample} |
| 3579 |
% |
| 3580 |
\end{key} |
| 3581 |
|
| 3582 |
|
| 3583 |
\subsubsection{Joining Operators} |
| 3584 |
|
| 3585 |
The following keys are typically used as options of an \meta{edge |
| 3586 |
specification}, but can also be called in a group specification (however, then, |
| 3587 |
the colors need to be set explicitly). |
| 3588 |
|
| 3589 |
\begin{key}{/tikz/graphs/complete bipartite=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})} |
| 3590 |
Adds all possible edges from every node having color \meta{from color} to |
| 3591 |
every node having color \meta{to color}: |
| 3592 |
% |
| 3593 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3594 |
\tikz \graph { {a, b} ->[complete bipartite] |
| 3595 |
{c, d, e} --[complete bipartite] |
| 3596 |
{g, h, i, j} --[complete bipartite] |
| 3597 |
k }; |
| 3598 |
\end{codeexample} |
| 3599 |
% |
| 3600 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3601 |
\tikz \graph [color class=red, color class=green, clockwise, n=6] { |
| 3602 |
[complete bipartite={red}{green}, ->] |
| 3603 |
a [red], b[red], c[red], d[green], e[green], f[green] |
| 3604 |
}; |
| 3605 |
\end{codeexample} |
| 3606 |
% |
| 3607 |
\end{key} |
| 3608 |
|
| 3609 |
\begin{key}{/tikz/graphs/induced complete bipartite} |
| 3610 |
Works like the |complete bipartite| operator, but in a |simple| graph any |
| 3611 |
edges between the vertices in either shore are removed (more precisely, |
| 3612 |
they get replaced by |-!-| edges). |
| 3613 |
% |
| 3614 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3615 |
\tikz \graph [simple] { |
| 3616 |
subgraph K_n [n=5, clockwise]; % Lots of edges |
| 3617 |
|
| 3618 |
{2, 3} ->[induced complete bipartite] {4, 5} |
| 3619 |
}; |
| 3620 |
\end{codeexample} |
| 3621 |
% |
| 3622 |
\end{key} |
| 3623 |
|
| 3624 |
\begin{key}{/tikz/graphs/matching=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})} |
| 3625 |
This joining operator forms a maximum \emph{matching} between the nodes of |
| 3626 |
the two sets of nodes having colors \meta{from color} and \meta{to color}, |
| 3627 |
respectively. The first node of the from set is connected to the first node |
| 3628 |
of to set, the second node of the from set is connected to the second node |
| 3629 |
of the to set, and so on. If the sets have the same size, what results is |
| 3630 |
what graph theoreticians call a \emph{perfect matching}, otherwise only a |
| 3631 |
maximum, but not perfect matching results. |
| 3632 |
% |
| 3633 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3634 |
\tikz \graph { |
| 3635 |
{a, b, c} ->[matching] |
| 3636 |
{d, e, f} --[matching] |
| 3637 |
{g, h} --[matching] |
| 3638 |
{i, j, k} |
| 3639 |
}; |
| 3640 |
\end{codeexample} |
| 3641 |
% |
| 3642 |
\end{key} |
| 3643 |
|
| 3644 |
\begin{key}{/tikz/graphs/matching and star=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})} |
| 3645 |
The |matching and star| connector works like the |matching| connector, only |
| 3646 |
it behaves differently when the two to-be-connected sets have different |
| 3647 |
size. In this case, all the surplus nodes get connected to the last node of |
| 3648 |
the other set, resulting in what is known as a \emph{star} in graph theory. |
| 3649 |
This simple rule allows for some powerful effects (since this connector is |
| 3650 |
the one initially set, there is no need to add it here): |
| 3651 |
% |
| 3652 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 3653 |
\tikz \graph { a -> {b, c} -> {d, e} -- f}; |
| 3654 |
\end{codeexample} |
| 3655 |
% |
| 3656 |
The |matching and star| connector also makes it easy to create trees and |
| 3657 |
series-parallel graphs. |
| 3658 |
\end{key} |
| 3659 |
|
| 3660 |
\begin{key}{/tikz/graphs/butterfly=\opt{\meta{options}}} |
| 3661 |
The |butterfly| connector is used to create the kind of connections present |
| 3662 |
between layers of a so-called \emph{butterfly network}. As for other |
| 3663 |
connectors, two sets of nodes are connected, which are the nodes having |
| 3664 |
color |target'| and |source'| by default. In a \emph{level $l$} connection, |
| 3665 |
the first $l$ nodes of the first set are connected to the second $l$ nodes |
| 3666 |
of the second set, while the second $l$ nodes of the first set get |
| 3667 |
connected to the first $l$ nodes of the second set. Then, for next $2l$ |
| 3668 |
nodes of both sets a similar kind of connection is installed. Additionally, |
| 3669 |
each node gets connected to the corresponding node in the other set with |
| 3670 |
the same index (as in a |matching|): |
| 3671 |
% |
| 3672 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}] |
| 3673 |
\tikz \graph [left anchor=east, right anchor=west, |
| 3674 |
branch down=4mm, grow right=15mm] { |
| 3675 |
subgraph I_n [n=12, name=A] --[butterfly={level=3}] |
| 3676 |
subgraph I_n [n=12, name=B] --[butterfly={level=2}] |
| 3677 |
subgraph I_n [n=12, name=C] |
| 3678 |
}; |
| 3679 |
\end{codeexample} |
| 3680 |
% |
| 3681 |
Unlike most joining operators, the colors of the nodes in the first and the |
| 3682 |
second set are not passed as parameters to the |butterfly| key. Rather, |
| 3683 |
they can be set using the \meta{options}, which are executed with the path |
| 3684 |
prefix |/tikz/graphs/butterfly|. |
| 3685 |
% |
| 3686 |
\begin{key}{/tikz/graphs/butterfly/level=\meta{level} (initially 1)} |
| 3687 |
Sets the level $l$ for the connections. |
| 3688 |
\end{key} |
| 3689 |
% |
| 3690 |
\begin{key}{/tikz/graphs/butterfly/from=\meta{color} (initially target')} |
| 3691 |
Sets the color class of the from nodes. |
| 3692 |
\end{key} |
| 3693 |
% |
| 3694 |
\begin{key}{/tikz/graphs/butterfly/to=\meta{color} (initially source')} |
| 3695 |
Sets the color class of the to nodes. |
| 3696 |
\end{key} |
| 3697 |
\end{key} |
| 3698 |
|
| 3699 |
|
| 3700 |
%%% Local Variables: |
| 3701 |
%%% mode: latex |
| 3702 |
%%% TeX-master: "pgfmanual-pdftex-version" |
| 3703 |
%%% End: |