Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-graphs.tex

raw
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: