Physics MCP Server

Features: 🌀 Magnus Force • 💨 Wind Effects • 🏔️ Altitude • 🌡️ Temperature • 🔄 Tumbling Drag • 🎮 Rigid-Body Sims • 📊 515 Tests

A Model Context Protocol (MCP) server that brings comprehensive physics simulation and calculation capabilities to Large Language Models.

Transform your LLM into a physics engine! This MCP server provides 55 specialized tools spanning classical mechanics, fluid dynamics, rotational motion, and rigid-body simulations. Built for seamless integration with Claude, ChatGPT, and any MCP-compatible AI system.

📚 Table of Contents

What is This?
What's Included
Quick Start
Use Cases
Available Tools
- Common Drag Coefficients
- Advanced Projectile Features 🌀💨🏔️
Examples
Development

🌟 What is This?

Physics MCP Server enables LLMs to perform sophisticated physics calculations and simulations through a standardized protocol. Instead of hallucinating physics formulas or making calculation errors, LLMs can now:

Calculate precisely: Use validated physics formulas for exact results
Simulate realistically: Run rigid-body physics with the Rapier engine
Visualize motion: Generate trajectory data for React Three Fiber, Remotion, and other 3D frameworks
Teach interactively: Answer physics questions with real calculations, not memorized facts
Design intelligently: Analyze forces, collisions, and motion for engineering applications

Why MCP?

The Model Context Protocol provides a standardized way to extend LLM capabilities beyond text generation. This server implements MCP to give language models direct access to:

⚡ Instant physics calculations (projectile motion, forces, energy)
🎮 Rigid-body simulations (collisions, bounces, stacking)
📊 Motion analysis (trajectory fitting, kinematics, velocity profiles)
🌊 Fluid dynamics (drag, buoyancy, lift, Bernoulli)
🔄 Rotational mechanics (torque, angular momentum, gyroscopes)
⚖️ Static analysis (equilibrium, beam reactions, friction)
🔄 Unit conversions (62 unit types: velocity, distance, mass, time, acceleration, torque, frequency, data size, and more)

📦 What's Included

55 Physics Tools Across 10 Categories

Category	Tools	Description
Basic Mechanics	8 tools	Projectile motion, forces, energy, momentum, collisions
Fluid Dynamics	10 tools	Drag, buoyancy, terminal velocity, lift, Magnus force, Bernoulli
Rotational Dynamics	5 tools	Torque, moment of inertia, angular momentum, rotational KE
Oscillations	5 tools	Springs, pendulums, harmonic motion, damping
Circular Motion	5 tools	Centripetal force, orbits, banking angles, escape velocity
Statics	7 tools	Force balance, torque balance, friction, beam reactions
Kinematics	7 tools	Motion analysis, trajectory fitting, velocity calculations, projectile with drag
Collisions	2 tools	Elastic and inelastic 3D collisions with energy loss
Conservation Laws	4 tools	Energy, momentum, and angular momentum verification
Unit Conversions	2 tools	62 unit types across 16 categories (velocity, distance, mass, time, acceleration, torque, frequency, data, etc.)

Realistic vs Ideal Physics Comparison

See the dramatic difference when including real-world effects:

Sport	Scenario	Ideal (No Drag)	Realistic (With Enhancements)	Difference
⚾ Baseball	90 mph fastball	87.5m	52.3m (with drag)	-40% range
⛳ Golf	Pro drive at sea level	251m	129m (with drag)	-49% range
⛳ Golf	Same drive in Denver	251m	181m (drag + altitude)	-28% range
⚽ Soccer	Free kick with wind	25m straight	26m + 5.6m curve (wind + spin)	Bends 5.6m!
🎾 Tennis	Serve on hot day	27m	26.8m (less drag)	+2.3% vs cold

💡 Key Insight: Real physics matters! Air resistance can reduce range by 20-70% depending on the sport.

Two Calculation Modes

Analytic Mode (Built-in, no setup)
- Instant mathematical calculations
- Perfect for education and quick answers
- Exact solutions using physics formulas
- Now includes: Advanced drag, spin (Magnus), wind, altitude effects
Simulation Mode (Requires Rapier service)
- Full rigid-body dynamics
- Complex multi-object interactions
- Realistic material properties and constraints

🚀 Quick Start (30 seconds)

# Try it instantly with uvx (no installation needed)
uvx chuk-mcp-physics

# Or with the public Rapier service for simulations
RAPIER_SERVICE_URL=https://rapier.chukai.io uvx chuk-mcp-physics

# Or use the public hosted MCP server (no local installation)
# Add to Claude Desktop config with URL: https://physics.chukai.io/mcp

For Claude Desktop: Add to your config file:

Option 1: Public Hosted MCP Server (Easiest - No Installation)

{
  "mcpServers": {
    "physics": {
      "command": "node",
      "args": ["-e", "require('https').get('physics.chukai.io/mcp')"]
    }
  }
}

Option 2: Local uvx (Recommended)

{
  "mcpServers": {
    "physics": {
      "command": "uvx",
      "args": ["chuk-mcp-physics"],
      "env": {
        "RAPIER_SERVICE_URL": "https://rapier.chukai.io"
      }
    }
  }
}

🎯 Use Cases

1. Interactive Physics Education

LLM as Physics Tutor

User: "If I throw a ball at 20 m/s at 45°, how far will it go?"
LLM: [calls calculate_projectile_motion]
     "The ball will travel 40.8 meters and reach a maximum height of 10.2 meters..."
     [generates visualization with trajectory points]

Real-World Problem Solving

Students ask physics questions in natural language
LLM calculates exact answers using the MCP tools
Can generate trajectory plots, force diagrams, energy graphs
Interactive "what-if" scenarios: "What if gravity was half?"

2. Game Development & Prototyping

Ballistics Design

User: "I'm designing a cannon in my game. Initial velocity 50 m/s, 30° angle.
       Will it clear a 15m wall at 80m distance?"
LLM: [calls calculate_projectile_motion]
     "At 80m, the projectile is at 18.6m height - it WILL clear the wall.
      It lands at 110.9m range."

Collision Detection

User: "Two spaceships: Ship A at (0,0,0) moving at (10,0,0) m/s, Ship B at (100,5,0)
       moving at (-8,0,0) m/s. Will they collide?"
LLM: [calls check_collision]
     "Yes, collision in 5.3 seconds at position (53.0, 2.65, 0.0) with impact speed 18 m/s"

Rapid Iteration

Test different launch angles, speeds, masses without coding
Verify collision logic before implementation
Generate realistic physics data for procedural content

3. 3D Visualization & Animation (React Three Fiber)

Automated Animation Data Generation

User: "Create a realistic basketball shot animation - 7m throw into 3m high basket"
LLM: [calls calculate_projectile_motion with solved angle]
     [returns trajectory_points array]
     "Here's the trajectory data for R3F. The ball needs 52° launch angle..."

     <mesh position={interpolate(trajectory)}>
       <sphereGeometry args={[0.12]} />
     </mesh>

Rigid-Body Simulations

User: "Simulate 10 boxes falling and stacking in a pile"
LLM: [calls create_simulation]
     [calls add_rigid_body for ground + 10 boxes with random positions]
     [calls record_trajectory for each box]
     "Here are 10 trajectory arrays for your R3F scene, ready to use..."

Use Cases:

Product visualizations (dropping phones, bouncing balls)
Architectural collapse simulations (building demolition previews)
Sports analytics visualizations (ball trajectories, collision analysis)
Sci-fi effects (asteroid fields, debris clouds)

4. Engineering & Design Analysis

Vehicle Crash Prediction

User: "Two cars: Car A (1500kg) at 30 m/s, Car B (1200kg) at 25 m/s approaching.
       Distance 100m. When do they collide and what's the impact energy?"
LLM: [calls check_collision for timing]
     [calls calculate_kinetic_energy for both cars]
     [calls calculate_momentum for momentum analysis]
     "Collision in 1.82 seconds. Total kinetic energy: 1,050,000 J..."

Safety Analysis

Calculate impact forces for crash test scenarios
Predict collision times for autonomous vehicle planning
Analyze momentum transfer in industrial equipment

Structural Testing (with Rapier simulations)

Simulate falling objects hitting structures
Test load-bearing capacity under dynamic loads
Model chain reactions (domino effects)

5. Sports & Athletics

Realistic Ball Trajectories with Air Resistance

User: "How far does a 90 mph baseball fastball actually travel with air resistance?"
LLM: [calls calculate_projectile_with_drag with baseball parameters]
     "With drag (realistic): 52.3m range
      Without drag (vacuum): 87.5m range
      Air resistance reduces range by 40%! Energy lost to drag: 89.2 J..."

Golf Drive Analysis

User: "Pro golfer hits 70 m/s (155 mph) at 12° angle. How far with real air resistance?"
LLM: [calls calculate_projectile_with_drag with golf ball parameters]
     "With drag: 129.4m (142 yards)
      Without drag: 251.0m (274 yards)
      Dimples reduce drag coefficient from 0.47 to 0.25 - saves ~50% range loss!"

Basketball 3-Pointer

User: "What launch angle for a 7.5 m/s shot from 6.75m away (3-point line)?"
LLM: [calls calculate_projectile_with_drag iterating angles]
     "With air resistance, optimal angle is 48° (high arc).
      Range: 6.73m (close!), max height: 3.2m, flight time: 1.1s..."

Shot Analysis Applications

Baseball: Pitch trajectories, drag reduces 90mph fastball range by 40%
Golf: Drive distance with dimpled ball (Cd=0.25 vs smooth ball Cd=0.47)
Basketball: Arc optimization for free throws and 3-pointers
Soccer: Penalty kick trajectories, minimal drag at short distances
Track & field: Javelin, shot put with realistic air resistance
Tennis: Serve and groundstroke trajectory analysis

6. Astrophysics & Space Exploration

Orbital Mechanics (Simplified)

User: "Two asteroids on collision course. A: 500m radius at (0,0,0) moving 15 km/s.
       B: 300m radius at (100km, 2km, 0) moving -12 km/s. Impact prediction?"
LLM: [calls check_collision with appropriate units]
     "Collision in 3.47 seconds at closest approach distance 650m.
      They will NOT collide - miss distance is 150m..."

Applications:

Asteroid impact prediction
Satellite collision avoidance
Debris field analysis
Launch trajectory planning (simplified cases)

7. Fluid Dynamics & Marine/Aerospace Engineering

Underwater Torpedo Simulation

User: "A torpedo is launched underwater at 20 m/s. It weighs 100kg, has a
       streamlined shape (Cd=0.04), and cross-section of 0.03 m².
       How far does it travel in 30 seconds?"
