ANIMATION_GUIDE.md

Animated Nuclear Reactions - Quick Guide

🎬 What's New?

Your nuclear reaction simulator now features cinematic animated sequences showing particles colliding and transforming in real-time!

🚀 Installation

# Install new animation dependencies
cd frontend
npm install

# The following will be installed:
# - @react-spring/three (physics-based animations)
# - maath (3D math utilities)

🎮 How to Use

1. Start the App

bash infrastructure/scripts/dev.sh

2. Open in Browser

Navigate to http://localhost:3000

3. Select Animated Mode

Click the 🎬 Animated 3D button (third option)

4. Watch the Show!

The reaction plays automatically:

1. Reactants enter from the left
2. Collision happens at center with explosion
3. Products emerge and move to the right

5. Replay Anytime

Click the 🔄 Replay Animation button to watch again

🎯 Animation Sequence

STEP 1: Reactant Entry (0-2 seconds)
┌────────────────────────────────────┐
│  ●→                                │  Particles enter
│                                    │  from left side
│    ●→                              │  with trail effects
└────────────────────────────────────┘

STEP 2: Collision (2-2.5 seconds)
┌────────────────────────────────────┐
│                                    │
│              💥                    │  BOOM!
│           Sparkles!                │  Explosion
│           Light flash              │  effect
└────────────────────────────────────┘

STEP 3: Product Emergence (2.5-4 seconds)
┌────────────────────────────────────┐
│                                    │
│                    ●               │  Products
│                      ●             │  emerge and
│                        ●           │  move right
└────────────────────────────────────┘

STEP 4: Final State (4+ seconds)
┌────────────────────────────────────┐
│                              ●     │  Products
│                              ●     │  float in
│                              ●     │  final position
└────────────────────────────────────┘

🎨 Visual Effects

Particle Trails

• Glowing trails follow moving particles
• Color-coded by particle type
• Fade effect as particles move

Explosion

• Expanding sphere of energy
• 50 sparkle particles burst out
• Light flash illuminates the scene
• Orange-amber colors represent energy release

Smooth Motion

• Spring physics create natural movement
• Bounce effect when products emerge
• Floating animation in final state

🔬 Try These Reactions!

Best for Animation

D-T Fusion (dt-fusion)

D + T → [BOOM!] → He-4 + n
Energy: 17.6 MeV
Perfect example of fusion!

U-235 Fission (u235-fission)

U-235 + n → [HUGE BOOM!] → Ba-141 + Kr-92 + 3n
Energy: 200 MeV
Massive energy release!

Pu-239 Fission (plutonium239-fission)

Pu-239 + n → [KABOOM!] → Xe-134 + Zr-103 + 3n
Energy: 207 MeV
Even more explosive!

C-14 Decay (carbon14-beta-decay)

C-14 → [gentle transformation] → N-14 + e− + ν̅e
Energy: 0.156 MeV
Subtle but beautiful!

🎛️ Three View Modes

Mode	Button	Best For
2D View	📊	Quick overview, static diagram
3D Interactive	🎮	Exploring angles, manual control
Animated 3D	🎬	Seeing the reaction happen ← NEW!

🎓 Educational Benefits

What Students Learn

1. Collision Process: See particles actually collide
2. Energy Release: Explosion size shows energy scale
3. Reaction Timing: Understand sequence of events
4. Product Formation: Watch new particles emerge
5. Conservation Laws: Track particle counts

Teaching Tips

• Start with simple reactions (2 particles)
• Progress to complex (multiple products)
• Compare fusion vs fission animations
• Discuss energy scales (explosion size)
• Use replay to focus on specific phases

🎮 Controls During Animation

Mouse Controls

• Left-click + drag: Rotate view
• Scroll wheel: Zoom in/out
• Right-click + drag: Pan camera

Animation Controls

• Replay button: Restart from beginning
• View mode buttons: Switch visualization types

Pro Tips

1. Watch once: Let it play completely
2. Replay and rotate: See from different angles
3. Compare reactions: Switch and replay
4. Zoom in: Focus on explosion
5. Pause (use 3D Interactive mode for frozen view)

⚡ Performance Tips

For Best Experience

✅ Use Chrome or Firefox (latest versions) ✅ Close other tabs/applications ✅ Use desktop/laptop (not phone) for best quality ✅ Ensure graphics drivers are updated

If Animation is Slow

• Switch to 3D Interactive or 2D View
• Reduce browser window size
• Close other browser tabs
• Check CPU usage (close background apps)

🐛 Troubleshooting

Animation doesn't start

# Clear cache and reinstall
cd frontend
rm -rf node_modules package-lock.json
npm install

Animation stutters

• Try: Lower browser zoom level (90% or 80%)
• Try: Switch to 3D Interactive mode
• Try: Close other applications

Replay button doesn't work

• Refresh the page
• Check console for errors (F12)

Explosion not visible

• Zoom out using scroll wheel
• Wait for full animation sequence
• Check lighting (may be too bright/dark)

📊 Animation Timing Reference

Event	When	Duration
First reactant enters	0.0s	1.5s
Second reactant enters	0.5s	1.5s
Collision begins	2.0s	0.5s
Explosion peaks	2.2s	0.3s
Products emerge	2.5s	0.8s each
Animation complete	~4.0s	-

🎨 Particle Colors

• 🔵 Blue: Neutrons
• 🔴 Red: Protons
• 🟢 Green: Electrons/Positrons
• 🟠 Orange: Gamma rays/Photons
• 🟣 Purple: Neutrinos
• 🔷 Indigo: Heavy nuclei (U, Pu, etc.)
• 🩷 Pink: Alpha particles

📚 Learn More

Documentation

• Full Animation Docs: docs/animated-3d-reactions.md
• 3D Basics: docs/enhancement-3d-visualization.md
• Visual Guide: docs/visual-guide.md

React Spring

• Official Docs: https://www.react-spring.dev/
• 3D Examples: https://docs.pmnd.rs/react-three-fiber/tutorials/using-with-react-spring

🎉 Share Your Reactions!

Capture screenshots or screen recordings of your favorite animated reactions and share them!

Best Practices

• Use Full Screen mode (F11)
• Record with OBS or similar
• Capture explosion moments
• Compare different reaction types

---

Version: 2.0.0 (Animated Edition)
Date: 2025-10-10
Status: Ready to Animate! 🎬

Enjoy watching nuclear physics come to life! 🔬💥✨