@mmogr/orrery

The observatory's physics. Small derived models for pages that draw their data as a world: a sky whose shape comes from a graph's spectrum, planets that obey Kepler, a moon computed rather than faked, terrain lit by an honest lamp, a camera that is the damped oscillator it always pretended to be.

Built for and used by mattogrady.com, where the notes of a maths/CS/physics degree hang as constellations over a mountain range grown from a year of commits. Everything here is the working part of that page, extracted because a model worth deriving is worth reading.

The models

| module | what it is | |---|---| | sky/spectral | rest positions for a notes graph from the three smallest non-trivial eigenvectors of its normalised Laplacian — what is taught together sits together, and the third mode is depth | | sky/springs | a velocity-Verlet layer over the rest state: springs breathe, hands deform, the shape comes home | | sky/heat | the heat equation on the graph — open a note and warmth diffuses along its links | | sky/curvature | Ollivier–Ricci curvature per link, by exact optimal transport between the two ends' lazy walks — a bridge is negative, a clique positive | | sky/hks | the heat kernel signature — what diffusing from every note at once leaves at each one, sampled at two times so a note reads locally busy against structurally central, and read as magnitudes on Pogson's ratio when it has to be drawn | | sky/ricci-flow | discrete Ricci flow on link lengths — a bridge stretches, a weave tightens, and the sky parts into the communities modularity reads off the lengths, counting how many of them the cut itself made | | sky/notes-graph | the rule that makes a sky of a notes feed: evergreen notes are stars, weekly notes mediate the links they pass through, landing pages never do | | sky/semantic | the sky by meaning — the notes' embeddings, reduced where the text lives, turned by Procrustes to face the link layout; the unlinked pairs that agree — one a note, if asked — and a Mantel test of how far meaning and links agree | | orbits/kepler | activity → semi-major axis → period by $T^2 \propto a^3$; position by solving Kepler's equation, not by lookup | | orbits/svd | language space: the principal directions of a repo × language byte matrix, stretching and leaning each orbit | | orbits/binaries | double planets: repos whose commits rose and fell together, found by lagged correlation against a permutation null with a stated false-discovery rate | | orbits/nbody | the pull between planets: the same system with masses, integrated by leapfrog, and the along-track shift it leaves on each Kepler orbit — smaller than a pixel, on purpose | | moon | the true lunar age from a truncated Meeus ephemeris, held against the old mean-lunation model it replaces | | terrain/* | a contribution heightfield with an analytic gradient, rivers by steepest descent, Lambert shading with a named lamp, snow by polygon clipping, and the year's derivatives, inflections and entropy | | camera | exponential follows and a damped harmonic sway, fitted from the per-frame constants they replace | | feeds/* | the contracts the observatory's public feeds speak, and total validators that turn whatever was actually sent into them — never throwing, never trusting | | math/circular | the week on a circle: a von Mises fit to weekday commits — mean day, concentration κ, and a density that cannot overflow | | math/* | the small dense toolbox underneath: Cholesky, Jacobi eigen, Gaussian derivative kernels with a per-parity boundary extension, DFT, lagged correlation, Benjamini–Hochberg, entropy | | math/wavelet | the year's beat in time: a Morlet scalogram of the weekly series by direct convolution, the cone of influence that says which scales each week can vouch for, and the ridge — which period beat loudest, week by week |

Every model has a derivation in docs/ listing its equations and constants — and an "Aesthetic terms" section admitting what exists for feel rather than physics. The rule of the house: every quantity that reaches the sky carries a name, a unit, and one sentence a legend can say about it. If the sentence cannot be written, it does not ship.

Character

• Zero dependencies. The whole package minifies to a few tens of kilobytes; a test keeps that promise.
• Deterministic. Time and randomness are arguments. Seed a model and it repeats to the bit; the site's fixtures depend on it.
• Small dense maths, on purpose. The graphs are hundreds of nodes, the matrices tens wide. Cholesky and Jacobi at that size are simpler, exact enough, and fit in your head — no numerics framework earns its place here.

Use

npm install @mmogr/orrery

import { spectralEmbedding, scaleToBox } from "@mmogr/orrery";

const rest = scaleToBox(spectralEmbedding({ n, edges }), width, height);

Written in strict TypeScript as ES modules; npm run build emits the JavaScript and declarations the package exports (installing from git runs it for you). npm test runs the suites under Node's own test runner, npm run demo serves the demo page, and the same demo runs live at https://mmogr.github.io/orrery/.

Releasing

A release note travels with the change: a pull request that alters what the package does adds a changeset (npx changeset, naming patch, minor or major with a sentence in your own words; CI insists on one when src/ moves). A standing "Version Packages" pull request gathers the notes into CHANGELOG.md and the version; merging it is the release — the workflow tags vX.Y.Z, writes the GitHub release, and publishes to npm with provenance through trusted publishing. Every version on npm carries a provenance attestation naming the commit and the workflow run that built it.