% The output-first catalogue: one drawn specimen per construct family that
% the tutorial and the recipes do not reach.  Every picture here is modelled
% on a benchmark case or a blueprint figure, so the reader learns the idiom
% the corpus actually writes rather than a toy.
\section{Catalogue of Constructs}\label{ch:catalogue}

The generated tables in Chapter~\ref{ch:reference} name every environment,
command, and key.  Naming is not showing.  This chapter draws one specimen
per family the tutorial and the recipes leave unpictured, in the order a
source is read: the frame first, then the atoms it places, then the
connections between them, then the annotations over them, and last the
setup that extends the alphabet.

Each specimen is modelled on a benchmark case or a blueprint figure, so
what you read is the spelling the corpus writes.  Where a family has words
the corpus does not write, the entry says so rather than inventing a use.

\subsection{Alternative frames}

A picture's frame is its coordinate system.  \tnkey{frame=}\tnval{flat} is
the default and the whole tutorial rides it; \tnval{plane} projects a
sheet.  The third word is \tnval{circle}, which seats the columns of one
row at equal angles on a ring and turns each glyph by its station's
tangent.  The object it draws is a network whose stations stand on a
cycle, and the contraction that closes the cycle is written rather than
seated.

\begin{tnexample}[
  label={tnex:cat-circle},
  formula={\psi_{ijk}=\sum_{\alpha\beta\gamma}
    A^{i}_{\gamma\alpha}B^{j}_{\alpha\beta}C^{k}_{\beta\gamma}},
  caption={three tensors contracted around a cycle},
  index={Each station carries one physical spoke, and the three virtual
    bonds close the triangle.  The signature records each spoke at the
    bearing its station transported it to, not at the face it was
    declared on.},
  signature={kernel-boundary|signature=phys:210, phys:330, phys:n}]
% Formula: psi_ijk = sum A^i_{gamma alpha} B^j_{alpha beta}
%   C^k_{beta gamma}.
% Ink: the circle frame seats the three sites and carries each
%   physical port out along its station's radius.
\begin{tenkz}[rows={wire}, cols=3, frame=circle, bonds=none]
  \tn[at=(1,1), name=a,
      ports={0:virtual, 180:virtual, 90:physical:$i$}]{}
  \tn[at=(1,2), name=b,
      ports={0:virtual, 180:virtual, 90:physical:$j$}]{}
  \tn[at=(1,3), name=c,
      ports={0:virtual, 180:virtual, 90:physical:$k$}]{}
  \tnbond[name=al]{a.0}{b.180}
  \tnbond[name=be]{b.0}{c.180}
  \tnbond[name=ga]{c.0}{a.180}
  \tnmark[form=label, label pos=e]{on al 0.5}{$\alpha$}
  \tnmark[form=label, label pos=s]{on be 0.5}{$\beta$}
  \tnmark[form=label, label pos=w]{on ga 0.5}{$\gamma$}
\end{tenkz}
\end{tnexample}

Three facts of the ring are visible at once.  A station's local faces are
its own: \tnval{0} is the direction the glyph at that station calls east,
not the page's east, so the one wire \tnval{a.0} to \tnval{b.180} means
the same thing at every station and the three bonds are written alike.
The physical port declared at \tnval{90} leaves along the station's
outward radius, because the row's north is the ring's outward normal.  And
the names read level, because a glyph turns and its label does not.

\tnkey{bonds=}\tnval{none} appears here for the reason it appears in
almost every ring in the corpus: the frame's adjacent-cell contraction
would join the columns in a line, which on a ring is one bond short of the
cycle.  Write the cycle's edges and the picture says what it means.

\dbendpar A ring whose closure is the trace itself, with no tensor on the
return, is common enough to have a word.  \tnkey{ring=}\meta{n} is sugar
for \tnkey{rows=}\tnval{\{wire\}}, \tnkey{cols=}\meta{n},
\tnkey{frame=}\tnval{circle}, \tnkey{west=}\tnval{trace},
\tnkey{east=}\tnval{trace}: the stations of a circle, closed to
themselves.

\begin{tnexample}[
  formula={\operatorname{tr}(M_1M_2M_3M_4)},
  caption={the traced word, drawn as a ring},
  index={The trace follows the frame's arc rather than the chord between
    the two stations it joins.  No index survives, so the picture is a
    scalar.  The names are inscribed: a label outside a glyph on a ring
    is placed toward the centre, where four of them would meet.},
  signature={kernel-boundary|signature=}]
% Formula: tr(M_1 M_2 M_3 M_4); the ring word is sugar for
%   rows={wire}, cols=4, frame=circle, west=trace, east=trace.
\begin{tenkz}[ring=4]
  \tn[skin=box]{M_1} & \tn[skin=box]{M_2} &
  \tn[skin=box]{M_3} & \tn[skin=box]{M_4}
\end{tenkz}
\end{tnexample}

The four side policies describe the boundary of a rectangular frame.
Opening the transverse sides exposes the north and south indices; tracing a
side instead joins its boundary sites through the frame.  A physical trace is
different: it closes the applicable pair of physical ports at each site.

\begin{tnexample}[
  wide,
  formula={\operatorname{tr}_{\mathrm{phys}}(A)\quad\text{and}\quad
    A\colon V_{\rm S}\longrightarrow V_{\rm N}},
  caption={a physical trace and two open transverse sides},
  index={Left: the upper and lower physical ports close to one another, while
    the virtual ends remain open.  Right: the north and south frame policies
    expose one virtual index per boundary site.  The signature below records
    the left panel.},
  signature={kernel-boundary|signature=open:e, open:w}]
