examples

Physics MCP Server - Examples

This directory contains example scripts demonstrating various use cases for the physics MCP server.

Running Examples

Phase 1 Examples (Core Physics)

Examples 00-04 use the analytic provider (no external dependencies):

# Core physics examples
python examples/00_quick_start.py
python examples/01_simple_projectile.py
python examples/02_collision_detection.py
python examples/03_force_energy_momentum.py
python examples/04_r3f_visualization.py

Examples 05-10 require the Rapier service:

# Set up Rapier service
export RAPIER_SERVICE_URL=https://rapier.chukai.io

# Simulation examples
python examples/05_rapier_simulation.py
python examples/06_bounce_detection.py
python examples/07_contact_events.py
python examples/08_pendulum.py
python examples/09_phase1_complete.py
python examples/10_fluid_dynamics.py

Phase 2 Examples (Advanced Physics)

Examples 11-17 use the analytic provider (no external dependencies):

# Advanced physics examples
python examples/11_rotational_dynamics.py
python examples/12_oscillations.py
python examples/13_circular_motion.py
python examples/14_statics.py
python examples/15_kinematics_analysis.py
python examples/17_viscosity_and_reynolds_number.py

Examples Overview

Phase 1: Core Physics (Examples 00-10)

1. Simple Projectile Motion (01_simple_projectile.py)

Demonstrates basic projectile motion calculations:

• Cannonball trajectory at 45° (maximum range)
• Basketball free throw simulation with height checking
• Angle comparison showing how launch angle affects range

Output:

• Maximum height, range, time of flight
• Trajectory sample points
• Comparison table for different angles

Use cases:

• Educational physics demonstrations
• Game development (ballistics)
• Sports analysis

---

2. Collision Detection (02_collision_detection.py)

Shows collision prediction between moving objects:

• Head-on car collision with impact prediction
• Near miss scenario in parallel lanes
• Asteroid collision tracking (space scale)
• Multiple scenarios comparison table

Output:

• Collision yes/no prediction
• Time to impact
• Collision point coordinates
• Impact speed
• Closest approach distance

Use cases:

• Crash avoidance systems
• Accident reconstruction
• Game physics
• Space debris tracking

---

3. Force, Energy, and Momentum (03_force_energy_momentum.py)

Fundamental physics calculations:

• Force calculations (F = ma) for cars, rockets, braking
• Kinetic energy (KE = ½mv²) for various speeds
• Momentum (p = mv) comparisons
• Collision analysis with energy loss calculation

Output:

• Force magnitudes in Newtons
• Energy values in Joules
• Momentum conservation demonstration
• Energy vs. speed relationship (quadratic)

Use cases:

• Engineering analysis
• Crash testing
• Physics education
• Safety calculations

---

4. React Three Fiber Visualization (04_r3f_visualization.py)

Generate 3D visualization data for React Three Fiber:

• Basketball shot with R3F component code
• Multiple trajectories comparison (different angles)
• Trail markers for time-based visualization
• JSON export for easy import into React

Output:

• Trajectory data in R3F-compatible format
• Complete React component examples
• JSON file (basketball_trajectory.json) ready to import
• Trail marker positions for path visualization

Use cases:

• 3D web visualizations
• Educational animations
• Game prototyping
• Scientific visualization

---

Output Examples

Projectile Motion

CANNONBALL TRAJECTORY CALCULATOR
================================================================

1. Cannonball fired at 45° (maximum range angle)
----------------------------------------------------------------
Initial velocity: 50.0 m/s
Launch angle: 45.0°

RESULTS:
  Maximum height: 63.7 m
  Range: 254.6 m
  Time of flight: 7.2 s
  Trajectory points: 51 samples

Collision Detection

COLLISION DETECTION EXAMPLES
================================================================

1. Head-on car collision
----------------------------------------------------------------
Car A: Position (0, 0, 0), Velocity (20, 0, 0) m/s
Car B: Position (100, 0, 0), Velocity (-25, 0, 0) m/s

RESULTS:
  Will collide: True
  ⚠️  COLLISION ALERT!
  Time to impact: 2.11 seconds
  Impact speed: 45.0 m/s (100.7 mph)

