manim-mcp 0.1.0

package/references/composer/references/mathematical-storytelling.md

@@ -0,0 +1,359 @@
+# Mathematical Storytelling in 3Blue1Brown Style
+
+The narrative craft behind 3b1b videos, extracted from 400+ video source files. This is not about animation technique -- it's about how to STRUCTURE the intellectual journey so viewers have genuine "aha moments."
+
+---
+
+## Principle 1: Start with a QUESTION, Not a Definition
+
+The single most important principle. Never open with "Definition: A vector space is..." Instead, open with a question that makes the viewer WANT the definition.
+
+### Examples from Actual Videos
+
+| Video | Bad Opening (avoided) | Actual Opening |
+|-------|----------------------|----------------|
+| EoLA Ch 1 | "A vector is an element of a vector space..." | "What are vectors? A physics student, a CS student, and a mathematician would give three different answers..." |
+| EoC Ch 2 | "The derivative is defined as the limit..." | "What does it mean for something to change instantaneously?" |
+| Neural Networks | "A neural network is a computational graph..." | "What IS a neural network?" (then immediately shows MNIST recognition) |
+| Transformers | "A transformer is an attention-based architecture..." | Shows GPT generating text, then asks "How does it actually do this?" |
+| Laplace Transform | "The Laplace transform is defined as..." | Shows how annoying ODEs are to solve, then previews the elegant shortcut |
+| Bayes Theorem | "Bayes' theorem states P(A|B) = ..." | "Most people get this wrong. Here's a medical test question..." |
+
+### How to Find the Right Question
+
+1. Ask "What would a curious student wonder BEFORE knowing this concept?"
+2. Find the gap between intuition and formalism
+3. Look for where the obvious approach fails
+4. Search for "Why does X work?" rather than "What is X?"
+
+---
+
+## Principle 2: Show the WRONG Approach First
+
+The "wrong then right" pattern creates contrast that makes the correct approach feel motivated and earned. This is Grant's version of the Socratic method.
+
+### The Moser's Circle Problem Pattern
+
+From `_2023/moser_reboot/main.py`:
+
+1. Points on a circle create regions when connected
+2. Count: 1, 2, 4, 8, 16... "Oh, it must be 2^n!"
+3. Wait. With 6 points: 31, not 32.
+4. "The pattern BREAKS. Why?"
+5. Now the actual combinatorial formula feels necessary
+
+### The Borwein Integral Pattern
+
+From `_2022/borwein/main.py`:
+
+1. integral of sinc(x) = pi
+2. integral of sinc(x)*sinc(x/3) = pi
+3. integral of sinc(x)*sinc(x/3)*sinc(x/5) = pi
+4. ... pattern continues...
+5. Then suddenly: NOT pi
+6. "What changed?" -- now the viewer is hooked
+
+### Implementation in Video Planning
+
+When planning a video, always ask:
+- What's the naive approach viewers will try?
+- Where does it break down?
+- Can I SHOW the failure before presenting the correct method?
+
+The time spent on the wrong approach is NOT wasted -- it's the most important pedagogical investment in the video.
+
+---
+
+## Principle 3: Use PHYSICAL ANALOGY Before Formal Math
+
+Ground abstract math in physical reality. The viewer should be able to SEE and FEEL the concept before encountering formulas.
+
+### Analogy Map from 3b1b Videos
+
+| Abstract Concept | Physical Analogy Used | Video |
+|-------------------|----------------------|-------|
+| Inverse square law | Lighthouses on a lake | Basel Problem (2018) |
+| Differential equations | Pendulum swinging | DiffEq Part 1 (2019) |
+| Fourier series | Rotating arrows (epicycles) | DiffEq Part 4 (2019) |
+| Matrix as transformation | Grid being deformed | EoLA (2016) |
+| Determinant | Area of parallelogram being scaled | EoLA Ch 6 (2016) |
+| Eigenvectors | Vectors that stay on their span during transformation | EoLA Ch 11 (2016) |
+| Normal distribution | Galton board / dice sums | CLT (2023) |
+| Convolution | Sliding dice distributions | Convolutions (2022) |
+| Wave interference | Light waves passing through glass | Optics (2023) |
+| Gradient descent | Ball rolling downhill | Neural Networks Part 2 (2017) |
+| Attention mechanism | Words "looking at" other words via arcs | Transformers (2024) |
+| Laplace transform | Spring-mass system | Laplace (2025) |
+| Hairy ball theorem | Combing hair on a sphere, airplane wind patterns | Hairy Ball (2026) |
+| Stereographic projection | Flattening a sphere to a plane | Hairy Ball (2026) |
+
+### The Analogy-to-Formal Pipeline
+
+```
+1. Physical scenario (60s): Show the physical system
+2. Observe patterns (30s): What regularities do we see?
+3. Quantify (30s): Introduce variables, axes, coordinates
+4. Write the equation (30s): The formula EMERGES from observation
+5. Verify (30s): Show the formula predicts the physical behavior
+```
+
+---
+
+## Principle 4: Build Intuition Through SPECIFIC CASES Before General Formula
+
+Never jump to the general case. Always start with n=2, then n=3, then "see the pattern."
+
+### Examples
+
+**Derivatives** (EoC Ch 3):
+1. Derivative of x^2: draw a square, grow it by dx, area change = 2x*dx
+2. Derivative of x^3: draw a cube, grow it by dx, volume change = 3x^2*dx
+3. Now the pattern: derivative of x^n = n*x^(n-1)
+
+**Determinant** (EoLA Ch 6):
+1. 2D: area of parallelogram
+2. 3D: volume of parallelepiped
+3. General: n-dimensional volume scaling
+
+**CLT** (`_2023/clt/main.py`):
+1. Roll 1 die: uniform
+2. Sum 2 dice: triangle
+3. Sum 5 dice: starting to look bell-shaped
+4. Sum 50 dice: Gaussian!
+
+**Convolutions** (`_2022/convolutions/discrete.py`):
+1. Start with dice example (discrete, small)
+2. Move to image blur (discrete, visual)
+3. Then continuous convolution (abstract)
+
+### The Speed Ramp
+
+First examples get full animation treatment. Later examples can be sped through because the viewer now has the pattern:
+
+```python
+# From CLT dice simulation
+for n in range(n_sums):
+    if n < 10:
+        self.run_one_sum(animated=True)
+    else:
+        self.run_one_sum(animated=False, still_frame=True)
+```
+
+---
+
+## Principle 5: Show MULTIPLE PERSPECTIVES
+
+The same concept viewed from different angles creates deeper understanding. This is the "Two Perspectives -> Unity" narrative pattern.
+
+### Examples from the Codebase
+
+**Vectors** (EoLA Ch 1):
+- Physics student: arrows in space
+- CS student: lists of numbers
+- Mathematician: abstract elements of a vector space
+
+**Dot Product** (EoLA Ch 9):
+- Geometric: projection of one vector onto another
+- Algebraic: component-wise multiplication and sum
+- Duality: linear transformation from vectors to numbers
+
+**Fourier Transform** (`_2018/fourier.py`, `_2022/borwein/`):
+- Time domain: wave amplitude over time
+- Frequency domain: amplitude at each frequency
+- "Fourier Land" side-by-side view
+
+**Change of Basis** (EoLA Ch 10):
+- "Your coordinate system"
+- "Jennifer's coordinate system"
+- Both describe the same vectors, different languages
+
+### Implementation
+
+The side-by-side comparison scene archetype is key here. Split the screen, show both views, then connect them with arrows, transforms, or color matching.
+
+---
+
+## Principle 6: The "Aha Moment" Placement
+
+The central insight should land at 60-70% through the video. This creates proper emotional build-up and leaves time for implications.
+
+### Structure Around the Aha Moment
+
+```
+0-15%:   Hook and setup
+15-30%:  Build tools and vocabulary
+30-60%:  Investigation, examples, building tension
+60-70%:  THE INSIGHT (FlashAround, long wait, dramatic pacing)
+70-85%:  "Now look what happens" -- applications of the insight
+85-100%: Broader connections, what's next, end screen
+```
+
+### Cinematic Techniques for the Aha Moment
+
+From the codebase, Grant uses these at the key insight:
+
+1. **`FlashAround(result)`**: Visual flash drawing attention
+2. **`Circumscribe(equation, color=YELLOW)`**: Circle around the key equation
+3. **`self.wait(2-3)`**: Extended pause -- the longest wait in the video
+4. **Camera zoom**: `frame.animate.set_height(smaller)` to focus on the result
+5. **Color burst**: Key element changes to a bright, distinct color
+6. **Sound (rare)**: `self.add_sound("clack")` or musical sting
+
+### Real Example Flow
+
+**Basel Problem lighthouses**:
+```
+...builds up the lighthouse geometry for 15 minutes...
+"And if we take the limit as the circle radius goes to infinity..."
+[The flat lighthouse sum equals the curved lighthouse sum]
+[FlashAround the equation]
+[self.wait(3)]
+"...we get pi squared over six."
+```
+
+---
+
+## Principle 7: Close with Broader Connections
+
+Never end with just "and that's the formula." End with WHERE this leads, WHY it matters, or HOW it connects to something unexpected.
+
+### Closing Patterns
+
+**"Where does this lead?"**
+- EoLA chapters end with preview of next chapter's concept
+- "In the next video, we'll see how this connects to..."
+
+**"This shows up everywhere"**
+- Fourier series: "This same idea appears in quantum mechanics, signal processing, music..."
+- Linear algebra: "Every time you see a matrix, think of this transformation"
+
+**"The deeper principle"**
+- Moser's Circle Problem: The general lesson about mathematical induction and pattern-matching
+- CLT: Why the normal distribution is "normal" -- it's the ONLY distribution this could converge to
+
+**"Isn't that beautiful?"**
+- Basel Problem: The unlikely connection between prime numbers and pi
+- Euler's Identity: "The most beautiful equation in mathematics"
+
+---
+
+## Principle 8: Calibrate Formality to Audience Need
+
+3b1b videos deliberately use informal language for maximum accessibility, reserving formal notation for when it earns its place.
+
+### The Formality Gradient
+
+```
+Level 0 (most accessible): Physical analogy, no math notation
+Level 1: Named concepts with visual representations
+Level 2: Simple equations with color-coded variables
+Level 3: Multi-step derivations with TransformMatchingTex
+Level 4: Formal proofs with epsilon-delta or axioms
+```
+
+Most 3b1b videos stay at levels 1-3. Level 0 is used for openings and physical setups. Level 4 is rare and always preceded by extensive level 1-2 groundwork.
+
+### Language Choices
+
+| Formal | 3b1b Style |
+|--------|-----------|
+| "infinitesimal quantity" | "tiny nudge dx" |
+| "the limit as n approaches infinity" | "as we take more and more terms" |
+| "the transformation T maps V to W" | "this transformation takes vectors and lands them in a new space" |
+| "the derivative is defined as..." | "the derivative tells you how sensitive the function is to small changes" |
+| "by the fundamental theorem of calculus" | "and this is the deep connection between derivatives and integrals" |
+
+---
+
+## Principle 9: Use Recurring Motifs
+
+Visual and conceptual callbacks create a sense of coherence across a video and across a series.
+
+### Within a Single Video
+
+- The same color always means the same thing (blue=input, green=output, yellow=highlight)
+- A geometric object introduced early returns transformed later
+- The opening question is explicitly answered at the end
+
+### Within a Series
+
+- The NumberPlane grid appears in every EoLA chapter
+- The Car mobject recurs throughout EoC
+- Pi creature modes establish emotional continuity
+- Color conventions carry across videos (s_domain=YELLOW, t_domain=BLUE in Laplace)
+
+### The "Callback" Technique
+
+```python
+# Early in the video:
+first_equation = Tex(R"f(x) = x^2")
+self.play(Write(first_equation))
+self.wait()
+self.play(FadeOut(first_equation))
+
+# ... 15 minutes later ...
+# Bring it back, transformed:
+callback = Tex(R"f(x) = x^2 + \epsilon g(x)")  # Same but evolved
+self.play(FadeIn(callback))
+# "Remember when we started with this simple case?"
+```
+
+---
+
+## Narrative Structure Templates
+
+### Template A: The Mystery (Best for standalone videos)
+
+```
+1. Surprising result (hook)
+2. "Let me show you why this is true"
+3. Build the framework
+4. Step-by-step reasoning
+5. "And that's why [result] must be true"
+6. "This connects to..."
+```
+
+### Template B: The Builder (Best for concept introduction)
+
+```
+1. "What is [concept]?"
+2. Simple version first
+3. Add complexity gradually
+4. "Now here's the full picture"
+5. "Notice how [elegant property]"
+6. "In the next video, we'll use this to..."
+```
+
+### Template C: The Debate (Best for "Two perspectives" topics)
+
+```
+1. Perspective A (geometric)
+2. Perspective B (algebraic)
+3. "These seem different, but..."
+4. Show the connection
+5. "Understanding both gives you..."
+6. Application that requires both
+```
+
+### Template D: The Journey (Best for historical topics)
+
+```
+1. "Imagine you're [historical figure]..."
+2. The problem they faced
+3. Their first attempt
+4. The breakthrough insight
+5. Modern understanding
+6. "And this opened the door to..."
+```
+
+---
+
+## Common Storytelling Mistakes to Avoid
+
+1. **Skipping the "why should I care?"** -- Every concept needs motivation before presentation.
+2. **Definition before intuition** -- Build visual understanding first, then name it.
+3. **Too many concepts at once** -- One major concept per scene. Two max per video section.
+4. **No emotional variation** -- Alternate between tension (confusion) and release (clarity).
+5. **Ending with a formula** -- End with meaning, connection, or beauty. The formula is a stepping stone.
+6. **Assuming the viewer sees what you see** -- Explicitly point out patterns. Use Indicate(), color changes, annotations.
+7. **Equal time for unequal importance** -- Spend 3 minutes on the key insight, 30 seconds on the trivial step. Don't allocate time evenly.