% Ink: trace=physical closes the site's two physical ports.
% north=open and south=open expose the frame boundary.
\begin{tenkz}[rows={wire}, cols=1, bonds=none,
              west=open, east=open, physical=updown,
              trace=physical]
  \tn[skin=box]{A}
\end{tenkz}
\qquad
\begin{tenkz}[lattice={2x2}, bonds=none, west=none, east=none,
              north=open, south=open]
  \tn{} & \tn{} \\
  \tn{} & \tn{}
\end{tenkz}
\end{tnexample}

Identifying opposite sides of a square gives a torus.  A horizontal segment
and a vertical segment become closed cycles after this identification.  They
represent winding classes $(1,0)$ and $(0,1)$ and meet transversely once.

\begin{center}
\begin{tikzpicture}[x=1.3cm,y=1.3cm,>=Stealth]
  % Matching arrows identify opposite edges of this fundamental square.
  \draw[gray,dashed] (0,0) rectangle (3,3);
  \draw[gray,->] (0.35,0) -- (1.05,0);
  \draw[gray,->] (0.35,3) -- (1.05,3);
  \draw[gray,->] (0,0.35) -- (0,1.05);
  \draw[gray,->] (3,0.35) -- (3,1.05);
  \node[below] at (0.7,0) {$a$};
  \node[above] at (0.7,3) {$a$};
  \node[left] at (0,0.7) {$b$};
  \node[right] at (3,0.7) {$b$};
  \draw[red!75!black,thick,->] (0,1.5) -- (3,1.5);
  \draw[blue!75!black,thick,->] (1.5,0) -- (1.5,3);
  \node[above,red!75!black] at (2.3,1.5) {$c_x$};
  \node[right,blue!75!black] at (1.5,2.3) {$c_y$};
  \fill (1.5,1.5) circle[radius=1.4pt];
\end{tikzpicture}

\small
A fundamental square: identify equally labeled edges in the arrow direction.
The dot marks the intersection of $c_x$ and $c_y$, not a tensor insertion.
\end{center}

This topological schematic is drawn with TikZ.  The current \tnkey{wind=}
renderer uses a projected curve that does not reliably display the two
fundamental cycles; it should not be used as a verified drawing of this
construction.

The metric profile rescales every pitch-relative length together.  It does not
introduce a second table of lengths: \tncmd{tnset} changes the single base
pitch, and \tnkey{metrics=} selects the one named ratio applied to it.

\begin{tnexample}[
  wide,
  caption={one tensor word at two metric scales},
  index={The two panels carry the same three-site network.  The right panel
    starts from a larger document pitch and then applies the compact profile;
    all pitch-relative distances move together.},
  signature={kernel-boundary|signature=open:e, open:w, phys:n}]
% Ink: tnset changes the one base pitch; metrics=compact scales
%   every pitch-relative metric from that base.
\begin{tenkz}[rows={wire}, cols=3, west=open, east=open]
  \tn{A} & \tn[ports={90:physical:$i$}]{B} & \tn{C}
\end{tenkz}
\qquad
{\tnset{pitch=17mm}
\begin{tenkz}[metrics=compact, rows={wire}, cols=3,
              west=open, east=open]
  \tn{A} & \tn[ports={90:physical:$i$}]{B} & \tn{C}
\end{tenkz}}
\end{tnexample}

Within an equation, \tnkey{align=} names the row whose axis is the common
mathematical baseline.  The policy belongs to the equation and is inherited by
its panels, so both sides below align on their operator row.

\begin{tnexample}[
  formula={AO\overline A=AO\overline A},
  caption={equation panels aligned on their second row},
  index={The ket, operator, and bra rows have different silhouettes.  The
    equation nevertheless places both panels on the operator axis because
    \tnkey{align=2} is shared by the composition.},
  signature={kernel-boundary|signature=}]
% Layout: align=2 makes the operator row the equation baseline.
\begin{tenkzeq}[align=2, check={signature}]
  \begin{tenkz}[rows={ket,op,bra}, cols=1, bonds=none]
    \tn[at=(1,1)]{A} \tn[at=(2,1), skin=mpo]{O}
    \tn[at=(3,1)]{\overline A}
  \end{tenkz}
  =
  \begin{tenkz}[rows={ket,op,bra}, cols=1, bonds=none]
    \tn[at=(1,1)]{A} \tn[at=(2,1), skin=mpo]{O}
    \tn[at=(3,1)]{\overline A}
  \end{tenkz}
\end{tenkzeq}
\end{tnexample}

The remaining frame spelling is the explicit one.  \tnkey{basis=} lists
ordered row-kind members at quarter-pitch offsets from the origin, and
every cell address then gains a member coordinate: \tnval{(r,c,k)} is the
$k$-th member's copy of cell \tnval{(r,c)}.  The \tnval{planes} word of
the tutorial's double layer is one two-member basis under a name; writing
the basis out places the members where the mathematics wants them.

\begin{tnexample}[
  caption={three basis members in one frame},
  index={One cell, three members.  The offsets are quarter-pitch steps
    from the origin member, and each member's copy of the cell is
    addressed by its index.},
  signature={kernel-boundary|signature=}]
