Metronome synchronization: why five on a rolling board fall into step

// game.js: five metronomes on a board that rests on two soda cans. Tap a metronome to stop or start it,
// free the board, make it heavier, or damp it, and watch whether the pendulums fall into step.
// Units: meters, kilograms, seconds, radians. The notebook writes every parameter into #data.
"use strict";

const DATA = JSON.parse(document.getElementById("data").textContent);
const {omega0: W0, l: L, mu: MU, theta0: TH0, amp: AMP, dt: DT, draw_scale: SCALE, r_lock: R_LOCK} = DATA;
const MASSES = DATA.board_masses;
const N = DATA.rates.length;                           // the group: five, unless the data says otherwise
const BOARD_LEN = 0.62, CAN_R = 0.033;                 // the drawing's board and cans, in meters

// ---- the state: everything that changes, in one object
const state = {n: N, board: "fixed", boardMass: 0.25, rates: [], theta: [], omega: [], on: [], x: 0, v: 0,
  t: 0, sound: false, running: true, vPeak: 0, tFree: 0, tAbove: null};

const angular = (rate) => 2 * Math.PI * (rate / 120) / DATA.rho;    // a tick is half a swing
const beta = () => DATA.m_bob / (state.boardMass + state.n * DATA.m_metronome);
const gamma = () => state.board === "damped" ? DATA.gamma_damped : 0;

// ---- the equations of the notebook: the board's acceleration first, then each pendulum's
function accelerations(s, theta, omega, v) {
  const w = s.rates.map(angular), b = beta();
  const f = theta.map((th, i) => s.on[i]
    ? -w[i] * w[i] * Math.sin(th) - MU * W0 * ((th / TH0) ** 2 - 1) * omega[i] : 0);   // own swing and escapement
  let a = 0;
  if (s.board !== "fixed") {
    let push = 0, inertia = 0;
    theta.forEach((th, i) => {
      if (!s.on[i]) return;
      push += Math.sin(th) * omega[i] ** 2 - Math.cos(th) * f[i];
      inertia += Math.cos(th) ** 2;
    });
    a = (b * L * push - gamma() * W0 * v) / (1 - b * inertia);
  }
  return {alpha: theta.map((th, i) => s.on[i] ? f[i] - (a / L) * Math.cos(th) : 0), a};
}

// one Runge-Kutta step: four slopes, averaged
function step(s, h) {
  const n = s.theta.length;
  const slope = (th, om, v) => { const {alpha, a} = accelerations(s, th, om, v); return {dth: om, dom: alpha, dx: v, dv: a}; };
  const shift = (k, c) => [s.theta.map((x, i) => x + c * k.dth[i]), s.omega.map((x, i) => x + c * k.dom[i]), s.v + c * k.dv];
  const k1 = slope(s.theta, s.omega, s.v);
  const k2 = slope(...shift(k1, h / 2));
  const k3 = slope(...shift(k2, h / 2));
  const k4 = slope(...shift(k3, h));
  const mix = (key, i) => (k1[key][i] + 2 * k2[key][i] + 2 * k3[key][i] + k4[key][i]) / 6;
  const before = s.theta.slice();
  for (let i = 0; i < n; i++) { s.theta[i] += h * mix("dth", i); s.omega[i] += h * mix("dom", i); }
  s.x += h * (k1.dx + 2 * k2.dx + 2 * k3.dx + k4.dx) / 6;
  s.v += h * (k1.dv + 2 * k2.dv + 2 * k3.dv + k4.dv) / 6;
  s.t += h;
  before.forEach((th, i) => { if (s.on[i] && th * s.theta[i] < 0) tick(); });   // a tick at every pass through the middle
}

// ---- phases and the order parameter r, over the swinging metronomes
const phase = (theta, omega) => Math.atan2(-omega / W0, theta);
function order(s) {
  let c = 0, sn = 0, k = 0;
  s.theta.forEach((th, i) => { if (s.on[i]) { const p = phase(th, s.omega[i]); c += Math.cos(p); sn += Math.sin(p); k++; } });
  return k ? {r: Math.hypot(c, sn) / k, psi: Math.atan2(sn, c)} : {r: 0, psi: 0};
}

