%% orbitals-doc.tex -- user manual for the orbitals package
%% Compile with pdfLaTeX (twice).
\documentclass[11pt]{article}
\usepackage[a4paper,margin=2.6cm]{geometry}
\usepackage{orbitals}              % the package being documented
\usepackage{xcolor}
\usepackage{listings}
\usepackage{hyperref}
\hypersetup{colorlinks=true,linkcolor=blue!55!black,urlcolor=teal!60!black,
            pdftitle={The orbitals package},pdfauthor={Your Name}}

% ---- code listing style ----
\definecolor{codebg}{gray}{0.96}
\lstset{
  basicstyle=\ttfamily\small,
  backgroundcolor=\color{codebg},
  frame=single,framerule=0pt,
  xleftmargin=6pt,xrightmargin=6pt,
  breaklines=true,
  columns=fullflexible,
  keepspaces=true,
}
% show "code  ->  result" pairs
\newcommand{\result}{\par\smallskip\noindent\textit{Result:}\quad}

\title{\textbf{The \texttt{orbitals} package}\\[2pt]
  \large Atomic subshell / orbital-box diagrams with automatic electron filling}
\author{Faris Hameed\\\small\texttt{classsec81@gmail.com}}
\date{Version 1.0\quad--\quad 2026/05/24}

\begin{document}
\maketitle
\hrule
\begin{abstract}
\noindent
\texttt{orbitals} draws the familiar ``box-and-arrow'' notation for atomic
subshells ($s$, $p$, $d$, $f$). You supply only the principal quantum number,
the subshell type and the number of electrons; the package places the
electrons automatically following \emph{Hund's rule} (maximum multiplicity)
and the \emph{Pauli principle}. It can draw a single subshell, a sequence of
subshells, a complete valence configuration with a noble-gas core, or an empty
transition-series template. Every diagram can be scaled and dropped inline
inside running text.
\end{abstract}
\hrule
\tableofcontents
\bigskip

% ============================================================
\section{Requirements and installation}
The package requires a TeX system no older than 2020 and the
\textsf{TikZ}/\textsf{pgf} bundle. It works with pdf\LaTeX, Xe\LaTeX{} and
Lua\LaTeX. \textsf{TikZ}, \textsf{xcolor} and \textsf{graphicx} are loaded
automatically; \textsf{mhchem} is loaded only if present (used by the optional
\verb|\chem| helper).

\paragraph{Manual installation.}
Place \texttt{orbitals.sty} either in the same folder as your document or in
your local \texttt{texmf} tree, e.g.
\begin{lstlisting}
TEXMFHOME/tex/latex/orbitals/orbitals.sty
\end{lstlisting}
then run \texttt{texhash} (for a TDS tree). Load it with:
\begin{lstlisting}
\usepackage{orbitals}
\end{lstlisting}

% ============================================================
\section{Quick start}
\begin{lstlisting}
\suborbital{4}{p}{5}
\end{lstlisting}
\result\suborbital{4}{p}{5}

\medskip
The three mandatory arguments are always \emph{principal quantum number},
\emph{subshell letter} and \emph{number of electrons}. The number of boxes is
chosen from the letter: $s\to1$, $p\to3$, $d\to5$, $f\to7$.

% ============================================================
\section{Command reference}

% ---------------------------------------------
\subsection{\texttt{\textbackslash suborbital} -- a single subshell}
\begin{lstlisting}
\suborbital[<scale>]{<n>}{<type>}{<electrons>}
\end{lstlisting}
The optional \texttt{<scale>} defaults to the global scale (Section
\ref{sec:scale}).

\begin{lstlisting}
\suborbital{4}{s}{1}   \suborbital{4}{s}{2}   \suborbital{3}{d}{6}
\end{lstlisting}
\result\suborbital{4}{s}{1}\quad\suborbital{4}{s}{2}\quad\suborbital{3}{d}{6}

% ---------------------------------------------
\subsection{\texttt{\textbackslash electronconfig} -- a sequence}
\begin{lstlisting}
\electronconfig[<scale>]{<n><type><electrons>, ...}
\end{lstlisting}
Each item uses the compact form \texttt{4p5} (one digit for $n$, one letter
for the type, the rest for the electron count, so \texttt{3d10} is fine).

\begin{lstlisting}
\electronconfig{3d6,4s2,4p0}
\end{lstlisting}
\result\electronconfig{3d6,4s2,4p0}

% ---------------------------------------------
\subsection{\texttt{\textbackslash atomconfig} -- configuration with a core}
\begin{lstlisting}
\atomconfig[<core>][<gap-cm>][<scale>]{<list>}
\end{lstlisting}
\begin{itemize}\itemsep2pt
  \item \texttt{<core>}: text of the noble-gas core (default: empty).
  \item \texttt{<gap-cm>}: horizontal space (in cm) reserved before the first
        box (default \texttt{1}).
  \item \texttt{<scale>}: scale factor (default: the global scale).
\end{itemize}
\textbf{Important:} if the core text itself contains a closing bracket
\verb|]| (as in \verb|[Ar]|), wrap the whole core in braces so \LaTeX{} does
not end the optional argument early:
\begin{lstlisting}
\atomconfig[{\textsubscript{18}[Ar]}][1.2]{3d6,4s2,4p0}
\end{lstlisting}
\result\atomconfig[{\textsubscript{18}[Ar]}][1.2]{3d6,4s2,4p0}

