% Task-oriented recipes.
\section{Practical Techniques}\label{ch:recipes}

The tutorial introduced the foundational grammar of \pkg{}; this chapter gathers
a collection of practical techniques for the everyday situations you will encounter
in research papers.  Each section focuses on a single semantic task.  When
designing a diagram of your own, start from the tutorial example that most
closely matches your mathematical structure, and add only the specific policies
your physics requires.

\subsection{Open operators versus closed scalars}

In tensor-network notation, an open perimeter denotes an operator map with free
physical or virtual indices, whereas a closed perimeter represents a scalar
amplitude (such as a wavefunction overlap $\langle\phi|\psi\rangle$ or a
partition function $Z$).  In \pkg{}, a perimeter side exposes indices only when
explicitly instructed: an unstated side draws no dangling legs and carries an
empty boundary signature.  Consequently, an operator map keeps its boundary
indices by stating \tnkey{boundary=open}---or \tnkey{west=open} for a single
side---while \tnkey{boundary=none} explicitly declares the default closed
behaviour.  The layout grid places the tensor nodes; it does not assume that
every perimeter site carries a dangling index.  That is why a quantum circuit
pyramid or a single four-legged junction never sprouts unwanted legs.

The rest of the boundary alphabet is equally intuitive: use
\tnkey{boundary=periodic} to trace a row back into itself (periodic boundary
conditions), and use \tnkey{west=cup} or \tnkey{east=cup} to connect adjacent
layers (such as contracting a ket with a bra).  Notice that two closures may
happen to have the same number of open ends and yet represent entirely
different mathematical operations!

\subsection{Sandwiching operators: ket, mid, and bra}

When calculating local expectation values $\langle\psi|O_1O_2|\psi\rangle$ or
sandwiching an MPO between ket and bra states, setting
\tnkey{rows=}\tnval{\{ket,op,bra\}} automatically establishes the three-tier
layer geometry: vertical connections contract the physical indices between ket
and operator, and between operator and bra, while open horizontal bonds expose
the virtual boundary indices of the transfer operator:

\begin{tnexample}[
  formula={\sum_{s,s'}A^s\otimes O^{ss'}\otimes\bar A^{s'}},
  caption={an expectation-value window},
  index={The rows declare their roles.  Vertical connections contract physical
    indices; six horizontal stubs keep the window a map.},
  signature={kernel-boundary|signature=open:e, open:e, open:e, open:w, open:w, open:w}]
% Formula: sum_{s,s'} A^s tensor O^{ss'} tensor conjugate(A^{s'}).
% Labels: automatic placement stands each name on its atom's free face --
% north for the ket row, south for the bra row.
\begin{tenkz}[rows={ket,op,bra}, cols=2, west=open, east=open]
  \tn{A} & \tn{A} \\
  \tn[skin=mpo]{O} & \tn[skin=mpo]{O} \\
  \tn{$\overline{A}$} & \tn{$\overline{A}$}
\end{tenkz}
\end{tnexample}

\subsection{Grouping tensors without altering topology}

In coarse-graining schemes (such as block-spin renormalization, DMRG
site-blocking, or MERA layers), a bracket mark over a cell range (\tncmd{tnmark}
with \tnkey{form=bracket}) declares a brace or measured grouping over existing
tensors, while \tnval{skin=dots} declares a pass-through ellipsis cell for omitted sites.  Neither construct alters the underlying
contractions!  A wide single tensor node is appropriate only after your formula
has already replaced the run by a single blocked tensor.

\subsection{Semantic roles versus persistent species}

A good diagram distinguishes between structural roles and persistent species.
Use \tnkey{role=} for a tensor's fixed semantic role in an algorithm, such as
\tnval{operator} or an active site being optimized.  By contrast, declare
\tnkey{species=} at setup scope when your paper features a recurring family of
tensors (such as isometries $W$, unitary disentanglers $U$, or projectors $P$)
whose members should maintain a consistent hue across multiple figures.  Always
remember: labels distinguish objects of the same kind; color should never be the
sole carrier of identity.  A role may modify visual style, but never network
topology.

\subsection{Labels on external legs}

An open leg is a wire like any other, and it carries an accessible name.  The
boundary policy names its legs after the side and the row or column they
depart from---\tnval{open-west-1}, \tnval{open-south-col-3}---while the
\tnkey{physical=} policy names each leg after its face and home
cell---\tnval{leg-n-1-1} and \tnval{leg-s-2-3}.  Similarly, a user-authored
wire takes whatever name its \tncmd{tnwire} declares.  You can address a
fractional station along that named wire to place a label or bead with complete
precision:

\begin{Verbatim}[fontsize=\small,frame=leftline]
\begin{tenkz}[rows={wire}, cols=2, west=open, east=open]
  \tn{A} & \tn{B}
  \tnmark[form=label, label pos=90]{on open-west-1 0.5}{$\alpha$}
\end{tenkz}
\end{Verbatim}

The fractional station is measured along the path the wire follows.  A leg has
one end anchored to a glyph and one free tip; fraction zero is always the end
where the wire began.  A policy leg runs outward from the glyph, so \tnval{on
leg-n-1-1 0} lies on the north face of the site in row~1, column~1, while
\tnval{on leg-n-1-1 1} reaches its outer tip.  Declaring a row's legs once with
\tnkey{physical=} is therefore especially convenient: the very same name
serves both for line crossings and for label placement.

\subsection{Highlighting specific bonds}

A lattice draws its bonds automatically from its row and column policies, and
every one of them is typeset as a standard black contraction.  When a figure
needs to highlight one specific edge---an entanglement cut across a bipartition
$A:B$, an SVD Schmidt spectrum cut, or a Hamiltonian interaction term $h_{i,j}$
on a particular link---you can restate that bond directly in the body.  An
index wire declared between two adjacent cells becomes that pair's bond: \pkg{}
creates no duplicate wire beneath it, and the wire's species, stroke, and route
become the bond's own:

\begin{Verbatim}[fontsize=\small,frame=leftline]
\tndeclare{species}{blocked-edge}{hue=source:red!65!black}
\begin{tenkz}[rows={wire,wire}, cols=3]
  \tn{} & \tn{} & \tn{}\\
  \tn{} & \tn{} & \tn{}
  \tnwire[species=blocked-edge]{(1,1)}{(1,2)}
\end{tenkz}
\end{Verbatim}

Because this restatement represents the same mathematical contraction, the
count of internal bonds and the external boundary signature remain unchanged;
only the visual ink reflects your styling.  You can address the pair by cell
coordinates as above, or by typed ports (\tnval{a.0} and \tnval{b.180}) on
named atoms.  (Specifying \tnkey{bonds=none} and redrawing every bond by hand is
needlessly tedious and completely unnecessary!)  A travelling string is not a
restatement: it carries an operator index, so it is drawn cleanly over the
lattice without retiring the underlying bonds.

\subsection{Directing physical indices}

In tensor-network theory, each port carries a defined index type: virtual
(mediating quantum entanglement between neighboring tensors) or physical
(spanning the local Hilbert space of a site).  The \tnkey{ports=} key types
each perimeter face individually, so \tnval{0:physical} directs a physical
index eastward just as naturally as \tnval{0:virtual} directs a virtual one.  A
single-tensor linear map types its opposing faces accordingly:

\begin{Verbatim}[fontsize=\small,frame=leftline]
\begin{tenkz}[rows={wire}, cols=1, bonds=none]
  \tn[at=(1,1), skin=box, ports={180:virtual:V, 0:physical:W}]{A}
\end{tenkz}
\end{Verbatim}

The \tnkey{physical=} key is a picture-wide policy, not the sole way to create
physical legs: it equips every cell atom with an outward physical port in the
frame's natural direction.  Both mechanisms complement each other harmoniously.
Picture policy shines on uniform rows: declare it once, and every site receives
its physical leg, with any rare exception opting out via \tnkey{physical=none}.
Conversely, on a sparse row where only a single site among many carries a
physical index, it is far cleaner to declare the port on that individual atom:

\begin{Verbatim}[fontsize=\small,frame=leftline]
\begin{tenkz}[rows={wire}, cols=5]
  \tn{} & \tn{} & \tn[ports={180:virtual, 0:virtual, 90:physical:$i$}]{} &
  \tn{} & \tn{}
\end{tenkz}
\end{Verbatim}

\subsection{Physical indices in projected sheets}

A PEPS tensor has five index directions: four virtual bonds mediating
entanglement within the 2D lattice plane, and one physical index projecting out
of the plane into the local Hilbert space.  The four numeric ports below follow
the projected planar axes, while the picture policy supplies the upward
transverse direction:

\begin{Verbatim}[fontsize=\small,frame=leftline]
\begin{tenkz}[rows={wire,wire,wire}, cols=3,
               frame=plane, bonds=none, physical=up]
  \tn[at=(2,2),
      ports={0:virtual,90:virtual,180:virtual,270:virtual}]{A}
\end{tenkz}
\end{Verbatim}

Do not attempt to add an artificial fifth numeric angle to straighten the
transverse leg!  A numeric angle always lives within the plane of the sheet,
whereas \tnkey{physical=up} follows the plane's independent transverse normal.

Remember also that physical indices belong to lattice sites defined by frame
addresses.  A mark positioned at a midpoint, along a wire, or at a crossing is a
geometric annotation, not a lattice site; hence, picture policies never sprout
physical legs from marks.  If an annotation represents an additional tensor with
its own physical index, simply declare that port explicitly via \tnkey{ports=}.

\subsection{Fusion trees}

When working with symmetric tensor networks (such as $SU(2)$ spin-rotation
symmetry or abelian $U(1)$ particle conservation), tensors decompose via the
Wigner-Eckart theorem into structural Clebsch-Gordan coefficients (represented
by fusion trees) and reduced matrix elements.  Use \tncmd{tntree} when you need
to draw parenthesized fusion words and tree contractions.  Commutative diagrams,
by contrast, compose morphisms between mathematical objects rather than
contracting tensor indices; they belong to the excellent \textsf{tikz-cd}
package, outside the scope of \pkg{}.  A \tncmd{tntree} atom is a
self-contained box that embeds gracefully inside any \textsf{tikz-cd} cell
whenever the two worlds meet.

\subsection{Inline diagrams}

A \pkg{} tensor network enters surrounding \TeX{} as a displayed mathematical
term.  There is no special ``inline'' key: inline mathematical alignment
belongs to the ambient equation or text scope, not to an internal property of
individual diagram records.