Module 1 — Exterior calculus, the exactness rule and area-preserving phase space

Lecture notes, adapted to midi-sink as shipped (libsumi 1.12.0, Voxo 0.26.0, 2026-10-25). Section references: §4, §10.2, §10.3, §13 are docs/PROJECT_SPEC.md — spec v6 since the fold of 2026-10-26, §10.7, §10.8 and §13.13 with them; KESSHO §n is the Kessho proposal, in git history (21ff974:_work/specs/medium_specs_v3.md), its substance §10.7. Every number quoted below is a gate’s printout (the headless suite, the desktop bench’s --dev gates, the decision log) — none is estimated.

1.1 Historical prologue: from crystal optics to symplectic geometry

Symplectic geometry was born in 1832 not in mechanics but in crystal optics, when William Rowan Hamilton used his characteristic function to predict conical refraction in biaxial crystals. midi-sink keeps the lineage in two places. The crystal drop of the Kessho medium (SUMI_MEDIUM_KESSHO, libsumi 1.6.0; the minerals 1.7.0) is written in Hamilton’s action-angle coordinates, where Jaffer’s expansion becomes a translation and a crystal habit becomes a kick generated by a function of the angle alone (§1.4, Family 3). And the Barite mineral carries Hamilton’s hollow cone as a stylisation: where the trace discriminant is near zero and the sheet strains, the caustic’s light is read through a ring kernel of eight points (conical_ring, §10.7.8) — a line on the fold doubling into two. The engine does not solve Fresnel’s wave surface; it reads a strained sheet between crossed polarizers.

Whether we track light through strained calcite, pigment rings floating on water (Sumi, the suminagashi medium), or the phase-space trajectory of an oscillator (Suzu, the synth inside Voxo), the governing structure is the same closed, non-degenerate differential 2-form $\omega$, and the one rule that is never broken is the canvas’s own: no element may create area it was not handed (the DSP class table).

1.2 Differential forms and symplectomorphisms in 2D and 4D

Let $M = \mathbb{R}^{2n}$ (or a cotangent bundle $T^*Q$) be phase space with canonical coordinates $(q_1, \dots, q_n, p_1, \dots, p_n)$.

1. The tautological 1-form. On $T^*Q$ the canonical 1-form is $\theta = \sum_i p_i\, dq_i$. Integrating $\theta$ around a closed loop $\gamma = \partial\Sigma$ measures the action $I = \frac{1}{2\pi}\oint_\gamma p\, dq$.

2. The symplectic 2-form. Its exterior derivative is the canonical 2-form

   $\omega = -d\theta = \sum_{i=1}^{n} dq_i \wedge dp_i .$

   Because $d^2 = 0$, $\omega$ is exact on $\mathbb{R}^{2n}$ and therefore closed: $d\omega = 0$. (On a general symplectic manifold only closedness is required; exactness is the special gift of $\mathbb{R}^{2n}$ and of cotangent bundles, and it is what lets §1.4 write every exact operator from a generating function.)

3. Symplectomorphisms and $\det J = 1$. A smooth map $\Phi: M \to M$ is a symplectomorphism if it preserves the 2-form under pullback, $\Phi^*\omega = \omega$. In 2D ($n = 1$: the libsumi canvas $(x, y)$, or a single Suzu cell $(x, y)$), $\omega = dx \wedge dy$ is the oriented area form. For $\Phi(x, y) = (u(x, y), v(x, y))$ with Jacobian

   $J = D\Phi = \begin{pmatrix} u_x & u_y \\ v_x & v_y \end{pmatrix},$

   the pullback is evaluated directly by the wedge product:

   $\Phi^*(dx \wedge dy) = du \wedge dv = (u_x v_y - u_y v_x)\, dx \wedge dy = (\det J)\, dx \wedge dy .$

   Thus on a 2D manifold $\Phi$ is symplectic if and only if $\det J = 1$ everywhere. This is the sentence the whole engine is built on: the operator book’s exact class is “det J = 1 at any magnitude” (§10.2), and Suzu’s symplectic row is “det of the per-sample map = 1 exactly” (§13.1).

1.3 Why Eulerian grids fail and why libsumi stores displacements

Advect pigment on a grid with an Eulerian velocity solver and the bilinear interpolation of pigment density introduces numerical diffusion that blurs sharp suminagashi rings into mud within seconds (§4, the founding rule: no Navier–Stokes solvers; the Lamb–Oseen swirl is Navier–Stokes entering as an exact solution, §4.3(7)).

libsumi instead models deformation as a group composition of closed-form inverse-lookup symplectomorphisms on two ping-pong textures, tex_A and tex_B, RGBA16F by default (RGBA32F behind a desktop quality flag; §4.1). For every output texel $P$ the engine asks where that water came from, $P_{src} = \Phi^{-1}(P)$, and reads the ink there.