package/references/composer/references/narrative-patterns.md

@@ -0,0 +1,221 @@
+# Narrative Patterns for Math Explainers
+
+Common structures used in effective 3Blue1Brown-style videos, derived from analysis of 400+ video source files (2015-2026).
+
+---
+
+## Pattern 1: Mystery --> Investigation --> Resolution
+
+**Structure:**
+1. Present a puzzling result or paradox
+2. Investigate why it's true through visual exploration
+3. Reveal the underlying principle
+4. Show how the principle generalizes
+
+**Example topics:** Euler's identity, Bayes theorem, infinite series paradoxes, Borwein integrals, colliding blocks and pi
+
+**Opening hooks:**
+- "What does it even mean to raise a number to an imaginary power?"
+- "This equation looks wrong, but it's actually true..."
+- "Most people get this probability question wrong..."
+- "Count the collisions. Why is pi showing up?"
+
+**Actual videos using this pattern:**
+- **Colliding Blocks** (`_2019/clacks/`): Pi appears in collision count. The mystery IS the hook.
+- **Basel Problem** (`_2018/basel/`): Why does 1 + 1/4 + 1/9 + ... = pi^2/6? Lighthouses provide the investigation.
+- **Borwein Integrals** (`_2022/borwein/`): Integrals equal pi until they don't. Moving averages provide the explanation.
+
+---
+
+## Pattern 2: Build Up --> Payoff
+
+**Structure:**
+1. Introduce simple building blocks
+2. Combine them to create something complex
+3. Show the beautiful/surprising result
+4. Reflect on why it works
+
+**Example topics:** Fourier series, neural networks, linear algebra, transformer architecture
+
+**Opening hooks:**
+- "Let's start with something simple..."
+- "Each piece here is easy, but together they do something remarkable..."
+
+**Actual videos using this pattern:**
+- **Fourier Series** (`_2019/diffyq/part4/`): Individual rotating arrows combine to trace any shape.
+- **Neural Networks** (`_2017/nn/`): Neurons -> layers -> network -> recognition.
+- **CLT / Gaussian Build-Up** (`_2023/clt/`): `BuildUpGaussian` constructs the Gaussian formula term by term.
+- **Transformer Architecture** (`_2024/transformers/network_flow.py`): Embedding -> attention -> MLP -> unembedding, one block at a time.
+
+---
+
+## Pattern 3: Two Perspectives --> Unity
+
+**Structure:**
+1. Show concept from perspective A (e.g., algebraic)
+2. Show same concept from perspective B (e.g., geometric)
+3. Reveal they're the same thing
+4. Explore implications of this connection
+
+**Example topics:** Dot product, determinants, complex multiplication, Fourier transform
+
+**Opening hooks:**
+- "There are two ways to think about this..."
+- "These seem like completely different ideas, but..."
+
+**Actual videos using this pattern:**
+- **EoLA Ch 9 - Dot Products and Duality** (`_2016/eola/chapter9.py`): Geometric projection vs. algebraic computation. Same result, deeply connected through duality.
+- **EoLA Ch 1 - Vectors** (`_2016/eola/chapter1.py`): Physics student (arrows), CS student (lists), mathematician (abstract). Three perspectives on one concept.
+- **Borwein/Convolutions Split Screen** (`_2022/borwein/supplements.py`): Time domain on left, "Fourier Land" on right with teal shading.
+- **Change of Basis** (`_2016/eola/chapter10.py`): "Your coordinates vs Jennifer's coordinates" -- same vectors, different languages.
+
+---
+
+## Pattern 4: Wrong --> Less Wrong --> Right
+
+**Structure:**
+1. Present common misconception or naive approach
+2. Show why it fails
+3. Refine the approach
+4. Arrive at correct understanding
+
+**Example topics:** Limits, probability distributions, definitions, Moser's circle problem
+
+**Opening hooks:**
+- "Your first instinct here is probably wrong..."
+- "The obvious approach doesn't quite work..."
+
+**Actual videos using this pattern:**
+- **Moser's Circle Problem** (`_2023/moser_reboot/`): 1, 2, 4, 8, 16... 32? No, 31. The "obvious" pattern of 2^n is WRONG.
+- **Bayes Theorem** (`_2019/bayes/`, `_2020/med_test.py`): Naive probability intuition fails. The population grid approach corrects it.
+- **EoC Ch 7 - Limits** (`_2017/eoc/chapter7.py`): Informal "approaches" notion refined to epsilon-delta.
+- **Wordle Analysis** (`_2022/wordle/footnote.py`): Original analysis had a bug! `HeresTheThing(TeacherStudentsScene)` acknowledges the error.
+
+---
+
+## Pattern 5: Specific --> General
+
+**Structure:**
+1. Solve a specific concrete example
+2. Notice patterns in the solution
+3. Abstract to general principle
+4. Apply to new situations
+
+**Example topics:** Derivatives, group theory, algorithm analysis, CLT
+
+**Opening hooks:**
+- "Let's work through a specific example..."
+- "Once you see the pattern here, it shows up everywhere..."
+
+**Actual videos using this pattern:**
+- **EoC Ch 3 - Derivative Formulas** (`_2017/eoc/chapter3.py`): d/dx(x^2) via square area, d/dx(x^3) via cube volume, then the general power rule.
+- **CLT Dice Sums** (`_2023/clt/main.py`): 1 die -> 2 dice -> 5 dice -> 50 dice -> "always Gaussian!"
+- **Convolutions** (`_2022/convolutions/discrete.py`): Dice example (discrete, small) -> image blur (discrete, visual) -> continuous convolution (abstract).
+
+---
+
+## Pattern 6: History as Narrative
+
+**Structure:**
+1. Present the problem as historically encountered
+2. Follow the journey of discovery
+3. Show key insights that led to breakthroughs
+4. Connect to modern understanding
+
+**Example topics:** Calculus, cryptography, quantum mechanics, Galois theory
+
+**Opening hooks:**
+- "Imagine you're a mathematician in the 1600s..."
+- "This problem stumped the greatest minds for centuries..."
+
+**Actual videos using this pattern:**
+- **Galois Theory** (`_2022/galois/`): Galois's night before his fatal duel, scribbling mathematics. Uses `OutpaintTransition` for artwork panning with custom bezier rate functions, `LastWordsQuote` for historical text.
+- **Feynman's Lost Lecture** (`_2018/lost_lecture.py`): Recreating Feynman's geometric proof of elliptical orbits.
+- **Cosmic Distance / Venus Transit** (`_2025/cosmic_distance/part2.py`): Historical timeline with GlowDots showing key astronomical measurements.
+
+---
+
+## Pattern 7: Tourist's Guide
+
+**Structure:**
+1. Explicitly frame as a survey, not a deep dive
+2. Show several related concepts at a birds-eye level
+3. Highlight connections between them
+4. Point the viewer toward deeper resources
+
+**Actual videos using this pattern:**
+- **DiffEq Part 1** (`_2019/diffyq/part1/`): "A tourist's guide to differential equations" -- pendulums, phase space, vector fields, population models, all in one video.
+- **Group Theory / Monster** (`_2020/monster.py`): Survey of symmetry groups leading to the Monster group's staggering size.
+
+---
+
+## Pattern 8: Puzzle / Challenge
+
+**Structure:**
+1. State a simple-sounding puzzle
+2. Let the viewer try (implicit or explicit pause)
+3. Show the elegant solution
+4. Connect to deeper mathematics
+
+**Actual videos using this pattern:**
+- **Windmill Problem** (`_2019/windmill.py`): IMO problem with visual solution.
+- **Chess Puzzle** (`_2020/chess.py`): XOR-based encoding with custom `FlipCoin` animation.
+- **Putnam Problems** (`_2017/putnam.py`): Competition problems with elegant visual proofs.
+- **Determinant Puzzle** (`_2018/determinant_puzzle.py`): Geometric puzzle using determinant properties.
+
+---
+
+## Combining Patterns
+
+Most effective videos combine multiple patterns:
+- **Mystery hook + Build Up explanation**: Colliding blocks (mystery: why pi?) + progressive understanding
+- **Two Perspectives + Specific -> General**: Dot product (geometric + algebraic) + works for any dimension
+- **Wrong -> Right + Puzzle**: Moser's circle (wrong pattern + counting puzzle)
+- **History + Mystery**: Basel problem (Euler's quest + why pi?)
+- **Tourist's Guide + Physical Scenario**: DiffEq (survey format + pendulum simulation)
+
+---
+
+## Pacing Guidelines
+
+| Video Length | Intro Hook | Main Content | Recap/Implications |
+|--------------|------------|--------------|-------------------|
+| 5-10 min     | 30-60s     | 4-8 min      | 30-60s            |
+| 15-20 min    | 1-2 min    | 12-16 min    | 1-2 min           |
+| 30+ min      | 2-3 min    | 24-26 min    | 2-4 min           |
+
+---
+
+## Emotional Arc
+
+Every video should have emotional beats:
+
+1. **Curiosity** (opening) - Why should I care? (Question, mystery, surprise)
+2. **Confusion** (early) - This is harder than it looks (Wrong approach, complexity)
+3. **Partial clarity** (middle) - I'm starting to see... (First examples, building blocks)
+4. **Aha moment** (climax, 60-70% through) - Oh! That's beautiful! (FlashAround, long wait)
+5. **Satisfaction** (end) - Now I truly understand (Recap, broader connections)
+
+### Pi Creature Emotional Modes as Audience Surrogates
+
+From the codebase, Pi creatures express the viewer's emotions:
+- **Confusion**: `"confused"`, `"erm"`, `"horrified"` -- "I don't get it yet"
+- **Curiosity**: `"pondering"`, `"thinking"` -- "Hmm, interesting..."
+- **Understanding**: `"happy"`, `"hooray"` -- "I see it now!"
+- **Surprise**: `"surprised"` -- "Wait, WHAT?"
+- **Skepticism**: `"sassy"`, `"angry"` -- "That can't be right..."
+
+These modes map to the emotional arc: confusion early, curiosity in the middle, understanding and surprise at the climax.
+
+---
+
+## The "Earned Insight" Principle
+
+The viewer must WORK for the aha moment. If you give away the insight too early, it doesn't feel earned. The emotional payoff is proportional to the intellectual investment.
+
+**Structure for earning an insight:**
+1. Show why the naive approach fails (investment)
+2. Build the correct framework piece by piece (investment)
+3. Let the pieces come together (payoff)
+4. Pause. Let it breathe. `self.wait(3)` (savor)
+5. Show what this enables (bonus payoff)