AtomSim
By
@yaasshh
- 6 Devlogs
- 70 Total hours
A physically rigorous, deeply customizable quantum mechanical atom model and visualization platform
Ship #2
AtomSim is a website I built that lets you actually see what an atom looks like.
You pick an element, or hydrogen, and pick which electron shell you want to look at. Then it draws it. Not a cartoon of dots going around a circle like the diagrams in school, the real shape, the cloud where the electron actually is. Some of them look like spheres, some look like dumbbells, some look like weird four leaf clovers. All of that is real, it just falls out of the math.
You can spin it around, slice it in half, look at it as a graph instead, or look at the colored lines of light the atom gives off when it gets hot. That last one is how we know what stars are made of, and you can watch it happen.
The part I care about most is that it never fakes anything. Every single number on the screen carries a label saying how it was made. Some are exact, straight from the equations. Some are computed numerically with an error bar attached. Some are approximations, and it says which physical effects it left out. And a few are deliberate “what if” experiments, like turning off the rule that stops two electrons sitting in the same place, just to see the atom collapse. Those are labeled too.
So if a picture is pretty rather than true, the app tells you. I wanted something a curious fifteen year old could poke at for an hour and come away with a correct picture in their head, not a comfortable wrong one.
It runs in a browser, works on a phone, and every view has its own link you can share.
PS: It also has mobile view now!
DEVLOG : 7?
Since that last update, the cleanup turned into actual features.
I finished the frontend narrator pass. Every disclosure string, every physics note, every view intro is now plain prose instead of the app talking about itself in first person.
Then I went after the parts of the app that were just annoying to use.
Plots are zoomable now. Wheel to zoom, drag to pan, on all five analytic views. I also built a small notation layer so the ASCII the engine emits gets typeset properly at render time, subscripts and superscripts where they belong, without dragging in a whole math library.
The big one was mobile. The app used to just refuse to render below a certain width. Now it works down to 320px: a proper mobile shell, view tabs instead of a sidebar list, controls that collapse, and per-view width floors so nothing spills sideways. That took a lot of small fixes I did not expect, a fixed SVG viewBox that hid fixed-width text, and an overflow rule that was already scrolling the page sideways before I touched anything.
After that, the URL got a real history. Back and Forward actually work now, and moving between orbitals pushes a history entry while flipping a display toggle just replaces one. Added a copy-link button and keyboard shortcuts for stepping through n, l, m and switching views.
Last thing, the title is now just AtomSim. The tagline was doing nothing for anyone.
Devlog #5 or 6???
Since the site went live, most of the work has been cleanup rather than new physics.
The whole app used to talk in first person. Every explanation said “I compute this” or “what I’m showing you.” It read like the code was narrating itself, which was odd. So I went through the entire Python engine module by module and rewrote it in plain technical prose. That’s done.
Then I started on the frontend, which had way more of it. The disclosure text, the physics notes under each equation, the view intros. That’s still in progress.
there were 2 things I had to be extra careful about. Some of those strings are checked word-for-word by tests, so rewording one has potential to break complete the build by itself.
In addition, I also tidied the repo layout for public viewing, fixed a deploy pipeline failure, and added privacy-safe visitor counting.
Right now i’m cutting padding, and pitching it so a high schooler can follow it without boring a physics grad.
Ship #1
Atom Sim is a browser app that solves atoms from scratch and shows you the result. Hydrogen comes out of closed-form math, real atoms like carbon and argon come out of a Hartree-Fock solver I wrote, and you can look at any of them as a 3D electron cloud, a 2D slice, a radial plot, an energy-level diagram or an emission spectrum. You can also break physics on purpose: switch off the Pauli exclusion principle, switch off electron exchange, or type in your own potential V(r) and see what kind of atom falls out.
The rule I built everything around is that the model never quietly lies. Every number carries a tag saying how it was made: exact, numerical, approximation, counterfactual, or just a visual choice. That tag follows the number from the solver all the way to the label on screen.
What was challenging
Hartree-Fock was brutal. The angular coefficients in the Fock operator are easy to get slightly wrong, and when you do, the solver still converges and hands you smooth, beautiful, completely wrong orbitals. Nothing crashes, nothing warns you. I had to re-derive the algebra instead of nudging numbers until a benchmark matched.
Error bars were the other trap. Mine looked great for a while and were simply lying, because the real error was coming from the box size, not the grid spacing I was measuring. Argon also took about an hour on a uniform grid until I moved to an exponential mesh, which cut it to seconds.
What I’m proud of
That it’s honest. Plenty of simulators draw a pretty orbital and say nothing about where it came from. Mine tells you, and the tests enforce it. The spectra are checked against real NIST data inside the test suite, so a physics regression fails CI rather than shipping quietly.
How to test it
It’s live at https://atomsim.fly.dev. The server sleeps when nobody is using it, so the very first load can take around 15 seconds. After that it’s quick.
Good things to try: pick n=3, l=1 and rotate the cloud, then flip to Plane view for the cross-section. Switch the element to argon. Open a guided tour if you want the short version. Every view is a shareable URL, so you can link someone to an exact state.
Devlog: Phase 30 to now
Phase 30, Instrument frontend. Redesigned the UI to read like a physics instrument. Bundled the fonts, dropped four fields nothing actually measured, and learned that text-transform: uppercase turns 3d into 3D and α² into A², so uppercase is now confined to section headings only.
Phase 31, Guided tours. Added walkthroughs that drive the app for you. Nearly shipped a tour that quoted the wrong hydrogen energy because it skipped reduced mass, and fixed two spotlight rings that measured their target before layout settled.
Absorption band cleanup. Abutting sub-pixel SVG rects were drawing lines that weren’t in the data. Settled the mean vs deepest-per-column question and fixed decade ticks that failed at both ends of the axis.
Housekeeping. Moved specs and plans out to docs/specs and docs/plans. Personal ignores went into .git/info/exclude so no tracked file carries tooling names.
Rate limiting. Sized the burst from the app’s real fan-out per action rather than from click counts. The n=6 row plus an auto-refetch was quietly doubling the load.
Web hosting. Containerized and deployed to Fly.io as a single process. Cold start from a snapshot is about 1.6s, occasionally up to 22s if the snapshot gets discarded. Argon solves in 2.8s on the deployed box against 1.4s locally. Suspended machines cost nothing, so occasional use stays near a dollar or two a month.
Also added rate-limiter logging that identifies refused clients, and confirmed the proxy overwrites forged IP headers, so spoofing doesn’t get you past the limit.
DevLog #3: New Frontend, Plus Small Bits
Phase 22 to now.
P22, distinguishable electrons. Turned off exchange in Hartree-Fock. Electrons still repel, they just stop being identical. Marked COUNTERFACTUAL. Helium came back exactly zero, so it was gone.
P24, Pauli off. Dropped the occupancy cap and everything falls into the 1s. Argon becomes 1s^18 and the periodic table stops existing. P22’s slow convergence was shells, not exchange.
P25, isosurfaces. Never size a box on the grid you draw on. The fraction error bar is blind to the box. A 90% p orbital is one piece, not two lobes.
P26, HF in 3D. Now in Cloud, Plane, Radial and Surface. Whole-atom and one-orbital radii move opposite ways. Fidelity tiers were literals under the solve.
P27, total density. Added D(r), the shape both models describe. A uniform grid steps over the 1s peak, so the test asserts convergence rate, not tolerance.
P28, screened density. GSZ gets its own D(r). A density needs its own box. A log axis quietly breaks area = electron count.
P29, comparison. Both models on one axis, gap measured. Caught a noise floor, a real number printing as zero, and a wrong caption.
Sulfur, chlorine. Split ATOM_KEYS into identity and capability. Derive flags, never pass them. A client check exposed a deep-link race.
P30, instrument frontend. Fonts bundled for offline. –edge is a border colour, never a fill. Dropped four fields with no engine behind them. Uppercase turned 3d into 3D, so headings only now.
Plot polish. Zoomed line profile labels offsets from window centre, since absolute wavelengths printed the same string six times. Drew xyz axes through the cloud.
Absorption, curve of growth. Stopped a zero equivalent width stretching the axis 300 decades. The band drew anti-aliasing seams as absorption lines where transmission was really 0.98 to 1.00. It now bins one column per unit and draws the deepest sample, beside what a real detector pixel would see.
DevLog: Phase 18 to now
P18, line shapes. Real lines are not infinitely thin spikes. Atoms move (Doppler) and get jostled by neighbours (pressure), so each line spreads into a bell shape, a Voigt profile. I added that, plus a zoom so you can look at one line up close. The useful trick was a flux-closure check: whatever area a line has before broadening, it has to still have after. That caught two grid bugs that were invisible on screen.
P19, optical depth. Until now every line acted as if light escaped freely. In a thick gas strong lines saturate, so doubling the atoms stops doubling the brightness. That is the curve of growth. Lesson: decide which regime a line sits in from the physics, not by eyeballing the slope. Also the wavelength window has to widen as the column thickens, or you clip the wings you are trying to measure.
P20, absorption. The mirror of emission. Shine a continuum through the gas, look at what is missing. The trap was that 14 hydrogen lines land on only 6 distinct wavelengths, so matching a profile to its source line by wavelength quietly pairs the wrong ones. I key on the transition instead.
P21, Hartree-Fock. The big one. Instead of a fitted screening formula, each electron feels a potential built from all the others, solved over and over until it stops changing. That gets me sulfur and chlorine, which the old model could not touch, plus ions with no preset. Two things worth remembering: the solver’s own error bar was lying to me and needed re-deriving, and what made convergence fast was not a clever algorithm, it was the right mixing constant.
P22, cleanup. Made features honest about where they apply. The classical ghost and the force-law lab only make sense for one-electron atoms, so they explain themselves now instead of erroring on a screened atom. Fixed He+ breaking every API call, because the “+” was never URL-encoded. Unknown systems say so instead of spinning. Right now I am fixing hint text that escapes its panel on narrow screens.
Atom_Sim: Physics Simulator Dev Log
An atom simulator built on one rule: Every number has a label (exact, numerical, approximation, counterfactual, or visual_liberty). Unlabeled numbers are treated as bugs.
Stack: Python physics engine -> React + Three.js frontend.
Phase Logs
Phases 1–3: The Hydrogen Foundation
- Hydrogen Core: Uses exact math for energies and wavefunctions. Validates its electron clouds using statistical KS tests.
- Numerical Solver: Solves the Schrödinger equation for custom shapes. It calculates its own accuracy by halving the grid spacing.
- Constants Lab: Allows changing fundamental constants (hbar, e, c). It proves that changing individual units changes nothing if the ratio between them stays the same.
- Classical Ghost: Shows old Bohr orbits collapsing, proving why classical physics cannot explain atoms.
Phases 4–6: Altered Potential & Real Atoms
- Fake Physics: Simulates universes with non-standard forces (like Yukawa or power laws) under a clear warning banner.
- Screened Atoms: Models elements from Helium to Argon using historic 1974 data. If an element (like Sulfur or Chlorine) lacks clean data, it is left out entirely rather than guessed.
Phases 7–12: Fields, Relativity & Nuance
- Dirac Math: Tracks exact relativistic shifts and highlights what the math misses (the Lamb shift).
- External Fields: Simulates atoms splitting under magnetic fields (Zeeman effect) and electric fields (Stark effect).
- Hyperfine: Models the 21 cm hydrogen line using the precise electron-to-proton mass ratio.
Phases 13–17: Light, Speed & Thermodynamics
- Fast Math: Uses a custom integration trick to calculate atomic lifetimes exactly and 13x faster.
- Doublet Ratios: Proves via quantum math (Wigner 6j) why certain spectral lines are twice as bright as others.
- Heat Sliders: Combines Saha and Boltzmann equations to turn raw rates into actual visible light. Dragging the temperature slider smoothly hands Lyman lines over to Balmer lines.
Phase 18: Line Profiles (Current Work)
Replaces infinitely sharp lines with realistic Voigt profiles using three combined factors:
- Natural Width: A Lorentzian shape caused by how fast an excited state decays.
- Doppler Width: A Gaussian shape caused by thermal motion. Works perfectly for normal hydrogen, positronium, and muonic hydrogen.
- Instrumental Width: A Gaussian blur based on the user’s chosen telescope or sensor resolution.
Note on Missing Physics: Collision/pressure broadening is not simulated. Instead of a text disclaimer, the app calculates how large that missing effect would be and prints the raw margin of error right next to the chart.
Core Development Rules
- No Smoke Tests: Every physics feature must pass an automated math test.
- No Live Fetches: All reference data is saved locally with a hard citation.
- No Silent Approximations: If the code cannot calculate something honestly, it stops and prints exactly what data is missing.