% Ink: an explicit three-member basis; the member index is the
%   third coordinate of every address.
\begin{tenkz}[rows={wire}, cols=1, bonds=none,
  frame={flat, basis={wire at (0,0), wire at (2,0),
                      wire at (1,2)}}]
  \tn[at=(1,1,1), skin=box]{A}
  \tn[at=(1,1,2), skin=box]{B}
  \tn[at=(1,1,3), skin=box]{C}
\end{tenkz}
\end{tnexample}

\dbendpar An explicit basis belongs to a picture-level \tnval{flat} or
\tnval{plane} frame.  A circle frame refuses one, because its members
would need a tangent-offset contract the language does not state, and a
group frame refuses one because a basis is picture-scoped.  An atom has
no frame of its own at all: neither \tnkey{frame=} nor \tnkey{basis=} is
an atom key, so a site that writes either is turned away as an unknown
word rather than accepted and restricted.

\subsection{Atom declarations}

An atom's silhouette and its type are separate data.  \tnkey{skin=} names
the silhouette alone; the stock vocabulary is eight words, and the
standard prelude declares two more.

\begin{tnexample}[
  caption={the stock silhouettes, and the two declared by the prelude},
  index={Left to right: dot, box, roundrect, ring, tri, triwest, dots,
    none, and the prelude's pill and mpo.  The eighth cell is empty
    because \tnval{none} draws neither glyph nor label.  None of the ten
    says anything about what a record contracts; that is a declared
    skin's \tnkey{pairings=}, which takes ports and appears with the
    declarations at the end of the chapter.},
  signature={kernel-boundary|signature=}]
% Ink: one atom per skin; bonds=none, so nothing here contracts.
% The none cell is deliberately blank -- that is what it draws.
\begin{tenkz}[rows={wire}, cols=10, bonds=none]
  \tn[skin=dot]{} & \tn[skin=box]{B} & \tn[skin=roundrect]{R} &
  \tn[skin=ring]{X} & \tn[skin=tri]{T} & \tn[skin=triwest]{W} &
  \tn[skin=dots]{} & \tn[skin=none]{} & \tn[skin=pill]{P} &
  \tn[skin=mpo]{O}
\end{tenkz}
\end{tnexample}

Two of these are structural rather than decorative.  \tnval{dots} is the
ellipsis cell of a chain whose middle is elided, and its wires pass
through it; \tnval{none} draws no glyph at all, which is what a corner
junction wants when the wire must turn at a place that carries no tensor.
Both appear in the traced word below.

A glyph's extent is \tnkey{size=}, and a record that stands for a block of
records is \tnkey{cluster=}: an $R\times C$ group of addressable
sub-atoms named after the host.

\begin{tnexample}[
  caption={three size classes, and one clustered site},
  index={The first three are one skin at the three metric classes.  The
    fourth is a single declaration standing for four addressable
    sub-atoms, reached as \tnval{q-1-1} through \tnval{q-2-2}.},
  signature={kernel-boundary|signature=}]
% Ink: size= chooses a glyph's extent from the metric table;
%   cluster= expands one declaration into an addressable group.
\begin{tenkz}[rows={wire}, cols=4, bonds=none]
  \tn[at=(1,1), skin=dot, size=s]{} &
  \tn[at=(1,2), skin=dot, size=m]{} &
  \tn[at=(1,3), skin=dot, size=l]{} &
  \tn[at=(1,4), name=q, cluster=2x2]{}
\end{tenkz}
\end{tnexample}

The two span counts belong to the atom rather than to the frame.
\tnkey{wide=} counts columns and \tnkey{wires=} counts rows; together they
place one tensor over the rectangular block of sites it represents.

\begin{tnexample}[
  formula={R\colon V^{\otimes 2}\longrightarrow V^{\otimes 2}},
  caption={one tensor spanning two rows and two columns},
  index={The rectangle is one atom, not four coincident sites.  Its slotted
    west and east ports expose the two virtual indices carried by the rows.},
  signature={kernel-boundary|signature=open:e, open:e, open:w, open:w}]
% Ink: wide=2 and wires=2 give one atom a two-by-two host rectangle.
\begin{tenkz}[rows={wire,wire}, cols=2, bonds=none]
  \tn[at=(1,1), skin=box, wide=2, wires=2, name=R,
      ports={180@1:virtual, 180@2:virtual,
             0@1:virtual, 0@2:virtual}]{R}
  \tnwire{open w}{R.180@1} \tnwire{open w}{R.180@2}
  \tnwire{R.0@1}{open e} \tnwire{R.0@2}{open e}
\end{tenkz}
\end{tnexample}

A declared skin may carry more than one internal pairing.  When two such
routes meet, \tnkey{pairing cross=} identifies the pairing instance and fixes
its order at the crossing, just as \tnkey{cross=} does for an authored wire.

\begin{tnexample}[
  caption={two declared pairings with a chosen crossing order},
  index={The horizontal and vertical routes belong to their skins.  The
    horizontal host declares that its first pairing passes under the first
    pairing of the vertical host.},
  signature={kernel-boundary|signature=}]
% Ink: pairing cross= orders two skin-owned routes
%   at their intersection.
\tndeclare{species}{warm}{hue=source:red}
\tndeclare{species}{cool}{hue=source:blue}
\tndeclare{skin}{crossed-horizontal}{
  base=box, pairings={w@1 > e@1 : warm}}
\tndeclare{skin}{crossed-vertical}{
  base=box, pairings={n@1 > s@1 : cool}}