// The board starts without a push: total momentum zero, so it rocks in place instead of drifting off.
function settleBoard() {
  let sx = 0, sv = 0;
  if (state.board !== "fixed") state.theta.forEach((th, i) => { sx += Math.sin(th); sv += Math.cos(th) * state.omega[i]; });
  Object.assign(state, {x: -beta() * L * sx, v: -beta() * L * sv, tFree: state.t, tAbove: null, vPeak: 0});
}

function start(phases) {
  const n = phases.length;
  Object.assign(state, {rates: n === N ? DATA.rates.slice() : DATA.rates2.slice(), on: Array(n).fill(true),
    theta: phases.map((p) => AMP * Math.cos(p)), omega: phases.map((p) => -AMP * W0 * Math.sin(p)), t: 0});
  settleBoard();
}

// ---- sound: a 3 ms click through the Web Audio API, allowed only after a tap
let audio = null, click = null;
function wakeAudio() {
  if (audio) return;
  audio = new (window.AudioContext || window.webkitAudioContext)();
  click = audio.createBuffer(1, Math.round(audio.sampleRate * 0.003), audio.sampleRate);
  click.getChannelData(0).forEach((_, i, d) => { d[i] = (Math.random() * 2 - 1) * (1 - i / d.length); });
  state.sound = true;
}
function tick() {
  if (!state.sound || !audio) return;
  const src = audio.createBufferSource(), gain = audio.createGain();
  gain.gain.value = 0.5;
  src.buffer = click;
  src.connect(gain).connect(audio.destination);
  src.start();
}

// ---- drawing
const $ = (id) => document.getElementById(id);
const canvas = $("scene");
let dpr = 1;

function layout() {
  dpr = window.devicePixelRatio || 1;
  const box = canvas.getBoundingClientRect();
  canvas.width = Math.round(box.width * dpr);
  canvas.height = Math.round(box.height * dpr);
  render();
}

function colors() {
  const css = getComputedStyle(document.documentElement);
  return Object.fromEntries(["bg", "fg", "ink", "accent", "second", "muted", "pale"].map((k) => [k, css.getPropertyValue(`--${k}`).trim()]));
}

const thickness = (mass) => 0.006 * Math.sqrt(mass / 0.25);      // a shelf at 0.25 kg, a plank at 5 kg
const pixelsPerMeter = (W, H) => Math.min(W / 0.74, H / 0.5);   // the scene, 0.74 m wide, fits the frame
const spots = (n) => n === 2 ? [-BOARD_LEN / 6, BOARD_LEN / 6] : Array.from({length: n}, (_, i) => -0.24 + 0.48 * i / (n - 1));

