manim-mcp 0.1.0

package/references/composer/references/domain-planning-guides/physics-planning.md

@@ -0,0 +1,249 @@
+# Physics Video Planning Guide
+
+Based on the Differential Equations series (2019), Optics Puzzles (2023), Cosmic Distance (2025), Hairy Ball Theorem (2026), and physics-related content across the 3b1b codebase.
+
+---
+
+## Core Visual Language
+
+### Phase Space (THE Physics Visualization)
+
+The dual representation -- physical system on one side, phase portrait on the other -- is 3b1b's signature approach to physics.
+
+**From `_2019/diffyq/part1/`:**
+```python
+# Physical space: pendulum swinging
+pendulum = Pendulum(length=3, initial_theta=PI/4)
+
+# Phase space: theta vs omega
+phase_plane = NumberPlane(
+    x_range=[-PI, PI],    # theta
+    y_range=[-5, 5],       # angular velocity
+)
+
+# Link: dot on phase space tracks pendulum state
+state_dot = Dot(color=YELLOW)
+state_dot.add_updater(lambda m: m.move_to(
+    phase_plane.c2p(pendulum.theta, pendulum.omega)
+))
+```
+
+### Vector Fields and Stream Lines
+
+```python
+# From _2021/matrix_exp.py
+stream_lines = StreamLines(func, x_range=(-4, 4), y_range=(-4, 4))
+animated_lines = AnimatedStreamLines(stream_lines)
+```
+
+Stream lines show how solutions flow through phase space. Use `AnimatedStreamLines` for dynamic, flowing visualization.
+
+### Physical Simulations
+
+Key simulation patterns from the codebase:
+
+**Spring-Mass System** (`_2025/laplace/shm.py`):
+```python
+class SrpingMassSystem(VGroup):
+    def time_step(self, delta_t, dt_size=1e-3):
+        state = [self.get_x(), self.velocity]
+        for _ in range(sub_steps):
+            x, v = state
+            state += np.array([v, self.get_force(x, v)]) * true_dt
+```
+
+**SIR Epidemic** (`_2020/sir.py`):
+```python
+class Person(VGroup):
+    CONFIG = {
+        "infection_radius": 0.5,
+        "infection_duration": 5,
+        "recovery_probability": 0.5,
+    }
+    # Physics-based movement with infection mechanics
+```
+
+**Sliding Blocks** (`_2019/clacks/question.py`):
+```python
+class SlidingBlocks(VGroup):
+    # Two blocks, elastic collisions
+    # Mass ratio determines number of collisions
+```
+
+---
+
+## Topic Planning
+
+### Differential Equations
+
+**Series structure (from `_2019/diffyq/`):**
+
+Part 1: Pendulum (ODE) -> Phase space -> Vector field
+Part 2: Heat equation (PDE) -> Temperature evolution
+Part 3: Solving heat equation -> Boundary conditions -> Fourier's insight
+Part 4: Fourier series -> Rotating vectors -> Complex exponentials
+Part 5: Euler's formula as rotational dynamics
+
+**Planning a DiffEq video:**
+1. Start with the PHYSICAL SYSTEM, not the equation
+2. Show the system evolving in time
+3. Ask "how would you describe this mathematically?"
+4. Derive the ODE from the physics
+5. Show the phase portrait as a map of all possible behaviors
+6. Vector field reveals the structure
+
+**File organization pattern:**
+```
+diffyq/partN/
+    pendulum.py (or physics simulation)
+    phase_space.py (phase portrait visualization)
+    staging.py (main scene assembly)
+    pi_scenes.py (TeacherStudentsScene interludes)
+    wordy_scenes.py (text-heavy explanation scenes)
+    shared_constructs.py (constants, helpers)
+```
+
+### Wave Physics / Optics
+
+**From `_2023/optics_puzzles/`:**
+
+**`OscillatingWave`** -- Time-varying parametric wave:
+```python
+class OscillatingWave(VMobject):
+    wave_func = lambda x, t: amplitude * np.cos(TAU * x / wavelength - TAU * freq * t)
+    # Updater-driven: wave updates every frame
+```
+
+**`SlicedWave`** -- Wave with per-layer phase kicks (for explaining index of refraction):
+```python
+class SlicedWave(OscillatingWave):
+    phase_kicks = [0.1, 0.2, ...]  # Phase shift per material layer
+```
+
+**`ChargedParticle`** -- Particle with position history:
+```python
+class ChargedParticle(Group):
+    # Tracks position history for field visualization
+    self.history.append(self.get_center().copy())
+```
+
+**Spectral color mapping:**
+```python
+def get_spectral_color(wavelength):
+    cmap = colormaps["Spectral"]
+    return Color(rgb=cmap(normalized_wavelength)[:3])
+```
+
+**Planning an optics video:**
+1. Show the physical wave phenomenon
+2. Slow down time to see individual oscillations
+3. Show superposition (adding wave heights at each point)
+4. Introduce phasor diagrams for analysis
+5. Connect to the mathematical formula
+
+### Celestial Mechanics / Cosmic Distance
+
+**From `_2025/cosmic_distance/`:**
+
+**Textured celestial bodies:**
+```python
+earth = TexturedSurface(Sphere(radius=r), "EarthTextureMap", "NightEarthTextureMap")
+sun = TexturedSurface(Sphere(radius=r), "SunTexture")
+```
+
+**3D star fields:**
+```python
+stars = GlowDots(points, radius=...)  # Depth-based sizing
+```
+
+**Parallax visualization:**
+Show Earth at two points in its orbit, observe how nearby stars shift against distant background.
+
+### Topology / Hairy Ball Theorem
+
+**From `_2026/hairy_ball/`:**
+
+**Fibonacci sphere sampling:**
+```python
+def fibonacci_sphere(n_points=1000):
+    golden_ratio = (1 + math.sqrt(5)) / 2
+    # Evenly distributed points on sphere surface
+```
+
+**Stereographic projection:**
+```python
+def stereographic_proj(point):
+    x, y, z = point
+    return np.array([x / (1 - z), y / (1 - z), 0])
+```
+
+**`SphereStreamLines`**: Vector field constrained to sphere surface, visualizing the impossibility of combing a hairy ball flat.
+
+---
+
+## Simulation Design Patterns
+
+### The Three Simulation Speeds
+
+1. **Full animation** (first few iterations): Every step shown with transitions
+2. **Quick animation** (middle iterations): Simplified, faster
+3. **Instant** (final iterations): Jump to result
+
+```python
+for n in range(total):
+    if n < 5:
+        self.run_step(animated=True, run_time=2)
+    elif n < 20:
+        self.run_step(animated=True, run_time=0.5)
+    else:
+        self.run_step(animated=False)
+```
+
+### Physics Integration
+
+For accurate physics simulations, use sub-stepping:
+```python
+def time_step(self, delta_t, dt_size=1e-3):
+    sub_steps = int(delta_t / dt_size)
+    for _ in range(sub_steps):
+        x, v = state
+        force = self.get_force(x, v)
+        state += np.array([v, force]) * dt_size
+```
+
+### Sound Effects
+
+For physical simulations, sound adds tangibility:
+```python
+self.add_sound("clack")  # Collision sound in Galton board
+```
+
+---
+
+## Color Conventions for Physics
+
+| Element | Color | Context |
+|---------|-------|---------|
+| Time domain / time variable | BLUE | Laplace series |
+| Frequency domain / s variable | YELLOW | Laplace series |
+| Force / acceleration | RED | Mechanics |
+| Velocity | GREEN | Mechanics |
+| Position | BLUE | Mechanics |
+| Electric field | YELLOW | Optics |
+| Magnetic field | MAROON | EM waves |
+| Positive charge | RED | Electrostatics |
+| Negative charge | BLUE | Electrostatics |
+| SIR: Susceptible | BLUE | Epidemiology |
+| SIR: Infected | RED | Epidemiology |
+| SIR: Recovered | GREEN | Epidemiology |
+
+---
+
+## Common Pitfalls in Physics Videos
+
+1. **Starting with the equation**: Show the physical system FIRST. The equation emerges from observation.
+2. **Ignoring phase space**: For any dynamical system, the phase portrait is more informative than the time series. Show both.
+3. **Static diagrams for dynamic systems**: Use updaters and simulations. Physics IS motion.
+4. **Not connecting to familiar experience**: "Imagine pushing a swing" is better than "consider a forced harmonic oscillator."
+5. **Mixing 2D and 3D carelessly**: If a concept is inherently 3D (EM waves, orbital mechanics), use 3D scenes with proper camera work. Don't flatten it.
+6. **Skipping the "tourist's guide" approach**: For survey-style physics videos, explicitly say "we won't prove this rigorously" -- this frees you to build intuition.