\begin{tenkz}[size=l, rows={wire}, cols=1, bonds=none]
  \tn[at=(1,1), name=H, skin=crossed-horizontal, size=l,
      pairing cross={
        1: under at crossing of self and pairing 1 of V}]{}
  \tn[at=0 e of H, name=V, skin=crossed-vertical, size=l]{}
\end{tenkz}
\end{tnexample}

A site that is not there is \tnkey{void=}.  The two words differ in how
much they take away.  \tnval{sealed} removes the site, the bonds that
reached it, and the leg the row's physical policy would have given it.
\tnval{open} removes the glyph alone: the bonds still meet at the station
and the leg still leaves it, so the picture loses a tensor's ink and not
one entry of its boundary.  The glyph goes because a void site's
silhouette falls to \tnval{none}, and that is a default rather than an
override: a site that names its own \tnkey{skin=} draws it.

\begin{tnexample}[
  formula={\lvert\psi\rangle\ \text{with one site removed}},
  caption={a sealed site in a sheet},
  index={The centre site and its four bonds are gone, and the sheet's
    remaining sites keep their physical legs.  A sealed hole exposes
    nothing, so the signature loses exactly the removed site's leg.},
  signature={kernel-boundary|signature=phys:n, phys:n, phys:n, phys:n,
    phys:n, phys:n, phys:n, phys:n}]
% Ink: void=sealed removes the site and the bonds that reached
%   it; void=open would keep both and drop only the glyph.
\begin{tenkz}[lattice={3x3}, frame=plane, physical=up]
  \tn{} & \tn{} & \tn{} \\
  \tn{} & \tn[void=sealed]{} & \tn{} \\
  \tn{} & \tn{} & \tn{}
\end{tenkz}
\end{tnexample}

\tnexercise{ex:cat-void} The eight physical legs above are the eight
surviving sites.  How many entries does the signature carry when the
centre is written \tnkey{void=}\tnval{open} instead, and which of them
are virtual?

\subsection{Connections}

Every connection is a \tncmd{tnwire}.  Its \tnkey{kind=} says which kind:
\tnval{index} is a contraction, the default, and \tncmd{tnbond} is its
one-word spelling; \tnval{string} travels over the picture carrying an
operator index; \tnval{pairing} is a declared skin's own internal route,
and is never authored at a call site.

The path a wire takes is \tnkey{route=}.  \tnval{straight} is the default
and joins the two ends directly.  A rectangular periodic return uses
straight segments and four corner junctions, as below.  Each junction pairs
two virtual ports and carries no tensor.

\begin{tnexample}[
  label={tnex:cat-periodic},
  formula={\lvert\psi(X)\rangle=\sum_{s_1\ldots s_N}
    \operatorname{tr}\!\left(XA^{s_1}\cdots A^{s_N}\right)\lvert s\rangle},
  caption={a periodic word with a symmetric return},
  index={The four corner junctions carry no tensor, and the elision cell
    passes its wires through.  Every virtual index closes through $X$;
    each drawn site keeps its physical leg.},
  signature={kernel-boundary|signature=phys:n, phys:n, phys:n}]
% Formula: |psi(X)> = sum tr(X A^{s_1} ... A^{s_N}) |s>.
% Ink: one virtual loop with four tensor-free corners.
% X is centered below the uniformly spaced tensor row.
\begin{tenkz}[rows={wire,wire}, cols=9, bonds=none]
  \tn[at=(1,2), skin=box, name=a1,
      ports={0:virtual, 180:virtual, 90:physical}]{A}
  \tn[at=(1,4), skin=box, name=a2,
      ports={0:virtual, 180:virtual, 90:physical}]{A}
  \tn[at=(1,6), skin=dots, name=d,
      ports={0:virtual, 180:virtual}]{}
  \tn[at=(1,8), skin=box, name=a4,
      ports={0:virtual, 180:virtual, 90:physical}]{A}
  \tn[at=(2,5), skin=box, name=x,
      ports={0:virtual, 180:virtual}]{X}
  \tnwire{a1.0}{a2.180} \tnwire{a2.0}{d.180}
  \tnwire{d.0}{a4.180}
  \tn[at=(1,1), skin=none, name=nw, ports={0:virtual,270:virtual}]{}
  \tn[at=(2,1), skin=none, name=sw, ports={0:virtual,90:virtual}]{}
  \tn[at=(1,9), skin=none, name=ne, ports={180:virtual,270:virtual}]{}
  \tn[at=(2,9), skin=none, name=se, ports={180:virtual,90:virtual}]{}
  \tnwire{a4.0}{ne.180} \tnwire{ne.270}{se.90}
  \tnwire{se.180}{x.0} \tnwire{x.180}{sw.0}
  \tnwire{sw.90}{nw.270} \tnwire{nw.0}{a1.180}
\end{tenkz}
\end{tnexample}

The corner junctions make the two sides of the return equal.  Every segment
is a contraction, so all virtual indices close through $X$ and only the three
physical indices remain open.

Use \tnval{arc} for a curved connection: it leaves and enters along its
ends' faces.  When neither end names a face, it follows the straight chord.
The next example uses four arcs to close a plaquette.

The same family draws a closed cycle of tensors laid out as a plaquette,
and a matrix inserted on one of its edges is an ordinary ring atom
addressed by a fraction along the named wire.

\begin{tnexample}[
  formula={\lambda\ \text{on one edge}},
  caption={four arcs, and a bead on one of them},
  index={The four operator-species arcs form the closed ring; the ring
    atom stands halfway along the named north-west arc.  Each tensor
    spends two of its four faces on the ring and leaves two open, so
    eight virtual ends reach the boundary.},
  signature={kernel-boundary|signature=open:e, open:e, open:n, open:n,
    open:s, open:s, open:w, open:w}]
% Ink: four arcs close the plaquette; at=on <wire> <fraction>
%   stands the inserted matrix halfway along one of them.
\tndeclare{species}{op}{hue=source:red}
\begin{tenkz}[rows={wire,wire,wire}, cols=5, bonds=none]
  \tn[skin=mpo, at=(1,3), name=N,
      ports={0:virtual, 90:virtual, 180:virtual, 270:virtual}]{}
  \tn[skin=mpo, at=(2,4), name=E,
      ports={0:virtual, 90:virtual, 180:virtual, 270:virtual}]{}
  \tn[skin=mpo, at=(3,3), name=S,
      ports={0:virtual, 90:virtual, 180:virtual, 270:virtual}]{}
  \tn[skin=mpo, at=(2,2), name=W,
      ports={0:virtual, 90:virtual, 180:virtual, 270:virtual}]{}
  \tnwire[route=arc, species=op, name=lam]{W.90}{N.180}
  \tnwire[route=arc, species=op]{N.0}{E.90}
  \tnwire[route=arc, species=op]{E.270}{S.0}
  \tnwire[route=arc, species=op]{S.180}{W.270}
  \tn[skin=ring, at=on lam 0.5]{\lambda}
\end{tenkz}
\end{tnexample}

The third route word is \tnval{orth}, which turns at right angles.  It is
the spelling for a string that must reach around the picture rather than
across it, and it takes its corners from \tnkey{via=}, a list of addresses
the path passes through.

\begin{tnexample}[
  caption={a string routed around the picture},
  index={The waypoint is an ordinary cell address.  The path leaves $A$
    southward, turns at the named cell, and enters $B$ from the west.},
  signature={kernel-boundary|signature=}]
% Ink: route=orth turns at right angles; via= names the cells
%   the path passes through.
\tndeclare{species}{gauge}{hue=source:blue}
\begin{tenkz}[rows={wire,wire,wire}, cols=4, bonds=none]
  \tn[at=(1,1), name=a, skin=box]{A}
  \tn[at=(3,4), name=b, skin=box]{B}
  \tnwire[kind=string, species=gauge, route=orth,
          via={(3,1)}]{a.270}{b.180}
\end{tenkz}
\end{tnexample}

A string that returns to itself is \tnkey{closed}, and a closed wire takes
no positional ends at all: it is a cycle, so it has none to give.  Its
shape comes from its route: a loop that rings a selection travels the
hull, \tnkey{route=}\tnval{\{all of z\}}, and a freer shape names its
waypoints with \tnkey{via=}.

\begin{tnexample}[
  caption={a closed string around a site},
  index={The loop carries an operator index and contracts nothing.  It
    exposes no end, so it adds no entry to the signature.},
  signature={kernel-boundary|signature=}]
% Ink: a closed string takes no ends; its route rings the named selection.
\begin{tenkz}[rows={wire}, cols=2, bonds=none]
  \tn[at=(1,1), name=z, skin=box]{Z}
  \tnwire[kind=string, closed, route={all of z}]
\end{tenkz}
\end{tnexample}

Three further wire keys decorate the rail rather than change its path.
\tnkey{stroke=} is the rail's pattern, and the corpus draws only three:
\tnval{solid} for a contraction, \tnval{dashed} for a line the figure
shows but its contraction does not use, \tnval{dotted} for a lattice
lying under the sheet being drawn.  Those are readings, and the pattern
is ink alone: a dashed wire keeps the default
\tnkey{kind=}\tnval{index}, and what decides whether a drawn line
contracts is what its two ends are.  A wire between two ports takes them
both, whatever its stroke; a wire between two atoms named as wholes
leaves their ports where they were.  That is how the dashed diagonals of
the benchmark's dual lattice recall an edge without contracting one:
their ends are junctions with no ports to take.  \tnkey{dir=} marks a
directed index against its dual.  Multiplicity is mathematics carried by
the index label, not a second field on the rail.

\begin{tnexample}[
  wide,
  caption={the three strokes and a direction},
  index={Left: the three declared rail patterns.  The four sites declare
    no ports, so the three rails differ in pattern and in nothing else.
    Right: one rail carrying the direction mark that distinguishes a
    space from its dual.},
  signature={kernel-boundary|signature=}]
% Ink: stroke= is the rail's pattern; dir= marks the direction.
\begin{tenkz}[rows={wire}, cols=4, bonds=none]
  \tn[at=(1,1), name=p]{} \tn[at=(1,2), name=q]{}
  \tn[at=(1,3), name=r]{} \tn[at=(1,4), name=s]{}
  \tnwire[stroke=solid]{p.0}{q.180}
  \tnwire[stroke=dashed]{q.0}{r.180}
  \tnwire[stroke=dotted]{r.0}{s.180}
\end{tenkz}
\qquad
\begin{tenkz}[rows={wire}, cols=2, bonds=none]
  \tn[at=(1,1), name=u]{U} \tn[at=(1,2), name=v]{V}
  \tnwire[dir=to]{u.0}{v.180}
\end{tenkz}
\end{tnexample}

\subsection{Annotations}

A mark speaks over a picture and owns none of it.  Its \tnkey{form=} is
the shape of the speech, and the alphabet is four words.  Three put ink
on the page: \tnval{label} stands text at a target, \tnval{bracket}
measures a span from outside it, and \tnval{enclosure} strokes the offset
hull of a selection.  The fourth, \tnval{prose}, is accepted and recorded
without ink.  This section draws the three, shows what a spelling the
alphabet has lost answers now, and reads \tnval{prose} out of the record
stream.

\begin{tnexample}[
  caption={a bracket over a span, a label on a site},
  index={The bracket names the range of two cells; the label names one.
    Neither touches the contraction, and the signature is the row's.},
  signature={kernel-boundary|signature=open:e, open:w, phys:n, phys:n,
    phys:n}]
% Ink: two mark forms over one row; no contraction changes.
\begin{tenkz}[rows={wire}, cols=3, west=open, east=open,
              physical=up]
  \tn{A} & \tn{B} & \tn{C}
  \tnmark[form=bracket]{(1,1) .. (1,2)}{$P$}
  \tnmark[form=label, label pos=n]{(1,3)}{$q$}
\end{tenkz}
\end{tnexample}

Contours nest by themselves.  A second enclosure over one selection
stands one clearance outside the first because it was declared second,
which is how a figure draws a boundary operator acting on the open
indices of a region it also has to show.

\begin{tnexample}[
  formula={\lvert\psi(X)\rangle},
  caption={a region, and an operator on its boundary},
  index={The inner contour is the retained block; the outer one, declared
    second and therefore one clearance further out, is the operator
    acting on the indices the block leaves open.  Their region species
    distinguish the selected block from its collar by the house palette.},
  signature={kernel-boundary|signature=phys:n, phys:n, phys:n, phys:n}]
% Ink: two semantically tinted contours over one selection;
%   concentric order steps the second declared clear of the first.
\begin{tenkz}[rows={wire}, cols=4, bonds=none, physical=up]
  \tn[at=(1,1), skin=box]{A} & \tn[at=(1,2), skin=box]{A} &
  \tn[at=(1,3), skin=box]{A} & \tn[at=(1,4), skin=box]{A}
  \tnmark[form=enclosure, species=selected]{(1,1) .. (1,4)}{}
  \tnmark[form=enclosure, species=collar, label pos=e]
    {(1,1) .. (1,4)}{$X$}
\end{tenkz}
\end{tnexample}

Nothing in the source states that order.  Contours are ranked by
containment, ties going to the earlier declaration, and each rank stands
one clearance further out than the rank inside it.  A bracket drawn
inside a region window is ranked the same way and clears it instead of
sharing its support.

\tnkey{species=} tints the contour, as it tints every other record: the
five region words -- \tnval{selected}, \tnval{secondary},
\tnval{complement}, \tnval{collar}, \tnval{neutral} -- are prelude
species carrying the house region palette, and \tnval{complement} also
dashes the contour it names, the grey rest of a picture under
discussion.  A contour naming no species is passive.  \tnkey{tint} lays
ink over the paper inside a contour rather than only stroking it; the
tutorial's blocked run shows the tinted form, and so does the band
below.

Use \tnval{bracket} to mark a span.  Its \tnkey{label pos=} names the side:
\tnval{90} places it above and the default places it below.  Use
\tnval{enclosure} with \tnkey{tint} for a shaded region around a selection.

\begin{tnexample}[
  caption={brackets above and below, and a tinted enclosure},
  index={One bracket named on two sides, and one tinted enclosure.  A
    bracket's arc follows its name, so \tnkey{label pos=}\tnval{90}
    carries both to the north and the default carries both to the south.
    The enclosure's \tnkey{tint} shades the selected region.},
  signature={kernel-boundary|signature=}]
% Ink: brackets on two sides and one tinted enclosure.
\begin{tenkz}[rows={wire}, cols=2]
  \tn[skin=box]{A} & \tn[skin=box]{A}
  \tnmark[form=bracket, label pos=90]{(1,1) .. (1,2)}{$N$}
\end{tenkz}
\qquad
\begin{tenkz}[rows={wire}, cols=2]
  \tn[skin=box]{A} & \tn[skin=box]{A}
  \tnmark[form=bracket]{(1,1) .. (1,2)}{$N$}
\end{tenkz}
\qquad
\begin{tenkz}[rows={wire}, cols=2]
  \tn[skin=box]{A} & \tn[skin=box]{A}
  \tnmark[form=enclosure, tint]{(1,1) .. (1,2)}{}
\end{tenkz}
\end{tnexample}

\tnval{prose} is the one form that is accepted without ink, and it is
accepted because it asks for none.  \tncmd{tnprose} states, in the
picture's own record stream, that a step of an argument was not drawn.
Nothing appears on the page and one line appears in the event stream:

\begin{center}
\tnlogline{mark|id=mark-1|form=prose|label=by~isometry|target=panel}
\end{center}

\noindent On a checked relation that line is a hard error without a
recorded opt-out, because prose is not a boundary signature and cannot be
compared with one.

\subsection{Fusion}

Two atoms are structured rather than atomic.  \tncmd{tntree} takes a
parenthesized fusion word and draws the tree that parses it; the strands
are drawn as lines by default, and \tnkey{tree style=}\tnval{ribbon}
draws the same parsed tree as a regular ribbon neighbourhood, one band per
simple object.

\begin{tnexample}[
  formula={m_{ab}^{x}\colon a\otimes b\to x},
  caption={one fusion tree in both strand styles},
  index={Both pictures are the same chosen fusion morphism.  The wire
    style meets three lines at one trivalent vertex; the ribbon style
    gives each simple object a band and joins them at a vertex patch.},
  signature={}]
% Ink: one parsed fusion word, drawn in both strand styles.
\tndeclare{species}{anyon}{}
$\tntree[tree style=wire, species=anyon]{(a\,b)_x}
 \qquad
 \tntree[tree style=ribbon, species=anyon]{(a\,b)_x}$
\end{tnexample}

A tree is a self-contained box and stands wherever mathematics stands: in
a display, in an alignment cell, in a \texttt{tikz-cd} cell.  It is the
one construct here that does not need a picture around it.

\tncmd{tnfuse} is the other.  It is a fusion atom, a triangle whose split
side the frame bonds to the rows it spans, and it is how a doubled-layer
object is written as one tensor.

\begin{tnexample}[
  formula={M^{ij}=\sum_{k}e\,(A^{(i,k)}\otimes\overline{A}^{(j,k)})
    \,e^{-1}},
  caption={a fuser, the doubled layer, and its inverse},
  index={The two fusion atoms span both rows and combine the ket and bra
    virtual indices into one; between them the two layers carry the
    physical indices $i$ and $j$.  The frame's bond between the rows is
    the ancillary index $k$ the sum runs over.},
  signature={kernel-boundary|signature=open:e, open:w, phys:n, phys:s}]
% Formula: M^{ij} = sum_k e (A^{(i,k)} tensor
%   conj(A)^{(j,k)}) e^{-1}; the fusers combine the ket and bra
%   virtual indices into one, and the bond between the rows is
%   the ancillary index k.
\begin{tenkz}[rows={op,op}, cols=3]
  \tnfuse[at=(1,1), name=e, skin=pill]{e}
  \tn[at=(1,2), skin=box, ports={90:physical:$i$}]{A}
  \tn[at=(2,2), skin=box, ports={270:physical:$j$}]{\overline{A}}
  \tnfuse[at=(1,3), name=ei, skin=pill]{e^{-1}}
  \tnwire{open w}{e.180} \tnwire{ei.0}{open e}
\end{tenkz}
\end{tnexample}

\dbendpar \tncmd{tnfuse} is sugar for
\tnval{\textbackslash tn[skin=tri, wires=2, \ldots]}, and authored keys
follow the preset, so the \tnkey{skin=}\tnval{pill} above overrides the
triangle the preset would have drawn.  Under
\tncmd{tnset}\tnval{\{strict\}} the sugar is refused and the kernel
spelling is required.

\subsection{Setup and extension}

\tncmd{tndeclare} is the one extension door, and it has three classes.
A \emph{species} is a named hue a paper's family of objects keeps across
figures.  A \emph{skin} is a base silhouette plus \tnkey{pairings=}, its
own internal routes between its own ports.  An \emph{atom} is a new typed
spelling in the atom class.

The skin class is the one that changes what a glyph means.  A tensor whose
two port pairs are joined inside the box is drawn once as a declaration
and used as a word:

\begin{tnexample}[
  wide,
  formula={U=U_{\rightarrow}\,U_{\leftarrow}},
  caption={two declared skins, each with its own internal routes},
  index={The upper row turns its north input east and its south input
    west; the lower row reverses both.  The pairings belong to the skin,
    so every site drawn with it carries them.  The row policy grows a leg
    on both faces of every site, and the frame's bond between the rows
    takes the inner one at each, so six legs reach the boundary and not
    twelve.},
  signature={kernel-boundary|signature=phys:n, phys:n, phys:n, phys:s,
    phys:s, phys:s}]
% Ink: a declared skin is a base silhouette plus its own
%   internal port pairings, tinted by declared species.
\tndeclare{species}{right}{hue=source:blue}
\tndeclare{species}{left}{hue=source:red}
\tndeclare{skin}{shift-right}{
  base=box, pairings={n@1 > e@1 : right, s@1 > w@1 : left}}
\tndeclare{skin}{shift-left}{
  base=box, pairings={n@1 > w@1 : left, s@1 > e@1 : right}}
\begin{tenkz}[rows={wire,wire}, cols=3, physical=updown]
  \tn[skin=shift-right]{} & \tn[skin=shift-right]{} &
  \tn[skin=shift-right]{} \\
  \tn[skin=shift-left]{} & \tn[skin=shift-left]{} &
  \tn[skin=shift-left]{}
\end{tenkz}
\end{tnexample}

A pairing is a wire whose two ends are the skin's own ports, so it is
reusable topology: declare it once and every site drawn with that skin
carries it.  \tnkey{base=} may name another declared skin, so a family of
related glyphs is written as a chain of small declarations rather than
one long one.  What the chain carries down is the silhouette alone: a
derived skin resolves its base to a primitive and inherits none of its
base's pairings, so a route the derived glyph wants is written again in
its own declaration.

The atom class has a two-argument spelling, \tncmd{tndeclareatom}, for the
common case of a new command with a skin and a port list.

\begin{tnexample}[
  caption={a declared atom command},
  index={The declaration adds one word to the atom class; the picture
    then spells it like any other atom.  The port list is complete: an
    anchor without a type is not an extension contract.},
  signature={kernel-boundary|signature=open:e, open:w, phys:n}]
% Ink: tndeclareatom names faces west|east:virtual and
%   up|down:physical; tndeclare{atom} also accepts angles.
\tndeclareatom{\tnprojector}{skin=box,
  ports={west:virtual, east:virtual, up:physical}}
\begin{tenkz}[rows={wire}, cols=3, west=open, east=open]
  \tn{A} & \tnprojector{P} & \tn{B}
\end{tenkz}
\end{tnexample}

\dbendpar The two spellings do not accept the same vocabulary, in ports
or in skins.  \tncmd{tndeclareatom} takes the four named faces only ---
\tnval{west}, \tnval{east} typed \tnval{virtual}, and \tnval{up},
\tnval{down} typed \tnval{physical} --- and answers anything else with
\tnval{[TKZ-ATOM-INVALID-PORT]}.  Its \tnkey{skin=} is four words as
well, \tnval{dot}, \tnval{box}, \tnval{pill} and \tnval{mpo}; a fifth is
refused as an unknown choice and the declaration falls back to
\tnval{dot}.  The three-argument \tncmd{tndeclare}\tnval{\{atom\}} also
takes compass letters, numeric angles, and every silhouette, so a glyph
with an off-axis face or a \tnval{ring} skin is declared there.

A declaration is setup, and setup happens outside a composition form.
Writing one among an equation's panels is refused: it would be a
document-wide act performed in the middle of an assertion, ordered by
where it happens to sit and read once for each time the equation is
measured.  Write it before the equation, where it says the same thing
once.

\tncmd{tnset} carries the same policy at document scope.  Two keys live
there: \tnkey{pitch=}, the one base metric every named ratio follows, and
\tnkey{strict}, which rejects every sugar spelling in the registry.  The
house semantic ink binds when the package loads.  A palette taken from a
cited source reaches ink through a species declaration with \tnkey{hue=}.
No benchmark case sets \tnkey{strict}.  The canonical cases write sugar freely, and
\tnkey{physical=} alone stands in fifty-one of the hundred and thirty of
them; the sources that turn \tnval{strict} on are the five refusal
fixtures that prove it refuses, together with the refusal below, which is
a sixth of the same kind.
What the checks hold is the sugar itself: eleven sugar spellings compile
beside their kernel expansions and must emit the same events and the same
picture, so a sugar word is a shorter way to write a canonical case and
never a second meaning.

\begin{tnexample}[
  wide,
  formula={\langle A\rvert O\lvert A\rangle},
  caption={the sandwich sugar and its strict kernel spelling},
  index={Both panels draw the same ket--operator--bra stack.  The left uses
    the \tnkey{sandwich} preset.  In the locally strict panel on the right,
    the three rows are written explicitly and therefore need no sugar.},
  signature={kernel-boundary|signature=}]
% Ink: sandwich expands to rows={ket,op,bra}; strict accepts the
%   explicit kernel spelling and would refuse the sugar word.
\begin{tenkz}[sandwich, cols=1, bonds=none]
  \tn[at=(1,1)]{A} \tn[at=(2,1), skin=mpo]{O}
  \tn[at=(3,1)]{\overline A}
\end{tenkz}
\qquad
{\tnset{strict}
\begin{tenkz}[rows={ket,op,bra}, cols=1, bonds=none]
  \tn[at=(1,1)]{A} \tn[at=(2,1), skin=mpo]{O}
  \tn[at=(3,1)]{\overline A}
\end{tenkz}}
\end{tnexample}

\begin{tnrefusal}[
  caption={strict setup rejects a sugar spelling},
  index={\tnkey{sandwich} is sugar for
    \tnkey{rows=}\tnval{\{ket,op,bra\}}.  Under \tnval{strict} the
    expansion is not performed; the spelling is refused and named.},
  diagnostic={[TKZ-LANG-STRICT] 'sandwich' is sugar and
    \textbackslash tnset\{strict\} is active.}]
% Refused: strict rejects sugar.  The kernel spelling of this
% picture is rows={ket,op,bra}.
\tnset{strict}
\begin{tenkz}[sandwich, cols=1]
  \tn{A} \\ \tn[skin=mpo]{O} \\ \tn{$\overline{A}$}
\end{tenkz}
\end{tnrefusal}

One composition word closes the alphabet.  \tncmd{tngroup} transforms a
sub-diagram as one object, and the records inside it keep the names they
were given, so the rest of the picture can still address them.

\begin{tnexample}[
  caption={a grouped sub-diagram},
  index={The group is one object of its picture.  Its member keeps the
    name \tnval{g} and is reachable from outside the group by that name.},
  signature={kernel-boundary|signature=}]
% Ink: a group is a sub-frame of its picture, and the names
%   declared inside it stay addressable outside it.
\begin{tenkz}[rows={ket}, cols=1, bonds=none]
  \tngroup[frame=flat]{ \tn[skin=box, name=g]{G} }
\end{tenkz}
\end{tnexample}

A group's options are picture keys, and \tnkey{frame=} is the one the
specimen writes, a sub-frame being what a group is for.  A group shares
its picture's metric, size class, and audit, so the three keys that would
set those over again are refused at group scope rather than accepted and
left inert: \tnkey{size=}, \tnkey{metrics=}, and \tnkey{check=}.  A
\tnkey{basis=} inside a group's frame is refused with them.

\subsection{Answers to the exercises}

\tnanswer{ex:cat-void} Nine entries, none of them virtual, which is the
signature of the sheet with no hole in it at all.  \tnval{open} takes
away the glyph and nothing else: the four bonds still meet at the empty
station, and the centre still carries the leg its row's policy gives it,
so a reader who wants the eight-leg boundary above must write
\tnval{sealed}.  Neither word turns a bond into an exposed index.  What
\tnval{open} buys is the picture: a station where the sheet contracts and
no tensor is drawn.