# Architecture: local-orbital molecular renderer

## Purpose

This project is a **scientific visualization engine**, not a full quantum-chemistry package.

The core idea is:

\[
\text{structure}
\rightarrow
\text{local basis}
\rightarrow
\text{compact orbital model}
\rightarrow
\text{rendered view}
\]

We deliberately avoid constructing the full many-electron wavefunction.

## Mathematical core

For an atom \(A\) centered at \(\mathbf R_A\), define a local basis

\[
\chi_{A,\mu}(\mathbf r)
=
R_{A,\mu}(r_A)\,
Y_{\ell_\mu m_\mu}^{\mathrm{real}}(\widehat{\mathbf r_A}),
\qquad
\mathbf r_A=\mathbf r-\mathbf R_A.
\]

In the MVP, the angular basis is restricted to

\[
\{s,p_x,p_y,p_z\},
\]

which is the real \(Y_{00}\oplus Y_{1m}\) space.

Local sigma hybrids are constructed from geometry-driven directional seed states and orthogonalized with

\[
C_A=(M_A M_A^T)^{-1/2}M_A.
\]

That gives the local orbital family

\[
h_{A,j}(\mathbf r)
=
\sum_\mu
(C_A)_{j\mu}\,\chi_{A,\mu}(\mathbf r).
\]

## Runtime decomposition

### Server-side
The server should perform only:
1. molecular parsing,
2. conformer generation,
3. local linear algebra,
4. compact orbital model assembly,
5. optional local mesh generation.

### Client-side
The client should perform:
1. camera interaction,
2. level-of-detail switching,
3. drawing atoms, bonds, orbital glyphs,
4. optional display of server-generated local orbital meshes.

## Why this scales

The local orbital construction scales approximately linearly in atom count:

\[
T(N) \approx O(N).
\]

The many-electron determinant space grows combinatorially, but this engine never constructs it.

## Scientific boundaries

This codebase does **not** currently compute:
- SCF / HF / DFT
- charge self-consistency
- correlation energy
- vibrational free energies
- crystal packing energies
- full molecular orbital energy spectra

It computes an **educated local-orbital layer**.

## Next implementation targets

1. **Conformer generation**
   - ETKDG
   - optional MMFF/UFF cleanup
   - later: PDB / CIF coordinates override generated conformers

2. **Mesh transfer size**
   - support server-side local mesh generation
   - quantize floats where possible
   - gzip / brotli at web server level
   - request-only selected orbital meshes

3. **Client-side triangle count**
   - LOD tiers:
     - atoms+bonds,
     - orbital glyphs,
     - selected local isosurfaces
   - frustum / distance culling
   - optional instancing

4. **Protein coordinate parsing**
   - parse PDB/mmCIF
   - infer residue / chain / atom metadata
   - construct local orbital models only in selected regions

5. **Caching**
   - canonical SMILES -> conformer cache
   - structure hash -> orbital model cache
   - per-orbital mesh cache for repeated requests

6. **Delocalized \(\pi\) systems**
   - detect conjugated components
   - solve small Hückel-like subproblems
   - represent π-clouds separately from localized sigma hybrids

7. **Crystallographic extension**
   - accept crystal cell / symmetry metadata
   - visualize packing contacts, H-bond networks, anisotropic environment
   - render electron-polarity / donor-acceptor fields for semi-crystalline materials

## Visual philosophy

We keep the current spirit:
- mathematically explicit,
- visually engaging,
- pedagogical without becoming toy-like,
- compact enough for a single-core host.