function drawScene(c) {
  const ctx = canvas.getContext("2d");
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  const W = canvas.width / dpr, H = canvas.height / dpr;
  ctx.fillStyle = c.bg;
  ctx.fillRect(0, 0, W, H);
  const k = pixelsPerMeter(W, H);
  const floor = Math.min(H - 22, H / 2 + 0.3 * k);       // the scene low in a wide frame, centered in a tall one
  const X = (x) => W / 2 + x * k, Y = (y) => floor - y * k;
  const shift = SCALE * state.x, T = thickness(state.boardMass), top = 2 * CAN_R + T;

  ctx.lineWidth = 1.5;
  ctx.strokeStyle = c.muted;                             // floor, mat, cans, clamps
  ctx.beginPath(); ctx.moveTo(0, Y(0)); ctx.lineTo(W, Y(0)); ctx.stroke();
  if (state.board === "damped") {
    ctx.beginPath();
    for (let x = -0.33; x < 0.33; x += 0.012) { ctx.moveTo(X(x), Y(0)); ctx.lineTo(X(x + 0.012), Y(0.012)); }
    ctx.stroke();
  }
  const lift = state.board === "damped" ? 0.012 : 0;
  for (const cx of [-0.2, 0.2]) {                        // a can rolls half as far as the board on it
    ctx.beginPath(); ctx.arc(X(cx + shift / 2), Y(CAN_R + lift), CAN_R * k, 0, 2 * Math.PI); ctx.stroke();
  }
  if (state.board === "fixed") {
    for (const sgn of [-1, 1]) {
      const x0 = sgn * (BOARD_LEN / 2 + 0.006);
      ctx.beginPath(); ctx.moveTo(X(x0), Y(0)); ctx.lineTo(X(x0), Y(top + lift + 0.01));
      ctx.lineTo(X(x0 - sgn * 0.02), Y(top + lift + 0.01)); ctx.stroke();
    }
  }
  ctx.fillStyle = c.pale;                                // the board
  ctx.strokeStyle = c.ink;
  ctx.beginPath();
  ctx.rect(X(shift - BOARD_LEN / 2), Y(top + lift), BOARD_LEN * k, T * k);
  ctx.fill(); ctx.stroke();

  ctx.font = `${Math.round(Math.min(22, Math.max(14, 0.022 * k)))}px system-ui, sans-serif`;   // grows with the scene
  ctx.textAlign = "center";
  ctx.textBaseline = "bottom";
  spots(state.n).forEach((sx, i) => {                    // the metronomes: box, rod, weight, rate
    const x = sx + shift, y = top + lift, on = state.on[i];
    ctx.strokeStyle = on ? c.ink : c.muted;
    ctx.beginPath();
    ctx.moveTo(X(x - 0.045), Y(y)); ctx.lineTo(X(x - 0.022), Y(y + 0.17));
    ctx.lineTo(X(x + 0.022), Y(y + 0.17)); ctx.lineTo(X(x + 0.045), Y(y)); ctx.closePath();
    ctx.stroke();
    const th = state.theta[i], px = X(x), py = Y(y + 0.035);
    ctx.lineWidth = 2;
    ctx.beginPath(); ctx.moveTo(px, py); ctx.lineTo(px + 0.19 * k * Math.sin(th), py - 0.19 * k * Math.cos(th)); ctx.stroke();
    ctx.fillStyle = on ? c.ink : c.muted;
    ctx.beginPath(); ctx.arc(px + 0.12 * k * Math.sin(th), py - 0.12 * k * Math.cos(th), 0.011 * k, 0, 2 * Math.PI); ctx.fill();
    ctx.lineWidth = 1.5;
    ctx.fillText(String(state.rates[i]), X(x), Y(y) - 2);
  });

  // the phase ring: one dot per swinging metronome, the mean arrow of length r
  const R = Math.max(18, Math.min((floor - 0.33 * k - 14) / 2, 0.11 * W, 64)), cx = 10 + R, cy = 10 + R;   // above the pendulums
  ctx.strokeStyle = c.muted;
  ctx.beginPath(); ctx.arc(cx, cy, R, 0, 2 * Math.PI); ctx.stroke();
  ctx.fillStyle = c.ink;
  state.theta.forEach((th, i) => {
    if (!state.on[i]) return;
    const p = phase(th, state.omega[i]);
    ctx.beginPath(); ctx.arc(cx + R * Math.cos(p), cy - R * Math.sin(p), Math.max(4, R / 10), 0, 2 * Math.PI); ctx.fill();
  });
  const {r, psi} = order(state);
  ctx.strokeStyle = c.accent;
  ctx.lineWidth = 3;
  ctx.beginPath(); ctx.moveTo(cx, cy); ctx.lineTo(cx + r * R * Math.cos(psi), cy - r * R * Math.sin(psi)); ctx.stroke();
  ctx.fillStyle = c.muted;
  ctx.font = "14px system-ui, sans-serif";
  ctx.textAlign = "right";
  ctx.textBaseline = "top";
  ctx.fillText(`board motion ×${SCALE}`, W - 6, Y(0) + 4);     // under the floor, out of the readouts' corner
}

function render() {
  const c = colors();
  drawScene(c);
  const {r} = order(state);
  $("r").textContent = `r ${r.toFixed(2)}`;
  $("speed").textContent = `board ${(100 * state.vPeak).toFixed(1)} cm/s`;
  $("time").textContent = `t ${Math.floor(state.t)} s`;
  const locked = state.board !== "fixed" && state.tAbove !== null && state.t - state.tAbove >= 5;
  $("status").textContent = locked ? `in step after ${Math.round(state.tAbove - state.tFree)} s` : "";
  for (const b of ["fixed", "cans", "damped"]) $(b).setAttribute("aria-pressed", state.board === b);
  $("n2").setAttribute("aria-pressed", state.n === 2);
  $("n5").setAttribute("aria-pressed", state.n === N);
  const idx = MASSES.indexOf(state.boardMass);
  $("mass").value = idx;
  $("mass-val").textContent = `${state.boardMass} kg`;
  for (const id of ["mass", "lighter", "heavier"]) $(id).disabled = state.board === "fixed";
  $("play").textContent = state.running ? "Pause" : "Play";
  $("sound").textContent = state.sound ? "Sound on" : "Sound off";
}