Rather than storing the raw pre-image coordinates $(u, v)$ — where half-float precision degrades to $2^{-11}$ across the outer half of the canvas — each texel stores, since libsumi 1.2.0 (Phase 8 step 55b, DECISIONS_7 #1), the accumulated displacement from the identity:

$d(P) = P_{pre}(P) - P = (u - x,\; v - y), \qquad \text{payload } (u - x,\; v - y,\; \text{ink},\; \text{aux}).$

At rest $d(P) = (0, 0)$, so the half-float quantum follows the displacement: $2^{-24}$ canvas heights at rest, $2^{-15}$ at a sixteenth of the canvas. When a new pass with inverse map $\Phi^{-1}(P) = P_{src}$ is applied, the shader re-bases the lookup (§4.2):

$d'(P) = d(P_{src}) + (P_{src} - P).$

Because the Jacobian of a composition is the product of Jacobians, $J(\Phi_2 \circ \Phi_1) = (J\Phi_2)(J\Phi_1)$, composing any number of $\det J = 1$ passes preserves $\det J = 1$ to floating-point rounding — and the regression check that proves the composition is exact is that forty passes of a $z/40$ tine equal one pass of a $z$ tine (§4.6).

1.4 The exactness rule (§10.2 additions, KESSHO §2.1)

In interactive graphics we want deformations that are spatially localized — decaying away from a note’s cell. But multiply a symplectic kick or shear by a naive radial window $W(r)$ and you immediately break $\det J = 1$.

Proposition 1.1 (the windowed-kick defect)

Take action-angle polar coordinates $(\rho, \theta)$ about a drop centre, with $\rho = \tfrac12 r^2$ so that $dx \wedge dy = r\, dr \wedge d\theta = d\rho \wedge d\theta$ is canonical. Apply a radially windowed action kick without touching the angle:

$\rho_1 = \rho - W(\rho)\, V'(\theta), \qquad \theta_1 = \theta .$

Then

$$J = \begin{pmatrix} 1 - W'(\rho) V'(\theta) & -W(\rho) V''(\theta) \\ 0 & 1 \end{pmatrix} \quad\Longrightarrow\quad \det J = 1 - W'(\rho)\, V'(\theta) \neq 1 .$$

Any spatial window on the coordinate being kicked breaks area conservation by (window slope) × (kick). This is not a hypothetical: it is the desktop bench’s red control. midi-sink --dev --kessho-flat evaluates the first draft’s windowed Arnol’d kick on the CPU beside the shipped operators and reads $|\det J - 1|$ of 50 at the maximum and 0.35 rms, as required (DECISIONS_10 #4).

From this the spec states the rule every new operator is written under (§10.2 additions):

Exact + localised ⟹ twist-type, or generating-function (implicit, Newton in the shader), or a kick generated by a function of the angle alone. Everything else is sub-stepped and must say so.

These notes sort the shipped operators into four constructions. The spec’s three families are Families 2, 4b and 3 below; Family 1 is the “shear that ignores its own coordinate” the spec’s first sentence names, and Family 4a is the pinch’s own trick, exact but not compactly supported.

Family 1 — pure coordinate shears (tines, cleavage profiles, the sine ripple, the chord wave)

In a local frame $(x, y)$ aligned with a stroke direction $\hat D$, let

$x_{src} = x - F(y), \qquad y_{src} = y .$

Because $F$ depends only on $y$, the Jacobian is upper-triangular with ones on the diagonal:

$J = \begin{pmatrix} 1 & -F'(y) \\ 0 & 1 \end{pmatrix} \quad\Longrightarrow\quad \det J = 1 \quad \forall F .$

This holds for every tine profile the engine ships (tine_profile, §10.7.8, deform.glsl’s tine_fs), with $d = |y|$ the perpendicular distance, $H = 4\alpha$ and $u = d/H$:

profile	$F$	where $J$ jumps
SUMI_TINE_SMOOTH (0) — Jaffer	$z\,\alpha/(\alpha + d)$, bitwise the v2 tine	nowhere
SUMI_TINE_TWIN_KINK (1) — Baumhauer’s lamella	$1$ for $u < 1/3$, then $1.5(1 - u)$ to zero at $u = 1$	two kink lines, which Kessho draws as the lamella’s edges
SUMI_TINE_TERRACE (2) — phyllosilicate slip	$v - \sin(2\pi N v)/(2\pi N)$, $v = 1 - u$ clamped, $N = 4$ flat terraces	the terrace risers

Every profile is a bump, zero beyond $H$. The first draft’s monotone ramp and staircase were exact too, but a monotone shear pulls texels in from outside the canvas and fabricates ink — the soak measured −99.9 % of the mass in 500 “pairs” (an odd profile reversed is the same shear, so $\pm z$ is not a pair). The bench keeps that fault as profile 3, dev only, as --tine-fault’s red control (DECISIONS_10 #6). The sine ripple $A\sin(ky + \phi)$ (§4.3(6)) and the chord wave — a ripple-tine windowed across its band, i.e. by the coordinate the shear ignores (§10.8.2) — are the same family.

Family 2 — twist maps in action-angle coordinates (vortices, Lamb–Oseen, torsion, Chladni)

In $(\rho = r^2/2, \theta)$, rotate the angle by a function of $\rho$ alone:

$$\rho_{src} = \rho, \qquad \theta_{src} = \theta - \Theta(\rho) \quad\Longrightarrow\quad J_{(\rho,\theta)} = \begin{pmatrix} 1 & 0 \\ -\Theta'(\rho) & 1 \end{pmatrix}, \quad \det J = 1 .$$

Twist maps are the one explicit family that is both exact and compactly supported in $r$ (§10.2 additions). That is why, as shipped in vortex_fs, swirl_fs and cells_fs, none of these needs sub-stepping at any amplitude and every $\pm A$ pair inverts analytically:

• the exponential vortex $\Theta(r) = A\, e^{-r/R}$ and the Rankine vortex (rigid for $r < R$, $\omega R^2/r^2$ outside — all the shear in the crease ring at $R$) — §4.3(3);
• the Lamb–Oseen swirl $\Theta(r) = \dfrac{S}{2\pi r^2}\left(1 - e^{-r^2/r_c^2}\right)$, $S = \Gamma\,\Delta t$ — §4.3(7), the viscous rotation, $C^\infty$;
• the wave torsion $\Theta(r) = A\sin(kr - \phi)\, e^{-r/R}$ — §10.3, rings of alternating angular shear, an outward wave when $\phi$ sweeps;
• the Chladni eddy, the exact rotation of one disc of radius $R$ by $\Theta = \theta_0\, w\, \big(4 s^2 (1 - s^2)\big)^2$ with $s = r/R$ — the ring peaks at $s = 1/\sqrt2$ and vanishes at the centre and the rim (cells_fs, mode 0; its mode 1, the summed “inverse Chladni” field, is the sub-stepped class).

Family 3 — angle-generated kicks: the symplectic crystal-drop theorem (§10.7.8)

Exchange the roles of $\rho$ and $\theta$ and kick $\rho$ by a potential $V(\theta) = \tfrac12 R(\theta)^2$ that depends on the angle alone:

$\rho_{src} = \rho - \tfrac12 R(\theta)^2, \qquad \theta_{src} = \theta \qquad (r \ge R(\theta)).$

In the Cartesian radius $r = \sqrt{2\rho}$ this maps each ray $\theta$ monotonically onto itself, $r_{src} = \sqrt{r^2 - R(\theta)^2}$. Its Jacobian in $(\rho, \theta)$ is

$$J_{(\rho,\theta)} = \begin{pmatrix} 1 & -R(\theta) R'(\theta) \\ 0 & 1 \end{pmatrix} \quad\Longrightarrow\quad \det J = 1 \text{ identically.}$$

For $R \equiv r_0$ this is Jaffer’s circular drop, the translation $\rho_{src} = \rho - r_0^2/2$; drop_habit 0 is bitwise the v2 drop.

Consequences, as ratified in §10.7.8 and built in drop_fs: (1) a drop need not be circular to be exact — any star-shaped habit $R(\theta) > 0$ conserves area identically, at any amplitude, with no sub-stepping; (2) boundary growth is free — scaling $R \to sR$ is the same map; (3) the interior ink phase is assigned from $r / R(\theta)$, so the rings inside are homothetic copies of the habit; (4) corners crease — where $R'$ jumps, $J$ jumps across the vertex ray, and the bands outside crease along it; in Kessho that crease is a birefringence line and reads as cleavage. The shipped habits, in the drop’s own frame (the strike’s angle), softened by a log-sum-exp with $k = 2 + 40(1 - \text{roundness})^2$ and then mixed toward the circle by habit_roundness:

drop_habit	$R(\theta)$	paired by the presets with
SUMI_HABIT_RHOMB (1) — the calcite cleavage rhomb, faces 78.1° / 101.9°	$r_0 / \max\big(\lvert\sin\theta\rvert, \lvert\sin(\theta - A)\rvert\big)$, $A = 78.1°$, $r_0$ the inradius	Calcite, Selenite (gypsum’s cleavage plate)
SUMI_HABIT_HEX (2) — the regular hexagon	$r_0 / \max_i \lvert\cos(\theta - 60°\, i)\rvert$	Quartz, Muscovite’s pseudo-hexagonal sheet, Fluorite (the cube on its diagonal)
SUMI_HABIT_ROSETTE (3) — $m$ tabular blades, habit_blades	$r_0\,(1 + \beta\cos^{8}(m\theta)) / (1 + \beta\cdot 35/128)$, $\beta = 0.6$, the mean radius $r_0$	Barite, $m = 5$

The pairing is the shells’ and the six presets/kessho_<mineral>.json; the optical half and the mechanical half are independent parameters, and a Calcite optic over a Barite rosette is allowed.

Family 4 — invariant-streamline windows and generating functions

4a. The Hamiltonian pinch (§4.3(5)). The global hyperbolic saddle $x_{src} = x e^{k}$, $y_{src} = y e^{-k}$ is generated by $H(x, y) = xy$. Because $s = xy$ is conserved along every trajectory, windowing the exponent by $w(s) = e^{-|s|/S}$ keeps the map closed-form:

$x_{src} = x\, e^{+k\, w(xy)}, \qquad y_{src} = y\, e^{-k\, w(xy)},$

and with $w' = dw/ds$,

$\det J = \big(1 + k s w'\big)\big(1 - k s w'\big) - \big(k x^2 w'\big)\big(-k y^2 w'\big) = 1 - k^2 s^2 w'^2 + k^2 s^2 w'^2 = 1 .$

The caveat the spec states as a feature: the window cannot decay along the two fold axes themselves ($s = 0$ there), so the pinch’s arms run outward as fading creases — which is what pinched paper does. The window is in $s$, not in $r$, so the pinch is exact but not compactly supported: it is not a counterexample to Family 2’s uniqueness.

4b. Type-2 generating functions — the Arnol’d tongue lock (SUMI_DEFORM_ARNOLD, §10.8.1). When a kick must be radially windowed by $W(\rho_1)$, derive the map from a mixed-variable generating function $F_2(\theta, \rho_1) = \theta\rho_1 + \frac{K}{q} W(\rho_1)\cos q(\theta - \varphi)$:

$$\rho = \frac{\partial F_2}{\partial \theta} = \rho_1 - K\, W(\rho_1) \sin q(\theta - \varphi), \qquad \theta_1 = \frac{\partial F_2}{\partial \rho_1} = \theta + \frac{K}{q}\, W'(\rho_1) \cos q(\theta - \varphi).$$

The radial slope $W'$ is compensated by an angular twist, and $\det J = 1$ exactly because the map is canonical by construction. As shipped in arnold_fs: one iteration $M = T \circ \text{Kick}$ about a voice’s drop, the twist $T$ a Lamb–Oseen-shaped rotation with $\Theta(R) = 2\pi\Omega_0$ turns, $C^2$-windowed to zero by $2.5R$; $W = 1$ on $[\rho_{drop}/2, \rho_{drop}]$ with quintic ramps to zero at the centre (a bijection needs $W(0) = 0$) and at $1.5\rho_{drop}$; the lookup is $M^{-1}$ — the twist undone, then the kick’s inverse by one scalar Newton iteration on $\theta$, five steps, monotone while $|K W'| < 1$, hence $K \le K_{max} = 0.8 / \max|W'|$. It is Kessho’s press default (press_mode 3): the tempered fifth’s two-cent beat precesses the islands.

1.5 Reading the Jacobian with shaders: Sumi, Anod and Kessho (§10.7.1–§10.7.4)

From the stored displacement $d(x, y) = (u - x, v - y)$ the composite shader reconstructs the inverse-lookup Jacobian $J = I + \nabla d$ by finite differences:

$J = \begin{pmatrix} 1 + \partial_x d_x & \partial_y d_x \\ \partial_x d_y & 1 + \partial_y d_y \end{pmatrix}.$

Two stencils, as shipped in composite.glsl: the short one (Anod’s, one-sided minimum, the half-float rounding bias subtracted) gives $\psi$ and $\sigma$; the trace for Layer B is read from a wide window (±3 texels at 512), because the fold at a large $z$ sits a few hundredths above $\operatorname{tr} J = 2$ and a texel-wide difference would read the quantum.

Take the polar decomposition $J = R_\phi\, U(\psi, \lambda)$, with $R_\phi$ a rotation and $U$ symmetric positive-definite, principal stretches $\lambda \ge 1 \ge \lambda^{-1}$ along the axis $\psi$. $J$ is the inverse map’s Jacobian, so $C = J^T J$ is the forward flow’s left Cauchy–Green tensor — Eulerian, which is what a polarizer on the screen sees (§10.7.1). Because $\det J = 1$, every spectral invariant reduces to the Frobenius norm $\lVert J\rVert_F^2$ and the trace $\operatorname{tr} J$:

1. Principal strain and the birefringence retardation (Anod, Kessho Layer A). Since $\lambda^2 + \lambda^{-2} = \operatorname{tr}(J^T J) = \lVert J\rVert_F^2$, $(\lambda - \lambda^{-1})^2 = \lVert J\rVert_F^2 - 2$, so the scalar shear strain is

   $\sigma = \lambda - \lambda^{-1} = \sqrt{\lVert J\rVert_F^2 - 2},$

   and the principal axis is

   $\psi = \tfrac12 \operatorname{atan2}\big(2 C_{12},\; C_{11} - C_{22}\big), \qquad C = J^T J .$

   Since 3.0 Layer A reads $\sigma$ through the strain buffer — averaged over the afterglow’s seconds (§10.10) — so the fringes build and settle instead of snapping. Layer A is then the mineral’s optical law (§10.7.8):

   $I_A = I_{\text{backlight}} \cdot \text{body} \cdot \text{brush}(\psi, \alpha) \cdot \mathrm{ML}(\Gamma\sigma),$

   with the brush by optic class — isotropic: dark (Fluorite shows Layer B alone); uniaxial: $\sin^2 2(\psi - \alpha)$, the isoclinic brush that paints the dark Maltese cross in a vortex’s shear annulus (Quartz, Calcite, Selenite); biaxial: the cross splits into two brushes $2V$ apart, $\lvert\cos^2 2V - \cos^2 2(\psi - \alpha)\rvert / \max(\cos^2 2V, \sin^2 2V)$ — a stylisation of the conoscopic figure, since that law lives in angle space, which a texel does not have (Muscovite $2V = 40°$, Barite $37°$). $\Gamma$ is the mineral’s retardation at unit strain scaled by the Exposure knob (kessho_retard/2000 — the ratios between minerals are physical, $\Delta n$), and $\mathrm{ML}$ is the Michel–Lévy chart as a 1024-texel LUT the engine builds from a spectral integration against the CIE 1931 curves (core/src/kessho_lut.h, tools/kessho_lut.py; beyond 2200 nm the orders wash to high-order white). The sensitive-tint plate (Selenite, $\Gamma_0 = 550$ nm) replaces the brush by $\Gamma_{\text{eff}} = \lvert\Gamma_0 + \Gamma\sigma\sin 2\psi\rvert$: the sign of the strain becomes visible. The three-channel $\sin^2(\pi\Gamma\sigma/\Lambda_{RGB})$ form is the fallback for the web demo only (KESSHO §1.2) — it is what the standalone lab below uses.

2. The trace discriminant: the elliptic/hyperbolic partition (Kessho Layer B). The eigenvalues of $J \in SL(2, \mathbb{R})$ satisfy $\mu^2 - (\operatorname{tr} J)\mu + 1 = 0$, with discriminant $\Delta = (\operatorname{tr} J)^2 - 4$:

   • elliptic, $\Delta < 0 \iff \lvert\operatorname{tr} J\rvert < 2$: purely rotational motion ($\mu = e^{\pm i\phi}$; vortex cores, Chladni eddies) — the cool tint;
   • hyperbolic, $\Delta > 0$: exponential stretching along unstable manifolds (saddles, wakes, Chirikov chaos) — the warm tint;
   • parabolic, $\Delta = 0$: the order-to-chaos boundary.

   The tint’s weight is $\text{smoothstep}(0.05, 0.8, \lvert\Delta\rvert)$ — the staircase’s noise sits under 0.05. The honest headline (§10.7.1): rigid rotation has $C = I$, so $\sigma = 0$ and $\psi$ is undefined — Layer A is dark exactly where Anod is dark, and $\operatorname{tr} J = 2\cos\phi$ is the only local observable that detects rigid elliptic rotation. What Kessho adds over Anod is orientation ($\psi$) and rotation ($\operatorname{tr} J$).

3. The collapsed Lagrangian caustic and the $z = 1$ flatness gate (§10.7.3). Refract rays through the displacement gradient $\nabla d = J - I$ onto a bed at depth $z$; the light focuses inversely to the ray-map determinant. For any $2\times2$ matrix, expanding $\det((1 - z)I + zJ)$ gives

   $\det(I + z\nabla d) = (1 - z)^2 + z(1 - z)\operatorname{tr} J + z^2 \det J .$

   • When $\det J = 1$: $(1 - z)^2 + z^2 = 1 - 2z(1 - z)$, and the determinant collapses to Kessho’s one line, exactly as kessho_caustic_w evaluates it:

     $\det(I + z\nabla d) = 1 + z(1 - z)\,(\operatorname{tr} J - 2).$

     The fold ($\det = 0$) is an iso-trace contour, not the parabolic horizon: for $z > 1$ it sits on $\operatorname{tr} J = 2 + \dfrac{1}{z(z - 1)}$ and sweeps from $+\infty$ toward $2^+$ as $z \to \infty$, so the depth control (caustic_z, 1.05..8, log-spaced) scans a level set of $\operatorname{tr} J$ through the hyperbolic regime toward the parabolic horizon. The shader draws it as a line (by fwidth) over a soft glow, and Barite’s dispersion reads it at three depths $z/\sqrt{1 + d},\, z,\, z\sqrt{1 + d}$ — a rainbow on the fold.

   • When $z = 1$: the uncollapsed determinant is $\det J$ itself. Evaluating it at $z = 1$ is therefore a direct detector of $d\omega \ne 0$: any exact operator renders flat, and a windowed kick lights up. The depth 1 is reachable only through the dev flag, and --kessho-flat <operator|all> is the gate — as measured (DECISIONS_10 #4), not as proposed: the identity sheet reads 0 exactly; an exact Lamb–Oseen twist on the CPU reads $1.4\cdot10^{-3}$ at the maximum (the stencil’s truncation); the GPU’s three-drop scene reads a median of $2\cdot10^{-3}$ (±3 texels) to $5\cdot10^{-3}$ (±1), with a p99 of 0.2–0.8 and a maximum of 8–30 owned by the drops’ rims, where the inverse of an exact expansion has an unbounded radial derivative — the pre-image’s one singularity, exact and unresolvable by any stencil, so the rims are masked. A few thousandths is the field’s floor; the proposal’s $10^{-4}$ cannot be held by a half-float field, and the class stays declared, with the gate as its runtime check.

1.6 Phase space in audio: Suzu’s magic circle, retuning and twisted 2-forms (§13)

Now drop from the 512 × 512 canvas to a single oscillator voice in Suzu (voxo/src/suzu.h, struct Cell). Where the canvas says area-preserving, the synth says amplitude-stable.

1. The symplectic magic circle versus the naive update (§13.2)

A harmonic oscillator of frequency $f$ at sample rate $f_s$ has the step parameter $\varepsilon = 2\sin(\pi f / f_s)$ — the prewarp, so the discrete rotation angle is exactly $2\pi f/f_s$.

The naive simultaneous update (update_mode 1, the lab’s red control; Cell::step_naive, the suite’s negative control):

$$x_{n+1} = x_n - \varepsilon y_n, \quad y_{n+1} = y_n + \varepsilon x_n \quad\Longrightarrow\quad J = \begin{pmatrix} 1 & -\varepsilon \\ \varepsilon & 1 \end{pmatrix}, \quad \det J = 1 + \varepsilon^2 > 1 .$$

Phase-space area grows by $1 + \varepsilon^2$ every sample. The suite’s drift gate at 440 Hz, $A = 0.5$, 48 kHz: over the 0.1 dB bound at 1.0 s and +690.2 dB after 600 s.

The symplectic leapfrog, the magic circle (update_mode 0, Cell::step): using the already-updated $x_{n+1}$ in the $y$ update composes two exact shears:

$x_{n+1} = x_n - \varepsilon y_n, \qquad y_{n+1} = y_n + \varepsilon x_{n+1} = \varepsilon x_n + (1 - \varepsilon^2) y_n ,$

$$J = \begin{pmatrix} 1 & 0 \\ \varepsilon & 1 \end{pmatrix}\begin{pmatrix} 1 & -\varepsilon \\ 0 & 1 \end{pmatrix} = \begin{pmatrix} 1 & -\varepsilon \\ \varepsilon & 1 - \varepsilon^2 \end{pmatrix} \quad\Longrightarrow\quad \det J = 1 \text{ identically.}$$

Moreover $\operatorname{tr} J = 2 - \varepsilon^2 = 2 - 4\sin^2(\pi f/f_s) = 2\cos(2\pi f/f_s) \in (-2, 2)$ for all $f < f_s/2$, so $\Delta < 0$: the oscillator is strictly elliptic — §1.5’s partition, one octave down — with the exact rotation angle $\phi = 2\pi f/f_s$. The same gate: ten minutes undriven and undamped, amplitude +0.0001 dB, frequency +0.000 cent; the tuning within 0.000 cent across MIDI 21–108 at 44.1 and 48 kHz.

2. The skewed invariant and MPE retuning (Cell::retune)

$\det J = 1$ guarantees bounded orbits, but the magic circle’s level curves are not circles $x^2 + y^2 = A^2$; they are the $\varepsilon$-sheared ellipses

$I_\varepsilon(x, y) = x^2 + y^2 - \varepsilon x y = A^2\Big(1 - \frac{\varepsilon^2}{4}\Big),$

on which $x$ peaks at $A$ where $y = \varepsilon x/2$ — the point the strike sets (Cell::kick: $x = A$, $y = \varepsilon A/2$).

When an MPE performer glides a note, $\varepsilon$ changes every frame. Change $\varepsilon \to \varepsilon'$ with the state left as it is and the state sits on an orbit of a different amplitude: the plain retune (retune_mode 1, Cell::retune_plain, “the printed justification, never the shipped sound”). What ships is a re-base onto the orbit of the held amplitude: with the new $\varepsilon'$, read the invariant the state would have, $q = x^2 + y^2 - \varepsilon' x y$, the $x$-amplitude it implies, $a = \sqrt{q / (1 - \varepsilon'^2/4)}$, and scale the state by $s = A/a$:

$(x, y) \;\mapsto\; \frac{A}{a}\,(x, y), \qquad \text{one rsqrt per retuned sample, none while } \varepsilon \text{ holds.}$

Note what this is and is not. It is a homothety, $\det = s^2$ — not itself a symplectic map, and the engine’s class table says so in its own words: “symplectic (a rescale to the same orbit)”. What makes it legitimate is the discipline of the projected row of the DSP class table: it measures a no-op whenever $\varepsilon$ holds ($s = 1$ exactly) and its work during a glide is bounded and gated. The suite’s glide gate, −48 to +48 semitones over 2 s through the ABI (step 86’s run): re-based 0.097 dB of amplitude ripple (the bound 0.5); the plain recurrence under the per-sample ramp 0.057 dB and stepped once per block 0.062 dB, both printed, not gated. (The cells chapter quotes 0.63 dB for a one-block jump from the first landing; the suite’s current printout is the number to teach from, and the two should be reconciled.) Problem 1.3 compares this rescale with the shear-scale alternative that keeps $x$ and moves $y$ onto the new ellipse.

3. Non-canonical closed 2-forms: the Boris–leapfrog magnetic gyroscope (voice_kind 11, §13.13)

Must a symplectic 2-form be the canonical $\omega_0 = dp_1 \wedge dx_1 + dp_2 \wedge dx_2$? Take a charged 2D oscillator in a perpendicular magnetic field $B$. The Lorentz force is encoded not by changing $H = \tfrac12\lvert p\rvert^2 + V(x)$ but by twisting the 2-form:

$\omega_B = dp_1 \wedge dx_1 + dp_2 \wedge dx_2 + B(x_1, x_2)\, dx_1 \wedge dx_2 .$

On $\mathbb{R}^4$, $d(B\, dx_1 \wedge dx_2) = \partial_{x_1}B\, dx_1 \wedge dx_1 \wedge dx_2 + \partial_{x_2}B\, dx_2 \wedge dx_1 \wedge dx_2 = 0$, so $\omega_B$ is closed for any smooth $B(x_1, x_2)$. (Suzu’s field is uniform over the voice and varies only in time: boris_b in hertz, 0..50, the poly pressure’s — rest + (full − rest) · swirl.)

The scheme, suzu::Gyro::step, with $y = \dot x/\omega_0$ in the cell’s units so that a free orbit is a circle of radius $A$: the half kick $y \mathrel{-}= (\varepsilon/2)\, x$; the Cayley rotation of the velocity by $\theta_B$, written as three shears — $y_1 \mathrel{-}= t\, y_2$, $y_2 \mathrel{+}= s\, y_1$, $y_1 \mathrel{-}= t\, y_2$ with $t = \tan(\theta_B/2)$, $s = \sin\theta_B$, exactly the rotation matrix — the Lorentz force does no work, so $\lvert y\rvert$ is left as it was; the half kick again; the drift $x \mathrel{+}= \varepsilon\, y$. Every factor is a shear, so $\det J = 1$ on the 4D state and the energy breathes with the kick’s splitting but does not drift: ten minutes at 96 kHz under a 20 Hz field, $H$ within ±0.031 dB, the minute means drifting 0.000000 dB. The reason for three shears rather than a cos/sin matrix is a Module-1 lesson in itself: a matrix whose $c^2 + s^2$ misses 1 by a unit in the last place scales the energy by that every step — $e^{\pm 1.7}$ over ten minutes — where the shears round as a walk, not a bias.

Both the spring and the field are prewarped, $\varepsilon = 2\sin(\omega_0 dt/2)$ and $\theta_B = \omega_B dt$ (the Boris angle $2\arctan(B_{num}dt/2)$ with $B_{num} = (2/dt)\tan(\omega_B dt/2)$). The degenerate 2D oscillator then splits into a chiral Zeeman doublet, one circular mode each way round the field:

$\omega_\pm = \sqrt{\omega_0^2 + \Big(\frac{\omega_B}{2}\Big)^2} \pm \frac{\omega_B}{2}.$

On $z = x_1 + i x_2$, $w = y_1 + i y_2$ the step is complex-linear with determinant $e^{i\theta}$ and the two angles $\theta/2 \pm \psi$, $\cos\psi = \cos(\theta/2)(1 - \varepsilon^2/2)$: the doublet to $(\omega_B dt/2)^2/6$, measured within 0.001 cent of the formula over five notes and six fields; with the prewarp off (boris_prewarp 0, the lab’s red) the pair is 1.21 cents sharp at B6. Sending $(x_1, x_2)$ straight to $(L, R)$ makes it the engine’s first stereo voice — a mono line without the field, a precessing rosette under the finger’s pressure — and the orbit trace draws the same pair into the water as a spirograph; the strobe’s own clock is the cyclotron period.

Beyond the cell. The same discipline carries the voices Phase 14 added, each in the class table with its red control: the Toda ring’s leapfrog in double with the minute-mean $H$ drifting 0.000017 dB over ten lossless minutes (Toda ring); the billiard’s exact rotation and specular reflection, $\det J = +1$ on the 4D state to $2\cdot10^{-12}$ dB over 66 000 collisions (Billiard); the Dirac network’s Cayley step $M = (I - \tfrac{h}{2}A)^{-1}(I + \tfrac{h}{2}A)$, lossless over a random skew $J$ to $2\cdot10^{-16}$ (Dirac network). Module 2 takes them up.

---

Module 1 Lab: exactness, Kessho flatness, and Suzu phase space

Objectives and deliverables

1. Task 1 — the symplectic crystal drop and its cleavage creases (shader). On the desktop bench: midi-sink --dev --habit-test (the homothety, the growth, the crease pair, calcite with the twin kink, the pass count) and --habit-corner <dir>, which renders the crease pair at roundness 0 and 1 and prints both contrasts; then --soak crystal_drop and --kessho-flat drop. Report $|\det J - 1|$‘s median, p99 and maximum and say which texels own the maximum (the rims) and why the gate masks them. In the standalone lab, replace the circle with the calcite rhomb or the five-bladed Barite rosette and watch the vertex rays appear in Layer A as the roundness goes to zero.

2. Task 2 — catching the non-symplectic leak at $z = 1$ (shader). Compare the Hamiltonian pinch ($w(s) = e^{-|xy|/S}$) with a naively radial-windowed kick ($\rho_{src} = \rho - k\,e^{-r^2/R^2}\sin 3\theta$, $\theta_{src} = \theta$). On the bench, --kessho-flat pinch prints the shipped operator beside the estimator’s CPU controls — the exact twist and the first draft’s windowed kick — in one run. In the standalone lab, toggle the $z = 1$ view (u_viewMode 2): prove analytically and visually why the pinch stays flat while the windowed kick glows, $\det J = 1 - W'(\rho) V'(\theta)$.

3. Task 3 — the magic circle, Cell::retune and the gyroscope (audio). Open the engine’s own lab page, /marble/suzu/cell.html (the book’s Cells chapter embeds it): the strip under the orbit tracks $x^2 + y^2 - \varepsilon xy$; the checkbox The naive update (update_mode 1) is the red control — at A3 the orbit grows twenty-thousandfold a second until the worklet mutes full scale and restarts the engine; the retune select switches retune_mode. Then on the desktop, the Gyroscope (Zeeman stereo) patch with the synth trace on: raise the field with pressure, hear the doublet open, set boris_prewarp 0 and measure the pair against the formula. The standalone lab repeats the three with its own state.

The standalone lab file

module_01_lab.html, beside these notes, is a single-file WebGL2 + WebAudio harness: it implements the ping-pong displacement field (in RGBA32F, where the engine’s is RGBA16F), the four operators above plus the red control, Kessho’s Layer A and Layer B, the $z = 1$ diagnostic, and a two-plane Suzu oscillator with the Boris rotation and a phase-space scope. It is a teaching re-implementation, not the engine — the book’s rule is that there is no second implementation of any operator or voice on the site, so this file stays with the lessons and is never embedded in the book. Where it departs from the engine it says so in its comments; where it could follow the engine it does: the habit profiles are drop_fs’s support forms with the same log-sum-exp softening, the retune is Cell::retune’s rescale (with the plain form and the shear-scale of Problem 1.3 beside it), the gyroscope step is suzu::Gyro::step’s half kick, three shears, half kick and drift, and the Michel–Lévy colour is the three-channel fallback KESSHO §1.2 names for the web. It also obeys §4.6’s orientation rule — one texture space in every pass, the only flip at the pointer — and the rule earns its place here: with a flip inside the chain the passes mirror instead of composing, and the $z = 1$ view lights the whole canvas. Read back from the lab’s field (±1 texel, the band boundaries skipped), its exact operators sit at the estimator’s floor — the swirl at a median of $3\cdot10^{-4}$, the crystal drops at $2\cdot10^{-4}$ with their rims owning the maximum, the pinch at $8\cdot10^{-6}$ — and the windowed kick reads a p99 of 0.25 and a maximum of 0.52: the same picture as the engine’s gate, two orders of magnitude apart in resolution.

Problem set

1. Problem 1.1 — the collapsed Kessho caustic identity (§10.7.3). Let $d = (u - x, v - y)$ be the stored displacement, $J = I + \nabla d$.

   • (a) Prove that for any differentiable 2D map, $\det(I + z\nabla d) = (1 - z)^2 + z(1 - z)\operatorname{tr} J + z^2 \det J$.
   • (b) Show that if the chain consists of exact symplectomorphisms only, this is Kessho’s $\det(I + z\nabla d) = 1 + z(1 - z)(\operatorname{tr} J - 2)$, and locate the fold for $z = \tfrac12$, $z = 2$ and $z \to \infty$.
   • (c) Explain why a vortex’s rigid core ($J = R_\phi$, $\lambda = 1$) gives zero birefringence in Layer A ($\sigma = \sqrt{\lVert J\rVert_F^2 - 2} = 0$) yet is tinted by Layer B, $\Delta = (\operatorname{tr} J)^2 - 4 = 4(\cos^2\phi - 1) < 0$ — and why the Maltese cross forms in the Lamb–Oseen vortex’s shear annulus, not in a Rankine core.

2. Problem 1.2 — the crystal-drop theorem and cleavage creases (§10.7.8). Under SUMI_MEDIUM_KESSHO a crystal drop of profile $R(\theta) > 0$ has the inverse lookup $r_{src} = \sqrt{r^2 - R(\theta)^2}$ along each ray for $r \ge R(\theta)$.

   • (a) In $(\rho = r^2/2, \theta)$ compute the pullback $\Phi^*(d\rho \wedge d\theta)$ and verify $\det J = 1$ for any piecewise-$C^1$ profile.
   • (b) Compute $\partial\rho_{src}/\partial\theta = -R(\theta)R'(\theta)$. With habit_roundness 0 on SUMI_HABIT_RHOMB, $R'$ jumps at the four vertex angles; show that the jump produces a ray of discontinuous shear strain $\sigma$ from each vertex outward — the line Kessho draws and reads as cleavage — and explain what the log-sum-exp softening $k = 2 + 40(1 - \text{roundness})^2$ does to it.

3. Problem 1.3 — the skewed invariant and MPE retuning (§13.2). Consider the magic circle $x_{n+1} = x_n - \varepsilon y_n$, $y_{n+1} = y_n + \varepsilon x_{n+1}$.

   • (a) Substitute into $I_\varepsilon = x^2 + y^2 - \varepsilon xy$ and prove $I_\varepsilon(x_{n+1}, y_{n+1}) = I_\varepsilon(x_n, y_n)$ for all $0 < \varepsilon < 2$.
   • (b) Two ways to re-base a state when $\varepsilon \to \varepsilon'$: the shipped rescale $(x, y) \mapsto (A/a)(x, y)$ with $a^2 = I_{\varepsilon'}(x, y)/(1 - \varepsilon'^2/4)$, and the shear-scale that keeps $x$ and moves $y$ onto the new ellipse, $v = \dfrac{y - \tfrac{\varepsilon}{2}x}{\sqrt{1 - \varepsilon^2/4}}$, $y' = \tfrac{\varepsilon'}{2}x + v\sqrt{1 - \varepsilon'^2/4}$. Show that both land on $I_{\varepsilon'} = A^2(1 - \varepsilon'^2/4)$; compute each map’s determinant (the shear-scale’s is $\sqrt{(4 - \varepsilon'^2)/(4 - \varepsilon^2)}$, the rescale’s $A^2/a^2$); say which preserves the orbit’s phase and which preserves the canonical area, and why neither is a symplectomorphism of the same $\omega$ (the ellipse itself moved). Then explain why the engine’s measured ripple, 0.097 dB over ±48 semitones in two seconds, is the criterion that decides between them, not the determinant.