manim-mcp 0.1.0

package/references/manimce/rules/physics-simulations.md

@@ -0,0 +1,610 @@
+---
+name: physics-simulations
+description: Physics-based animation patterns from 3b1b including Euler integration, pendulums, particle systems, phase space, vector fields, and sound
+metadata:
+  tags: physics, simulation, euler-integration, pendulum, particles, phase-space, vector-field, spring, SIR, sound
+---
+
+# Physics Simulations in ManimCE
+
+Patterns derived from 3b1b's differential equations series, SIR epidemic model, optics puzzles, Galton board, and other physics-heavy videos.
+
+## Euler Integration with Substeps (n_steps_per_frame)
+
+The foundational pattern for smooth physics simulations. 3b1b's pendulum code uses `n_steps_per_frame = 100` for numerical stability at 30fps.
+
+```python
+from manim import *
+import numpy as np
+
+class PendulumSimulation(Scene):
+    """Euler integration with substeps, directly from 3b1b's diffyq/pendulum.py"""
+
+    def construct(self):
+        pendulum = PendulumMobject(
+            length=3,
+            initial_theta=0.8,
+            damping=0.1,
+            gravity=9.8,
+            n_steps_per_frame=100,
+        )
+        pendulum.shift(UP)
+        self.add(pendulum)
+        self.wait(10)
+
+
+class PendulumMobject(VGroup):
+    """A pendulum that simulates via Euler integration in an updater."""
+
+    def __init__(
+        self,
+        length=3,
+        initial_theta=0.3,
+        omega=0,
+        damping=0.1,
+        gravity=9.8,
+        top_point=2 * UP,
+        n_steps_per_frame=100,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.length = length
+        self.theta = initial_theta
+        self.omega = omega
+        self.damping = damping
+        self.gravity = gravity
+        self.top_point = top_point
+        self.n_steps_per_frame = n_steps_per_frame
+
+        # Visual elements
+        self.rod = Line(UP, DOWN, stroke_width=3, stroke_color=GREY_B)
+        self.rod.set_height(length)
+        self.weight = Circle(radius=0.25, fill_opacity=1, fill_color=GREY_BROWN)
+        self.weight.set_stroke(width=0)
+        self.pivot = Dot(top_point, color=WHITE, radius=0.07)
+
+        self.add(self.rod, self.weight, self.pivot)
+        self._update_visual()
+
+        # Physics updater
+        self.add_updater(self._physics_step)
+
+    def _physics_step(self, mob, dt):
+        """Euler integration with substeps for stability."""
+        if dt == 0:
+            return
+        n = self.n_steps_per_frame
+        sub_dt = dt / n
+        for _ in range(n):
+            # d(theta)/dt = omega
+            d_theta = self.omega * sub_dt
+            # d(omega)/dt = -damping * omega - (g/L) * sin(theta)
+            d_omega = (
+                -self.damping * self.omega
+                - (self.gravity / self.length) * np.sin(self.theta)
+            ) * sub_dt
+            self.theta += d_theta
+            self.omega += d_omega
+        self._update_visual()
+
+    def _update_visual(self):
+        """Position rod and weight based on current theta."""
+        direction = np.array([
+            np.sin(self.theta), -np.cos(self.theta), 0
+        ])
+        end_point = self.top_point + self.length * direction
+        self.rod.put_start_and_end_on(self.top_point, end_point)
+        self.weight.move_to(end_point)
+```
+
+## Spring-Mass System
+
+From `_2019/diffyq/part1/pendulum.py` where a spring-mass analogy is shown alongside the pendulum.
+
+```python
+class SpringMassSystem(VGroup):
+    """A horizontal spring-mass system with Euler integration."""
+
+    def __init__(
+        self,
+        mass=1.0,
+        k=4.0,       # spring constant
+        damping=0.3,
+        initial_x=2.0,
+        initial_v=0.0,
+        n_steps_per_frame=100,
+        anchor_point=3 * LEFT,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.mass = mass
+        self.k = k
+        self.damping_coeff = damping
+        self.x = initial_x
+        self.v = initial_v
+        self.n_steps = n_steps_per_frame
+        self.anchor = anchor_point
+
+        # Visual elements
+        self.wall = Line(UP, DOWN, color=GREY_B).set_height(1.5)
+        self.wall.move_to(anchor_point)
+
+        self.block = Square(side_length=0.6, fill_opacity=1, fill_color=BLUE_D)
+        self.spring_line = VMobject(stroke_color=WHITE, stroke_width=2)
+
+        self.add(self.wall, self.spring_line, self.block)
+        self._update_visual()
+        self.add_updater(self._physics_step)
+
+    def _get_spring_points(self, start, end, n_coils=8, amplitude=0.2):
+        """Generate zigzag spring points between start and end."""
+        points = [start]
+        direction = end - start
+        length = np.linalg.norm(direction)
+        unit = direction / length if length > 0 else RIGHT
+        perp = np.array([-unit[1], unit[0], 0])
+
+        for i in range(1, n_coils * 2 + 1):
+            frac = i / (n_coils * 2 + 1)
+            sign = 1 if i % 2 == 0 else -1
+            point = start + frac * direction + sign * amplitude * perp
+            points.append(point)
+        points.append(end)
+        return points
+
+    def _physics_step(self, mob, dt):
+        if dt == 0:
+            return
+        sub_dt = dt / self.n_steps
+        for _ in range(self.n_steps):
+            force = -self.k * self.x - self.damping_coeff * self.v
+            acc = force / self.mass
+            self.v += acc * sub_dt
+            self.x += self.v * sub_dt
+        self._update_visual()
+
+    def _update_visual(self):
+        block_center = self.anchor + RIGHT * (2 + self.x)
+        self.block.move_to(block_center)
+        spring_points = self._get_spring_points(
+            self.anchor + 0.2 * RIGHT,
+            block_center + 0.3 * LEFT,
+        )
+        self.spring_line.set_points_as_corners(spring_points)
+
+
+class SpringMassDemo(Scene):
+    def construct(self):
+        system = SpringMassSystem(
+            initial_x=1.5,
+            k=6.0,
+            damping=0.2,
+        )
+        self.add(system)
+        self.wait(8)
+```
+
+## Particle Systems (SIR Model Pattern)
+
+From `_2020/sir.py` -- a particle-based epidemic simulation with states, color-coded by status.
+
+```python
+class Particle(VGroup):
+    """A particle with position, velocity, and state -- from the SIR model pattern."""
+
+    def __init__(
+        self,
+        status="S",
+        radius=0.1,
+        max_speed=1.0,
+        color_map=None,
+        bounds=None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        if color_map is None:
+            color_map = {"S": BLUE, "I": RED, "R": GREY_D}
+        if bounds is None:
+            bounds = {
+                "x_min": -FRAME_WIDTH / 2 + 0.5,
+                "x_max": FRAME_WIDTH / 2 - 0.5,
+                "y_min": -FRAME_HEIGHT / 2 + 0.5,
+                "y_max": FRAME_HEIGHT / 2 - 0.5,
+            }
+
+        self.status = status
+        self.max_speed = max_speed
+        self.color_map = color_map
+        self.bounds = bounds
+        self.velocity = max_speed * normalize(
+            np.array([np.random.randn(), np.random.randn(), 0])
+        )
+
+        self.body = Dot(radius=radius)
+        self.body.set_color(color_map[status])
+        self.add(self.body)
+
+        self.add_updater(self._move_and_bounce)
+
+    def _move_and_bounce(self, mob, dt):
+        """Random walk with wall bouncing."""
+        center = self.get_center()
+        new_pos = center + self.velocity * dt
+
+        b = self.bounds
+        if new_pos[0] < b["x_min"] or new_pos[0] > b["x_max"]:
+            self.velocity[0] *= -1
+        if new_pos[1] < b["y_min"] or new_pos[1] > b["y_max"]:
+            self.velocity[1] *= -1
+
+        self.shift(self.velocity * dt)
+
+    def set_status(self, new_status):
+        """Change status with color transition."""
+        self.status = new_status
+        self.body.set_color(self.color_map[new_status])
+
+
+class SIRDemo(Scene):
+    """Simplified SIR epidemic model visualization."""
+
+    def construct(self):
+        # SIR colors -- standard 3b1b convention
+        color_map = {"S": BLUE, "I": RED, "R": GREY_D}
+
+        # Legend
+        legend = VGroup(*[
+            VGroup(
+                Dot(color=color_map[s]),
+                Text(label, font_size=20),
+            ).arrange(RIGHT, buff=0.2)
+            for s, label in [("S", "Susceptible"), ("I", "Infected"), ("R", "Recovered")]
+        ]).arrange(DOWN, aligned_edge=LEFT).to_corner(UL)
+        self.add(legend)
+
+        # Create particles
+        n_particles = 50
+        particles = VGroup(*[
+            Particle(
+                status="S",
+                max_speed=0.8 + 0.4 * np.random.random(),
+                color_map=color_map,
+            )
+            for _ in range(n_particles)
+        ])
+
+        # Scatter initial positions
+        for p in particles:
+            p.move_to([
+                np.random.uniform(-5, 5),
+                np.random.uniform(-3, 3),
+                0
+            ])
+
+        # Patient zero
+        particles[0].set_status("I")
+
+        self.add(particles)
+        self.wait(15)
+```
+
+## Galton Board (Ball Drop Simulation)
+
+From `_2023/clt/galton_board.py` -- demonstrates falling balls with sound cues.
+
+```python
+class SimpleGaltonBoard(Scene):
+    """Simplified Galton board pattern from 3b1b's CLT video."""
+
+    n_rows = 5
+    peg_radius = 0.1
+    ball_radius = 0.08
+    spacing = 0.8
+
+    def construct(self):
+        pegs = self.create_pegs()
+        buckets = self.create_buckets(pegs)
+
+        self.play(
+            LaggedStartMap(Write, pegs, lag_ratio=0.02),
+            LaggedStartMap(Write, buckets, lag_ratio=0.05),
+        )
+        self.wait()
+
+        # Drop balls
+        for _ in range(15):
+            self.drop_ball(pegs, buckets)
+
+        self.wait(2)
+
+    def create_pegs(self):
+        pegs = VGroup()
+        for row in range(self.n_rows):
+            n_pegs = row + 1
+            row_group = VGroup()
+            for col in range(n_pegs):
+                x = (col - row / 2) * self.spacing
+                y = -row * self.spacing * 0.866 + 2  # Triangle layout
+                peg = Dot(
+                    point=[x, y, 0],
+                    radius=self.peg_radius,
+                    color=WHITE,
+                )
+                row_group.add(peg)
+            pegs.add(row_group)
+        return pegs
+
+    def create_buckets(self, pegs):
+        buckets = VGroup()
+        bottom_y = pegs[-1][0].get_y() - self.spacing
+        for i in range(self.n_rows + 1):
+            x = (i - self.n_rows / 2) * self.spacing
+            bucket = Line(
+                [x, bottom_y - 0.5, 0],
+                [x, bottom_y + 0.5, 0],
+                stroke_color=GREY_B, stroke_width=2,
+            )
+            buckets.add(bucket)
+        return buckets
+
+    def drop_ball(self, pegs, buckets):
+        ball = Dot(radius=self.ball_radius, color=YELLOW)
+        ball.move_to(pegs[0][0].get_center() + 0.5 * UP)
+        self.add(ball)
+
+        # Bounce through pegs
+        col = 0
+        for row in range(self.n_rows):
+            direction = np.random.choice([-1, 1])
+            if direction == 1:
+                col += 1
+            target_peg = pegs[row][min(col, len(pegs[row]) - 1)]
+            offset = direction * self.spacing * 0.3
+            target = target_peg.get_center() + np.array([offset, -0.2, 0])
+
+            self.play(
+                ball.animate.move_to(target),
+                run_time=0.15,
+                rate_func=rate_functions.rush_into,
+            )
+
+        # Fall to bucket
+        final_x = ball.get_x()
+        bottom_y = pegs[-1][0].get_y() - self.spacing - 0.3
+        self.play(
+            ball.animate.move_to([final_x, bottom_y, 0]),
+            run_time=0.2,
+        )
+```
+
+## Phase Space Visualization
+
+From `_2019/diffyq/` and `_2018/div_curl.py` -- showing trajectories in phase space.
+
+```python
+class PhaseSpaceVisualization(Scene):
+    """Phase portrait for a damped pendulum -- theta vs omega."""
+
+    def construct(self):
+        # Phase plane
+        axes = Axes(
+            x_range=[-PI, PI, PI / 2],
+            y_range=[-4, 4, 1],
+            x_length=8,
+            y_length=5,
+            axis_config={"include_tip": True},
+        )
+        x_label = MathTex(r"\theta").next_to(axes.x_axis, RIGHT)
+        y_label = MathTex(r"\dot{\theta}").next_to(axes.y_axis, UP)
+        axes.add(x_label, y_label)
+
+        self.play(Create(axes))
+        self.wait()
+
+        # Trace a trajectory through phase space
+        gravity = 9.8
+        length = 2.0
+        damping = 0.3
+
+        def phase_trajectory(theta0, omega0, dt=0.01, steps=2000):
+            points = []
+            theta, omega = theta0, omega0
+            for _ in range(steps):
+                points.append(axes.c2p(theta, omega))
+                d_omega = -damping * omega - (gravity / length) * np.sin(theta)
+                omega += d_omega * dt
+                theta += omega * dt
+                # Wrap theta to [-pi, pi]
+                if abs(theta) > PI:
+                    break
+            return points
+
+        # Draw multiple trajectories from different initial conditions
+        colors = [BLUE, GREEN, YELLOW, RED, PURPLE]
+        initial_conditions = [
+            (2.5, 0), (1.5, 2), (-1.0, 3), (0.5, -2), (-2.0, -1)
+        ]
+
+        for (theta0, omega0), color in zip(initial_conditions, colors):
+            points = phase_trajectory(theta0, omega0)
+            if len(points) > 2:
+                path = VMobject()
+                path.set_points_smoothly(points)
+                path.set_stroke(color, 2)
+
+                # Starting dot
+                start_dot = Dot(points[0], color=color, radius=0.06)
+                self.play(FadeIn(start_dot), run_time=0.3)
+                self.play(Create(path), run_time=2)
+
+        self.wait(2)
+```
+
+## Vector Fields and StreamLines
+
+From `_2019/diffyq/part1/staging.py` and `_2018/div_curl.py`.
+
+```python
+class VectorFieldDemo(Scene):
+    """Vector field visualization -- pendulum phase space."""
+
+    def construct(self):
+        plane = NumberPlane(
+            x_range=[-4, 4], y_range=[-3, 3],
+            background_line_style={"stroke_opacity": 0.3},
+        )
+        self.add(plane)
+
+        # Define the vector field function
+        gravity, length = 9.8, 2.0
+        damping = 0.3
+
+        def pendulum_field(pos):
+            theta, omega = pos[0], pos[1]
+            d_theta = omega
+            d_omega = -damping * omega - (gravity / length) * np.sin(theta)
+            return np.array([d_theta, d_omega, 0])
+
+        # Arrow-based vector field
+        field = ArrowVectorField(
+            pendulum_field,
+            x_range=[-4, 4, 0.5],
+            y_range=[-3, 3, 0.5],
+            length_func=lambda norm: 0.4 * sigmoid(norm),
+        )
+        field.set_opacity(0.7)
+
+        self.play(Create(field), run_time=2)
+        self.wait(2)
+
+        # Stream lines for flow visualization
+        stream_lines = StreamLines(
+            pendulum_field,
+            x_range=[-4, 4, 0.3],
+            y_range=[-3, 3, 0.3],
+            stroke_width=1.5,
+            max_anchors_per_line=30,
+        )
+        self.play(FadeOut(field))
+        self.play(stream_lines.create(), run_time=3)
+        self.wait(2)
+```
+
+## Sound Integration
+
+From `_2019/windmill.py` (hit sounds), `_2023/clt/galton_board.py` (clink sounds). ManimCE supports `self.add_sound()`.
+
+```python
+class SoundIntegration(Scene):
+    """Add sound effects synchronized with animations."""
+
+    def construct(self):
+        # Create a bouncing ball
+        ball = Dot(radius=0.2, color=YELLOW)
+        ball.move_to(3 * UP)
+        floor = Line(5 * LEFT, 5 * RIGHT, color=WHITE).shift(2 * DOWN)
+        self.add(floor)
+
+        # Drop and bounce with sound
+        self.play(FadeIn(ball))
+
+        for height in [3, 1.5, 0.75]:
+            # Fall
+            self.play(
+                ball.animate.move_to(2 * DOWN + 0.2 * UP),
+                run_time=0.3 * np.sqrt(height),
+                rate_func=rate_functions.rush_into,
+            )
+            # Sound on impact (requires .wav/.mp3 file in working directory)
+            # self.add_sound("bounce.wav")
+
+            # Bounce up
+            self.play(
+                ball.animate.shift(height * 0.5 * UP),
+                run_time=0.3 * np.sqrt(height * 0.5),
+                rate_func=rate_functions.rush_from,
+            )
+
+        self.wait()
+```
+
+## Wave Simulation
+
+From `_2023/optics_puzzles/slowing_waves.py` -- oscillating waves with phase tracking.
+
+```python
+class WaveSimulation(Scene):
+    """Oscillating wave with ValueTracker-driven phase."""
+
+    def construct(self):
+        axes = Axes(
+            x_range=[-8, 8, 1],
+            y_range=[-2, 2, 1],
+            x_length=12,
+            y_length=4,
+        )
+        self.add(axes)
+
+        # Wave parameters
+        wave_length = 2.0
+        amplitude = 1.0
+        speed = 1.5
+        time_tracker = ValueTracker(0)
+
+        def wave_func(x):
+            t = time_tracker.get_value()
+            return amplitude * np.sin(
+                TAU * x / wave_length - TAU * t * speed / wave_length
+            )
+
+        wave = always_redraw(
+            lambda: axes.plot(wave_func, color=YELLOW, stroke_width=3)
+        )
+        self.add(wave)
+
+        # Animate time passing
+        self.play(
+            time_tracker.animate.set_value(10),
+            run_time=10,
+            rate_func=linear,
+        )
+```
+
+## Combining Physics with Visualization
+
+The 3b1b pattern: show the physical simulation AND the mathematical representation side by side.
+
+```python
+class PhysicsAndMath(Scene):
+    """Show physical system alongside its phase portrait."""
+
+    def construct(self):
+        # Left: physical pendulum
+        physical_group = VGroup()
+        # ... pendulum visualization
+
+        # Right: phase space
+        phase_axes = Axes(
+            x_range=[-PI, PI], y_range=[-5, 5],
+            x_length=5, y_length=4,
+        ).shift(3 * RIGHT)
+        phase_label = Text("Phase Space", font_size=24)
+        phase_label.next_to(phase_axes, UP)
+
+        # Divider
+        divider = DashedLine(3 * UP, 3 * DOWN)
+
+        self.add(divider, phase_axes, phase_label)
+        self.wait(8)
+```
+
+## Best Practices for Physics Simulations
+
+1. **Use substeps** (`n_steps_per_frame`) -- at least 100 for pendulums, 10+ for simple systems
+2. **Separate physics from visuals** -- compute in the updater, update positions at the end
+3. **Color-code states** -- SIR: S=BLUE, I=RED, R=GREY_D
+4. **Show phase space** alongside the physical system when possible
+5. **Use `always_redraw`** for wave functions that depend on ValueTrackers
+6. **Wall bouncing** -- check bounds in the updater and reflect velocity
+7. **Sound cues** -- `self.add_sound()` on impacts for visceral feedback
+8. **Start simple** -- show one ball/particle first, then many