% \iffalse meta-comment
%
% matrixdiagrams.dtx
% Copyright (C) 2026 Kyle Monette
% https://github.com/kylemonette/matrix-diagrams
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%   https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Kyle Monette.
%
% This work consists of the files matrixdiagrams.dtx and
% matrixdiagrams.ins and the derived file matrixdiagrams.sty.
%
% \fi
%
% \iffalse
%<*package>
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{matrixdiagrams}[2026/08/15 v1.0 Matrix diagrams]
%</package>
%
%<*driver>
\documentclass[11pt,english]{article}
\usepackage{babel}
\usepackage{amsmath}
\usepackage{booktabs}
\usepackage{geometry}
\geometry{margin=0.8in}
\usepackage{doc}
\usepackage{matrixdiagrams}
\usepackage{showexpl}
\lstset{
  basicstyle=\ttfamily\small,
  breaklines=true,
  breakatwhitespace=false,
  columns=fullflexible,
  showstringspaces=false,
  explpreset={pos=b,numbers=none,rframe={},width=\linewidth}
}
\usepackage{hyperref}
\hypersetup{colorlinks=true}
\usepackage{tabularx}
\title{\texttt{matrixdiagrams.sty}}
\author{Kyle Monette (\href{https://kylemonette.github.io}{kylemonette.github.io}) \\
  \small Released under the LaTeX Project Public License (LPPL), version 1.3c}
\date{\today}

\begin{document}
\maketitle

\section*{Overview}

\texttt{matrixdiagrams} is a LaTeX package that draws schematic matrix diagrams in TikZ for the purposes of illustrating structure in matrices.
All diagrams use
\verb|\matrixdiagram[scale][aspect]{content}|, where \texttt{content} is a
sequence of small drawing commands (\verb|\mdFill|, \verb|\mdLabel|,
\verb|\mdDiagBand|, \ldots) working in a normalized coordinate system that
automatically adapts to the diagram's scale and aspect ratio.
This easily allows one to visualize structure in matrices such as bidiagonal, tridiagonal, upper triangular, and Hessenberg varieties.
The sections
below give a quick reference followed by every command with a runnable
example.

\tableofcontents

\section{Quick Reference}

\noindent
\begin{tabularx}{\linewidth}{lX}
\toprule
\verb|\matrixdiagram[s][a]{c}|
  & Main command. \\
  & \texttt{s} = scale (default 1), \texttt{a} = aspect (default 1). \\
  & Position args below are fractions $x,y \in [0,1]$, any aspect. \\
\midrule
\verb|\mdDiag|
  & Main diagonal \\
\verb|\mdDiagBand|
  & Tridiagonal band. \\
\verb|\mdDiagBandN{n}|
  & $n$-diagonal band ($n$ odd). \\
\verb|\mdBidiagUpper|
  & Main diagonal + super-diagonal. \\
\verb|\mdBidiagLower|
  & Main diagonal + sub-diagonal. \\
\verb|\mdHessenberg|
  & Upper-triangular outline + sub-diagonal. \\
\verb|\mdHessenberg[color]|
  & Same with filled interior. \\
\midrule
\verb|\mdDiagFrom{x1}{y1}{x2}{y2}|
  & Main diagonal from $(x_1,y_1)$ to $(x_2,y_2)$ \\
\verb|\mdDiagBandFrom{x1}{y1}{x2}{y2}|
  & Tridiagonal band, clipped. \\
\verb|\mdDiagBandNFrom{n}{x1}{y1}{x2}{y2}|
  & $n$-diagonal band, clipped. \\
\midrule
\verb|\mdFill[col]{x0}{y0}{x1}{y1}|
  & Filled rectangle. Default color \texttt{gray!20}. \\
\verb|\mdVLine{x}|
  & Vertical line, full height. \\
\verb|\mdHLine{y}|
  & Horizontal line, full width, at fractional height $y$. \\
\midrule
\verb|\mdLabel{x}{y}{text}|
  & Math-mode label at $(x,y)$. \\
\verb|\mdLabel[color]{x}{y}{text}|
  & Same with filled node label\\
\verb|\mdLabelRaw{x}{y}{text}|
  & Raw-text label at $(x,y)$. \\
\verb|\mdLabelCenter{text}|
  & Math label at center (any aspect). \\
\midrule
\verb|\mdSpike{x}{y}{dir}|
  & L-corner; \texttt{dir} $\in$ \{\texttt{tl, tr, bl, br}\}. \\
\verb|\mdBlank|
  & Empty content (brackets only). \\
\verb|\mdH|
  & Expands to the aspect value, i.e.\ the top edge's $y$-coordinate. \\
\bottomrule
\end{tabularx}


\section{Main command}

\noindent \texttt{\textbackslash matrixdiagram[scale][aspect]\{content\}}

Inside \texttt{content}, the raw TikZ canvas runs $x \in [0,1]$ and
$y \in [0,\text{aspect}]$: \texttt{aspect} is literally the $y$-coordinate of
the top edge, and \verb|\mdH| expands to that value, so
\texttt{(0,\textbackslash mdH)}--\texttt{(1,\textbackslash mdH)} is always the
top edge, whatever the aspect. Every built-in positioning command
(\verb|\mdFill|, \verb|\mdLabel|, \verb|\mdLabelRaw|, \verb|\mdHLine|,
\verb|\mdSpike|, and the \texttt{...From} diagonal variants) instead takes
$y$ as a plain fraction of the height, $y \in [0,1]$, and multiplies by
\verb|\mdH| internally --- so \texttt{y=0.5} always means mid-height,
regardless of aspect. Raw \texttt{\textbackslash draw} commands written
directly inside \texttt{content} see the unscaled canvas, so they must
reference \verb|\mdH| themselves, e.g.\ \texttt{(1,\textbackslash mdH)} for
the top-right corner.

\subsection{Scale (aspect = 1)}

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[1]{\mdBlank}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[2]{\mdBlank}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdBlank}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[4]{\mdBlank}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[5]{\mdBlank}$
\end{LTXexample}
\end{minipage}
\begin{minipage}[t]{0.31\linewidth}
\,
\end{minipage} 


\subsection{Aspect ratio (scale = 3)}

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][0.5]{
  \mdBlank
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][1]{
  \mdBlank
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][1.5]{
  \mdBlank
}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdBlank
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][3]{
  \mdBlank
}$
\end{LTXexample}
\end{minipage}
\begin{minipage}[t]{0.31\linewidth}
\,
\end{minipage} 


