% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Petri-Net Drawing Library}

\begin{tikzlibrary}{petri}
  This packages provides shapes and styles for drawing Petri nets. 
\end{tikzlibrary}



\subsection{Places}

The package defines a style for drawing places of Petri nets. 

\begin{itemize}
  \itemstyle{place}
  This style indicates that a node is a place of a Petri net. Usually,
  the text of the node should be empty since places do not contain any
  text. You should use the |label| option to add text outside the node
  like its name or its capacity. You should use the |tokens| options,
  explained in Section~\ref{section-tokens}, to add tokens inside the
  place.
  
\begin{codeexample}[]
\begin{tikzpicture}
  \node[place,label=above:$p_1$,tokens=2]        (p1) {};
  \node[place,label=below:$p_2\ge1$,right of=p1] (p2) {};
\end{tikzpicture}
\end{codeexample}
  
  \itemstyle{every place}
  This stype is envoked by the style |place|. To change the
  appearance of places, you can change this style.
\begin{codeexample}[]
\tikzstyle{every place}=[draw=blue,fill=blue!20,thick,minimum size=9mm]
\begin{tikzpicture}
  \node[place,tokens=7,label=above:$p_1$]  (p1) {};
  \node[place,structured tokens={3,2,9},
        label=below:$p_2\ge1$,right of=p1] (p2) {};
\end{tikzpicture}
\end{codeexample}
\end{itemize}



\subsection{Transitions}

Transitions are also nodes. They should be drawn using the following
style: 

\begin{itemize}
  \itemstyle{transition}
  This style indicates that a node is a transition. As for places, the
  text of a transition should be empty and the |label| option should
  be used for adding labels.

  To connect a transition to places, you can use the |edge| command as
  in the following example:
  
\begin{codeexample}[]
\begin{tikzpicture}[node distance=2cm]
  \node[place,tokens=2,label=above:$p_1$]        (p1) {};
  \node[place,label=above:$p_2\ge1$,right of=p1] (p2) {};

  \node[transition,below right of=p1,label=below:$t_1$] {}
    edge[pre]                 (p1)
    edge[post] node[auto] {2} (p2);
\end{tikzpicture}
\end{codeexample}
  
  \itemstyle{every transition}
  This style is envoked by the style |transition|.

  \itemstyle{pre}
  This style can be used with paths leading \emph{from} a transition
  \emph{to} a place to indicate that the place is in the pre-set of
  the transition. By default, this style is |<-,shorten <=1pt|, but
  feel free to redefine it.

  \itemstyle{post}
  This style is also used with paths leading \emph{from} a transition
  \emph{to} a place, but this time the place is in the post-set of
  the transition. Again, feel free to redefine it.

  \itemstyle{pre and post}
  This style is to be used to indicate that a place is both in the
  pre- and post-set of a transition.
\end{itemize}


\subsection{Tokens}
\label{section-tokens}

Interestingly, the most complicated aspect of drawing Petri nets in
\tikzname\ turns out to be the placement of tokens.

Let us start with a single token. They are also nodes and there is a
simple style for typesetting them.


\begin{itemize}
  \itemstyle{token}
  This style indicates that a node is a token. By default, this causes
  the node to be a small black circle. Unlike places and transitions,
  it \emph{does} make sense to provide text for the token node. Such
  text will be typeset in a tiny font and in white on black
  (naturally, you can easily change this by setting the style
  |every token|).
    
\begin{codeexample}[]
\begin{tikzpicture}
  \node[place,label=above:$p_1$]             (p1) {};
  \node[token] at (p1) {};

  \node[place,label=above:$p_2$,right of=p1] (p2) {};
  \node[token] at (p2) {$y$};
\end{tikzpicture}
\end{codeexample}
\end{itemize}

In the above example, it is bothersome that we need an extra command
for the token node. Worse, when we have \emph{two} tokens on a node,
it is difficult to place both nodes inside the node without overlap.

The Petri net library offers a solution to this problem: The
|children are tokens| style.


\begin{itemize}
  \itemstyle{children are tokens}
  The idea behind this style is to use trees mechanism for placing
  tokens. Every token lying on a place is treated as a child of the
  node. Normally this would have the effect that the tokens are placed
  below the place and they would be connected to the place by an
  edge. The |children are tokens| style, however, redefines the growth
  function of trees such that it places the children next to each
  other inside (or, rather, on top) of the place node. Additionally,
  the edge from the parent node is not drawn.