R3F Data

{
  "time": 0.0,
  "position": [0.0, 2.0, 0.0],
  "index": 0
},
{
  "time": 0.02,
  "position": [0.12, 2.06, 0.0],
  "index": 1
}

---

---

Phase 2: Advanced Physics (Examples 11-15)

11. Rotational Dynamics (11_rotational_dynamics.py)

Rotational motion and angular mechanics:

• Torque calculations - Wrenches, forces at distance
• Moment of inertia - Various shapes (disk, sphere, rod)
• Angular momentum - Conservation (figure skater example)
• Rotational KE - Flywheel energy storage
• Angular acceleration - Motor startup
• Real-world - Bicycle wheel gyroscopic effects

Output:

• Torque magnitudes and directions
• Moment of inertia for different shapes
• Angular momentum conservation demonstration
• Energy storage in rotating systems

Use cases:

• Mechanical engineering
• Robotics (joint torques)
• Sports science
• Aerospace (satellite attitude)

---

12. Oscillations (12_oscillations.py)

Harmonic motion and spring systems:

• Hooke's law - Spring forces and energy
• Spring-mass period - Natural frequencies
• Simple harmonic motion - Position vs. time
• Damped oscillations - Underdamped, critical, overdamped
• Pendulum motion - Period calculations
• Energy analysis - KE ↔ PE oscillation

Output:

• Spring forces and potential energy
• Oscillation periods and frequencies
• Damping regime classification
• Energy transfer visualization

Use cases:

• Suspension design
• Seismology
• Clock mechanisms
• Vibration isolation

---

13. Circular Motion (13_circular_motion.py)

Circular motion and orbital mechanics:

• Centripetal force - Car on curved road
• Orbital mechanics - ISS orbit analysis
• Banking angles - Highway curve design
• Escape velocity - Various celestial bodies
• Geostationary orbits - 24-hour satellites

Output:

• Required centripetal forces
• Orbital periods and velocities
• Optimal banking angles for speeds
• Escape velocities for planets

Use cases:

• Space mission planning
• Highway design
• Astrophysics
• Amusement park rides

---

14. Statics & Equilibrium (14_statics.py)

Static equilibrium and structural analysis:

• Force balance - Bridge supports
• Torque balance - Seesaws and levers
• Center of mass - Multi-body systems
• Static friction - Will it slide?
• Normal forces - Inclined planes
• Complete equilibrium - Force + torque
• Beam reactions - Simply supported beams

Output:

• Force and torque equilibrium checks
• Center of mass locations
• Friction limits and slip predictions
• Support reactions for beams

Use cases:

• Structural engineering
• Architecture
• Mechanical design
• Safety analysis

---

15. Kinematics Analysis (15_kinematics_analysis.py)

Motion data analysis and trajectory processing:

• Acceleration from position - Numerical differentiation
• Jerk analysis - Motion smoothness
• Trajectory fitting - Polynomial regression
• Motion graphs - Position/velocity/acceleration
• Average speed - Path length vs. displacement
• Instantaneous velocity - With interpolation

Output:

• Derived velocities and accelerations
• Jerk magnitudes (smoothness metrics)
• Fitted trajectory equations
• Graph data for visualization
• Speed and velocity calculations

Use cases:

• Motion capture analysis
• Robotics trajectory planning
• Sports biomechanics
• Autonomous vehicle testing

---

17. Viscosity & Reynolds Number (17_viscosity_and_reynolds_number.py)

Demonstrates the viscosity parameter for accurate Reynolds number calculations:

• Viscosity comparison - Same ball through different fluids
• Motor oil accuracy - Why explicit viscosity matters (100x error without it!)
• Temperature effects - How temp changes flow behavior
• Industrial fluids - Hydraulic oil, glycerin, honey, molasses
• Backwards compatibility - Old code still works

Output:

• Reynolds numbers for various fluids
• Flow regime classification (laminar/transitional/turbulent)
• Comparison tables showing viscosity impact
• Temperature-dependent behavior
• Engineering insights on flow regimes