\section{Diagonal commands}

\subsection{\texttt{\textbackslash mdDiag} --- main diagonal}

The single diagonal line from $(0,H)$ to $(1,0)$.

\begin{LTXexample}[pos=l,width=0.3\linewidth]
$\matrixdiagram[3]{\mdDiag} \matrixdiagram[3][2]{\mdDiag}$
\end{LTXexample}

\subsection{\texttt{\textbackslash mdDiagBand} --- tridiagonal band}

Three parallel anti-diagonals with spacing $d = 0.1$.

\begin{LTXexample}[pos=l,width=0.24\linewidth]
$\matrixdiagram[3]{\mdDiagBand} \matrixdiagram[3][2]{\mdDiagBand}$
\end{LTXexample}

\subsection{\texttt{\textbackslash mdDiagBandN\{n\}} --- variable band width}

$n = 3, 5, 7, 9$ (spacing fixed at $d=0.1$ per diagonal); \verb|\mdDiagBandN{3}|
is identical to \verb|\mdDiagBand|:

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdDiagBandN{3}}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdDiagBandN{5}}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdDiagBandN{7}}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdDiagBandN{9}}$
\end{LTXexample}
\end{minipage}

\vspace{1.5em}

\noindent With aspect $= 2$:

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{\mdDiagBandN{3}}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{\mdDiagBandN{5}}$
\end{LTXexample}
\end{minipage}