package/references/composer/references/domain-planning-guides/probability-planning.md

@@ -0,0 +1,200 @@
+# Probability Video Planning Guide
+
+Based on the Bayesian reasoning series (2019-2020), Beta distribution series (2020), CLT series (2023), Essentials of Probability (2018), and related content.
+
+---
+
+## Core Visual Language
+
+### Population Grids
+
+The fundamental probability visual: a grid of people/dots/icons where subsets are colored differently.
+
+**From `_2020/med_test.py`:**
+```python
+class Population:
+    # Grid of people colored by disease status and test result
+    # Susceptible=one color, Infected=another
+    # Correct test results=bright, incorrect=muted
+```
+
+**From Bayes videos:** Pi creature grids where each creature represents a member of the population.
+
+### Bar Charts / Histograms
+
+**`ChartBars`** from `_2023/clt/main.py` and **`Histogram`** from `_2020/beta/helpers.py`:
+```python
+bars = ChartBars(axes, values)
+bars.set_submobject_colors_by_gradient(BLUE, GREEN)
+```
+
+**Dynamic updating with `make_number_changeable()`:**
+```python
+label = Tex(R"\mu = 0.00")
+decimal = label.make_number_changeable("0.00")
+decimal.add_updater(lambda m: m.set_value(get_mean()))
+```
+
+### Probability Distributions as Curves
+
+**Beta distribution** (`_2020/beta/helpers.py`):
+```python
+def get_beta_graph(axes, a, b):
+    return axes.get_graph(lambda x: scipy.stats.beta.pdf(x, a, b))
+```
+
+**Gaussian** (`_2023/clt/main.py`):
+```python
+gaussian = axes.get_graph(lambda x: np.exp(-x**2 / 2) / np.sqrt(2 * np.pi))
+gaussian.set_color(YELLOW)  # Gaussian is always YELLOW in CLT series
+```
+
+---
+
+## Topic Planning
+
+### Bayesian Reasoning
+
+**Series structure (from `_2019/bayes/` and `_2020/med_test.py`):**
+
+1. **The medical test problem**: 1% disease prevalence, 90% sensitivity, 9% false positive. What's P(disease|positive test)?
+2. **Population approach**: Show 1000 people, color by disease, then by test result
+3. **The odds form**: Likelihood ratio as the "update factor"
+4. **Bayes' rule formula**: Derived from the population visualization
+
+**Key visual technique -- population frequency approach:**
+```
+1000 people → 10 sick + 990 healthy
+10 sick → 9 true positive + 1 false negative
+990 healthy → 89 false positive + 901 true negative
+P(sick|positive) = 9/(9+89) = 9%
+```
+
+**Color conventions for Bayes:**
+- Disease positive: RED
+- Disease negative: GREEN
+- Test positive: highlighted/bright
+- Test negative: muted
+- True positive: RED + bright
+- False positive: GREEN + bright (the surprising case!)
+
+### Central Limit Theorem
+
+**Series structure (from `_2023/clt/`):**
+
+1. **Dice sums**: Roll dice, sum them, see distribution shape
+2. **Mean and standard deviation**: What these statistics measure
+3. **Building the Gaussian**: Construct the formula piece by piece
+4. **Why it works**: Convolution + moment generating functions
+
+**The convolution visualization is key:**
+```python
+new_dist = np.convolve(dist1, dist2)
+```
+
+Show two distributions being convolved:
+1. One distribution fixed, the other slides across
+2. At each position, multiply corresponding values
+3. Sum gives the convolution value at that point
+4. The result distribution approaches Gaussian
+
+**Galton Board (`_2023/clt/galton_board.py`):**
+Physical simulation of balls bouncing through pegs. Sound effects (`self.add_sound("clack")`) add tangibility. The balls accumulate into bins that form a bell curve.
+
+### Beta Distribution
+
+**Series structure (from `_2020/beta/`):**
+
+1. **beta1.py**: Comparing online sellers (100%/10 reviews vs 96%/50 reviews)
+2. **beta2.py**: Bayesian updating with weighted coins
+3. **beta3.py**: Full Bayesian update visualization
+
+**Key visual: coin grid with dynamic updating**
+- Grid of coins, some showing heads, some tails
+- As the probability parameter changes, coins flip
+- The posterior distribution updates accordingly
+
+**ValueTracker pattern for interactive distributions:**
+```python
+h_tracker = ValueTracker(0.5)
+graph = always_redraw(lambda: axes.get_graph(
+    lambda x: scipy.stats.beta.pdf(x, a, b),
+    color=BLUE
+))
+self.play(h_tracker.animate.set_value(0.8))
+```
+
+### Conditional Probability / Essentials of Probability
+
+**From `_2018/eop/`:**
+
+Chapter 0: What does probability even mean? (Frequentist vs Bayesian)
+Chapter 1: Counting, combinations, Pascal's triangle
+Chapter 2: Binomial distribution, random walks
+
+**Pascal's triangle** (`_2018/eop/pascal.py`): Visual construction with combination values.
+
+**Combinations** (`_2018/eop/combinations.py`): Choosing subsets with visual counting.
+
+---
+
+## Storytelling Patterns for Probability
+
+### The "Most People Get This Wrong" Hook
+
+Probability is IDEAL for this opening because human intuition about probability is consistently poor.
+
+**Examples:**
+- Medical test: "A test is 90% accurate. You test positive. What's the probability you actually have the disease? Most people say 90%. The real answer shocks them."
+- Monty Hall: "Should you switch doors?"
+- Birthday problem: "How many people do you need for a 50% chance of shared birthday?"
+
+### The Population Approach (3b1b's Preferred Method)
+
+Instead of abstract formulas, SHOW a population:
+1. Draw a large group (grid of dots/people)
+2. Color subsets by property
+3. Zoom into the relevant subset
+4. Count directly
+
+This makes conditional probability visual and intuitive.
+
+### The Simulation Approach
+
+Run many trials and show the empirical distribution converging to the theoretical one:
+```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)
+```
+
+The speed-up pattern is essential: show the first few trials slowly, then accelerate to show convergence.
+
+---
+
+## Color Conventions for Probability
+
+| Element | Color | Context |
+|---------|-------|---------|
+| Favorable outcomes | GREEN | Positive events |
+| Unfavorable outcomes | RED | Negative events |
+| Gaussian curve | YELLOW | CLT series |
+| Prior distribution | BLUE | Bayesian updating |
+| Posterior distribution | YELLOW or GREEN | Bayesian updating |
+| Likelihood | RED or MAROON | Bayesian updating |
+| Dice faces | Distinct per die | CLT dice examples |
+| Probability bars | BLUE-GREEN gradient | Distribution charts |
+
+---
+
+## Common Pitfalls in Probability Videos
+
+1. **Starting with axioms**: Probability axioms are dry. Start with a concrete problem.
+2. **Formula before intuition**: P(A|B) = P(A and B)/P(B) means nothing without a population grid.
+3. **Not showing enough trials**: One trial is an anecdote. Show 10, 100, 1000 trials to build the distribution.
+4. **Treating discrete and continuous the same**: They need different visual approaches. Bars for discrete, smooth curves for continuous.
+5. **Ignoring the emotional hook**: Probability problems that SURPRISE people ("the answer is only 9%!") are the best hooks.
+6. **Not calibrating the "intuition pump"**: Before showing the math, ask the viewer what they think the answer is. This primes them to be surprised.