Use cases:

• Industrial process design
• Lubrication engineering
• Food processing (honey, syrup flows)
• Temperature-sensitive fluid analysis
• Accurate flow regime determination

Key Insight: Without explicit viscosity, motor oil Reynolds number is 100x too high, leading to completely wrong flow regime classification! This example shows how the new viscosity parameter fixes this limitation.

---

Extending Examples

All Phase 1 examples (00-10) use the analytic provider. For simulation-based examples (Rapier), see:

• 05_rapier_simulation.py (requires Rapier service)
• 06_bounce_detection.py (requires Rapier service)
• 07_contact_events.py (requires Rapier service)
• 08_pendulum.py (requires Rapier service)
• 09_phase1_complete.py (requires Rapier service)

All Phase 2 examples (11-17) use the analytic provider (no external dependencies).

---

Integration with MCP

These examples call providers directly. In a real MCP scenario:

# Instead of direct provider calls:
from chuk_mcp_physics.providers.analytic import AnalyticProvider
provider = AnalyticProvider()
result = await provider.calculate_projectile_motion(request)

# LLM calls via MCP tools:
# User: "How far does a ball go at 30 m/s, 45°?"
# LLM calls: calculate_projectile_motion(30, 45)
# Returns: ProjectileMotionResponse

---

Additional Resources

• Main README: ../README.md - Complete documentation
• Rapier Service: ../RAPIER_SERVICE.md - Simulation setup
• API Reference: See tool docstrings in ../src/chuk_mcp_physics/server.py

---

16. Casino Roulette Simulation (16_roulette_simulation.py) 🎰

🌟 SHOWCASE EXAMPLE - Complete Physics Engine Demonstration

A comprehensive casino roulette wheel simulation that demonstrates the full capabilities of the physics engine:

Features Demonstrated:

• Spinning wheel with rotational dynamics
• Ball launch with tangential velocity
• Deflector bounces (8 diamond obstacles)
• Pocket divisions (37 numbered pockets - European roulette)
• Energy dissipation through friction and damping
• Realistic settling behavior
• Complete trajectory recording with bounce detection
• Result determination based on final ball position

Physics Concepts:

• Rotational motion (spinning wheel at 40-60 RPM)
• Collision detection (ball hitting deflectors)
• Friction (wheel, rim, and pocket surfaces)
• Damping (air resistance, rotational friction)
• Energy loss per bounce
• Multi-body interactions (46+ bodies: wheel, rim, 8 deflectors, 37 pockets, ball)
• Complex geometry (cylinders, spheres, boxes)

Output:

• Winning number (0-36) and color (RED/BLACK/GREEN)
• Even/odd classification
• High/low range (1-18 or 19-36)
• Physics statistics (bounces, contacts, distance traveled)
• Energy dissipation analysis
• Full trajectory data for visualization

Use Cases:

• Game development (realistic casino simulations)
• Physics education (complex system dynamics)
• Visualization (3D casino table rendering)
• Probability analysis (physics + statistics)
• Engine capability demonstration

Requires:

• Rapier service
• ~12 seconds simulation time
• Multi-body physics support

export PHYSICS_PROVIDER=rapier
export RAPIER_SERVICE_URL=https://rapier.chukai.io
python examples/16_roulette_simulation.py

Why This Example? This is the perfect showcase for demonstrating what the physics engine can do:

• ✅ Complex real-world scenario everyone understands
• ✅ Combines multiple physics concepts (rotation, collision, friction, damping)
• ✅ Visually impressive (46+ interacting bodies)
• ✅ Realistic behavior (ball bounces, slows, settles)
• ✅ Practical application (actual casino physics)
• ✅ Generates quantifiable results (specific number outcome)
• ✅ Ready for 3D visualization (full trajectory data)

---

Tips

1. Modify parameters in examples to explore different scenarios
2. Save trajectory data to JSON for visualization
3. Combine examples to create complex analyses
4. Add visualization using matplotlib or R3F
5. Scale values for different domains (space, microscopic, etc.)

Enjoy exploring physics with the MCP server! 🚀