% \begin{LTXexample}
% $\matrixdiagram[3][2]{\mdDiagBandN{7}}$
% \end{LTXexample}


\section{Bidiagonal commands}

\subsection{\texttt{\textbackslash mdBidiagUpper} --- main + super-diagonal}

Main diagonal plus a single super-diagonal, offset $d=0.1$ toward the top-right.

\begin{LTXexample}[pos=l,width=0.2\linewidth]
$\matrixdiagram[3]{\mdBidiagUpper} \matrixdiagram[3][2]{\mdBidiagUpper}$
\end{LTXexample}

\subsection{\texttt{\textbackslash mdBidiagLower} --- main + sub-diagonal}

Main diagonal plus a single sub-diagonal, offset $d=0.1$ toward the bottom-left.

\begin{LTXexample}[pos=l,width=0.2\linewidth]
$\matrixdiagram[3]{\mdBidiagLower} \matrixdiagram[3][2]{\mdBidiagLower}$
\end{LTXexample}

\section{Hessenberg command}

\subsection{\texttt{\textbackslash mdHessenberg} --- outline only (default)}

Upper-triangular outline $(0,H)\to(1,H)\to(1,0)$ plus one sub-diagonal.

\begin{LTXexample}[pos=l,width=0.24\linewidth]
$\matrixdiagram[3]{\mdHessenberg} \matrixdiagram[3][2]{\mdHessenberg}$
\end{LTXexample}

\subsection{\texttt{\textbackslash mdHessenberg[color]} --- with fill}

\noindent
\begin{minipage}[t]{0.49\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdHessenberg[gray!15]}$
\end{LTXexample}
\end{minipage}
\hfill
\begin{minipage}[t]{0.5\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdHessenberg[blue!15]}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.49\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdHessenberg[green!20]}$
\end{LTXexample}
\end{minipage}
\hfill
\begin{minipage}[t]{0.5\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{\mdHessenberg[orange!20]}$
\end{LTXexample}
\end{minipage}


\section{Fill and line commands}

\subsection{\texttt{\textbackslash mdFill[color]\{x0\}\{y0\}\{x1\}\{y1\}}}

The default color is \texttt{gray!20}:

\noindent
\begin{minipage}[t]{0.49\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[green!30]{0}{0.5}{0.5}{1}
}$
\end{LTXexample}
\end{minipage}
\hfill
\begin{minipage}[t]{0.49\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[blue!20]{0.5}{0.5}{1}{1}
}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.49\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[red!20]{0}{0}{0.5}{0.5}
}$
\end{LTXexample}
\end{minipage}
\hfill
\begin{minipage}[t]{0.49\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill{0}{0}{1}{1}
}$
\end{LTXexample}
\end{minipage}





\vspace{1.5em}

\noindent With aspect $= 2$ ($y$ is still a fraction of the height, in $[0,1]$):

\noindent

\begin{LTXexample}[pos=l,width=0.3\linewidth]
$\matrixdiagram[3][2]{\mdFill[green!25]{0}{0.5}{0.5}{1}}$
\end{LTXexample}

\begin{LTXexample}[pos=l,width=0.3\linewidth]
$\matrixdiagram[3][2]{\mdFill[blue!15]{0}{0}{1}{0.5}}$
\end{LTXexample}

% \begin{LTXexample}
% $\matrixdiagram[3][2]{\mdFill[gray!15]{0}{0}{0.75}{1}}$
% \end{LTXexample}


\subsection{\texttt{\textbackslash mdVLine\{x\}} and \texttt{\textbackslash mdHLine\{y\}}}