LLM: [calls simulate_underwater_motion]
     "The torpedo travels 147.5 meters before drag and buoyancy slow it down.
      Final velocity: 0.2 m/s. Maximum depth: 729.9 m..."

Terminal Velocity & Drag Analysis

User: "What's the terminal velocity of a skydiver (70kg, 0.7m² area)?"
LLM: [calls calculate_terminal_velocity]
     "Terminal velocity is 40 m/s (90 mph) in belly-down position.
      Takes 12.2 seconds to reach 95% of terminal velocity..."

Buoyancy & Float/Sink Predictions

User: "Will a 1kg steel ball (10cm diameter) float in water?"
LLM: [calls calculate_buoyancy]
     "No, it will sink. Buoyant force is 5.14 N, but weight is 9.81 N.
      The ball is denser than water..."

Applications:

Marine engineering: Submarine drag, torpedo trajectories, underwater vehicles
Aerospace: Parachute descent, atmospheric re-entry, drag optimization
Sports science: Swimming efficiency, diving trajectories
Product design: Floatation devices, drag reduction, hydrodynamics
Environmental: Particle settling rates, pollutant dispersion

8. Film & VFX Pre-visualization

Stunt Planning

User: "Car jumps off 3m ramp at 25 m/s, 20° angle. How far does it fly and where does it land?"
LLM: [calls calculate_projectile_motion]
     "Airtime: 1.75 seconds, landing at 42.9m horizontal distance,
      impact speed 26.3 m/s. Recommend crashmat at 40-45m mark..."

Destruction Sequences

Building collapses with rigid-body sim
Explosion debris trajectories
Vehicle stunts and crashes
Realistic object interactions

8. Military & Defense (Training/Education)

Ballistics Training

User: "Artillery shell: muzzle velocity 800 m/s, 45° elevation. Range and time of flight?"
LLM: [calls calculate_projectile_motion]
     "Range: 65.3 km, flight time: 115.5 seconds, max altitude: 16.3 km"

Collision Avoidance

Projectile trajectory analysis
Impact point prediction
Intercept course calculations

9. Robotics & Automation

Path Planning

User: "Robot arm needs to toss part into bin 2m away, 0.5m higher.
       What velocity is needed?"
LLM: [reverse-calculates using projectile_motion multiple times]
     "Minimum velocity: 4.7 m/s at 38° angle. Recommend 5.0 m/s for safety margin..."

Collision Detection

Multi-robot coordination
Object catching/throwing
Assembly line optimization

10. Data Science & Research

Physics Simulations for ML Training Data

# Generate thousands of collision scenarios for ML model training
for i in range(10000):
    result = await check_collision(random_params())
    training_data.append({
        'features': params,
        'label': result.will_collide,
        'impact_time': result.collision_time
    })

Use Cases:

Generate labeled physics data for ML models
Validate physics-informed neural networks
Test scientific hypotheses with rapid iteration
Monte Carlo simulations (vary parameters, aggregate results)

🚀 Real-World Example Workflows

Workflow 1: Basketball Shot Optimizer

1. User: "I'm 2m tall shooting from free-throw line (4.6m). Basket is 3.05m high.
          What's the minimum velocity needed?"

2. LLM calls calculate_projectile_motion with varying velocities
   - Try v=5 m/s → doesn't reach
   - Try v=7 m/s → reaches
   - Binary search finds minimum: v=6.2 m/s at 52° angle

3. LLM: "Minimum velocity is 6.2 m/s at 52° launch angle.
         For comfortable margin, use 7.0 m/s (typical free throw speed).
         Here's the trajectory visualization..."

Workflow 2: Car Crash Investigation

1. User: "Analyze accident: Car A (1500kg) skid marks 30m, Car B (1200kg) skid marks 25m.
          Coefficient of friction 0.7. What were impact speeds?"

2. LLM:
   - Calculates deceleration from friction: a = μg = 0.7 × 9.81 = 6.87 m/s²
   - Uses v² = 2ad to find velocities
   - Calls calculate_kinetic_energy for both cars
   - Calls calculate_momentum for momentum analysis

3. LLM: "Car A impact speed: ~20.3 m/s (45 mph), Car B: ~18.5 m/s (41 mph).
         Total kinetic energy at impact: 513,000 J. Here's the force analysis..."

Workflow 3: Game Level Design with Physics Simulation

1. User: "Create a Rube Goldberg machine: ball rolls down ramp, hits dominos,
          dominos knock ball into basket"

2. LLM:
   - Calls create_simulation(gravity_y=-9.81)
   - Adds ground plane (static)
   - Adds ramp (static, angled)
   - Adds ball (dynamic, sphere, position at ramp top)
   - Adds 10 dominos (dynamic boxes in a line)
   - Adds basket (static)
   - Calls step_simulation(steps=1000)
   - Analyzes contacts to verify chain reaction
   - Calls record_trajectory for each piece

3. LLM: "Simulation complete! Ball triggers all dominos successfully.
         Here are the trajectories for R3F visualization.
         Domino #3 falls at t=1.2s, domino #7 at t=2.1s..."

Workflow 4: Satellite Collision Warning

1. User: "Satellite A: position (6700km, 0, 0), velocity (0, 7.5km/s, 0)
          Satellite B: position (6650km, 50km, 0), velocity (0, 7.6km/s, 0.1km/s)
          Collision risk?"

2. LLM:
   - Calls check_collision with satellite data
   - Analyzes closest approach

3. LLM: "No collision. Closest approach: 48.3 km at t=412 seconds.
         Satellites are in similar orbits but safe separation.
         Recommend: monitor as orbits may precess over time."

🎨 Visualization Integration

React Three Fiber (R3F) Example

function PhysicsAnimation() {
  const [trajectory, setTrajectory] = useState([]);

  useEffect(() => {
    // LLM generated this trajectory data via MCP
    fetch('/api/mcp/record_trajectory', {
      body: JSON.stringify({
        sim_id: "sim_xyz",
        body_id: "ball",
        steps: 300
      })
    }).then(res => setTrajectory(res.frames));
  }, []);

  return (
    <Canvas>
      <AnimatedBall trajectory={trajectory} />
      <Ground />
    </Canvas>
  );
}

function AnimatedBall({ trajectory }) {
  const ref = useRef();

  useFrame((state) => {
    const t = state.clock.getElapsedTime();
    const frame = trajectory[Math.floor(t / 0.016) % trajectory.length];
    if (frame && ref.current) {
      ref.current.position.fromArray(frame.position);
      ref.current.quaternion.fromArray(frame.orientation);
    }
  });

  return (
    <mesh ref={ref}>
      <sphereGeometry args={[0.5]} />
      <meshStandardMaterial color="orange" />
    </mesh>
  );
}

📊 Trajectory Data Format

All trajectory recordings follow a canonical schema for maximum interoperability with R3F, Remotion, Three.js, and other animation systems.

Schema Definition

interface Trajectory {
  dt: number;              // Time step between frames (seconds)
  frames: Frame[];         // Ordered list of frames
  meta: {
    body_id: string;       // Fully qualified: "rapier://sim-123/body-1"
    total_time: number;    // Total duration (seconds)
    num_frames: number;    // Frame count
  };
}

interface Frame {
  t: number;                               // Absolute time (seconds)
  position: [number, number, number];      // [x, y, z] in meters
  rotation: [number, number, number, number];  // Quaternion [x, y, z, w]
  velocity?: [number, number, number];     // Optional: linear velocity (m/s)
  angular_velocity?: [number, number, number];  // Optional: angular velocity (rad/s)
}

JSON Example

{
  "dt": 0.016,
  "frames": [
    {
      "t": 0.0,
      "position": [0, 1, 0],
      "rotation": [0, 0, 0, 1],
      "velocity": [0, 0, 0]
    },
    {
      "t": 0.016,
      "position": [0.1, 1.01, 0],
      "rotation": [0, 0.01, 0, 0.9999],
      "velocity": [6.25, 0.61, 0]
    }
  ],
  "meta": {
    "body_id": "rapier://sim-abc123/ball",
    "total_time": 4.8,
    "num_frames": 300
  }
}

Usage in React Three Fiber

import { useRef } from "react";
import { useFrame } from "@react-three/fiber";

function AnimatedObject({ trajectory }) {
  const ref = useRef();

  useFrame((state) => {
    const elapsed = state.clock.getElapsedTime();
    const frameIdx = Math.floor(elapsed / trajectory.dt);
    const frame = trajectory.frames[frameIdx % trajectory.frames.length];

    if (frame && ref.current) {
      ref.current.position.fromArray(frame.position);
      ref.current.quaternion.fromArray(frame.rotation);
    }
  });

  return (
    <mesh ref={ref}>
      <sphereGeometry args={[0.5]} />
      <meshStandardMaterial color="orange" />
    </mesh>
  );
}

Usage in Remotion

import { useCurrentFrame } from "remotion";
import { ThreeCanvas } from "@remotion/three";

export const PhysicsAnimation = ({ trajectory }) => {
  const frame = useCurrentFrame();
  const frameData = trajectory.frames[frame];

  return (
    <AbsoluteFill>
      <ThreeCanvas>
        <mesh position={frameData.position}>
          <sphereGeometry />
        </mesh>
      </ThreeCanvas>
    </AbsoluteFill>
  );
};

Design Notes

Quaternions for rotation: More compact and interpolation-friendly than Euler angles
Absolute time: Each frame has absolute time t, making scrubbing easier
Constant dt: Frames are evenly spaced, simplifying playback
Optional velocities: Include if needed for motion blur or physics visualization
Qualified body_id: Format is rapier://sim-{id}/{body_id} for traceability

🛠️ Installation

Prerequisites

Python 3.11+
For simulations: Rapier service (see RAPIER_SERVICE.md)
- Public service available at: https://rapier.chukai.io
- Or run locally with Docker (see below)

Quick Start with uvx (Recommended)

The fastest way to try chuk-mcp-physics without installation:

# Run directly with uvx (no installation needed)
uvx chuk-mcp-physics

# With environment variables
uvx --with chuk-mcp-physics chuk-mcp-physics

Installation Methods

Option 1: Install from PyPI (Recommended)

# Install globally
pip install chuk-mcp-physics

# Or with pipx (isolated environment)
pipx install chuk-mcp-physics

# Run the server
chuk-mcp-physics

# Or via python module
python -m chuk_mcp_physics.server

Option 2: Install from Source

# Clone repository (from your source location)
cd chuk-mcp-physics

# Install in development mode
make dev-install

# Run the server
chuk-mcp-physics

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Using uvx (Recommended - No Installation Required)

