# Hydrogen Observatory v1 — science and rendering

## Physical model

The analytic field evaluator is byte-identical to v0. It represents stationary
hydrogen eigenstates ψ=RₙℓYℓᵐ for a fixed, point proton and one nonrelativistic
electron. Coordinates use Bohr radii a₀; energies are −1/(2n²) Hartree. There are
30 states with 1≤n≤4, 0≤ℓ<n, and −ℓ≤m≤ℓ. Spherical harmonics use the
Condon–Shortley convention and complex exp(imφ) dependence. Nonzero m states
are not real pₓ/pᵧ combinations. Global phase is arbitrary. The overall time
phase is suppressed; density is stationary.

See [v0's complete model and equations](../v0/SCIENCE.md) in the repository,
or [the archived v0 science note](/experiments/releases/quantum/v0/SCIENCE.md).
No spin, relativity, transitions, photons, measurement dynamics, or interatomic
interactions are included. Selecting a state is not a physical transition.

## Volume representation

The domain is a cube with each physical axis spanning ±3n² a₀. A worker samples
73³ points for Balanced and 97³ for Fine detail. Grid coordinates g uniformly
span [−1,1], but physical coordinates are sign(g)g² times the domain half-width.
This concentrates samples near the nucleus and includes the origin exactly.
The inverse mapping is used by both the CPU reference sampler and GPU texture
lookup. The grid is not a uniform Cartesian spatial lattice.

The maximum sampled amplitude sets the display normalization for that state.
Real and imaginary components, divided by this maximum, are rounded to signed
16-bit precision and packed into RGBA8: q=round(32767a+32768). The inverse mapping
is linear in texture channels, so trilinear filtering reconstructs complex
amplitudes before computing |ψ|² and arg(ψ). Interpolating phase angles directly
would incorrectly cross the −π/+π branch cut; this implementation avoids that.

A second RGBA8 texture stores approximate outward density gradients, with finite
differences divided by local physical grid spacing. These normals are used only
for the optional illustrative lighting. Lighting is not electron emission or
an interaction with photons. Density calculations do not use these normals.

## Rendering and controls

A perspective camera traces rays through the cube. Midpoint ray samples use a
piecewise-square spacing around closest approach to the nucleus. Balanced uses
120 samples, Fine detail 192, and active dragging 72. Pixel resolution is capped
separately. Thus field-grid, ray-step, and screen-resolution errors are distinct.

- **Density surface:** Find the first sample at or above the selected fraction
  of sampled peak density and refine the crossing with six bisection steps.
  The contour does not enclose a specified probability and is not a hard physical
  boundary. Thin features between samples can be missed.
- **Cloud:** The opacity increment is 1−exp(−d×gain×Δs), with d the normalized
  density, gain set by Cloud depth, and Δs in normalized scene coordinates.
  Front-to-back emission/absorption compositing makes a view of the density.
  This is neither a linear density projection nor physical optical transport.
- **Phase:** Cyclic color denotes arg(ψ); nodes have no defined phase. Density
  mode uses a single cyan color. Colors are illustrative, not observable hues.
- **Lighting:** Optional gradient-based diffuse and rim shading makes shape
  easier to read. Switch it off to remove this appearance transform.
- **Cutaway:** Discard the positive side of the selected coordinate plane. On
  the exposed side, blend in a logarithmically mapped 2D density section. The
  plane outline is a guide, not a physical boundary.

Display brightness uses a fixed power of 0.82 after compositing. Camera rotation
is opt-in; it changes the view, not the quantum state. Changing opacity or contour
threshold also changes appearance without changing the wavefunction. Export saves
the current rendered canvas, without adding an experimental measurement claim.

## Validation

`node quantum/v1/scripts/validate.mjs` repeats v0's 312 checks over all 30 states:
closed-form low-order states, nodes, normalization, mean radius, radial
orthogonality, ±m conjugation, and sampled Cartesian Schrödinger residuals.

`node quantum/v1/scripts/validate-volume.mjs` checks that the analytic source
matches v0, bounds 16-bit encoding error, probes all 30 states on both grid
resolutions, and verifies that the finer grid reduces aggregate interpolation
error. `results/volume-validation.json` records measured maxima, RMS errors,
worst probes, and reference values for browser GPU checks. Errors are normalized
to each grid's sampled peak amplitude, not relative to local amplitudes near
nodes. They are sampled results, not global error bounds.

Browser tests read actual GPU texture values through the production fragment
shader, compare them with both CPU interpolation and the analytic evaluator, and
exercise surface/cloud/phase modes, cutaways, camera input, quality changes,
PNG export, idle rendering, missing WebGL and context restoration. Screenshot
and browser evidence are generated by the site's Playwright suite.

The domain is finite; orbitals have tails beyond it. Field interpolation can
smooth nodes or miss fine structure. Ray sampling and finite pixels impose
additional limitations not covered by pointwise texture checks. No physical-phone
frame-rate or energy claims are made; tests use desktop and emulated mobile
Chromium, not Safari or a native mobile implementation.

## Reference and visual direction

- Richard Fitzpatrick, University of Texas at Austin: [Energy Levels of Hydrogen
  Atom](https://farside.ph.utexas.edu/teaching/qm/lectures/node42.html).
- kavan, [Simulating Atoms in C++](https://www.youtube.com/watch?v=OSAOh4L41Wg),
  supplied as visual direction. This implementation does not copy its assets.

The [Atoms reference implementation](https://github.com/kavan010/Atoms/tree/5c4283a29069cbd1599eab6bfccca3f133b9b997)
uses sampled points from hydrogen orbitals, with camera motion, clipping and
illustrative lighting. This viewer represents the same stationary hydrogen model
with continuous density surfaces and volume compositing. Atoms also animates
azimuthal probability flow for nonzero m; that is distinct from a measured electron
trajectory. A future probability-current overlay could show this flow while the
density remains stationary. No Atoms source code or assets are included here.