vizmatic 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/PROMPT.md +75 -531
  2. package/README.md +85 -1052
  3. package/ROADMAP.md +49 -67
  4. package/SCIENCE.md +250 -0
  5. package/assets/THIRD_PARTY_LICENSES.md +40 -1
  6. package/assets/fonts/InstrumentSerif-Italic.ttf +0 -0
  7. package/assets/fonts/InstrumentSerif-Regular.ttf +0 -0
  8. package/assets/licenses/raster-codecs-MIT.txt +74 -0
  9. package/dist/chunk-3F2VQ7NW.js +1 -0
  10. package/dist/{chunk-FEIPTPBZ.js → chunk-4XE64I2U.js} +53 -463
  11. package/dist/chunk-JHHPLALU.js +79 -0
  12. package/dist/chunk-LTX44BAE.js +112 -0
  13. package/dist/chunk-MLKGABMK.js +9 -0
  14. package/dist/chunk-PSBF4TEK.js +1 -0
  15. package/dist/chunk-RPAHMKAR.js +605 -0
  16. package/dist/chunk-RWF4VBUL.js +3617 -0
  17. package/dist/chunk-WHT6HRMX.js +4201 -0
  18. package/dist/cli.js +369 -12
  19. package/dist/index.cjs +7413 -1810
  20. package/dist/index.d.cts +900 -599
  21. package/dist/index.d.ts +900 -599
  22. package/dist/index.js +5019 -3278
  23. package/dist/math-LXB4FH4E.js +7 -0
  24. package/dist/math-QVCETQDQ.js +1 -0
  25. package/dist/scene-browser-assets.d.ts +38 -0
  26. package/dist/scene-browser-assets.js +53 -0
  27. package/dist/scene-browser-chunks/chunk-5MVLYGXM.js +70 -0
  28. package/dist/scene-browser-chunks/chunk-ASXKN3NU.js +1 -0
  29. package/dist/scene-browser-chunks/chunk-CM5Y5LZP.js +1 -0
  30. package/dist/scene-browser-chunks/chunk-DP7NB4EW.js +6 -0
  31. package/dist/scene-browser-chunks/emscripten-module.browser-M5AEKJGE.js +1 -0
  32. package/dist/scene-browser-chunks/ffi-FL6ORJU3.js +1 -0
  33. package/dist/scene-browser-chunks/module-ES6BEMUI-JD5S5VKR.js +1 -0
  34. package/dist/scene-browser-chunks/module-asyncify-2EFITU5U-HWPFJFJC.js +1 -0
  35. package/dist/scene-browser-chunks/scene-browser-layout-M3XSXMV4.js +27 -0
  36. package/dist/scene-browser.d.ts +117 -0
  37. package/dist/scene-browser.js +220 -0
  38. package/dist/scene-cli.js +1 -1
  39. package/dist/scene-runtime.cjs +168 -103
  40. package/dist/scene-runtime.d.cts +3 -2
  41. package/dist/scene-runtime.d.ts +3 -2
  42. package/dist/scene-runtime.js +3 -1
  43. package/dist/server-2FYHZ4UO.js +331 -0
  44. package/dist/stage-browser/browser.d.ts +2482 -0
  45. package/dist/stage-browser/chunk-SQE76S5B.js +1 -0
  46. package/dist/stage-browser/chunk-VZNL6JY2.js +59 -0
  47. package/dist/stage-browser/dagre.esm-N2NIVIAZ.js +6 -0
  48. package/dist/stage-browser/math-4WFNHVV2.js +18 -0
  49. package/dist/stage-browser/stage.js +19 -0
  50. package/dist/stage-export.cjs +4950 -0
  51. package/dist/stage-export.d.cts +112 -0
  52. package/dist/stage-export.d.ts +112 -0
  53. package/dist/stage-export.js +544 -0
  54. package/dist/stage.cjs +9745 -0
  55. package/dist/stage.d.cts +1678 -0
  56. package/dist/stage.d.ts +1678 -0
  57. package/dist/stage.js +5404 -0
  58. package/dist/svg-import-Djj2q7Pc.d.cts +742 -0
  59. package/dist/svg-import-Djj2q7Pc.d.ts +742 -0
  60. package/dist/video-CcHW1qhV.d.cts +532 -0
  61. package/dist/video-CcHW1qhV.d.ts +532 -0
  62. package/examples/README.md +18 -0
  63. package/examples/agent-pipeline.tsx +4 -4
  64. package/examples/animated-pipeline.tsx +1 -5
  65. package/examples/attention-head.tsx +12 -12
  66. package/examples/aurora-incident.tsx +4 -3
  67. package/examples/building-blocks.tsx +8 -9
  68. package/examples/catalog-charts.tsx +4 -4
  69. package/examples/catalog-content.tsx +7 -9
  70. package/examples/catalog-convolution-kernel.tsx +116 -0
  71. package/examples/catalog-data.tsx +2 -8
  72. package/examples/catalog-dataflow.tsx +5 -9
  73. package/examples/catalog-dense.tsx +80 -0
  74. package/examples/catalog-deployment.tsx +5 -11
  75. package/examples/catalog-diagrams.tsx +13 -16
  76. package/examples/catalog-drawing.tsx +7 -7
  77. package/examples/catalog-flows.tsx +4 -4
  78. package/examples/catalog-foundations.tsx +11 -11
  79. package/examples/catalog-gaussian-blur.tsx +146 -0
  80. package/examples/catalog-image-tensors.tsx +115 -0
  81. package/examples/catalog-ml.tsx +36 -31
  82. package/examples/catalog-numeric-matrices.tsx +93 -0
  83. package/examples/catalog-photo-blur.tsx +209 -0
  84. package/examples/catalog-science-ai.tsx +130 -0
  85. package/examples/catalog-science-chemistry.tsx +103 -0
  86. package/examples/catalog-science-math.tsx +93 -0
  87. package/examples/catalog-science-physics.tsx +84 -0
  88. package/examples/catalog-sequence.tsx +59 -38
  89. package/examples/data-pipeline-lineage-presentation.tsx +5 -0
  90. package/examples/data-pipeline-lineage.tsx +85 -0
  91. package/examples/daybreak-launch.tsx +1 -0
  92. package/examples/desired-quadrant.tsx +7 -8
  93. package/examples/engineering-dashboard-presentation.tsx +13 -0
  94. package/examples/engineering-dashboard.tsx +160 -0
  95. package/examples/engineering-flow.tsx +2 -4
  96. package/examples/eval-dashboard.tsx +6 -6
  97. package/examples/films/attention.ts +278 -0
  98. package/examples/films/cache-miss.ts +431 -0
  99. package/examples/films/catalog.json +132 -0
  100. package/examples/films/central-limit.ts +269 -0
  101. package/examples/films/complex-maps.ts +273 -0
  102. package/examples/films/deck-example.ts +224 -0
  103. package/examples/films/euler-circle.ts +179 -0
  104. package/examples/films/fourier-epicycles.ts +265 -0
  105. package/examples/films/gradient-descent.ts +345 -0
  106. package/examples/films/linear-maps.ts +175 -0
  107. package/examples/films/lorenz.ts +207 -0
  108. package/examples/films/pythagoras.ts +185 -0
  109. package/examples/films/taylor-series.ts +159 -0
  110. package/examples/films/vizmatic-title.ts +117 -0
  111. package/examples/llm-serving-stack-presentation.tsx +5 -0
  112. package/examples/llm-serving-stack.tsx +94 -0
  113. package/examples/model-garden.tsx +1 -0
  114. package/examples/model-router.tsx +6 -6
  115. package/examples/nccl-all-gather.tsx +3 -3
  116. package/examples/nccl-all-reduce.tsx +3 -3
  117. package/examples/nccl-all-to-all.tsx +1 -1
  118. package/examples/nccl-broadcast.tsx +1 -1
  119. package/examples/nccl-reduce-scatter.tsx +5 -5
  120. package/examples/orthogonal-routing.tsx +4 -4
  121. package/examples/pareto-frontier.tsx +9 -10
  122. package/examples/presentation-frame.tsx +6 -6
  123. package/examples/production-system-map-presentation.tsx +5 -0
  124. package/examples/production-system-map.tsx +130 -0
  125. package/examples/rag-graph.tsx +7 -7
  126. package/examples/release-card.tsx +5 -5
  127. package/examples/spec-anatomy.tsx +5 -5
  128. package/examples/system-architecture.tsx +19 -32
  129. package/examples/theme-system.tsx +1 -1
  130. package/examples/token-matrix.tsx +4 -2
  131. package/examples/transparent-badge.tsx +1 -2
  132. package/examples/videos/README.md +36 -2
  133. package/examples/videos/calculus-tangent.tsx +101 -0
  134. package/examples/videos/catalyst-pathway.tsx +56 -0
  135. package/examples/videos/causal-attention.tsx +91 -0
  136. package/examples/videos/convolution-kernel.tsx +34 -0
  137. package/examples/videos/gaussian-blur.tsx +32 -0
  138. package/examples/videos/image-to-matrix.tsx +22 -0
  139. package/examples/videos/matrix-multiplication.tsx +128 -0
  140. package/examples/videos/photo-gaussian-blur.tsx +39 -0
  141. package/examples/videos/wave-interference.tsx +80 -0
  142. package/examples/vizmatic-bare.d.ts +1 -0
  143. package/examples/vizmatic-hero.tsx +9 -18
  144. package/examples/website-workflow.tsx +7 -7
  145. package/examples/weekend-field-notes.tsx +3 -2
  146. package/package.json +65 -11
  147. package/dist/chunk-TH3F4SDB.js +0 -79