{
  "mcpServers": {
    "physics": {
      "command": "uvx",
      "args": ["chuk-mcp-physics"],
      "env": {
        "PHYSICS_PROVIDER": "rapier",
        "RAPIER_SERVICE_URL": "https://rapier.chukai.io"
      }
    }
  }
}

Option 2: Using Installed Package

{
  "mcpServers": {
    "physics": {
      "command": "python",
      "args": ["-m", "chuk_mcp_physics.server"],
      "env": {
        "PHYSICS_PROVIDER": "rapier",
        "RAPIER_SERVICE_URL": "https://rapier.chukai.io"
      }
    }
  }
}

Option 3: Analytic Only (No External Service)

{
  "mcpServers": {
    "physics": {
      "command": "uvx",
      "args": ["chuk-mcp-physics"],
      "env": {
        "PHYSICS_PROVIDER": "analytic"
      }
    }
  }
}

📖 Available Tools

Tool Organization

Tools are organized into two tiers to help you choose the right abstraction:

1️⃣ Analytic Primitives (No External Service)

Best for: Quick calculations, education, simple scenarios

Direct formula-based calculations that return instant results:

Tool	What It Does	Example Use Case
`calculate_projectile_motion`	Ballistic trajectory using kinematic equations	"How far does a cannonball go?"
`check_collision`	Predict if two spheres will collide	"Will these asteroids hit?"
`calculate_force`	F = ma calculations	"What force accelerates this car?"
`calculate_kinetic_energy`	KE = ½mv²	"How much energy in this crash?"
`calculate_momentum`	p = mv	"What's the momentum transfer?"
`calculate_potential_energy`	PE = mgh	"What's the energy at height?"
`calculate_work_power`	Work (F·d) and power (W/t)	"How much work lifting this box?"
`calculate_elastic_collision`	1D elastic collision (conserves energy & momentum)	"Pool balls colliding?"
`calculate_drag_force`	Air/water resistance (F = ½ρv²C_dA)	"What's the drag on this car?"
`calculate_buoyancy`	Will it float? (Archimedes)	"Does a steel ball float in water?"
`calculate_terminal_velocity`	Maximum fall speed	"How fast does a skydiver fall?"
`simulate_underwater_motion`	Underwater trajectory with drag & buoyancy	"How far does a torpedo travel?"

Characteristics:

⚡ Instant execution (< 1ms)
📦 No external dependencies
🎯 Exact mathematical solutions
✅ Always available (no service required)

Limitations:

Only spherical objects (for collisions)
No complex shapes
No multi-body interactions
No friction or material properties

2️⃣ Simulation Primitives (Requires Rapier Service)

Best for: Complex physics, multi-body dynamics, visualization data

Low-level building blocks for rigid-body simulations:

Tool	What It Does	When to Use
`create_simulation`	Initialize physics world	Start any simulation
`add_rigid_body`	Add objects (box, sphere, capsule, etc.)	Build scene
`step_simulation`	Advance time	Run physics
`record_trajectory`	Capture motion for R3F/Remotion	Generate animation data
`destroy_simulation`	Cleanup resources	End simulation

Characteristics:

🦀 Requires Rapier service
🔄 Stateful (track simulation ID)
🧩 Composable (combine for complex scenarios)
💪 Full rigid-body dynamics

Typical workflow:

# 1. Create world
sim = create_simulation(gravity_y=-9.81)

# 2. Add objects
add_rigid_body(sim.sim_id, "ground", type="static", shape="plane")
add_rigid_body(sim.sim_id, "ball", type="dynamic", shape="sphere",
               radius=0.5, position=[0, 5, 0])

# 3. Run simulation
step_simulation(sim.sim_id, steps=300)

# 4. Record for visualization
trajectory = record_trajectory(sim.sim_id, "ball", steps=300)

# 5. Cleanup
destroy_simulation(sim.sim_id)

📋 Complete Tool Reference

Basic Mechanics (8 tools)

Tool	Purpose	Example
`calculate_projectile_motion`	Ballistic trajectories	"How far does a cannonball travel?"
`check_collision`	Predict sphere collisions	"Will these asteroids hit?"
`calculate_force`	F = ma calculations	"What force accelerates this car?"
`calculate_kinetic_energy`	KE = ½mv²	"Energy in moving object?"
`calculate_momentum`	p = mv	"Momentum of moving object?"
`calculate_potential_energy`	PE = mgh	"Energy at height?"
`calculate_work_power`	Work (F·d) and power (W/t)	"Work done lifting object?"
`calculate_elastic_collision`	1D elastic collision	"Pool ball velocities after impact?"

Fluid Dynamics (10 tools)

Tool	Purpose	Example
`calculate_drag_force`	Air/water resistance	"Drag on car at speed?"
`calculate_buoyancy`	Will it float? (Archimedes)	"Does steel ball float?"
`calculate_terminal_velocity`	Maximum fall speed	"Skydiver terminal velocity?"
`simulate_underwater_motion`	Underwater trajectory	"How far does torpedo travel?"
`calculate_lift_force`	Aerodynamic lift	"Lift on aircraft wing?"
`calculate_magnus_force`	Force on spinning ball	"Why does curveball curve?"
`calculate_bernoulli`	Pressure in flowing fluid	"Pressure in pipe constriction?"
`calculate_pressure_at_depth`	Hydrostatic pressure	"Pressure at 30m depth?"
`calculate_reynolds_number`	Flow regime classification	"Is flow turbulent?"
`calculate_venturi_effect`	Flow through constriction	"Velocity in throat?"

Rotational Dynamics (5 tools)

Tool	Purpose	Example
`calculate_torque`	τ = r × F (cross product)	"Torque from wrench?"
`calculate_moment_of_inertia`	Rotational inertia	"MOI of spinning disk?"
`calculate_angular_momentum`	L = Iω	"Angular momentum of wheel?"
`calculate_rotational_kinetic_energy`	Rotational KE = ½Iω²	"Energy in flywheel?"
`calculate_angular_acceleration`	α = τ/I	"How fast does it spin up?"

Oscillations & Waves (5 tools)

Tool	Purpose	Example
`calculate_hookes_law`	Spring force F = -kx	"Force in compressed spring?"
`calculate_spring_mass_period`	Oscillation period	"How fast does mass oscillate?"
`calculate_simple_harmonic_motion`	Position at time t	"Where is mass at t=2s?"
`calculate_damped_oscillation`	Motion with damping	"How quickly does it settle?"
`calculate_pendulum_period`	Pendulum swing time	"Period of 1m pendulum?"

Circular Motion & Orbits (5 tools)

Tool	Purpose	Example
`calculate_centripetal_force`	F_c = mv²/r	"Force for circular motion?"
`calculate_orbital_period`	Kepler's 3rd law	"Satellite orbital period?"
`calculate_banking_angle`	Optimal curve angle	"Banking for highway curve?"
`calculate_escape_velocity`	Escape from gravity	"Earth escape velocity?"
`analyze_circular_orbit`	Complete orbital analysis	"Analyze ISS orbit?"

Statics & Equilibrium (7 tools)

Tool	Purpose	Example
`check_force_balance`	Verify ΣF = 0	"Are forces balanced?"
`check_torque_balance`	Verify Στ = 0	"Will seesaw balance?"
`calculate_center_of_mass`	Balance point	"Where is center of mass?"
`calculate_static_friction`	Max friction force	"Will object slip?"
`calculate_normal_force`	Force on incline	"Normal force on ramp?"
`check_equilibrium`	Force + torque balance	"Is structure stable?"
`calculate_beam_reactions`	Support forces	"Reaction forces on beam?"

Kinematics Analysis (7 tools)

Tool	Purpose	Example
`calculate_acceleration_from_position`	Derive from position data	"Acceleration from motion capture?"
`calculate_jerk`	Rate of acceleration change	"How jerky is motion?"
`fit_trajectory`	Find trajectory equation	"Fit parabola to data?"
`generate_motion_graph`	Position/velocity/accel graphs	"Generate motion graphs?"
`calculate_average_speed`	Speed along path	"Average speed on route?"
`calculate_instantaneous_velocity`	Velocity at exact time	"Speed at t=2.5s?"
`calculate_projectile_with_drag`	Realistic projectile with air resistance	"How far does baseball actually go?"

Advanced Collisions (2 tools)

Tool	Purpose	Example
`calculate_elastic_collision_3d`	3D perfect collision	"Pool balls in 3D?"
`calculate_inelastic_collision_3d`	3D collision with energy loss	"Car crash analysis?"

Conservation Laws (4 tools)

Tool	Purpose	Example
`check_energy_conservation`	Verify energy conserved	"Is collision realistic?"
`check_momentum_conservation`	Verify momentum conserved	"Is momentum preserved?"
`check_angular_momentum_conservation`	Verify L conserved	"Is rotation valid?"
`track_energy_dissipation`	Energy loss over time	"Where did energy go?"

Unit Conversions (2 tools)

Tool	Purpose	Supported Units
`convert_unit`	Convert between units	Velocity: m/s, km/h, mph, ft/s, knots Distance: m, km, mi, ft, yd, in Mass: kg, g, lb, oz Force: N, kN, lbf Energy: J, kJ, cal, BTU, kWh Power: W, kW, hp Temperature: K, C, F Angle: rad, deg Pressure: Pa, kPa, bar, psi, atm Area: m², km², ft², acre Volume: m³, L, gal, ft³ Time: s, min, hr, day Acceleration: m/s², g, ft/s² Torque: N·m, lb·ft, lb·in Frequency: Hz, kHz, MHz, GHz Data Size: B, KB, MB, GB
`list_unit_conversions`	Get all supported units	Returns complete list of conversions

Examples:

# Natural language queries work perfectly
"Convert 60 mph to m/s"  # → 26.82 m/s
"How fast is 100 km/h in mph?"  # → 62.14 mph
"What's 10 kg in pounds?"  # → 22.05 lb
"Convert 100 feet to meters"  # → 30.48 m
"What's 98.6°F in Celsius?"  # → 37°C
"Convert 3 g-force to m/s²"  # → 29.42 m/s²
"What's 300 N·m in lb·ft?"  # → 221.27 lb·ft
"Convert 1 hour to seconds"  # → 3600 s

Features:

⚡ Instant conversions (no external service needed)
🔄 Automatic indirect conversions (e.g., mph → km/h via m/s)
📐 70+ unit types across 16 categories
🎯 Perfect for natural language physics queries
🚀 Includes engineering units (torque, acceleration, frequency)

Common Drag Coefficients (Cd) Reference

For use with calculate_projectile_with_drag tool:

