% Installation and the public mental model.
\section{First Principles}\label{ch:install}

Welcome to \pkg{}!  The goal of this system is to make the creation of
tensor-network diagrams in \TeX{} as pleasant, natural, and mathematically
rigorous as typesetting ordinary formulas.  If you have ever tried to draw a
matrix product state or a tensor contraction by placing low-level coordinates
by hand, you know how quickly manual geometry obscures the algebraic meaning
of the network.  In \pkg{}, we declare the mathematics, and let \TeX{} draw the ink.

To begin, you need only load the package and declare your first network:

\begin{Verbatim}[fontsize=\small,frame=leftline]
\usepackage{tikz-tensor-networks}
\begin{tenkz}[cols=2, physical=up] \tn{A} & \tn{B} \end{tenkz}
\end{Verbatim}
which immediately produces the elementary two-site chain:
\begin{center}
  \begin{tenkz}[cols=2, physical=up] \tn{A} & \tn{B} \end{tenkz}
\end{center}


For a working repository checkout, simply add \tnfile{tex/tenkz/} to
your \texttt{TEXINPUTS} search path; for an archived article, ship
\tnfile{tikz-tensor-networks.sty} and its companion files beside the document source.
XeLaTeX is our reference engine, both for high-quality print output and for the
reproducible XDV-to-SVG web pipeline.

The golden rule of \pkg{} can be stated in a single sentence:

\begin{quote}\large
A picture chooses one layout; its options declare topology and policy; its
body declares atoms, connections, regions, and annotations.
\end{quote}

Whenever you encounter a \pkg{} picture---or sit down to write one of your
own---proceed in this natural order.  First, the environment establishes the
placement grammar.  Second, its optional arguments declare global facts and
policies shared by the entire picture.  Third, the commands within the body
declare the mathematical entities themselves; they describe the \emph{structure}
of the network, rather than giving imperative painting instructions.

Five grammatical classes span the entire public vocabulary: \emph{atoms};
\emph{connections and closures}; \emph{regions and annotations};
\emph{composition}; and \emph{setup and extension}.  A command introduces an
object belonging to one of these classes, while a key modifies the record being
declared.  This clean separation keeps the grammar delightfully compact and easy
to read directly from source.

Scoping in \pkg{} is completely explicit.  A declaration made via \tncmd{tnset}
applies to the whole document; an option on an environment applies to that
picture; an option on an atom applies to that single object; and a join or
side-policy option governs that particular connection.  Furthermore, a shared
key name retains exactly one value type and one meaning across every
environment where it appears.

Notice that open ink is genuine mathematical data: a matrix keeps its two
virtual indices, an operator channel keeps its input and output indices, and a
scalar keeps none at all.  Closing an uncontracted bond merely for aesthetic
``neatness'' would change the mathematical object itself!  To ensure that your
diagrams always say what they mean, \pkg{} writes a companion \tnfile{.tnlog}
audit stream during compilation, recording the resolved model and boundary
signature used for rendering.  The log also records the type of every port: a
contracted index carries its type in the record even though it strokes
identically on the page, so that physical contractions and virtual bonds stroke
alike without confusing the underlying physics.