// ---- controls, keys, and the loop
function set(partial) {
  const n = partial.n !== undefined && partial.n !== state.n;
  Object.assign(state, partial);
  if (n) start(state.n === N ? DATA.start : DATA.start2);
  else if ("board" in partial || "boardMass" in partial) settleBoard();
  render();
}

function toggle(i) {                                     // a swinging metronome stops at the bottom; a stopped one is let go at 34°
  if (i >= state.n) return;
  state.on[i] = !state.on[i];
  state.theta[i] = state.on[i] ? AMP : 0;
  state.omega[i] = 0;
  settleBoard();
  render();
}

let seed = 382;
function restart() {                                     // new random phases from a small seeded generator
  const rand = () => { seed = (seed * 16807) % 2147483647; return seed / 2147483647; };
  start(Array.from({length: state.n}, () => 2 * Math.PI * rand()));
  render();
}

const nudge = (d) => { const i = Math.min(MASSES.length - 1, Math.max(0, MASSES.indexOf(state.boardMass) + d)); set({boardMass: MASSES[i]}); };
const cycle = () => set({board: {fixed: "cans", cans: "damped", damped: "fixed"}[state.board]});

for (const b of ["fixed", "cans", "damped"]) $(b).addEventListener("click", () => set({board: b}));
$("n2").addEventListener("click", () => set({n: 2}));
$("n5").addEventListener("click", () => set({n: N}));
$("n5").textContent = N;                                 // the group's button names its size
$("mass").addEventListener("input", (e) => set({boardMass: MASSES[Number(e.target.value)]}));
$("lighter").addEventListener("click", () => nudge(-1));
$("heavier").addEventListener("click", () => nudge(1));
$("play").addEventListener("click", () => set({running: !state.running}));
$("restart").addEventListener("click", restart);
$("sound").addEventListener("click", () => { if (audio) set({sound: !state.sound}); else { wakeAudio(); render(); } });
document.addEventListener("pointerdown", (e) => { if (e.target !== $("sound")) wakeAudio(); });
canvas.addEventListener("pointerdown", (e) => {          // which metronome: the nearest column to the touch
  const box = canvas.getBoundingClientRect(), W = box.width, k = pixelsPerMeter(W, box.height);
  const x = (e.clientX - box.left - W / 2) / k - SCALE * state.x;
  const d = spots(state.n).map((sx) => Math.abs(sx - x)), i = d.indexOf(Math.min(...d));
  if (d[i] < 0.06) toggle(i);
});
document.addEventListener("keydown", (e) => {
  wakeAudio();
  const key = e.key.toLowerCase();
  const actions = {" ": () => set({running: !state.running}), b: cycle, "[": () => nudge(-1), "]": () => nudge(1),
    n: () => set({n: state.n === N ? 2 : N}), r: restart, s: () => set({sound: !state.sound})};
  if (/^[1-5]$/.test(key)) toggle(Number(key) - 1);
  else if (actions[key] && !(e.target instanceof HTMLButtonElement && key === " ")) { e.preventDefault(); actions[key](); }
});

let last = null, owed = 0, window_ = 0, vMax = 0;
function frame(now) {                                    // called by the browser once per screen refresh
  const elapsed = last === null ? 0 : Math.min((now - last) / 1000, 0.05);   // capped: a background tab does not jump
  last = now;
  if (state.running) {
    for (owed += elapsed; owed >= DT; owed -= DT) {    // fixed steps of DT; the remainder waits for the next frame
      step(state, DT);
      vMax = Math.max(vMax, Math.abs(state.v));
    }
    window_ += elapsed;
    if (window_ >= 0.6) { state.vPeak = vMax; vMax = 0; window_ = 0; }        // the peak speed over about one swing
    const {r} = order(state);
    if (r < R_LOCK) state.tAbove = null;
    else if (state.tAbove === null) state.tAbove = state.t;
  }
  render();
  requestAnimationFrame(frame);
}

start(DATA.start);
window.addEventListener("resize", layout);
layout();
requestAnimationFrame(frame);
window.game = {state, set, render};