Object	Drag Coefficient (Cd)	Notes
Sports Balls
Baseball	0.4	Stitched surface
Golf ball (dimpled)	0.25	Dimples reduce drag by ~50%
Golf ball (smooth)	0.47	Without dimples (don't use!)
Basketball	0.55	Large, textured surface
Soccer ball	0.25	Modern, smooth panels
Tennis ball	0.55	Fuzzy surface
Football (American)	0.05-0.15	Highly streamlined, orientation-dependent
Generic Shapes
Sphere (smooth)	0.47	Default reference
Flat plate (perpendicular)	1.28	Maximum drag
Streamlined body	0.04	Teardrop/airfoil
Cylinder (perpendicular)	1.15	Like a pole
Vehicles
Car (modern)	0.25-0.35	Aerodynamic design
Truck	0.6-0.9	Boxy shape
Bicycle + rider	0.9	Upright position
Human Body
Skydiver (belly-down)	1.0-1.3	Maximum drag
Skydiver (head-down)	0.7	Streamlined
Projectiles
Bullet (supersonic)	0.295	Pointed nose
Artillery shell	0.15-0.25	Streamlined

Basic Usage Example:

# Baseball pitch with realistic drag
result = await calculate_projectile_with_drag(
    initial_velocity=40.23,  # 90 mph
    angle_degrees=10,
    mass=0.145,
    cross_sectional_area=0.0043,  # π × (0.037m)²
    drag_coefficient=0.4  # Baseball Cd
)

Advanced Projectile Features

The calculate_projectile_with_drag tool supports optional enhancements for ultra-realistic simulations:

🌀 Magnus Force (Spin Effects)

Spin creates a pressure differential that deflects the ball's path. Essential for:

Baseball: Curveballs (topspin drops), fastballs (backspin lifts)
Golf: Backspin increases carry, sidespin causes slices/hooks
Soccer: Bending free kicks around defensive walls
Tennis: Topspin brings ball down faster

# Baseball curveball with topspin
result = await calculate_projectile_with_drag(
    initial_velocity=35,
    angle_degrees=0,
    mass=0.145,
    cross_sectional_area=0.0043,
    drag_coefficient=0.4,
    spin_rate=261.8,  # 2500 rpm = 261.8 rad/s
    spin_axis=[0, 0, -1]  # Topspin (negative z-axis)
)
# Returns lateral_deflection and magnus_force_max

Spin Parameters:

spin_rate: Rotation speed in rad/s (convert from RPM: rpm × 2π/60)
spin_axis: Unit vector [x, y, z] indicating spin direction
- [0, 0, 1] = Backspin (lifts)
- [0, 0, -1] = Topspin (drops)
- [0, 1, 0] = Sidespin (hooks/slices)

💨 Wind Effects

Constant wind vector affects trajectory throughout flight:

# Soccer free kick with 5 m/s crosswind
result = await calculate_projectile_with_drag(
    initial_velocity=28,
    angle_degrees=12,
    mass=0.43,
    cross_sectional_area=0.0388,
    drag_coefficient=0.25,
    wind_velocity=[5.0, 0.0]  # [horizontal, vertical] in m/s
)
# Returns wind_drift showing total deflection

Wind Types:

Tailwind: [+X, 0] - increases range
Headwind: [-X, 0] - decreases range
Crosswind: [X, 0] - lateral deflection
Updraft: [0, +Y] - increases height and flight time
Downdraft: [0, -Y] - decreases height

🏔️ Altitude & Temperature Effects

Air density varies with elevation and temperature, dramatically affecting drag:

# Golf drive in Denver (1600m elevation, 20°C)
result = await calculate_projectile_with_drag(
    initial_velocity=70,
    angle_degrees=12,
    mass=0.0459,
    cross_sectional_area=0.00143,
    drag_coefficient=0.25,
    altitude=1600,  # meters above sea level
    temperature=20  # Celsius
)
# Returns effective_air_density showing actual density used

Real-World Impact:

Denver (1600m): ~10% longer drives than sea level
Hot day (+20°C): ~2-3% less drag than cold day
Everest Base Camp (5300m): ~50% less air density!

Air Density Formula:

ρ(h,T) = ρ₀ × exp(-Mgh/RT₀) × (T₀/T)

Where:

ρ₀ = sea level density (1.225 kg/m³)
h = altitude (meters)
T = temperature (Kelvin)
M = molar mass of air (0.029 kg/mol)
g = gravity (9.81 m/s²)
R = gas constant (8.314 J/(mol·K))

🌟 Combined Effects Example

# Golf ball with ALL effects (spin + wind + altitude)
result = await calculate_projectile_with_drag(
    initial_velocity=70,
    angle_degrees=12,
    mass=0.0459,
    cross_sectional_area=0.00143,
    drag_coefficient=0.25,
    spin_rate=200,  # Backspin
    spin_axis=[0, 0, 1],
    wind_velocity=[3, 0],  # Tailwind
    altitude=1000,  # Moderate elevation
    temperature=25  # Warm day
)
# All effects combine for maximum realism!

See Examples:

examples/sports_projectiles_with_drag.py - Basic drag effects
examples/advanced_projectile_effects.py - Magnus force, wind, altitude

🔄 Orientation-Dependent Drag (Rapier Simulations)

For tumbling objects like footballs, frisbees, and javelins, drag varies dramatically based on orientation. A football in a perfect spiral has 3-6× less drag than when tumbling end-over-end!

Available via Rapier rigid-body simulations using the add_rigid_body tool with orientation-dependent drag parameters.

How It Works

Objects moving through air experience drag that depends on their orientation:

Football spiral: Streamlined along flight path → low drag (~0.1 Cd)
Football tumbling: Broadside to airflow → high drag (~0.6 Cd)
Frisbee flat: Minimal cross-section → low drag (~0.08 Cd)
Frisbee tilted: Larger cross-section → higher drag

New add_rigid_body Parameters:

drag_coefficient: float      # Base Cd value
drag_area: float             # Reference cross-sectional area (m²)
drag_axis_ratios: [x, y, z]  # Drag variation along body axes
fluid_density: float         # Fluid density (air=1.225, water=1000)

Example: Football Spiral vs Tumble

# Perfect spiral (low drag along Y-axis)
await add_rigid_body(
    sim_id,
    id="spiral",
    shape="capsule",
    size=[0.17, 0.28],  # diameter, length
    mass=0.42,
    position=[0, 2, 0],
    velocity=[vx, vy, 0],
    angular_velocity=[0, 126, 0],  # 20 rev/s spin
    # Orientation-dependent drag
    drag_coefficient=0.1,
    drag_area=0.023,  # End-on area
    drag_axis_ratios=[1.0, 0.2, 1.0],  # 5× less drag along Y
    fluid_density=1.225
)

# Tumbling (higher drag, averaging all orientations)
await add_rigid_body(
    sim_id,
    id="tumble",
    shape="capsule",
    size=[0.17, 0.28],
    mass=0.42,
    position=[0, 2, 0],
    velocity=[vx, vy, 0],
    angular_velocity=[31.4, 0, 0],  # Tumbling rotation
    # Orientation-dependent drag
    drag_coefficient=0.6,  # Higher base Cd
    drag_area=0.048,  # Broadside area
    drag_axis_ratios=[0.8, 1.0, 0.8],  # Less streamlining
    fluid_density=1.225
)

Result: Spiral can travel 20-40% farther than tumble!

Common `drag_axis_ratios` Patterns

The drag_axis_ratios parameter specifies how drag varies along each body-local axis [X, Y, Z]:

Object	Ratios	Streamlined Axis	Use Case
Football spiral	`[1.0, 0.2, 1.0]`	Y (length)	Perfect pass
Javelin	`[1.5, 0.2, 1.5]`	Y (length)	Optimal flight
Frisbee flat	`[1.0, 0.1, 1.0]`	Y (vertical)	Stable throw
Sphere	`[1.0, 1.0, 1.0]`	None	Basketball, etc.
Disc tumbling	`[0.8, 1.0, 0.8]`	Less variation	Wobbly throw

Physical Meaning:

0.2 = 20% of base drag along that axis (very streamlined)
1.0 = 100% of base drag (normal)
1.5 = 150% of base drag (higher resistance)

Real-World Examples

⚽ Football Throw (spiral vs tumble):

# Spiral: 45-50 yards typical
# Tumble: 30-35 yards (30-40% loss)

🥏 Frisbee (stable vs wobbling):

# Stable (600 rpm spin): 60-80 meters
# Wobbling (slow spin): 30-40 meters (50% loss)

🏹 Javelin (optimal vs poor technique):

# Optimal angle: 70-90 meters (Olympic level)
# Poor release: 40-50 meters (45% loss)

Important Notes

⚠️ Requires Rapier Service: Orientation-dependent drag calculations are performed by the Rapier physics service (Rust implementation). The Python MCP server defines the API and passes parameters to Rapier.

🎯 When to Use:

Sports simulations (football, frisbee, discus)
Projectile accuracy (javelin, arrows, darts)
Aerospace applications (rocket tumbling, debris)

🔬 Physics: The drag force is calculated in the Rapier service using the body's current orientation (quaternion) to transform body-local drag coefficients into world-space drag forces.

Hybrid Drag Implementation: Rapier uses a hybrid approach to handle extreme drag cases:

Normal drag (ratio < 2.0): Force-based orientation-dependent drag with full anisotropic behavior
Extreme drag (ratio ≥ 2.0): Damping-based drag for stability when drag-to-weight ratio is very high
- Automatically activates for objects like ping pong balls (high drag, low mass)
- Prevents numerical instabilities while maintaining realistic energy dissipation
- Logged as INFO when triggered: "Body 'name' has extreme drag (ratio=X.XX), using damping"

Where drag_ratio = 0.5 * fluid_density * drag_coefficient * drag_area * v_typical^2 / (mass * g)

Measurement Notes: When analyzing trajectories, use max(x_positions) instead of final_x to measure range. Rapier's solver may occasionally jitter backward slightly near ground impact, but this is a measurement artifact, not a physics error. The drag forces always oppose motion correctly.

See Example:

examples/tumbling_projectiles.py - Football, frisbee, and javelin orientation effects

✨ Phase 1 Features (Production Ready)

All Phase 1 features are complete, tested (98% coverage), and deployed to production!

Phase 1.1: Bounce Detection 🏀

Automatically detect and analyze bounces in ball trajectories with energy loss calculations.

What it does:

Detects bounce events from trajectory data (velocity reversals near ground)
Calculates energy loss percentage for each bounce
Provides before/after velocities and heights
Perfect for answering "how many bounces?" and "when does it stop?"

Tool: record_trajectory_with_events

Example:

# Record a bouncing ball
traj = await record_trajectory_with_events(
    sim_id=sim_id,
    body_id="ball",
    steps=300,
    detect_bounces=True,
    bounce_height_threshold=0.01  # 1cm = "on ground"
)

print(f"Detected {len(traj.bounces)} bounces")
for bounce in traj.bounces:
    print(f"Bounce #{bounce.bounce_number}:")
    print(f"  Time: {bounce.time:.2f}s")
    print(f"  Height: {bounce.height_at_bounce:.3f}m")
    print(f"  Energy loss: {bounce.energy_loss_percent:.1f}%")
    print(f"  Speed before: {bounce.speed_before:.2f} m/s")
    print(f"  Speed after: {bounce.speed_after:.2f} m/s")

Output:

Detected 5 bounces
Bounce #1: Time: 1.43s, Height: 0.00m, Energy loss: 36.0%, Speed: 14.0→9.0 m/s
Bounce #2: Time: 2.51s, Height: 0.00m, Energy loss: 36.0%, Speed: 8.9→5.7 m/s
Bounce #3: Time: 3.23s, Height: 0.00m, Energy loss: 36.0%, Speed: 5.7→3.6 m/s
...

Use Cases:

Sports analytics (basketball arc, tennis serve bounces)
Product testing (phone drop tests, durability simulations)
Game development (realistic ball physics)
Education (demonstrate energy conservation)

See: examples/06_bounce_detection.py for full demo

Phase 1.2: Contact Events 📊

Real-time collision tracking with detailed contact information from the physics engine.

What it does:

Tracks all contact events between bodies during simulation
Reports contact start, ongoing, and end events
Provides impulse magnitudes, normals, and relative velocities
Essential for collision analysis and force calculations

Included in: All trajectory recordings (record_trajectory, record_trajectory_with_events)

Contact Event Data:

ContactEvent(
    time=1.43,                          # When contact occurred
    body_a="ball",                      # First body
    body_b="ground",                    # Second body
    contact_point=[0.0, 0.05, 0.0],    # World space position
    normal=[0.0, 1.0, 0.0],            # Contact normal (from A to B)
    impulse_magnitude=14.2,             # Collision impulse (N⋅s)
    relative_velocity=[0.0, -14.0, 0.0], # Relative velocity
    event_type="started"                # "started", "ongoing", or "ended"
)

Example:

traj = await record_trajectory(sim_id, "ball", steps=300)

# Analyze contacts
for event in traj.contact_events:
    if event.event_type == "started":
        print(f"Collision at t={event.time:.2f}s")
        print(f"  Bodies: {event.body_a} ↔ {event.body_b}")
        print(f"  Impulse: {event.impulse_magnitude:.1f} N⋅s")
        print(f"  Impact speed: {abs(event.relative_velocity[1]):.1f} m/s")

Use Cases:

Collision analysis (car crashes, sports impacts)
Force calculations (derive forces from impulses)
Interaction tracking (which objects touched what)
VFX triggers (spark effects on collisions)

See: examples/07_contact_events.py for full demo

Phase 1.3: Joints & Constraints 🔗

Connect rigid bodies with realistic joints for complex mechanical systems.

What it does:

Create constraints between bodies (hinges, sliders, ball-and-socket, fixed)
Build complex systems (pendulums, chains, ragdolls, machinery)
Realistic mechanical motion (doors, wheels, linkages)
Perfect for simulating articulated structures

Tool: add_joint

Joint Types:

Type	Description	Example Uses
FIXED	Rigid connection (glue)	Attach hat to head, weld joints
REVOLUTE	Hinge rotation around axis	Doors, pendulums, wheels
SPHERICAL	Ball-and-socket rotation	Ragdoll shoulders, gimbal mounts
PRISMATIC	Sliding along axis	Pistons, elevators, sliders

Example - Simple Pendulum:

# Create anchor point
await add_rigid_body(
    sim_id=sim_id,
    body_id="anchor",
    body_type="static",
    shape="sphere",
    size=[0.05],
    position=[0.0, 3.0, 0.0]
)

# Create pendulum bob
await add_rigid_body(
    sim_id=sim_id,
    body_id="bob",
    body_type="dynamic",
    shape="sphere",
    size=[0.2],
    mass=1.0,
    position=[1.5, 1.5, 0.0]  # Start displaced
)

# Connect with revolute joint (hinge)
await add_joint(
    sim_id=sim_id,
    joint=JointDefinition(
        id="hinge",
        joint_type=JointType.REVOLUTE,
        body_a="anchor",
        body_b="bob",
        anchor_a=[0.0, 0.0, 0.0],    # Center of anchor
        anchor_b=[0.0, 0.2, 0.0],    # Top of bob
        axis=[0.0, 0.0, 1.0]         # Rotate around Z-axis
    )
)

# Simulate and see realistic pendulum motion!
traj = await record_trajectory(sim_id, "bob", steps=300)

Example - Multi-Link Chain:

# Create anchor
await add_rigid_body(sim_id, "anchor", body_type="static", ...)

# Create 3 chain links
for i in range(3):
    await add_rigid_body(
        sim_id,
        f"link{i}",
        body_type="dynamic",
        shape="box",
        size=[0.1, 0.4, 0.1],
        position=[0.0, 2.5 - i*0.5, 0.0]
    )

# Connect with spherical joints (ball-and-socket)
await add_joint(sim_id, JointDefinition(
    id="joint0",
    joint_type=JointType.SPHERICAL,
    body_a="anchor",
    body_b="link0",
    anchor_a=[0.0, 0.0, 0.0],
    anchor_b=[0.0, 0.2, 0.0]
))

await add_joint(sim_id, JointDefinition(
    id="joint1",
    joint_type=JointType.SPHERICAL,
    body_a="link0",
    body_b="link1",
    anchor_a=[0.0, -0.2, 0.0],
    anchor_b=[0.0, 0.2, 0.0]
))

# ... and so on

Use Cases:

Mechanical systems (engines, gears, levers)
Character animation (ragdolls, inverse kinematics)
Vehicle suspension (wheels, shocks)
Architectural simulations (doors, drawbridges)

See: examples/08_pendulum.py for full demo

Phase 1.4: Damping & Advanced Controls 🌬️

Realistic energy dissipation through linear and angular damping.

What it does:

Simulates air resistance (linear damping)
Simulates rotational friction (angular damping)
Makes simulations more realistic and stable
Perfect for settling physics and reducing "floaty" motion

Parameters: Added to add_rigid_body tool

Damping Parameters:

await add_rigid_body(
    sim_id=sim_id,
    body_id="damped_ball",
    body_type="dynamic",
    shape="sphere",
    size=[0.5],
    mass=1.0,
    position=[0.0, 5.0, 0.0],

    # Phase 1.4: Damping
    linear_damping=0.5,   # 0.0 (none) to 1.0 (high) - like air resistance
    angular_damping=0.3   # 0.0 (none) to 1.0 (high) - like rotational friction
)

Effect of Linear Damping:

0.0 = No air resistance (vacuum physics)
0.1-0.3 = Light damping (tennis ball in air)
0.5-0.7 = Moderate damping (underwater motion)
0.9+ = Heavy damping (very viscous fluid)

Effect of Angular Damping:

0.0 = Spins forever (vacuum)
0.1-0.3 = Realistic friction (rolling ball)
0.5-0.7 = High friction (rough surface)
0.9+ = Almost no rotation (sticky surface)

Comparison:

# Without damping - bounces forever
await add_rigid_body(..., linear_damping=0.0)
# Result: Ball bounces 20+ times, takes 30+ seconds to settle

# With damping - realistic settling
await add_rigid_body(..., linear_damping=0.5)
# Result: Ball bounces 5 times, settles in ~5 seconds

Use Cases:

Realistic object motion (not "floaty" game physics)
Faster settling (less simulation time needed)
Underwater simulations (high damping)
Space simulations (zero damping)

See: examples/09_phase1_complete.py for all Phase 1 features combined

Phase 1.5: Fluid Dynamics 🌊

Analytical fluid calculations for drag, buoyancy, and underwater motion.

What it does:

Calculates drag forces (quadratic air/water resistance)
Computes buoyancy using Archimedes' principle
Determines terminal velocity for falling objects
Simulates underwater projectile motion with drag and buoyancy

Tools Available:

1. `calculate_drag_force` - Air/Water Resistance

Calculate the force opposing motion through a fluid.

# Ball falling through water
result = await calculate_drag_force(
    velocity=[0, -5.0, 0],          # 5 m/s downward
    cross_sectional_area=0.00785,   # π*r² for 10cm diameter
    fluid_density=1000,              # water (air=1.225)
    drag_coefficient=0.47,           # sphere (streamlined=0.04)
    viscosity=1.002e-3               # optional: water viscosity for accurate Re
)

print(f"Drag force: {result['magnitude']:.1f} N (upward)")
print(f"Reynolds number: {result['reynolds_number']:.0f}")

Common drag coefficients:

Sphere: 0.47
Streamlined (torpedo): 0.04
Flat plate: 1.28
Human (standing): 1.0-1.3
Car: 0.25-0.35

Optional viscosity parameter (for accurate Reynolds number):

Water at 20°C: 1.002e-3 Pa·s
Air at 20°C: 1.825e-5 Pa·s
Motor oil: 0.1 Pa·s
If omitted, estimated from density (water-like if >100 kg/m³, else air-like)

2. `calculate_buoyancy` - Will it Float?

Determine buoyant force and whether objects float or sink.

# Check if 1kg steel ball floats
volume = (4/3) * π * (0.05)**3  # 10cm diameter sphere
result = await calculate_buoyancy(
    volume=0.000524,          # m³
    fluid_density=1000        # water
)

weight = 1.0 * 9.81  # 9.81 N
buoyancy = result['buoyant_force']  # 5.14 N

# weight > buoyancy → SINKS

3. `calculate_terminal_velocity` - Maximum Fall Speed

Calculate the speed where drag equals weight.

# Skydiver terminal velocity
result = await calculate_terminal_velocity(
    mass=70,                      # kg
    cross_sectional_area=0.7,     # m² (belly-down)
    fluid_density=1.225,          # air
    drag_coefficient=1.0          # human
)

print(f"Terminal velocity: {result['terminal_velocity']:.1f} m/s")
# Result: ~40 m/s (90 mph)
print(f"Time to 95%: {result['time_to_95_percent']:.1f}s")

4. `simulate_underwater_motion` - Full Fluid Simulation

Simulate motion through fluids with drag and buoyancy forces.

# Torpedo launched underwater
result = await simulate_underwater_motion(
    initial_velocity=[20, 0, 0],   # 20 m/s forward
    mass=100,                       # kg
    volume=0.05,                    # m³
    cross_sectional_area=0.03,      # m²
    fluid_density=1000,             # water
    drag_coefficient=0.04,          # streamlined
    duration=30.0
)

print(f"Distance traveled: {result['total_distance']:.1f}m")
print(f"Final velocity: {result['final_velocity']}")
print(f"Max depth: {result['max_depth']:.1f}m")

Use Cases:

Marine engineering: Torpedo trajectories, submarine drag
Aerospace: Skydiving, parachute descent, atmospheric re-entry
Sports: Swimming, diving, underwater ballistics
Product design: Drag optimization, floatation devices
Environmental: Particle settling, pollutant dispersion

Physics Models:

Quadratic drag: F_drag = 0.5 * ρ * v² * C_d * A
Buoyancy: F_b = ρ_fluid * V * g (Archimedes)
Terminal velocity: v_t = √(2mg / ρC_dA)
Numerical integration for complex underwater motion

See: examples/10_fluid_dynamics.py for comprehensive demonstrations

🎉 Phase 1 Complete Summary

Status: ✅ All features production-ready

Feature	Status	Tool	Coverage
Bounce Detection	✅ Shipped	`record_trajectory_with_events`	100%
Contact Events	✅ Shipped	All trajectory tools	100%
Joints & Constraints	✅ Shipped	`add_joint`	100%
Damping Controls	✅ Shipped	`add_rigid_body`	100%
Fluid Dynamics	✅ Shipped	`calculate_drag_force`, `calculate_buoyancy`, `calculate_terminal_velocity`, `simulate_underwater_motion`	100%

Test Coverage: 98% (350 tests passing)

Deployment:

🌐 MCP Server: https://physics.chukai.io/mcp
🦀 Rapier Service: https://rapier.chukai.io

Examples: See examples/06_bounce_detection.py through examples/10_fluid_dynamics.py

🚀 Phase 2 Features (Production Ready)

All Phase 2 features are complete, tested (98% coverage), and deployed to production!

Phase 2.1: Rotational Dynamics 🔄

Complete rotational motion calculations including torque, moment of inertia, angular momentum, and rotational kinetic energy.

Tools Available:

Tool	Description	Example Use
`calculate_torque`	Calculate torque from force and position (τ = r × F)	"What torque does this wrench apply?"
`calculate_moment_of_inertia`	Moment of inertia for common shapes (disk, sphere, rod, etc.)	"What's the rotational inertia?"
`calculate_angular_momentum`	Angular momentum (L = Iω)	"How much rotational momentum?"
`calculate_rotational_kinetic_energy`	Rotational KE (½Iω²)	"Energy in spinning flywheel?"
`calculate_angular_acceleration`	Angular acceleration (α = τ/I)	"How fast does it spin up?"

Example - Calculate Torque:

result = await calculate_torque(
    force_x=50.0,
    force_y=0.0,
    force_z=0.0,
    position_x=0.0,
    position_y=0.0,
    position_z=0.8  # 80cm wrench
)
# torque magnitude = 40 N⋅m

Use Cases:

Mechanical engineering (gear systems, engines)
Robotics (joint torques, motor sizing)
Sports science (bat swings, golf clubs)
Aerospace (satellite attitude control)

Phase 2.2: Oscillations & Waves 🌊

Harmonic motion and spring systems with damping effects.

Tools Available:

Tool	Description	Example Use
`calculate_hookes_law`	Spring force and potential energy (F = -kx)	"How much force in compressed spring?"
`calculate_spring_mass_period`	Period and frequency of spring-mass system	"How fast does it oscillate?"
`calculate_simple_harmonic_motion`	Position, velocity, acceleration at time t	"Where is the mass at t=2s?"
`calculate_damped_oscillation`	Damped harmonic motion (underdamped, critically damped, overdamped)	"How quickly does it settle?"
`calculate_pendulum_period`	Period of simple pendulum	"How long is one swing?"

Example - Spring-Mass System:

result = await calculate_spring_mass_period(
    mass=0.5,           # 500g mass
    spring_constant=20.0  # N/m
)
# period ≈ 0.99s, frequency ≈ 1.01 Hz

Use Cases:

Mechanical design (suspension systems, vibration isolation)
Seismology (earthquake oscillations)
Electronics (LC circuits, resonance)
Horology (pendulum clocks)

Phase 2.3: Circular Motion & Orbits 🌍

Circular motion, orbital mechanics, and centripetal forces.

Tools Available:

Tool	Description	Example Use
`calculate_centripetal_force`	Force required for circular motion	"What force keeps car on curve?"
`calculate_orbital_period`	Period and velocity for circular orbit	"How long is satellite orbit?"
`calculate_banking_angle`	Optimal banking for curved road	"What angle for this turn?"
`calculate_escape_velocity`	Minimum velocity to escape gravity	"Can rocket escape Earth?"
`analyze_circular_orbit`	Complete orbital analysis (altitude, period, velocity)	"Analyze ISS orbit"

Example - Satellite Orbit:

result = await analyze_circular_orbit(
    altitude=400000.0,       # 400 km above surface
    planet_mass=5.972e24,    # Earth mass
    planet_radius=6.371e6    # Earth radius
)
# orbital_velocity ≈ 7670 m/s
# period ≈ 5530 seconds (92 minutes)

Use Cases:

Space missions (orbital calculations, satellite deployment)
Astrophysics (planetary motion, binary stars)
Transportation (highway curve design)
Amusement parks (loop-the-loop, centrifuges)

Phase 2.4: Advanced Collisions 💥

3D collision calculations with elastic and inelastic collisions.

Tools Available:

Tool	Description	Example Use
`calculate_elastic_collision_3d`	3D elastic collision (energy conserved)	"Pool ball collisions in 3D"
`calculate_inelastic_collision_3d`	3D inelastic collision with restitution	"Car crash with energy loss"

Example - Car Crash:

result = await calculate_inelastic_collision_3d(
    mass1=1500.0,
    velocity1=[20.0, 0.0, 0.0],
    mass2=1200.0,
    velocity2=[-15.0, 0.0, 0.0],
    coefficient_of_restitution=0.0  # Perfectly inelastic
)
# final_velocity1 = [1.11, 0, 0]
# final_velocity2 = [1.11, 0, 0]  # Stick together
# energy_loss > 0 (deformation energy)

Phase 2.5: Conservation Laws ⚖️

Verify and track conservation of energy, momentum, and angular momentum.

Tools Available:

Tool	Description	Example Use
`check_energy_conservation`	Verify total energy is conserved	"Is this collision realistic?"
`check_momentum_conservation`	Verify momentum is conserved	"Does this violate physics?"
`check_angular_momentum_conservation`	Verify angular momentum conserved	"Is rotation energy conserved?"
`track_energy_dissipation`	Track energy loss over trajectory	"Where did the energy go?"

Example - Validate Collision:

result = await check_energy_conservation(
    initial_kinetic_energy=100.0,
    final_kinetic_energy=50.0,
    initial_potential_energy=0.0,
    final_potential_energy=50.0
)
# is_conserved = True (100 = 50 + 50)
# energy_difference ≈ 0

Phase 2.6: Statics & Equilibrium ⚖️

Static equilibrium analysis for structures and forces.

Tools Available:

Tool	Description	Example Use
`check_force_balance`	Verify ΣF = 0 (force equilibrium)	"Are these forces balanced?"
`check_torque_balance`	Verify Στ = 0 (torque equilibrium)	"Will this seesaw balance?"
`calculate_center_of_mass`	Find center of mass for system	"Where is the balance point?"
`calculate_static_friction`	Maximum friction force, will object slip?	"Will box slide down ramp?"
`calculate_normal_force`	Normal force on inclined plane	"What force on ramp?"
`check_equilibrium`	Complete equilibrium check (force + torque)	"Is structure stable?"
`calculate_beam_reactions`	Reaction forces for simply supported beam	"What are support forces?"

Example - Beam Analysis:

result = await calculate_beam_reactions(
    beam_length=10.0,
    loads=[1000, 500],  # Two point loads
    load_positions=[3.0, 7.0]  # Positions along beam
)
# reaction_left = 800 N
# reaction_right = 700 N
# is_balanced = True

Use Cases:

Structural engineering (bridges, buildings)
Mechanical design (levers, balances)
Architecture (load analysis)
Safety analysis (stability checks)

Phase 2.7: Kinematics Analysis 📊

Analyze motion data to extract velocities, accelerations, and trajectories.

Tools Available:

Tool	Description	Example Use
`calculate_acceleration_from_position`	Derive velocity and acceleration from position data	"Analyze motion capture data"
`calculate_jerk`	Calculate jerk (rate of change of acceleration)	"How jerky is this motion?"
`fit_trajectory`	Fit polynomial to trajectory (linear, quadratic, cubic)	"Find trajectory equation"
`generate_motion_graph`	Generate position/velocity/acceleration graphs	"Visualize kinematics"
`calculate_average_speed`	Average speed along path	"What's average speed?"
`calculate_instantaneous_velocity`	Velocity at specific time with interpolation	"Speed at exact moment?"

Example - Motion Analysis:

result = await calculate_acceleration_from_position(
    times=[0, 1, 2, 3, 4],
    positions=[[0,0,0], [5,0,0], [10,0,0], [15,0,0], [20,0,0]]
)
# velocities = [[5,0,0], [5,0,0], ...]  # Constant 5 m/s
# average_acceleration ≈ [0,0,0]  # No acceleration

Use Cases:

Motion capture analysis (sports, biomechanics)
Robotics (trajectory planning, motion smoothness)
Autonomous vehicles (trajectory optimization)
Scientific research (particle tracking)

Phase 2.8: Advanced Fluid Dynamics 💨

Extended fluid calculations including lift, Magnus force, Bernoulli, and viscous flow.

Tools Available:

Tool	Description	Example Use
`calculate_lift_force`	Aerodynamic lift (L = ½ρv²C_LA)	"What lift on wing?"
`calculate_magnus_force`	Force on spinning ball	"Why does curveball curve?"
`calculate_bernoulli`	Bernoulli's equation for flowing fluids	"Pressure in pipe constriction?"
`calculate_pressure_at_depth`	Hydrostatic pressure	"Pressure at 30m depth?"
`calculate_reynolds_number`	Flow regime (laminar/turbulent)	"Is flow turbulent?"
`calculate_venturi_effect`	Flow through constriction	"Velocity in throat?"

Example - Aircraft Wing:

result = await calculate_lift_force(
    velocity=70,          # m/s (~250 km/h)
    wing_area=20.0,       # m²
    lift_coefficient=1.2,
    fluid_density=1.225   # air
)
# lift_force ≈ 73,500 N

Use Cases:

Aerospace engineering (aircraft design, aerodynamics)
Marine engineering (hull design, submarine motion)
Sports science (ball trajectories, swimming efficiency)
HVAC design (airflow optimization)

🎉 Phase 2 Complete Summary

Status: ✅ All features production-ready

Feature Area	Tools	Coverage
Rotational Dynamics	5 tools	100%
Oscillations	5 tools	100%
Circular Motion	5 tools	100%
Advanced Collisions	2 tools	100%
Conservation Laws	4 tools	100%
Statics	7 tools	100%
Kinematics Analysis	6 tools	100%
Advanced Fluids	6 tools	100%

Total Tools: 79 tools across all categories Test Coverage: 98% overall (350 tests passing)

Next Up: Phase 3 - Performance Optimization & Visualization

Batch simulation API for ML training data
Parameter sweep utilities
Enhanced visualization exports
Performance profiling and optimization

🎓 Example Conversations

Projectile Motion

User: A golf ball is hit at 70 m/s at 15 degrees. How far does it go and what's the flight time?

LLM: [calls calculate_projectile_motion(70, 15)]

     Range ≈ 249.7 m
     Time of flight ≈ 3.694 s
     Maximum height ≈ 16.73 m

     Here are 50 trajectory points for visualization...

User: What angle gives maximum range for a cannonball fired at 100 m/s?

LLM: [calls calculate_projectile_motion multiple times with different angles]

     The optimal angle is 45°, which gives:
     - Maximum range: 1019.4 m
     - Flight time: 14.4 s
     - Peak height: 254.8 m

Collision Detection

User: Two asteroids: one at (0,0,0) moving at 1000 m/s in x direction,
      another at (50000, 100, 0) moving at -800 m/s in x. Will they collide?

LLM: [calls check_collision with both objects]

     Yes, they will collide!
     - Collision time: ~27.8 seconds
     - Impact location: (27,778, 100, 0)
     - Impact speed: 1,800 m/s
     - This would be a devastating impact given the closing speed.

User: Two cars 500m apart, one at 60 mph, other at 45 mph heading toward each other.
      When do they collide?

LLM: [calls check_collision]

     Collision in 10.7 seconds at position 250m from car 1's starting point.
     Combined approach speed is 105 mph (46.9 m/s).

Force & Energy Calculations

User: What force is needed to accelerate a 1500 kg car at 3 m/s²?

LLM: [calls calculate_force(1500, 3)]

     Force required: 4,500 N (Newtons)
     This is about 1,011 pounds of force.

User: What's the kinetic energy of a 2000 kg car at 30 m/s (about 67 mph)?

LLM: [calls calculate_kinetic_energy(2000, 30)]

     Kinetic energy: 900,000 J (Joules)
     That's 900 kJ or 0.25 kWh of energy.
     For perspective, this is why car crashes at highway speeds are so dangerous.

Momentum Analysis

User: Calculate momentum of a 70 kg runner at 10 m/s

LLM: [calls calculate_momentum(70, 10)]

     Momentum: 700 kg⋅m/s
     Direction: same as velocity vector

Complex Multi-Step Problems

User: I'm designing a water fountain. Water shoots up at 15 m/s.
      How high does it go and when does it come back down?

LLM: [calls calculate_projectile_motion(15, 90)]

     The water will:
     - Rise to maximum height: 11.47 m
     - Take 1.53 seconds to reach peak
     - Return to ground level after 3.06 seconds total
     - Have the same 15 m/s speed when it lands (just downward)

User: A basketball player shoots from 2m high at 7 m/s toward a hoop
      3.05m high and 4.6m away. What angles work?

LLM: [calls calculate_projectile_motion with various angles]

     Two possible angles work:
     1. Low arc: 38° (faster, flatter shot)
     2. High arc: 52° (slower, higher shot)

     Most players use 50-55° for better chance of going in.

Rigid Body Simulations

User: Create a simulation of a ball dropping from 10 meters and bouncing

LLM: [calls create_simulation(gravity_y=-9.81)]
     [calls add_rigid_body for ground plane (static)]
     [calls add_rigid_body for ball (dynamic, sphere, position=(0,10,0))]
     [calls record_trajectory(steps=200)]

     Simulation complete! The ball:
     - Hits ground at t=1.43s with velocity 14.0 m/s
     - Bounces to 7.5m (with restitution=0.8)
     - Makes 5 bounces before settling

     Here's the full trajectory data for R3F visualization...

User: Simulate 5 boxes stacked, then another box hits them from the side

LLM: [calls create_simulation]
     [calls add_rigid_body for ground]
     [calls add_rigid_body 5 times for stacked boxes]
     [calls add_rigid_body for projectile box with velocity]
     [calls step_simulation(300)]
     [calls record_trajectory for each box]

     The collision causes a realistic toppling effect!
     Boxes 1-2 fall left, boxes 3-5 scatter right.
     Peak chaos at t=0.8s. All settled by t=3.2s.

     Full trajectory data ready for 3D visualization...

💡 Try These Prompts

Copy and paste these into your LLM chat to see the physics tools in action:

Projectile Motion

A golf ball is hit at 70 m/s at 15 degrees. How far does it go and what's the flight time?
What angle gives maximum range for a cannonball fired at 100 m/s?
If I throw a javelin at 28 m/s from 2 meters high, what angle gives maximum distance?
A basketball player shoots from 2m high at 7 m/s toward a hoop 3.05m high and 4.6m away. What angles work?

Collision Detection

Two cars 500m apart, one at 60 mph, other at 45 mph heading toward each other. When do they collide?
Two asteroids: one at (0,0,0) moving at 1000 m/s in x direction, another at (50000, 100, 0) moving at -800 m/s in x. Will they collide?
Spaceship A at (10000,0,0) moving at (-50,0,0) m/s, spaceship B at (-10000,100,0) moving at (45,0,0) m/s. Collision check?

Force, Energy & Momentum

What force is needed to accelerate a 1500 kg car at 3 m/s²?
What's the kinetic energy of a 2000 kg car traveling at 30 m/s?
Calculate the momentum of a 70 kg runner sprinting at 10 m/s
How much energy does a 0.145 kg baseball have when pitched at 45 m/s?

Real-World Applications

I'm designing a water fountain. Water shoots up at 15 m/s. How high does it go?
A cannon on a 50 meter cliff fires horizontally at 200 m/s. How far from the base does the projectile land?
Two cars crash: Car A (1500kg) at 30 m/s, Car B (1200kg) at 25 m/s. What's the total kinetic energy at impact?

Simulations (Requires Rapier Service)

Create a simulation of a ball dropping from 10 meters height and bouncing on the ground
Simulate 5 boxes stacked on top of each other, then have another box hit them from the side
Create a Newton's cradle with 5 spheres and record their motion
Simulate a sphere rolling down a 30-degree ramp

📝 Example Scripts

The examples/ directory contains working demonstration scripts:

Ready to Run (No External Services Required)

These examples use the built-in analytic provider and work immediately:

00_quick_start.py - Quick demo of all 5 analytic tools
01_simple_projectile.py - Cannonball trajectories, basketball shots, angle comparisons
02_collision_detection.py - Car crashes, near misses, asteroid collisions
03_force_energy_momentum.py - F=ma, kinetic energy, momentum conservation
04_r3f_visualization.py - Generate React Three Fiber visualization data

# Run any example
python examples/00_quick_start.py
python examples/01_simple_projectile.py
# ... etc

Requires Rapier Service

These examples demonstrate rigid-body simulations and Phase 1 features. They need the Rapier service running:

05_rapier_simulation.py - Bouncing balls, collisions, stacking boxes
06_bounce_detection.py - Phase 1.1: Automatic bounce detection and energy analysis
07_contact_events.py - Phase 1.2: Real-time contact tracking and collision events
08_pendulum.py - Phase 1.3: Joints and constraints (pendulums, chains)
09_phase1_complete.py - Phase 1.4: All Phase 1 features (damping, bounces, contacts, joints)
10_fluid_dynamics.py - Phase 1.5: Fluid calculations (drag, buoyancy, terminal velocity)
11_rotational_dynamics.py - Phase 2.1: Torque, angular momentum, gyroscopes
12_oscillations.py - Phase 2.2: Springs, pendulums, harmonic motion, damping
13_circular_motion.py - Phase 2.3: Orbital mechanics, centripetal force
14_statics.py - Phase 2.6: Static equilibrium, force balance, beam analysis
15_kinematics_analysis.py - Phase 2.7: Motion analysis, trajectory fitting
16_roulette_simulation.py - 🎰 Casino Roulette - Complete showcase of multi-body physics, collisions, and energy dissipation

# Option 1: Use public Rapier service (easiest)
export RAPIER_SERVICE_URL=https://rapier.chukai.io
python examples/05_rapier_simulation.py
python examples/06_bounce_detection.py
# ... etc

# Option 2: Run local Rapier service with Docker
docker run -p 9000:9000 chuk-rapier-service
export RAPIER_SERVICE_URL=http://localhost:9000
python examples/05_rapier_simulation.py

Note:

Examples 00-04 work instantly (no external services)
Examples 05-09 showcase advanced rigid-body physics with Rapier
Use the public Rapier service at https://rapier.chukai.io or run your own

⚙️ Configuration

Environment Variables

# Provider selection
PHYSICS_PROVIDER=analytic          # or "rapier"

# Rapier service (only if using Rapier provider)
# The default is automatically determined:
# - On Fly.io: uses https://rapier.chukai.io (public service)
# - Locally: uses http://localhost:9000
#
# Override with:
RAPIER_SERVICE_URL=https://rapier.chukai.io  # or http://localhost:9000

# Optional configuration
RAPIER_TIMEOUT=30.0
RAPIER_MAX_RETRIES=3
RAPIER_RETRY_DELAY=1.0

YAML Configuration

Create physics.yaml in your working directory or ~/.config/chuk-mcp-physics/:

default_provider: rapier

providers:
  # Override provider per tool type
  simulations: rapier
  projectile_motion: analytic

rapier:
  # Public service (recommended)
  service_url: https://rapier.chukai.io

  # Or local development
  # service_url: http://localhost:9000

  timeout: 30.0
  max_retries: 3
  retry_delay: 1.0

🛡️ Safety & Limits

Recommended Ranges

Understanding these limits helps prevent timeouts, instabilities, and confusion:

Parameter	Recommended	Maximum	Notes
Units	meters, kg, seconds	-	SI units throughout
dt	0.008 - 0.033	0.001 - 0.1	<0.008 = overkill, >0.033 = unstable
steps	100 - 5000	10,000	Depends on dt and complexity
bodies	1 - 100	1,000	Performance degrades >100
gravity	-20 to 0 m/s²	-100 to +100	Earth = -9.81
velocity	0 - 100 m/s	1,000 m/s	Very high speeds may cause tunneling
mass	0.1 - 10,000 kg	1e-6 - 1e6	Extreme ratios cause instability

Public Service Limits

The public Rapier service at https://rapier.chukai.io has these limits:

Max steps per call: 5,000
Max bodies per simulation: 100
Max concurrent simulations: 10 per IP
Request timeout: 30 seconds
Max simulation lifetime: 1 hour (auto-cleanup)

For larger simulations, run your own Rapier service (see RAPIER_SERVICE.md).

Common Pitfalls

❌ Simulation explodes or bodies fly away

Symptoms:

Bodies gain extreme velocities
Objects disappear from view
NaN values in positions

Causes:

dt too large for the forces involved
Very high mass ratios (1g object hitting 1000kg object)
Extreme initial velocities

Solutions:

Reduce dt to 0.008 or lower
Use more similar masses (within 2-3 orders of magnitude)
Limit initial velocities to <100 m/s

❌ Simulation runs very slowly

Symptoms:

Request takes >10 seconds
Timeout errors
High CPU usage

Causes:

Too many bodies (>100)
Very small dt (<0.005)
Complex mesh colliders
Too many steps (>5000)

Solutions:

Reduce body count or simplify shapes
Increase dt (balance accuracy vs. speed)
Break large step counts into multiple calls
Use primitive shapes (sphere, box) instead of meshes

❌ Objects tunnel through each other

Symptoms:

Fast-moving objects pass through walls
Collisions not detected
Objects appear inside each other

Causes:

Very high velocities + large dt
Thin colliders (<0.1m)
Disabled continuous collision detection (CCD)

Solutions:

Reduce dt for high-speed scenarios
Thicken colliders (minimum 0.1m recommended)
Reduce velocities
Enable CCD if available (future feature)

Best Practices

Start simple: Test with 2-3 bodies before scaling up
Validate inputs: Check for NaN, Inf, extreme values before simulation
Monitor performance: Track step time, adjust dt/steps accordingly
Cleanup: Always destroy_simulation when done (prevent memory leaks)
Use analytic when possible: For simple scenarios, analytic is faster and exact

🔧 Development

# Navigate to project directory
cd chuk-mcp-physics

# Install in development mode
make dev-install

# Run tests
make test

# Run tests with coverage
make test-cov

# Format code
make format

# Run all checks
make check

# Build package
make build

🐳 Docker Deployment

# Build image
make docker-build

# Run container
make docker-run

# Access at http://localhost:8000

☁️ Production Deployment

Live Public Services

Current Production Services:

MCP Physics Server: https://physics.chukai.io/mcp
- Public hosted MCP server endpoint
- No local installation required
- Pre-configured with Rapier service
- Ready to use in Claude Desktop
Rapier Physics Engine: https://rapier.chukai.io
- Public API for physics simulations
- No authentication required for basic usage
- Rate limits may apply

Quick Test:

# Test the public Rapier service
curl https://rapier.chukai.io/health

# Use with chuk-mcp-physics locally
export RAPIER_SERVICE_URL=https://rapier.chukai.io
uvx chuk-mcp-physics

Deploy Your Own Rapier Service

If you need your own private Rapier service instance:

1. Deploy Rapier Service to Fly.io with Redis

cd rapier-service

# Login to Fly.io
fly auth login

# Create Redis instance for distributed storage
fly redis create
# Choose: your-rapier-redis, region sjc (or your preferred region), plan 256MB

# Set Redis URL secret (use URL from previous step)
fly secrets set REDIS_URL="redis://default:password@fly-your-rapier-redis.upstash.io"

# Create and deploy the service
fly apps create your-rapier-physics
fly deploy

# Verify Redis connection in logs
fly logs
# Look for: "📦 Initialized RedisStorage backend"

# Add custom domain (optional)
fly certs add rapier.yourdomain.com -a your-rapier-physics

# Verify service is running
curl https://your-rapier-physics.fly.dev/health

Redis Benefits:

✅ Horizontal scaling (multiple service instances share state)
✅ Automatic cleanup (TTL-based simulation expiration)
✅ Distributed coordination across instances
✅ Session persistence within TTL window

Configuration: The service uses Redis automatically on Fly.io (see rapier-service/fly.toml). For local development, it defaults to in-memory storage.

See rapier-service/FLY_REDIS_SETUP.md for detailed Redis setup guide, monitoring, and troubleshooting.

2. Configure chuk-mcp-physics to Use Your Service

# Option 1: Environment variable
export RAPIER_SERVICE_URL=https://rapier.yourdomain.com
uvx chuk-mcp-physics

# Option 2: YAML config (physics.yaml)
# rapier:
#   service_url: https://rapier.yourdomain.com

Why deploy your own?

🔒 Private instance for production workloads
📈 Custom scaling and resource allocation
🌍 Deploy closer to your users (different regions)
💾 Persistent simulations and custom configurations

See DEPLOYMENT.md for complete deployment guide, scaling strategies, and CI/CD setup.

🦀 Rapier Service Setup

For full rigid-body simulations, you have several options:

Option 1: Use Public Service (Easiest)

# No setup required - just configure the URL
export RAPIER_SERVICE_URL=https://rapier.chukai.io
uvx chuk-mcp-physics

Option 2: Run Locally with Docker

# Using Docker
docker run -p 9000:9000 chuk-rapier-service

# Configure to use local service
export RAPIER_SERVICE_URL=http://localhost:9000
uvx chuk-mcp-physics

Option 3: Build from Source

# Build and run the Rust service
cd rapier-service
cargo run --release

# In another terminal
export RAPIER_SERVICE_URL=http://localhost:9000
uvx chuk-mcp-physics

See RAPIER_SERVICE.md for:

Complete API specification
Rust implementation guide
Docker deployment details
Testing examples

📊 Comparison: Analytic vs Rapier

Feature	Analytic Provider	Rapier Provider
Projectile motion	✅ Exact (kinematic eqs)	✅ Simulated
Simple collisions	✅ Exact (sphere-sphere, elastic)	✅ Simulated
Force/energy/momentum	✅ F=ma, KE, PE, momentum, work/power	✅ Can derive from sim
Fluid dynamics	✅ Drag, buoyancy, terminal velocity	❌ Not supported
Rigid-body dynamics	❌ Not supported	✅ Full 3D/2D physics
Complex shapes	❌ Spheres only	✅ Box, capsule, mesh, etc
Friction/restitution	❌ Not modeled	✅ Full material properties
Multi-body systems	❌ Not supported	✅ Unlimited bodies
Constraints/joints	❌ Not supported	✅ Hinges, sliders, etc
Performance	⚡ Instant	🐇 Fast (Rust)
Setup	📦 Built-in	🦀 Requires Rapier service

Recommendation:

Use Analytic for simple calculations, education, quick answers
Use Rapier for complex simulations, games, visualizations, multi-body dynamics

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md.

📄 License

Apache License 2.0 - see LICENSE for details.

This is a demonstration project provided as-is for learning and testing purposes.

🙏 Acknowledgments

Rapier - Fast 2D/3D physics engine in Rust
Model Context Protocol - Protocol specification

📚 See Also

RAPIER_SERVICE.md - Rapier microservice specification
Examples - Example usage patterns
API Documentation - Detailed tool reference

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
.github/workflows		.github/workflows
examples		examples
rapier-service		rapier-service
src/chuk_mcp_physics		src/chuk_mcp_physics
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
EXAMPLE_PROMPTS.md		EXAMPLE_PROMPTS.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
RAPIER_SERVICE.md		RAPIER_SERVICE.md
README.md		README.md
physics.example.yaml		physics.example.yaml
pyproject.toml		pyproject.toml
renovate.json		renovate.json
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Physics MCP Server

📚 Table of Contents

🌟 What is This?

Why MCP?

📦 What's Included

55 Physics Tools Across 10 Categories

Realistic vs Ideal Physics Comparison

Two Calculation Modes

🚀 Quick Start (30 seconds)

🎯 Use Cases

1. Interactive Physics Education

2. Game Development & Prototyping

3. 3D Visualization & Animation (React Three Fiber)

4. Engineering & Design Analysis

5. Sports & Athletics

6. Astrophysics & Space Exploration

7. Fluid Dynamics & Marine/Aerospace Engineering

8. Film & VFX Pre-visualization

8. Military & Defense (Training/Education)

9. Robotics & Automation

10. Data Science & Research

🚀 Real-World Example Workflows

Workflow 1: Basketball Shot Optimizer

Workflow 2: Car Crash Investigation

Workflow 3: Game Level Design with Physics Simulation

Workflow 4: Satellite Collision Warning

🎨 Visualization Integration

React Three Fiber (R3F) Example

📊 Trajectory Data Format

Schema Definition

JSON Example

Usage in React Three Fiber

Usage in Remotion

Design Notes

🛠️ Installation

Prerequisites

Quick Start with uvx (Recommended)

Installation Methods

Option 1: Install from PyPI (Recommended)

Option 2: Install from Source

With Claude Desktop

Option 1: Using uvx (Recommended - No Installation Required)

Option 2: Using Installed Package

Option 3: Analytic Only (No External Service)

📖 Available Tools

Tool Organization

1️⃣ Analytic Primitives (No External Service)

2️⃣ Simulation Primitives (Requires Rapier Service)

📋 Complete Tool Reference

Basic Mechanics (8 tools)

Fluid Dynamics (10 tools)

Rotational Dynamics (5 tools)

Oscillations & Waves (5 tools)

Circular Motion & Orbits (5 tools)

Statics & Equilibrium (7 tools)

Kinematics Analysis (7 tools)

Advanced Collisions (2 tools)

Conservation Laws (4 tools)

Unit Conversions (2 tools)

Common Drag Coefficients (Cd) Reference

Advanced Projectile Features

🌀 Magnus Force (Spin Effects)

💨 Wind Effects

🏔️ Altitude & Temperature Effects

🌟 Combined Effects Example

🔄 Orientation-Dependent Drag (Rapier Simulations)

How It Works

Example: Football Spiral vs Tumble

Common drag_axis_ratios Patterns

Real-World Examples

Important Notes

✨ Phase 1 Features (Production Ready)

Phase 1.1: Bounce Detection 🏀

Phase 1.2: Contact Events 📊

Phase 1.3: Joints & Constraints 🔗

Phase 1.4: Damping & Advanced Controls 🌬️

Common `drag_axis_ratios` Patterns

1. `calculate_drag_force` - Air/Water Resistance

2. `calculate_buoyancy` - Will it Float?

3. `calculate_terminal_velocity` - Maximum Fall Speed

4. `simulate_underwater_motion` - Full Fluid Simulation