\medskip
Wide cores simply need a larger gap:
\begin{lstlisting}
\atomconfig[{\textsubscript{54}[Xe]\,4f14}][2.7]{5d6,6s2,6p0}
\end{lstlisting}
\result\atomconfig[{\textsubscript{54}[Xe]\,4f14}][2.7]{5d6,6s2,6p0}

% ---------------------------------------------
\subsection{\texttt{\textbackslash transitionseries} -- empty templates}
\begin{lstlisting}
\transitionseries[<scale>]{<1|2|3>}
\end{lstlisting}
Draws an empty $d$/$s$/$p$ frame for the first ($1$), second ($2$) or third
($3$) transition series, with the appropriate noble-gas core.
\begin{lstlisting}
\transitionseries{1}
\end{lstlisting}
\result\transitionseries{1}

% ========================== 4 ==============================
\section{Customisation}\label{sec:custom}

% ========================== 4-1 =============================
\subsection{Scaling}\label{sec:scale}
Two mechanisms are available. A \emph{per-call} optional argument:
\begin{lstlisting}
\suborbital[0.5]{4}{p}{5}   \suborbital[1.4]{4}{p}{5}
\end{lstlisting}
\result\suborbital[0.5]{4}{p}{5}\quad\suborbital[1.4]{4}{p}{5}

\medskip
\noindent and a \emph{global} setting applied to all subsequent diagrams:
\begin{lstlisting}
\setOrbitalScale{0.7}   % everything afterwards is 70%
\setOrbitalScale{1}     % back to normal
\end{lstlisting}

% ========================== 4-2 =============================
\subsection{Inline placement and vertical alignment}
Diagrams are vertically centred on the text line by default, so they sit
naturally at the beginning, middle or end of a sentence. Switch the alignment
with:
\begin{lstlisting}
\setOrbitalAlign{center}  % centred on the line (default)
\setOrbitalAlign{bottom}  % sitting on the baseline
\end{lstlisting}
For example, the Fe$^{3+}$ ion has a
\suborbital[0.38]{3}{d}{5} half-filled configuration.\\
\setOrbitalAlign{bottom}
Here it sits on the line For example, the Fe$^{3+}$ ion has a \suborbital[0.4]{4}{s}{2} like this.

% ========================== 4-3 =============================
\subsection{Colours, box size and spacing}
\begin{lstlisting}
\setElectronColor{blue}   % arrow colour (default red)
\setOrbitalBox{0.8}{1.0}  % {box width}{box height} in cm
\setOrbitalGap{0.9}       % gap between subshells in cm
\end{lstlisting}

\textbf{Default:}\\
\suborbital{3}{d}{7}\quad\electronconfig{3d6,4s2,4p0}

\bigskip
\textbf{arrow colour} \verb|\setElectronColor{blue}|\\
\setElectronColor{blue}
\suborbital{3}{d}{7}\quad\electronconfig{3d6,4s2,4p0}

\bigskip
\textbf{box size} \verb|\setOrbitalBox{0.8}{1.0}|\\
\setOrbitalBox{0.8}{1.0}
\suborbital{3}{d}{7}\quad\electronconfig{3d6,4s2,4p0}

\bigskip
\textbf{gap} \verb|\setOrbitalGap{0.9}|\\
\setOrbitalGap{0.9}
\electronconfig{3d6,4s2,4p0}

\bigskip
\textbf{all three together:}\\
\setElectronColor{teal}\setOrbitalBox{0.6}{0.8}\setOrbitalGap{1.4}
\electronconfig{3d6,4s2,4p0}

\newpage

% ========================== 4-4 =============================
\subsection{Arrow shape}
Electrons are drawn as half-arrows (\textsf{TikZ} \texttt{pics}
\texttt{halfarrowup} / \texttt{halfarrowdown}). Adjust them with:
\begin{lstlisting}
\setElectronArrow{<stem length>}{<line width>}  % e.g. {0.5}{1.2pt}
\end{lstlisting}

% ========================== 4-5 =============================
\subsection{The \texttt{\textbackslash chem} helper}
If \textsf{mhchem} is available, \verb|\chem{Fe^3+}| typesets a formula via
\verb|\ce|.

% ========================== 5 ==============================
\section{How electrons are placed}
For a subshell with $k$ boxes and $N$ electrons the package computes the number
of doubly occupied boxes as $\max(0,N-k)$ and fills the remaining electrons as
single ``spin-up'' arrows. This reproduces the high-spin (free-atom) ground
state expected from Hund's rule and the Pauli principle. Low-spin (complex)
fillings are not produced automatically.

% ========================== 6 ==============================
\section{Command summary}
\begin{tabular}{@{}ll@{}}
\verb|\suborbital[s]{n}{t}{e}|        & one subshell\\
\verb|\electronconfig[s]{list}|       & a row of subshells\\
\verb|\atomconfig[core][gap][s]{list}|& configuration with a core\\
\verb+\transitionseries[s]{1|2|3}+    & empty transition template\\[4pt]
\verb|\setOrbitalScale{f}|            & global scale\\
\verb+\setOrbitalAlign{center|bottom}+& inline alignment\\
\verb|\setElectronColor{c}|           & arrow colour\\
\verb|\setOrbitalBox{w}{h}|           & box size (cm)\\
\verb|\setOrbitalGap{g}|              & subshell gap (cm)\\
\verb|\setElectronArrow{stem}{lw}|    & arrow geometry\\
\end{tabular}

% ============================================================
\section{License and version history}
This package is distributed under the \LaTeX{} Project Public License
(LPPL) version 1.3c . \\[4pt]
\textbf{v1.0} (2026/05/24): first public release.

\end{document}