"Orbitae: Building a Verifiable 3D Quantum Microscope in Python & Pure WebGL"

Most 3D orbital visualizers you find online fall into one of two buckets: either they are pretty artistic approximations with no mathematical rigor, or they are heavy desktop tools like VMD or Avogadro that require a steep learning curve just to inspect a single wave function.

I wanted something in between: a fast, browser-based "quantum microscope" where every rendered point comes from verified physics - and where the limitations of each mathematical model are explicitly measured and shown to the user. That is why I built Orbitae.

👉 Live Demo: amurlaniakea.github.io/orbitae

What Orbitae Does

Orbitae samples 3D probability clouds (20,000+ points per orbital with two-color phase rendering) directly from wave functions and lets you inspect atoms, ions, and small molecules in real time:

• Exact Hydrogen (Z = 1): Analytical solutions up to n = 4 (s, p, d, f) using real spherical harmonics (p_x, d_{xy}, etc.), exact radial nodes, energies (E_n = -Z^2 / 2n^2), and 95% probability radii.
• Atoms 1-36 & Biomedical Ions: Interactive periodic table highlighting elements essential to human biology, using Slater's shielding rules alongside individual subshell breakdowns and biomedical ions (\text{Na}^+, \text{K}^+, \text{Fe}^{2+}, \text{Fe}^{3+}, \text{Zn}^{2+}, etc.).
• Small Molecules (Hartree-Fock): Restricted Hartree-Fock (def2-TZVP via PySCF) for closed-shell molecules (\text{H}_2\text{O}, \text{NH}_3, \text{CO}, \text{N}_2, \text{CO}_2), displaying valence molecular orbitals, LUMOs, nuclear positions, and orbital energies.
• Standard .cube Export: A built-in CLI exporter so you can take any computed molecular orbital straight into desktop tools like PyMOL, VMD, or Avogadro:

python -m orbitae.molecules --cube CO --orbital HOMO --cube-out CO_HOMO.cube

Architecture: Scientific Python + Zero-Dependency WebGL

I kept the stack intentionally lean to avoid framework bloat and supply-chain noise:

• Backend / Math Core (Python 3.10+, SciPy, optional PySCF): Handles spherical harmonics, radial integration, Monte Carlo rejection/importance sampling, and Hartree-Fock reference runs. It exports compact, static JSON datasets into web/data/.
• Frontend (Pure WebGL + Vanilla JS): Zero third-party 3D libraries (no Three.js). Just raw WebGL shaders rendering point clouds at 60 FPS even on mobile devices, locked down with a strict Content Security Policy (CSP) that makes zero external network requests.

from orbitae import sample_orbital, radial_cutoff
# Sample 50,000 points from a 2p_x orbital in Bohr radii (a0)
points = sample_orbital(n=2, l=1, m=1, size=50_000, seed=0)
r95 = radial_cutoff(2, 1, p=0.95)

Engineering Lesson 1: Measuring Where Your Model Lies

Slater-type orbitals are great for teaching, but they are a didactic approximation: they have no radial nodes and ignore electron correlation. Instead of hiding that, I wrote a benchmarking pipeline (orbitae.hf_compare) against Unrestricted Hartree-Fock (def2-TZVP) to measure the exact mean radius error across all 36 elements and display it right inside the UI.

While Slater rules hold up decently for early periods, they break down hard in $3d$ transition metals:

Catching a Subtle Occupation Bug (v0.7)

During benchmarking, I noticed $\text{Mn, Fe, Co,}$ and $\text{Ni}$ had suspiciously high total radius errors ($\text{Fe}$ was showing $+25.1%$ instead of $+18.9%$).

It turned out that unrestricted HF was converging to $3d^{n+1} 4s^1$ configurations while Slater's rules assumed $3d^n 4s^2$, mixing configuration differences with radial approximation error. Enforcing matching subshell occupations in the reference calculation - and locking it with a CI test - fixed the comparison.

Engineering Lesson 2: Testing Physics Like Software

Every mathematical property in Orbitae is guarded by pytest in CI:

• Analytical Checks: Radial/angular normalization, orthogonality, radial Schrödinger equation residuals, and analytical node positions for $2s$ and $3s$.
• Molecular Symmetry Checks: For $\text{H}_2\text{O}$, the HOMO has $b_1$ symmetry, meaning the molecular plane is a strict nodal plane. Our test suite verifies that electron density on that plane drops to $\sim 10^{-14}$ (compared to $0.69$ at peak density).
• Grid Boundaries: On a $0.2\ a_0$ grid, valence molecular orbitals normalize cleanly ($0.9997\text{-}1.0016$), whereas core $1s$ orbitals are too sharp for that grid spacing - so the web viewer restricts display to valence + LUMO while .cube export handles arbitrary grids.

Try It Out & Inspect the Code

A fun detail to check out in the live demo: switch to Molecules, select Carbon Monoxide ($\text{CO}$), and look at the HOMO. You will see a $\sigma$ lone-pair lobe heavily localized (88% of its density) on the carbon atom - the exact orbital that binds to iron in hemoglobin and causes CO poisoning.

• GitHub Repository: https://github.com/amurlaniakea/orbitae (AGPL-3.0-or-later)
• Zenodo Concept DOI: 10.5281/zenodo.24135885

Next on the roadmap: open-shell molecules with unpaired spin ($\text{O}_2$ triplet, $\text{NO}$) and more small biomolecules. Feedback, PRs, and physics nitpicks are always welcome!