\verb|\mdVLine{x}| runs the full height at $x\in[0,1]$;
\verb|\mdHLine{y}| runs the full width at height $y\in[0,1]$.

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdVLine{0.5}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdHLine{0.5}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdVLine{0.5}
  \mdHLine{0.5}
}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdVLine{0.33}
  \mdVLine{0.67}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdHLine{0.33}
  \mdHLine{0.67}
}$
\end{LTXexample}
\end{minipage}
\hfill
\begin{minipage}[t]{0.31\linewidth}
\,
\end{minipage} 


% \vspace{1.5em}

% \noindent With aspect $= 2$:

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdVLine{0.5}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdHLine{0.5}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdVLine{0.5}
  \mdHLine{0.5}
}$
\end{LTXexample}
\end{minipage}

\vspace{2em}

\noindent Combined with fills (block partitioning):

\begin{LTXexample}[pos=l,width=0.4\linewidth]
$\matrixdiagram[3]{
  \mdFill[blue!15]{0}{0.5}{0.5}{1}
  \mdFill[green!15]{0.5}{0}{1}{0.5}
  \mdVLine{0.5}
  \mdHLine{0.5}
  \mdLabel{0.25}{0.75}{A}
  \mdLabel{0.75}{0.25}{D}
}$
\end{LTXexample}

\begin{LTXexample}[pos=l,width=0.4\linewidth]
$\matrixdiagram[3][2]{
  \mdFill[gray!15]{0}{0}{0.75}{1}
  \mdVLine{0.75}
  \mdLabel{0.375}{0.5}{A}
  \mdLabel{0.875}{0.5}{b}
}$
\end{LTXexample}

\section{Label commands}

\subsection{\texttt{\textbackslash mdLabel\{x\}\{y\}\{text\}} --- math mode}

Places \texttt{text} in math mode at $(x,y)$; the optional first argument
fills the label's background node with that color.

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdLabel{0.2}{0.5}{A}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdLabel[red!20]{0.5}{0.5}{Q^T}
}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdLabel{0.5}{0.5}{\Sigma}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdDiagBand
  \mdLabel{0.25}{0.2}{T}
}$
\end{LTXexample}
\end{minipage}

\subsection{\texttt{\textbackslash mdLabelCenter\{text\}} --- always centered}

Automatically placed at $(0.5,\,H/2)$ regardless of aspect ratio:

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][1]{
  \mdLabelCenter{Q}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdLabelCenter{Q}
}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][3]{
  \mdLabelCenter{Q}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][0.5]{
  \mdLabelCenter{Q}
}$
\end{LTXexample}
\end{minipage}

\subsection{\texttt{\textbackslash mdLabelRaw\{x\}\{y\}\{text\}} --- raw text}

Same placement as \texttt{\textbackslash mdLabel}, but \texttt{text} is
typeset as-is instead of in math mode --- useful for plain words like
``dense'' or for text that already contains its own \texttt{\$...\$}.

\begin{LTXexample}[pos=l,width=0.3\linewidth]
$\matrixdiagram[3]{
  \mdLabelRaw{0.5}{0.5}{dense}
}
\matrixdiagram[3]{
  \mdLabelRaw{0.5}{0.5}{$\approx 0$}
}$
\end{LTXexample}

\section{Spike commands}

\verb|\mdSpike{x}{y}{dir}| draws an L-shaped corner at $(x,y)$.
\texttt{tl} (top+left),\ \texttt{tr} (top+right),\ \texttt{bl} (bottom+left),\ \texttt{br} (bottom+right).
Optionally, add a color fill via \verb|\mdSpike[color]{x}{y}{dir}|.

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdSpike{0.5}{0.5}{tl}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdSpike{0.5}{0.5}{tr}
}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdSpike{0.5}{0.5}{bl}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdSpike{0.5}{0.5}{br}
}$
\end{LTXexample}
\end{minipage}

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[blue!15]{0.5}{0.5}{1}{1}
  \mdSpike{0.5}{0.5}{tr}
}$
\end{LTXexample}
\end{minipage}

