# orbitals

Atomic subshell / orbital-box diagrams for LaTeX, with automatic electron
filling following Hund's rule and the Pauli principle.

* Version:   1.0
* Date:    2026/05/24
* Author:  Faris Hameed 
* email:   classsec81@gmail.com
* License: LaTeX Project Public License (LPPL) v1.3c 
* Status:  maintained

## Description

`orbitals` draws the familiar "box-and-arrow" notation for atomic subshells
(s, p, d, f). You give only the principal quantum number, the subshell letter
and the number of electrons; the package fills the boxes automatically (one
spin-up arrow per box first, then pairing), reproducing the high-spin
free-atom ground state.

It can draw:

* a single subshell (`\suborbital`),
* a row of subshells (`\electronconfig`),
* a valence configuration with a noble-gas core (`\atomconfig`),
* an empty transition-series template (`\transitionseries`).

Every diagram can be scaled and placed inline in running text. Colours, box
size, spacing and arrow shape are configurable.

## Requirements

* LaTeX2e (kernel 2020-10-01 or newer, for `\NewDocumentCommand`)
* TikZ / pgf
* xcolor, graphicx (loaded automatically with TikZ)
* mhchem (optional; only for the `\chem` helper)

Engines: pdfLaTeX, XeLaTeX or LuaLaTeX.

## Installation

Copy `orbitals.sty` to your local texmf tree, e.g.

    <TEXMFHOME>/tex/latex/orbitals/orbitals.sty

and refresh the filename database (`texhash` / `mktexlsr`) if your tree needs
it. For a single document you may simply place `orbitals.sty` next to the
`.tex` file.

## Usage

    \usepackage{orbitals}
    ...
    \suborbital{4}{p}{5}
    \electronconfig{3d6,4s2,4p0}
    \atomconfig[{\textsubscript{18}[Ar]}][1.2]{3d6,4s2,4p0}
    \transitionseries{1}

See `orbitals-doc.pdf` for the full manual.

## Files

* `orbitals.sty`      -- the package
* `orbitals-doc.tex`  -- manual source
* `orbitals-doc.pdf`  -- compiled manual
* `README.md`         -- this file

## License

Copyright (C) 2026 Faris Hameed.

This work may be distributed and/or modified under the conditions of the
LaTeX Project Public License, version 1.3c of this license 
https://www.latex-project.org/lppl.txt