\begin{codeexample}[]
\begin{tikzpicture}
  \node[place,label=above:$p_1$] {}
  [children are tokens]
  child {node [token] {1}}
  child {node [token] {2}}
  child {node [token] {3}};
\end{tikzpicture}
\end{codeexample}

  In detail, what happens is the following: Tree growth functions tell
  \tikzname\ where it should place the children of nodes. These
  functions get passed the number of children that a node has an the
  number of the child that should be placed. The special tree growth
  function for tokens has a special mapping for each possible number
  of children up to nine children. This mapping decides for each child
  where it should be placed on top of the place. For example, a single
  child is placed directly on top of the place. Two children are
  placed next to each other, separated by the |token distance|. Three
  children are placed in a triangle whose side lengths are
  |token distance|; and so on up to nine tokens. If you wish to place
  more than nice tokens on a place, you will have to write your own
  placement code.
\begin{codeexample}[]
\begin{tikzpicture}
  \node[place,label=above:$p_2$] {}
  [children are tokens]
  child {node [token] {1}}
  child {node [token,fill=red] {2}}
  child {node [token,fill=red] {2}}
  child {node [token] {1}};
\end{tikzpicture}
\end{codeexample}

  \itemoption{token distance}|=|\meta{distance}
  This specifies the distance between the centers of the tokens in the
  arrangements of the option |children are tokens|.
\begin{codeexample}[]
\begin{tikzpicture}
  \node[place,label=above:$p_3$] {}
  [children are tokens,token distance=1.1ex]
  child {node [token] {}}
  child {node [token,red] {}}
  child {node [token,blue] {}}
  child {node [token] {}};
\end{tikzpicture}
\end{codeexample}
\end{itemize}

The |children are tokens| options gives you a lot of flexibility, but
it is a bit cumbersome to use. For this reason there are some options
that help in standard situations. They all use |children are tokens|
internally, so any change to, say, the |every tokens| style will
affect how these options depict tokens.

\begin{itemize}
  \itemoption{tokens}|=|\meta{number}
  This option is given to a |place| node, not to a |token| node. The
  effect of this option is to add \meta{number} many child nodes to
  the place, each having the style |token|. Thus, the following two
  pieces of codes have the same effect:
\begin{codeexample}[]
\tikz
  \node[place] {}
  [children are tokens]
  child {node [token] {}}
  child {node [token] {}}
  child {node [token] {}};
\tikz
  \node[place,tokens=3] {};
\end{codeexample}
  It is legal to say |tokens=0|, no tokens are drawn in this
  case. This option does not handle ten or more tokens correctly. If
  you need this many tokens, you will have to program your own code.
\begin{codeexample}[]
\begin{tikzpicture}
  \tikzstyle{every place}=[minimum size=9mm]

  \foreach \x/\y/\tokennumber in {0/2/1,1/2/2,2/2/3,
                                  0/1/4,1/1/5,2/1/6,
                                  0/0/7,1/0/8,2/0/9}
    \node [place,tokens=\tokennumber] at (\x,\y) {};
\end{tikzpicture}
\end{codeexample}
  \itemoption{colored tokens}|=|\meta{color list}
  This option, which must also be given when a place node is being
  created, gets a list of colors as parameter. It will then add as
  many tokens to the place are in this list, each colored with the
  corresponding color in the list.
\begin{codeexample}[]
\tikz  \node[place,colored tokens={black,black,red,blue}] {};
\end{codeexample}
  \itemoption{structured tokens}|=|\meta{token texts}
  This option, which must again be passed to a place, gets a list
  texts for tokens. For each text, another token will be added to the place.
\begin{codeexample}[]
\tikz  \node[place,structured tokens={$x$,$y$,$z$}] {};
\end{codeexample}
\begin{codeexample}[]
\begin{tikzpicture}
  \tikzstyle{every place}=[minimum size=9mm]

  \foreach \x/\y/\tokennumber in {0/2/1,1/2/2,2/2/3,
                                  0/1/4,1/1/5,2/1/6,
                                  0/0/7,1/0/8,2/0/9}
    \node [place,structured tokens={1,...,\tokennumber}] at (\x,\y) {};
\end{tikzpicture}
\end{codeexample}
  If you use lots of structured tokens, consider redefining the
  |every token| style so that the tokens are larger.
\end{itemize}



%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: 