% \noindent
% \begin{minipage}[t]{0.48\linewidth}
% \begin{LTXexample}
% $\matrixdiagram[3]{
%   \mdFill[red!15]{0}{0}{0.5}{0.5}
%   \mdSpike{0.5}{0.5}{bl}
% }$
% \end{LTXexample}
% \end{minipage}\hfill
% \begin{minipage}[t]{0.48\linewidth}
% \begin{LTXexample}
% $\matrixdiagram[3]{
%   \mdFill[orange!20]{0.5}{0}{1}{0.5}
%   \mdSpike{0.5}{0.5}{br}
% }$
% \end{LTXexample}
% \end{minipage}

\vspace{1.5em}

\noindent With aspect $= 2$, corner at mid-height $(0.5, 0.5)$:

\noindent
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdFill[blue!15]{0.5}{0.5}{1}{1}
  \mdSpike{0.5}{0.5}{tr}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.31\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdFill[red!15]{0}{0}{0.5}{0.5}
  \mdSpike{0.5}{0.5}{bl}
}$
\end{LTXexample}
\end{minipage}

\section{Clipped diagonal commands}

The \texttt{...From} variants force the diagonal band from $[x_1,y_1]$ to $[x_2,y_2]$.
Always pair with \verb|\mdSpike| at the same corner.

\subsection{\texttt{\textbackslash mdDiagFrom\{x1\}\{y1\}\{x2\}\{y2\}}}

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagFrom{0.5}{0.5}{1}{0}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagFrom{0.5}{0.5}{1}{0}
}$
\end{LTXexample}
\end{minipage}

\subsection{\texttt{\textbackslash mdDiagBandFrom\{x1\}\{y1\}\{x2\}\{y2\}}}

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagBandFrom{0.5}{0.5}{1}{0}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3][2]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagBandFrom{0.5}{0.5}{1}{0}
}$
\end{LTXexample}
\end{minipage}

\subsection{\texttt{\textbackslash mdDiagBandNFrom\{n\}\{x1\}\{y1\}\{x2\}\{y2\}}}

$n = 3, 5, 7$:

\noindent
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagBandNFrom{3}{0.5}{0.5}{1}{0}
}$
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\linewidth}
\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagBandNFrom{5}{0.5}{0.5}{1}{0}
}$
\end{LTXexample}
\end{minipage}


\begin{LTXexample}
$\matrixdiagram[3]{
  \mdFill[green!20]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagBandNFrom{7}{0.5}{0.5}{1}{0}
}$
\end{LTXexample}

\section{Realistic equations}

\subsection{QR decomposition: $A = QR$}

\begin{LTXexample}[pos=l,width=0.5\linewidth]
$\matrixdiagram[3][2]{\mdLabelCenter{A}}
=
\matrixdiagram[3][2]{\mdLabelCenter{Q}}
\matrixdiagram[3]{\mdLabelCenter{R}}$
\end{LTXexample}

\subsection{Bidiagonalization: $A = U B V^T$}

\begin{LTXexample}[pos=l,width=0.5\linewidth]
$\matrixdiagram[3]{\mdLabelCenter{A}}
=
\matrixdiagram[3]{\mdLabelCenter{U}}
\matrixdiagram[3]{\mdBidiagUpper}
\matrixdiagram[3]{\mdLabelCenter{V^T}}$
\end{LTXexample}

\subsection{Similarity: $Q^T T_m Q = \widetilde{T}_m$}

\begin{LTXexample}[pos=l,width=0.5\textwidth]
$\matrixdiagram[3]{\mdLabelCenter{Q^T}}
\matrixdiagram[3]{
  \mdDiagBand
  \mdLabel{0.25}{0.15}{T_m}
}
\matrixdiagram[3]{\mdLabelCenter{Q}}
=
\matrixdiagram[3]{
  \mdFill[green!25]{0}{0.5}{0.5}{1}
  \mdSpike{0.5}{0.5}{tl}
  \mdDiagBandFrom{0.5}{0.5}{1}{0}
  \mdLabel{0.3}{0.12}{\widetilde{T}_m}
}$
\end{LTXexample}