@@ -0,0 +1,345 @@
1
+ /**
2
+ * Gradient descent on a two-basin loss, with real iterates. Two starts 0.12 apart
3
+ * are found by bisection on the ridge between the basins, so they travel together
4
+ * for a long time and still finish in different minima.
5
+ */
6
+ import {
7
+ Node, arrow, dot, dynamic, fadeIn, film, line, linear, parseColor, polyPath, ramp, rect, smoother, text, tex, write,
8
+ type Rgba, type Ring, type Vec,
9
+ } from 'vizmatic/stage'
10
+
11
+ const SIZE = 3
12
+ const GRID = 38
13
+ const ETA = 0.32
14
+ const STEPS = 170
15
+ const CENTER: Vec = [-235, 16]
16
+ const SCALE = 124
17
+ const CAMERA_DISTANCE = 16
18
+ const FLOOR = -1.02
19
+ const HEIGHT = 2.15
20
+ const COLUMN = 480
21
+
22
+ const bump = (dx: number, dy: number, s: number) => Math.exp(-(dx * dx + dy * dy) / (2 * s * s))
23
+ const loss = (x: number, y: number) => 1.5 - 1.25 * bump(x - 1.25, y + 0.95, 0.95) - 0.82 * bump(x + 1.45, y - 1.05, 0.8)
24
+ + 0.045 * (x * x + y * y) + 0.1 * Math.sin(1.5 * x + 0.4) * Math.cos(1.3 * y)
25
+
26
+ function gradient(x: number, y: number): Vec {
27
+ const h = 1e-4
28
+ return [(loss(x + h, y) - loss(x - h, y)) / (2 * h), (loss(x, y + h) - loss(x, y - h)) / (2 * h)]
29
+ }
30
+
31
+ function descend(x0: number, y0: number): Vec[] {
32
+ const path: Vec[] = [[x0, y0]]
33
+ let x = x0, y = y0
34
+ for (let i = 0; i < STEPS; i++) {
35
+ const [gx, gy] = gradient(x, y)
36
+ x -= ETA * gx
37
+ y -= ETA * gy
38
+ path.push([x, y])
39
+ }
40
+ return path
41
+ }
42
+
43
+ /** Which minimum a start falls into. */
44
+ const fallsRight = (x: number, y: number) => descend(x, y)[STEPS]![0] > 0
45
+
46
+ function ridge(y: number): number {
47
+ let low = -1, high = 2.8
48
+ for (let i = 0; i < 40; i++) {
49
+ const mid = (low + high) / 2
50
+ if (fallsRight(mid, y)) high = mid
51
+ else low = mid
52
+ }
53
+ return (low + high) / 2
54
+ }
55
+
56
+ /** Marching squares over the floor, as one list of short segments per level. */
57
+ function contours(levels: readonly number[], resolution: number): [Vec, Vec][][] {
58
+ const out: [Vec, Vec][][] = levels.map(() => [])
59
+ const cell = (2 * SIZE) / resolution
60
+ const at = (i: number, j: number) => loss(-SIZE + i * cell, -SIZE + j * cell)
61
+ for (let i = 0; i < resolution; i++) {
62
+ for (let j = 0; j < resolution; j++) {
63
+ const v = [at(i, j), at(i + 1, j), at(i + 1, j + 1), at(i, j + 1)]
64
+ const corners: Vec[] = [[i, j], [i + 1, j], [i + 1, j + 1], [i, j + 1]]
65
+ levels.forEach((level, index) => {
66
+ const hits: Vec[] = []
67
+ for (let k = 0; k < 4; k++) {
68
+ const a = v[k]!, b = v[(k + 1) % 4]!
69
+ if ((a < level) === (b < level)) continue
70
+ const t = (level - a) / (b - a)
71
+ const [ax, ay] = corners[k]!, [bx, by] = corners[(k + 1) % 4]!
72
+ hits.push([-SIZE + (ax + (bx - ax) * t) * cell, -SIZE + (ay + (by - ay) * t) * cell])
73
+ }
74
+ if (hits.length >= 2) out[index]!.push([hits[0]!, hits[1]!])
75
+ if (hits.length === 4) out[index]!.push([hits[2]!, hits[3]!])
76
+ })
77
+ }
78
+ }
79
+ return out
80
+ }
81
+
82
+ export default film({
83
+ title: 'Gradient descent',
84
+ description: 'Two starts a hair apart run downhill together, then finish in different minima.',
85
+ fps: 60,
86
+ bloom: 0.12,
87
+ }, (s) => {
88
+ const azimuth = s.value(-0.55)
89
+ const elevation = s.value(0.6)
90
+ const rise = s.value(0)
91
+ const stepA = s.value(0)
92
+ const stepB = s.value(0)
93
+ const showB = s.value(0)
94
+ const showA = s.value(0)
95
+ const arrowAlpha = s.value(0)
96
+
97
+ const split = ridge(2.6)
98
+ const pathA = descend(split + 0.06, 2.6)
99
+ const pathB = descend(split - 0.06, 2.6)
100
+
101
+ // Loss range, for mapping height to color.
102
+ let low = Infinity, high = -Infinity
103
+ for (let i = 0; i <= 120; i++) {
104
+ for (let j = 0; j <= 120; j++) {
105
+ const v = loss(-SIZE + (i * 2 * SIZE) / 120, -SIZE + (j * 2 * SIZE) / 120)
106
+ low = Math.min(low, v)
107
+ high = Math.max(high, v)
108
+ }
109
+ }
110
+ const heightOf = (x: number, y: number) => ((loss(x, y) - low) / (high - low)) * HEIGHT + FLOOR + 0.16
111
+
112
+ // The surface is dark glass. Height shows through its contour lines, which carry the light.
113
+ const palette = ramp(64, 'blue', 'teal', 'green', 'yellow')
114
+ const groundTone = parseColor('bg')
115
+ const dark = s.look.dark
116
+ const surfaceTone = (level: number, light: number): Rgba => {
117
+ const base = palette[level]!
118
+ const amount = dark ? 0.1 + 0.34 * light * (0.35 + (0.65 * level) / 63) : 0.2 + 0.3 * light
119
+ return [
120
+ groundTone[0] + (base[0] - groundTone[0]) * amount,
121
+ groundTone[1] + (base[1] - groundTone[1]) * amount,
122
+ groundTone[2] + (base[2] - groundTone[2]) * amount,
123
+ 1,
124
+ ]
125
+ }
126
+ interface Quad { corners: [number, number][]; fill: Rgba; edge: Rgba; lines: { a: Vec; b: Vec; level: number }[] }
127
+ const levels = Array.from({ length: 16 }, (_, i) => low + ((i + 0.6) * (high - low)) / 16)
128
+ const levelColors = ramp(levels.length, 'blue', 'teal', 'green', 'yellow')
129
+ const quads: Quad[] = []
130
+ const cell = (2 * SIZE) / GRID
131
+ for (let i = 0; i < GRID; i++) {
132
+ for (let j = 0; j < GRID; j++) {
133
+ const x0 = -SIZE + i * cell, y0 = -SIZE + j * cell, x1 = x0 + cell, y1 = y0 + cell
134
+ const [gx, gy] = gradient((x0 + x1) / 2, (y0 + y1) / 2)
135
+ const k = HEIGHT / (high - low)
136
+ const nx = -gx * k, ny = -gy * k, nz = 1
137
+ const size = Math.hypot(nx, ny, nz)
138
+ const lambert = Math.max(0, (nx * -0.42 + ny * -0.58 + nz * 0.7) / size)
139
+ const level = Math.min(63, Math.floor(((loss((x0 + x1) / 2, (y0 + y1) / 2) - low) / (high - low)) * 64))
140
+ const light = 0.45 + 0.75 * lambert
141
+ const corners: [number, number][] = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]]
142
+ const values = corners.map(([x, y]) => loss(x, y))
143
+ const lines: Quad['lines'] = []
144
+ levels.forEach((value, index) => {
145
+ const hits: Vec[] = []
146
+ for (let c = 0; c < 4; c++) {
147
+ const va = values[c]!, vb = values[(c + 1) % 4]!
148
+ if ((va < value) === (vb < value)) continue
149
+ const t = (value - va) / (vb - va)
150
+ const [ax, ay] = corners[c]!, [bx, by] = corners[(c + 1) % 4]!
151
+ hits.push([ax + (bx - ax) * t, ay + (by - ay) * t])
152
+ }
153
+ if (hits.length >= 2) lines.push({ a: hits[0]!, b: hits[1]!, level: index })
154
+ })
155
+ quads.push({ corners, fill: surfaceTone(level, light), edge: surfaceTone(level, light * 1.7), lines })
156
+ }
157
+ }
158
+
159
+ const levelLines = contours(levels, 96)
160
+ const faintPaint = parseColor('faint')
161
+
162
+ const stage = dynamic(() => {
163
+ const az = azimuth.value, el = elevation.value
164
+ const ca = Math.cos(az), sa = Math.sin(az), ce = Math.cos(el), se = Math.sin(el)
165
+ const project = (x: number, y: number, z: number): { p: Vec; depth: number } => {
166
+ const X = x * ca - y * sa, Y = x * sa + y * ca
167
+ const depth = Y * ce - z * se + CAMERA_DISTANCE
168
+ const k = (SCALE * CAMERA_DISTANCE) / depth
169
+ return { p: [CENTER[0] + X * k, CENTER[1] - (Y * se + z * ce) * k], depth }
170
+ }
171
+ const out: Node[] = []
172
+
173
+ // The floor sits under everything, because the camera stays above the horizon.
174
+ const floorCorners: Vec[] = ([[-SIZE, -SIZE], [SIZE, -SIZE], [SIZE, SIZE], [-SIZE, SIZE]] as const).map(([x, y]) => project(x, y, FLOOR).p)
175
+ out.push(new Node(polyPath(floorCorners, true)).stroke(faintPaint, 1.4).fill('surface', 0.55))
176
+ levelLines.forEach((segments, index) => {
177
+ const rings: Ring[] = []
178
+ for (const [a, b] of segments) rings.push(...polyPath([project(a[0], a[1], FLOOR).p, project(b[0], b[1], FLOOR).p]))
179
+ if (rings.length) out.push(new Node(rings).stroke(levelColors[index]!, 1.2, 0.72))
180
+ })
181
+ const shadow = (path: Vec[], step: number, color: string, alpha: number) => {
182
+ if (alpha <= 0) return
183
+ const end = Math.min(path.length - 1, Math.floor(step))
184
+ const points: Vec[] = []
185
+ for (let i = 0; i <= end; i++) points.push(project(path[i]![0], path[i]![1], FLOOR).p)
186
+ if (points.length > 1) out.push(new Node(polyPath(points)).stroke(color, 2.4, alpha))
187
+ }
188
+ shadow(pathA, stepA.value, 'orange', showA.value)
189
+ shadow(pathB, stepB.value, 'pink', showB.value)
190
+
191
+ interface Item { depth: number; node: Node }
192
+ const items: Item[] = []
193
+ const lift = rise.value
194
+ const z = (x: number, y: number) => FLOOR + (heightOf(x, y) - FLOOR) * lift
195
+ for (const quad of quads) {
196
+ const corners = quad.corners.map(([x, y]) => project(x, y, z(x, y)))
197
+ const depth = (corners[0]!.depth + corners[1]!.depth + corners[2]!.depth + corners[3]!.depth) / 4
198
+ const parts: Node[] = [new Node(polyPath(corners.map((corner) => corner.p), true)).fill(quad.fill).stroke(quad.edge, 0.7)]
199
+ for (const mark of quad.lines) {
200
+ parts.push(line(project(mark.a[0], mark.a[1], z(mark.a[0], mark.a[1]) + 0.004).p, project(mark.b[0], mark.b[1], z(mark.b[0], mark.b[1]) + 0.004).p, {
201
+ stroke: levelColors[mark.level]!, width: 1.5,
202
+ }))
203
+ }
204
+ items.push({ depth, node: parts.length === 1 ? parts[0]! : new Node().add(...parts) })
205
+ }
206
+ const trail = (path: Vec[], step: number, color: string, alpha: number) => {
207
+ if (alpha <= 0) return
208
+ const end = Math.min(path.length - 1, step)
209
+ const whole = Math.floor(end)
210
+ const position = (i: number): Vec => {
211
+ const a = path[Math.floor(i)]!, b = path[Math.min(path.length - 1, Math.floor(i) + 1)]!
212
+ const f = i - Math.floor(i)
213
+ return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f]
214
+ }
215
+ const lifted = (i: number) => {
216
+ const [x, y] = position(i)
217
+ return project(x, y, z(x, y) + 0.035)
218
+ }
219
+ for (let i = 0; i < whole; i++) {
220
+ const a = lifted(i), b = lifted(i + 1)
221
+ items.push({
222
+ depth: (a.depth + b.depth) / 2 - 0.18,
223
+ node: line(a.p, b.p, { stroke: color, width: 4.2 }).opacity(alpha),
224
+ })
225
+ }
226
+ const tip = lifted(end)
227
+ items.push({ depth: tip.depth - 0.3, node: dot(11, color).at(tip.p).glow(14).opacity(alpha) })
228
+ }
229
+ trail(pathA, stepA.value, 'orange', showA.value)
230
+ trail(pathB, stepB.value, 'pink', showB.value)
231
+
232
+ const alpha = arrowAlpha.value
233
+ if (alpha > 0) {
234
+ const index = Math.min(pathA.length - 1, Math.floor(stepA.value))
235
+ const [x, y] = pathA[index]!
236
+ const [gx, gy] = gradient(x, y)
237
+ const size = Math.hypot(gx, gy) || 1
238
+ const length = 1.05
239
+ const tx = x - (gx / size) * length, ty = y - (gy / size) * length
240
+ const a = project(x, y, z(x, y) + 0.05)
241
+ const b = project(tx, ty, z(tx, ty) + 0.05)
242
+ items.push({ depth: a.depth - 0.4, node: arrow(a.p, b.p, { stroke: 'ink', width: 4, tip: 20 }).opacity(alpha) })
243
+ const away = tex('-\\nabla f', { size: 34, color: 'ink', display: false })
244
+ // Sit beside the shaft, on its upper side, so the label covers neither the ball nor the arrow.
245
+ const shaftX = b.p[0] - a.p[0], shaftY = b.p[1] - a.p[1]
246
+ const shaftLength = Math.hypot(shaftX, shaftY) || 1
247
+ const upward = shaftX > 0 ? -1 : 1
248
+ const sideX = (-shaftY / shaftLength) * upward, sideY = (shaftX / shaftLength) * upward
249
+ away.moveTo([(a.p[0] + b.p[0]) / 2 + sideX * 58, (a.p[1] + b.p[1]) / 2 + sideY * 58])
250
+ const bb = away.bounds()
251
+ items.push({ depth: a.depth - 0.5, node: new Node().add(
252
+ rect(bb.width + 14, bb.height + 10, { fill: 'bg', stroke: null, radius: 6 }).at(bb.x + bb.width / 2, bb.y + bb.height / 2).opacity(0.94),
253
+ away,
254
+ ).opacity(alpha) })
255
+ }
256
+ items.sort((p, q) => q.depth - p.depth)
257
+ for (const item of items) out.push(item.node)
258
+ return out
259
+ })
260
+
261
+ // ── Column ──────────────────────────────────────────────────────────────
262
+
263
+ const backing = rect(960 - COLUMN + 70, 1080, { fill: 'bg', stroke: null }).at((COLUMN - 70 + 960) / 2, 0).zIndex(5)
264
+ const rule = line([COLUMN - 70, -540], [COLUMN - 70, 540], { stroke: 'grid', width: 1.2 }).zIndex(5)
265
+ const place = <T extends Node>(node: T, top: number): T => {
266
+ node.alignTo([COLUMN, 0], 'left').alignTo([0, top], 'top')
267
+ node.zIndex(6)
268
+ return node
269
+ }
270
+ const label = (content: string, top: number) => place(text(content, { size: 19, color: 'dim', uppercase: true, tracking: 0.08, weight: 600 }), top)
271
+ const title = place(text('Downhill, one step at a time.', { font: 'serif', size: 58, maxWidth: 410, leading: 1.08 }), -490)
272
+ const rule1 = place(tex('\\theta_{t+1} = \\theta_t - \\eta \\, \\nabla f(\\theta_t)', { size: 36 }), -340)
273
+ const etaNote = place(text(`Step size eta = ${ETA}. Each step moves against the local slope, and nothing else.`, { size: 22, color: 'dim', maxWidth: 400, leading: 1.4 }), -280)
274
+
275
+ const stepLabel = label('Step', -176)
276
+ const stepRead = dynamic(() => place(text(String(Math.floor(Math.max(stepA.value, stepB.value))).padStart(3, ' '), { font: 'mono', size: 56, color: 'ink' }), -150)).zIndex(6)
277
+
278
+ const lossLabelA = label('Loss, start A', -66)
279
+ const lossReadA = dynamic(() => {
280
+ const [x, y] = pathA[Math.min(STEPS, Math.floor(stepA.value))]!
281
+ return place(text(loss(x, y).toFixed(3), { font: 'mono', size: 38, color: 'orange' }), -40)
282
+ }).zIndex(6)
283
+ const lossLabelB = label('Loss, start B', -66)
284
+ lossLabelB.alignTo([COLUMN + 200, 0], 'left')
285
+ const lossReadB = dynamic(() => {
286
+ const [x, y] = pathB[Math.min(STEPS, Math.floor(stepB.value))]!
287
+ const node = place(text(loss(x, y).toFixed(3), { font: 'mono', size: 38, color: 'pink' }), -40)
288
+ node.alignTo([COLUMN + 200, 0], 'left')
289
+ return node
290
+ }).zIndex(6)
291
+
292
+ // Loss against step, for both runs.
293
+ const CHART_X = COLUMN, CHART_W = 380, CHART_TOP = 72, CHART_H = 200
294
+ const chartY = (v: number) => CHART_TOP + CHART_H - ((v - low) / (high - low)) * CHART_H
295
+ const chartLabel = label('Loss against step', 36)
296
+ const chartAxes = new Node().add(
297
+ line([CHART_X, CHART_TOP], [CHART_X, CHART_TOP + CHART_H], { stroke: 'faint', width: 1.3 }),
298
+ line([CHART_X, CHART_TOP + CHART_H], [CHART_X + CHART_W, CHART_TOP + CHART_H], { stroke: 'faint', width: 1.3 }),
299
+ ).zIndex(6)
300
+ const chartTick0 = place(text('0', { font: 'mono', size: 18, color: 'dim' }), CHART_TOP + CHART_H + 8)
301
+ const chartTick1 = place(text(String(STEPS), { font: 'mono', size: 18, color: 'dim' }), CHART_TOP + CHART_H + 8)
302
+ chartTick1.alignTo([CHART_X + CHART_W, 0], 'right')
303
+ const chart = dynamic(() => {
304
+ const draw = (path: Vec[], step: number, color: string, alpha: number): Node | null => {
305
+ if (alpha <= 0) return null
306
+ const end = Math.min(STEPS, Math.floor(step))
307
+ if (end < 1) return null
308
+ const points: Vec[] = []
309
+ for (let i = 0; i <= end; i++) points.push([CHART_X + (i / STEPS) * CHART_W, chartY(loss(path[i]![0], path[i]![1]))])
310
+ return new Node(polyPath(points)).stroke(color, 3, alpha)
311
+ }
312
+ return [draw(pathA, stepA.value, 'orange', showA.value), draw(pathB, stepB.value, 'pink', showB.value)].filter((n): n is Node => n !== null)
313
+ }).zIndex(6)
314
+ const outcome = place(text('Same rule, same step size, starts 0.12 apart. Different answers.', { size: 24, color: 'ink', maxWidth: 400, leading: 1.38 }), 340)
315
+
316
+ // ── Timeline ────────────────────────────────────────────────────────────
317
+
318
+ s.add(stage)
319
+ s.add(backing, rule)
320
+ s.chapter('The landscape')
321
+ s.play(rise.to(1, { ease: smoother }), azimuth.to(-0.15, { ease: smoother }), write(title), { duration: 3.2 })
322
+ s.wait(0.4)
323
+
324
+ s.chapter('The rule')
325
+ s.play(showA.to(1), arrowAlpha.to(1), write(rule1), fadeIn(etaNote), azimuth.to(0.1, { ease: linear }), { duration: 1.6 })
326
+ s.play(fadeIn([stepLabel, stepRead, lossLabelA, lossReadA, chartLabel, chartAxes, chartTick0, chartTick1, chart]), azimuth.to(0.2, { ease: linear }), { duration: 0.9 })
327
+ for (let i = 1; i <= 4; i++) {
328
+ s.play(stepA.to(i * 6), azimuth.to(0.2 + i * 0.05, { ease: linear }), { duration: 0.9 })
329
+ s.wait(0.25)
330
+ }
331
+
332
+ s.chapter('Let it run')
333
+ s.play(arrowAlpha.to(0), { duration: 0.5 })
334
+ s.play(stepA.to(STEPS, { ease: linear }), azimuth.to(1.15, { ease: smoother }), { duration: 8 })
335
+ s.wait(0.8)
336
+
337
+ s.chapter('A close neighbor')
338
+ s.play(showB.to(1), fadeIn([lossLabelB, lossReadB]), azimuth.to(0.75, { ease: smoother }), { duration: 1.4 })
339
+ s.play(stepB.to(STEPS, { ease: linear }), azimuth.to(-0.25, { ease: smoother }), { duration: 8.5 })
340
+ s.wait(0.6)
341
+
342
+ s.chapter('From above')
343
+ s.play(elevation.to(1.32, { ease: smoother }), azimuth.to(0.05, { ease: smoother }), fadeIn(outcome, { shift: [0, 10] }), { duration: 3.6 })
344
+ s.wait(4.4)
345
+ })
@@ -0,0 +1,175 @@
1
+ /**
2
+ * A matrix moves the whole plane. Follow the two basis arrows, watch the unit
3
+ * square's area scale by the determinant, and find the two directions that stay
4
+ * on their own lines. For A = [2 1; 0.5 1.5]: det A = 2.5, and the eigenvalues
5
+ * are 2.5 on (2, 1) and 1 on (1, -1), so their product is the determinant.
6
+ */
7
+ import {
8
+ Node, applyMatrix, arrow, draw, dynamic, fade, fadeIn, film, flash, grow, indicate, line, plane, polyPath, ramp, rect, shape, text, tex, write,
9
+ type Rgba, type Vec,
10
+ } from 'vizmatic/stage'
11
+
12
+ const A = [[2, 1], [0.5, 1.5]] as const
13
+ const INVERSE = [[0.6, -0.4], [-0.2, 0.8]] as const
14
+ const UNIT = 104
15
+ const ORIGIN_X = -250
16
+ const COLUMN = 480
17
+
18
+ export default film({
19
+ title: 'What a matrix does',
20
+ description: 'A grid under a matrix: basis arrows, the determinant as area, and eigenvectors that keep their lines.',
21
+ fps: 60,
22
+ }, (s) => {
23
+ const k = s.value(0)
24
+ const moved = (x: number, y: number): Vec => {
25
+ const a = k.value
26
+ return [x + a * (A[0][0] * x + A[0][1] * y - x), y + a * (A[1][0] * x + A[1][1] * y - y)]
27
+ }
28
+ const P = (x: number, y: number): Vec => [ORIGIN_X + x * UNIT, -y * UNIT]
29
+ const Pm = (x: number, y: number): Vec => {
30
+ const [mx, my] = moved(x, y)
31
+ return P(mx, my)
32
+ }
33
+ const determinant = () => {
34
+ const a = k.value
35
+ const m00 = 1 + a * (A[0][0] - 1), m01 = a * A[0][1], m10 = a * A[1][0], m11 = 1 + a * (A[1][1] - 1)
36
+ return m00 * m11 - m01 * m10
37
+ }
38
+
39
+ // ── The plane ───────────────────────────────────────────────────────────
40
+
41
+ const still = plane({ unit: UNIT, x: [-14, 14], y: [-11, 11], color: 'grid', axisColor: 'gridStrong', width: 1.2 }).at(ORIGIN_X, 0)
42
+ const grid = plane({ unit: UNIT, x: [-14, 14], y: [-11, 11], color: 'blue', axisColor: 'ink', width: 1.5 }).at(ORIGIN_X, 0)
43
+ grid.major.opacity(0.62)
44
+ grid.axes.opacity(0.85)
45
+
46
+ const chip = (label: Node, at: Vec, pad = 8): Node[] => {
47
+ label.moveTo(at)
48
+ const b = label.bounds()
49
+ const back = rect(b.width + pad * 2, b.height + pad * 2, { fill: 'bg', stroke: null, radius: 6 })
50
+ .at(b.x + b.width / 2, b.y + b.height / 2).opacity(0.88)
51
+ return [back, label]
52
+ }
53
+ /** Label beside an arrow tip, not past it, so the chip never breaks the axis the arrow lies on. */
54
+ const tipLabel = (x: number, y: number, source: string, color: string, side: 1 | -1): Node[] => {
55
+ const [tx, ty] = Pm(x, y)
56
+ const length = Math.hypot(tx - ORIGIN_X, ty) || 1
57
+ const dx = (tx - ORIGIN_X) / length, dy = ty / length
58
+ const normalX = -dy * side, normalY = dx * side
59
+ return chip(tex(source, { size: 34, color, display: false }), [tx - dx * 10 + normalX * 34, ty - dy * 10 + normalY * 34])
60
+ }
61
+
62
+ const basis = dynamic(() => [
63
+ arrow(P(0, 0), Pm(1, 0), { stroke: 'green', width: 5, tip: 22 }),
64
+ arrow(P(0, 0), Pm(0, 1), { stroke: 'red', width: 5, tip: 22 }),
65
+ ...tipLabel(1, 0, '\\hat{\\imath}', 'green', 1),
66
+ ...tipLabel(0, 1, '\\hat{\\jmath}', 'red', -1),
67
+ ])
68
+
69
+ const square = dynamic(() => {
70
+ const corners = [Pm(0, 0), Pm(1, 0), Pm(1, 1), Pm(0, 1)]
71
+ const cx = corners.reduce((sum, c) => sum + c[0], 0) / 4, cy = corners.reduce((sum, c) => sum + c[1], 0) / 4
72
+ return [
73
+ shape(polyPath(corners, true), { fill: 'yellow', stroke: 'yellow', width: 2.5 }).set('fillOpacity', 0.32),
74
+ ...chip(tex(determinant().toFixed(2), { size: 30, color: 'yellow', display: false }), [cx, cy], 6),
75
+ ]
76
+ })
77
+
78
+ // The fan: one short arrow per direction, tinted by direction, all from the origin.
79
+ const FAN = 56
80
+ const fanColors: readonly Rgba[] = ramp(FAN + 1, 'teal', 'blue', 'purple', 'pink', 'orange', 'gold', 'teal')
81
+ const eigenAngles = [Math.atan2(1, 2), Math.atan2(1, 2) + Math.PI, Math.atan2(-1, 1), Math.atan2(-1, 1) + Math.PI]
82
+ const fan = dynamic(() => {
83
+ const out: Node[] = []
84
+ for (let i = 0; i < FAN; i++) {
85
+ const angle = (i / FAN) * Math.PI * 2
86
+ if (eigenAngles.some((e) => Math.abs(Math.atan2(Math.sin(angle - e), Math.cos(angle - e))) < 0.06)) continue
87
+ const x = Math.cos(angle) * 1.15, y = Math.sin(angle) * 1.15
88
+ out.push(arrow(P(0, 0), Pm(x, y), { stroke: fanColors[i]!, width: 2.4, tip: 11 }))
89
+ }
90
+ return out
91
+ })
92
+ const lineStretch = line(P(-5.4, -2.7), P(5.4, 2.7), { stroke: 'yellow', width: 2, dash: [10, 9] })
93
+ const lineFixed = line(P(-5, 5), P(5, -5), { stroke: 'teal', width: 2, dash: [10, 9] })
94
+ const eigen = dynamic(() => [
95
+ arrow(P(0, 0), Pm(2 * 0.8, 0.8), { stroke: 'yellow', width: 6, tip: 24, glow: 8 }),
96
+ arrow(P(0, 0), Pm(-2 * 0.8, -0.8), { stroke: 'yellow', width: 6, tip: 24, glow: 8 }),
97
+ arrow(P(0, 0), Pm(1.1, -1.1), { stroke: 'teal', width: 6, tip: 24, glow: 8 }),
98
+ arrow(P(0, 0), Pm(-1.1, 1.1), { stroke: 'teal', width: 6, tip: 24, glow: 8 }),
99
+ ])
100
+
101
+ // ── The column ──────────────────────────────────────────────────────────
102
+
103
+ const column = rect(960 - COLUMN + 70, 1080, { fill: 'bg', stroke: null }).at((COLUMN - 70 + 960) / 2, 0).zIndex(5)
104
+ const rule = line([COLUMN - 70, -540], [COLUMN - 70, 540], { stroke: 'grid', width: 1.2 }).zIndex(5)
105
+ const place = <T extends Node>(node: T, top: number): T => {
106
+ node.alignTo([COLUMN, 0], 'left').alignTo([0, top], 'top')
107
+ node.zIndex(6)
108
+ return node
109
+ }
110
+ const title = place(text('A matrix moves the whole plane.', { font: 'serif', size: 58, maxWidth: 400, leading: 1.08 }), -490)
111
+ const matrix = place(tex('A = \\begin{bmatrix} 2 & 1 \\\\ 0.5 & 1.5 \\end{bmatrix}', { size: 44 }), -340)
112
+ // Column one is where the first arrow lands. Column two is where the second lands.
113
+ for (const i of [3, 5, 6, 7]) matrix.glyphs[i]!.fill('green')
114
+ for (const i of [4, 8, 9, 10]) matrix.glyphs[i]!.fill('red')
115
+
116
+ const label = (content: string, top: number) => place(text(content, { size: 19, color: 'dim', uppercase: true, tracking: 0.08, weight: 600 }), top)
117
+ const tracksLabel = label('Where the arrows land', -196)
118
+ const reads = dynamic(() => {
119
+ const [ix, iy] = moved(1, 0), [jx, jy] = moved(0, 1)
120
+ const row = (name: string, x: number, y: number, color: string, top: number) =>
121
+ place(text(`${name} (${x.toFixed(2)}, ${y.toFixed(2)})`, { font: 'mono', size: 30, color }), top)
122
+ return [row('i', ix, iy, 'green', -162), row('j', jx, jy, 'red', -116)]
123
+ }).zIndex(6)
124
+ const areaLabel = label('Area of the unit square', -42)
125
+ const areaRead = dynamic(() => place(text(determinant().toFixed(2), { font: 'mono', size: 72, color: 'yellow' }), -12)).zIndex(6)
126
+ const detEq = place(tex('\\det A = 2 \\cdot 1.5 - 1 \\cdot 0.5 = 2.5', { size: 30 }), 96)
127
+
128
+ const eigenLabel = label('Arrows that keep their line', 180)
129
+ const eqA = place(tex('A \\vec{v} = \\lambda \\vec{v}', { size: 48, color: 'ink' }), 214)
130
+ const stretchRow = place(tex('\\vec{v} = (2, 1), \\quad \\lambda = 2.5', { size: 30, color: 'yellow' }), 296)
131
+ const fixedRow = place(tex('\\vec{v} = (1, -1), \\quad \\lambda = 1', { size: 30, color: 'teal' }), 346)
132
+ const closing = place(tex('\\lambda_1 \\lambda_2 = 2.5 \\cdot 1 = \\det A', { size: 34, color: 'ink' }), 416)
133
+
134
+ // ── Timeline ────────────────────────────────────────────────────────────
135
+
136
+ s.add(still, grid)
137
+ s.add(column, rule)
138
+ s.chapter('Two arrows')
139
+ s.play(write(title), draw(grid.major, { lag: 0.015 }), draw(grid.axes), { duration: 2.4 })
140
+ s.play(grow(basis, { from: P(0, 0) }), write(matrix), { duration: 1.4 })
141
+ s.play(fadeIn([tracksLabel, reads], { shift: [0, 8] }), { duration: 0.8 })
142
+ s.wait(1.2)
143
+
144
+ s.chapter('The move')
145
+ s.play(applyMatrix(grid, A, { origin: [ORIGIN_X, 0] }), k.to(1), { duration: 3.4 })
146
+ s.wait(0.4)
147
+ s.play(indicate(matrix.glyphs.filter((_, i) => [3, 5, 6, 7].includes(i)), { color: 'green', scale: 1.16 }), { duration: 0.9 })
148
+ s.play(indicate(matrix.glyphs.filter((_, i) => [4, 8, 9, 10].includes(i)), { color: 'red', scale: 1.16 }), { duration: 0.9 })
149
+ s.wait(0.8)
150
+
151
+ s.chapter('Area')
152
+ s.play(applyMatrix(grid, INVERSE, { origin: [ORIGIN_X, 0] }), k.to(0), { duration: 1.8 })
153
+ s.add(square)
154
+ s.play(fadeIn(square), fadeIn([areaLabel, areaRead], { shift: [0, 8] }), { duration: 0.8 })
155
+ s.wait(0.5)
156
+ s.play(applyMatrix(grid, A, { origin: [ORIGIN_X, 0] }), k.to(1), { duration: 3.2 })
157
+ s.play(write(detEq), { duration: 1.4 })
158
+ s.wait(1)
159
+
160
+ s.chapter('Lines that stay')
161
+ s.play(applyMatrix(grid, INVERSE, { origin: [ORIGIN_X, 0] }), k.to(0), fade(square, 0), fade(basis, 0), { duration: 1.8 })
162
+ s.add(fan)
163
+ s.play(grow(fan, { from: P(0, 0) }), draw(lineStretch), draw(lineFixed), { duration: 1.4 })
164
+ s.add(eigen)
165
+ s.play(fadeIn(eigen), { duration: 0.6 })
166
+ s.play(fadeIn(eigenLabel), write(eqA), { duration: 1.2 })
167
+ s.wait(0.6)
168
+ s.play(applyMatrix(grid, A, { origin: [ORIGIN_X, 0] }), k.to(1), { duration: 4 })
169
+ s.wait(0.5)
170
+ s.play(flash(Pm(1.6, 0.8), { color: 'yellow' }), write(stretchRow), { duration: 1.2 })
171
+ s.play(flash(Pm(1.1, -1.1), { color: 'teal' }), write(fixedRow), { duration: 1.2 })
172
+ s.wait(0.8)
173
+ s.play(write(closing), { duration: 1.4 })
174
+ s.wait(2)
175
+ })