\subsection{Hessenberg reduction: $Q^T A Q = H$}

\begin{LTXexample}[pos=l,width=0.5\textwidth]
$\matrixdiagram[3]{\mdLabelCenter{Q^T}}
\matrixdiagram[3]{\mdLabelCenter{A}}
\matrixdiagram[3]{\mdLabelCenter{Q}}
=
\matrixdiagram[3]{
  \mdHessenberg
  \mdLabel{0.7}{0.55}{H}
}$
\end{LTXexample}

\subsection{Schur complement structure}

\begin{LTXexample}[pos=l,width=0.5\textwidth]
$\matrixdiagram[4]{
  \mdFill[blue!10]{0}{0.5}{0.5}{1}
  \mdFill[green!10]{0.5}{0}{1}{0.5}
  \mdFill[gray!10]{0.5}{0.5}{1}{1}
  \mdVLine{0.5}
  \mdHLine{0.5}
  \mdLabel{0.25}{0.75}{A}
  \mdLabel{0.75}{0.75}{B}
  \mdLabel{0.25}{0.25}{C}
  \mdLabel{0.75}{0.25}{S}
}$
\end{LTXexample}



\DocInput{matrixdiagrams.dtx}
\end{document}
%</driver>
% \fi
%
% \section{Implementation}
%
%    \begin{macrocode}
%<*package>
\RequirePackage{tikz}
\RequirePackage{xparse}
\RequirePackage{calc}

\usetikzlibrary{arrows.meta, bending, matrix, positioning, calc, arrows}

%% -----------------------------------------------------------------------
%% Internal dimensions
%% -----------------------------------------------------------------------
\newdimen\md@bracewidth % length of the horizontal tick at each bracket corner
\newdimen\md@innersep   % gap between the content and the brackets
\newdimen\md@baseunit   % size of one coordinate unit at scale=1
\newdimen\md@hsep       % margin added left and right of every \matrixdiagram
\md@bracewidth=3pt
\md@innersep=2pt
\md@baseunit=0.5cm
\md@hsep=3pt

%% \md@H: current aspect ratio = y-coordinate of top edge. Default 1.
\def\md@H{1}
%% \mdH: user-facing alias usable inside content arguments
\def\mdH{\md@H}

%% \md@bandstep: spacing between adjacent diagonals in a band, in x-units.
\def\md@bandstep{0.1}

%% -----------------------------------------------------------------------
%% Core drawing macro: \md@draw@box{scale}{aspect}{content}
%% -----------------------------------------------------------------------
\newcommand{\md@draw@box}[3]{%
  \def\md@H{#2}%
  \kern\md@hsep
  \vcenter{\hbox{%
    \tikz[baseline={(MDNODO.base)}]{%
      \node[inner sep=\md@innersep](MDNODO){%
        \tikz[baseline={($(MDcenter)-(0.25em,0.25em)$)},
              x={#1*\md@baseunit}, y={#1*\md@baseunit}]{%
          \coordinate (MDcenter) at (0.5,{#2*0.5});
          \draw[draw=none] (0,0) rectangle (1,#2);
          #3
        }%
      };
      \draw[thick]
        (MDNODO.north west)+(\md@bracewidth,0)
        -- (MDNODO.north west)
        -- (MDNODO.south west)
        -- ($(MDNODO.south west)+(\md@bracewidth,0)$);
      \draw[thick]
        (MDNODO.north east)+(-\md@bracewidth,0)
        -- (MDNODO.north east)
        -- (MDNODO.south east)
        -- ($(MDNODO.south east)+(-\md@bracewidth,0)$);
    }%
  }}%
  \kern\md@hsep
}

%% -----------------------------------------------------------------------
%% \matrixdiagram[scale][aspect]{content}
%% -----------------------------------------------------------------------
\NewDocumentCommand{\matrixdiagram}{O{1} O{1} m}{%
  \md@draw@box{#1}{#2}{#3}%
}

%% -----------------------------------------------------------------------
%% Content commands — all use \md@H for the top edge
%% -----------------------------------------------------------------------

%% \md@superdiag{k} — super-diagonal offset by k*\md@bandstep
\newcommand{\md@superdiag}[1]{%
  \draw[thick] ({#1*\md@bandstep},\md@H) -- (1,{#1*\md@bandstep*\md@H});%
}
%% \md@subdiag{k} — sub-diagonal offset by k*\md@bandstep
\newcommand{\md@subdiag}[1]{%
  \draw[thick] (0,{\md@H-#1*\md@bandstep*\md@H}) -- ({1-#1*\md@bandstep},0);%
}

%% \mdDiagBandN{n} — n-diagonal band (n odd), spacing \md@bandstep between diagonals.
%% n=1 draws only the main diagonal. Max useful n is 9.
\newcommand{\mdDiagBandN}[1]{%
  \draw[thick] (0,\md@H) -- (1,0);%
  \pgfmathtruncatemacro{\md@half}{int((#1-1)/2)}%
  \ifnum\md@half>0
    \foreach \md@k in {1,...,\md@half}{%
      \md@subdiag{\md@k}%
      \md@superdiag{\md@k}%
    }%
  \fi
}

%% \mdDiag — main anti-diagonal (top-left to bottom-right)
\newcommand{\mdDiag}{\mdDiagBandN{1}}
\let\mdIdentity\mdDiag

%% \mdDiagBand — tridiagonal band
\newcommand{\mdDiagBand}{\mdDiagBandN{3}}

%% \mdFill[color]{x0}{y0}{x1}{y1} — y0,y1 are fractions of the height, in [0,1]
\newcommand{\mdFill}[5][gray!20]{%
  \fill[#1] (#2,{#3*\md@H}) rectangle (#4,{#5*\md@H});%
}

%% \mdLabel[fill]{x}{y}{text} — math-mode label, optional node fill color; y in [0,1]
\newcommand{\mdLabel}[4][none]{%
  \node[fill=#1] at (#2,{#3*\md@H}) {$#4$};%
}

%% \mdLabelRaw[fill]{x}{y}{text} — raw text label, optional node fill color; y in [0,1]
\newcommand{\mdLabelRaw}[4][none]{%
  \node[fill=#1] at (#2,{#3*\md@H}) {#4};%
}

%% \mdLabelCenter{text} — math label at the center (x=0.5, y=H/2)
\newcommand{\mdLabelCenter}[1]{%
  \node at (0.5,{0.5*\md@H}) {$#1$};%
}

%% \mdVLine{x} — full-height vertical line (0 to H)
\newcommand{\mdVLine}[1]{%
  \draw[thick] (#1,0) -- (#1,\md@H);%
}

%% \mdHLine{y} — full-width horizontal line; y is a fraction of the height, in [0,1]
\newcommand{\mdHLine}[1]{%
  \draw[thick] (0,{#1*\md@H}) -- (1,{#1*\md@H});%
}

%% -----------------------------------------------------------------------
%% Clipped diagonal commands
%% Draw diagonal bands clipped to the rectangle (x1,y1)--(x2,y2),
%% where (x1,y1) is the bottom-left corner and (x2,y2) is the top-right.
%%
%% \mdDiagFrom{x1}{y1}{x2}{y2}
%% \mdDiagBandFrom{x1}{y1}{x2}{y2}
%% \mdDiagBandNFrom{n}{x1}{y1}{x2}{y2}
%%   n=1 draws only the main diagonal (no off-diagonals).
%%
%% Typical spike usage — clip to the region outside the block:
%%   \mdSpike{0.5}{0.5}{tl}
%%   \mdDiagBandFrom{0.5}{0}{1}{0.5}    % bottom-left=(0.5,0), top-right=(1,0.5)
%% -----------------------------------------------------------------------

%% \mdDiagBandNFrom{n}{x1}{y1}{x2}{y2} — y1,y2 are fractions of the height, in [0,1]
\newcommand{\mdDiagBandNFrom}[5]{%
  \begin{scope}%
    \clip (#2,{#3*\md@H}) rectangle (#4,{#5*\md@H});%
    \mdDiagBandN{#1}%
  \end{scope}%
}

%% \mdDiagFrom{x1}{y1}{x2}{y2}
\newcommand{\mdDiagFrom}[4]{\mdDiagBandNFrom{1}{#1}{#2}{#3}{#4}}

%% \mdDiagBandFrom{x1}{y1}{x2}{y2}
\newcommand{\mdDiagBandFrom}[4]{\mdDiagBandNFrom{3}{#1}{#2}{#3}{#4}}

%% -----------------------------------------------------------------------
%% Spike commands — L-shaped block boundary corners
%%   tl: corner at (x,y), arms to top (y=H) and left (x=0)
%%   tr: corner at (x,y), arms to top (y=H) and right (x=1)
%%   bl: corner at (x,y), arms to bottom (y=0) and left (x=0)
%%   br: corner at (x,y), arms to bottom (y=0) and right (x=1)
%% -----------------------------------------------------------------------
\def\md@tl{tl}\def\md@tr{tr}\def\md@bl{bl}\def\md@br{br}

%% \mdSpike{x}{y}{dir} — y is a fraction of the height, in [0,1]
\newcommand{\mdSpike}[3]{%
  \def\md@spikedir{#3}%
  \ifx\md@spikedir\md@tl \draw[thick] (#1,\md@H) -- (#1,{#2*\md@H}) -- (0,{#2*\md@H});%
  \else\ifx\md@spikedir\md@tr \draw[thick] (#1,\md@H) -- (#1,{#2*\md@H}) -- (1,{#2*\md@H});%
  \else\ifx\md@spikedir\md@bl \draw[thick] (#1,0) -- (#1,{#2*\md@H}) -- (0,{#2*\md@H});%
  \else\ifx\md@spikedir\md@br \draw[thick] (#1,0) -- (#1,{#2*\md@H}) -- (1,{#2*\md@H});%
  \fi\fi\fi\fi
}

%% -----------------------------------------------------------------------
%% Bidiagonal commands
%%   upper: main diagonal + one super-diagonal
%%   lower: main diagonal + one sub-diagonal
%% -----------------------------------------------------------------------

%% \mdBidiagUpper — main diagonal + super-diagonal
\newcommand{\mdBidiagUpper}{%
  \draw[thick] (0,\md@H) -- (1,0);%
  \md@superdiag{1}%
}

%% \mdBidiagLower — main diagonal + sub-diagonal
\newcommand{\mdBidiagLower}{%
  \draw[thick] (0,\md@H) -- (1,0);%
  \md@subdiag{1}%
}

%% -----------------------------------------------------------------------
%% Hessenberg command
%% \mdHessenberg[fillcolor]
%%   No argument: outline only (default).
%%   With color argument: filled triangle + outline.
%% -----------------------------------------------------------------------
\newcommand{\mdHessenberg}[1][none]{%
  \def\md@hessarg{#1}\def\md@hessnone{none}%
  \ifx\md@hessarg\md@hessnone
    \draw[thick] (0,\md@H) -- (1,\md@H) -- (1,0) -- (0,\md@H);%
  \else
    \fill[#1] (0,\md@H) -- (1,\md@H) -- (1,0) -- cycle;%
    \draw[thick] (0,\md@H) -- (1,\md@H) -- (1,0) -- (0,\md@H);%
  \fi
  \md@subdiag{1}%
}

%% \mdBlank — empty content (brackets only)
\newcommand{\mdBlank}{}
%</package>
%    \end{macrocode}
%
\endinput