Chuk MCP Physics

物理MCP服务器

   

特征： 🌀 马格纳斯力量•💨 风效应•🏔️ 海拔高度•🌡️ 温度•🔄 翻滚拖动•🎮 刚体模拟游戏•📊 515测试

一种模型上下文协议（MCP）服务器，为大型语言模型带来了全面的物理模拟和计算能力。

将你的法学硕士转化为物理引擎！此MCP服务器提供55个专业工具，涵盖经典力学、流体动力学、旋转运动和刚体模拟。专为与Claude、ChatGPT和任何兼容MCP的AI系统无缝集成而构建。

📚 目录

• 这是什么？
• 包含什么
• 快速开始
• 用例
• 可用工具

- 常见阻力系数 - 先进的弹丸特征 🌀💨🏔️

• 例子
• 发展

🌟 这是什么？

物理MCP服务器 使LLM能够通过标准化协议执行复杂的物理计算和模拟。LLM现在可以：

• 精确计算：使用经过验证的物理公式获得精确结果
• 逼真地模拟：使用Rapier引擎运行刚体物理学
• 可视化运动：为React Three Fiber、Remion和其他3D框架生成轨迹数据
• 互动式教学：用真实的计算来回答物理问题，而不是记住事实
• 智能设计：分析工程应用中的力、碰撞和运动

为什么选择MCP？

这 模型上下文协议 提供了一种标准化的方法，将LLM功能扩展到文本生成之外。此服务器实现MCP，使语言模型可以直接访问：

• ⚡ 即时物理计算 （射弹运动、力、能量）
• 🎮 刚体模拟 （碰撞、反弹、堆叠）
• 📊 运动分析 （轨迹拟合、运动学、速度剖面）
• 🌊 流体力学 （阻力、浮力、升力、伯努利）
• 🔄 旋转力学 （扭矩、角动量、陀螺仪）
• ⚖️ 静态分析 （平衡、梁反作用力、摩擦）
• 🔄 单位换算 （62种单位类型：速度、距离、质量、时间、加速度、扭矩、频率、数据大小等）

📦 包含什么

10个类别的55个物理工具

现实物理与理想物理的比较

当包括真实世界的效果时，可以看到巨大的差异：

💡 关键洞察真正的物理很重要！根据运动的不同，空气阻力会使续航里程减少20-70%。

两种计算模式

1. 分析模式 （内置，无需设置）

- 即时数学计算 - 非常适合教育和快速回答 - 使用物理公式的精确解 - 现在包括：高级阻力、旋转（马格纳斯）、风、高度效果

1. 模拟模式 （需要Rapier服务）

- 全刚体动力学 - 复杂的多对象交互 - 真实的材质特性和约束

🚀 快速启动（30秒）

# 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

对于Claude Desktop： 添加到您的配置文件中：

选项1：公共托管MCP服务器（最简单-无需安装）

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

选项2：本地uvx（推荐）

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

______________________________________________________________________

🎯 用例

1. 互动物理教育

法学硕士物理导师

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]

现实世界问题解决

• 学生用自然语言问物理问题
• LLM使用MCP工具计算精确答案
• 可以生成轨迹图、力图、能量图
• 交互式“假设”场景：“如果重力是一半呢？”

______________________________________________________________________

2. 游戏开发与原型制作

弹道学设计

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."

碰撞检测

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"

快速迭代

• 无需编码即可测试不同的发射角度、速度和质量
• 实施前验证冲突逻辑
• 为程序内容生成逼真的物理数据

______________________________________________________________________

3. 3D可视化与动画（React Three Fiber）

自动动画数据生成

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..."

     
       
     

刚体模拟

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..."

使用案例：

• 产品可视化（掉落手机、弹跳球）
• 建筑倒塌模拟（建筑拆除预览）
• 运动分析可视化（球轨迹、碰撞分析）
• 科幻效应（小行星场、碎片云）

______________________________________________________________________

4. 工程与设计分析

车辆碰撞预测

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..."

安全性分析

• 计算碰撞试验场景的冲击力
• 预测自动驾驶汽车规划的碰撞时间
• 分析工业设备中的动量传递

结构测试（采用Rapier模拟）

• 模拟坠落物体撞击结构
• 动态载荷下的承载能力测试
• 模型连锁反应（多米诺效应）

______________________________________________________________________

5. 体育与竞技

具有空气阻力的真实球轨迹

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..."

高尔夫驾驶分析

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!"

篮球三分球

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..."

镜头分析应用程序

• 棒球：俯仰轨迹，阻力使90英里/小时的快球射程减少40%
• 高尔夫：带凹坑球的驱动距离（Cd=0.25 vs光滑球Cd=0.47）
• 篮球：罚球和三分球弧线优化
• 足球：点球轨迹，短距离阻力最小
• 田径标枪，具有逼真空气阻力的铅球
• 网球：发球和触地击球轨迹分析

______________________________________________________________________

6. 天体物理学与太空探索

轨道力学（简化）

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..."

应用：

• 小行星撞击预测
• 卫星防撞
• 碎片场分析
• 发射轨迹规划（简化案例）

______________________________________________________________________

7. 流体动力学与海洋/航空航天工程

水下鱼雷仿真

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..."

终端速度和阻力分析

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..."

浮力和浮/沉预测

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..."

应用：

• 海洋工程： 潜艇阻力、鱼雷轨迹、水下航行器
• 航空航天： 降落伞下降、大气层再入、阻力优化
• 体育科学： 游泳效率、跳水轨迹
• 产品设计： 漂浮装置、减阻、流体力学
• 环境的： 颗粒沉降率、污染物扩散

______________________________________________________________________

8. 电影和视觉特效预可视化

特技规划

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..."

销毁顺序

• 建筑倒塌与刚体模拟
• 爆炸碎片轨迹
• 车辆特技和碰撞
• 逼真的对象交互

______________________________________________________________________

8. 军事与国防（训练/教育）

弹道学训练

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"

避碰

• 弹丸弹道分析
• 弹着点预测
• 拦截航向计算

______________________________________________________________________

9. 机器人与自动化

路径规划

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..."

碰撞检测

• 多机器人协调
• 物体捕捉/投掷
• 装配线优化

______________________________________________________________________

10. 数据科学与研究

机器学习训练数据的物理模拟

# 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
    })

使用案例：

• 为ML模型生成标记的物理数据
• 验证基于物理的神经网络
• 用快速迭代检验科学假设
• 蒙特卡洛模拟（改变参数，汇总结果）

______________________________________________________________________

🚀 真实世界示例工作流

工作流程1：篮球投篮优化器

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..."

工作流程2：车祸调查

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..."

工作流程3：带有物理模拟的游戏关卡设计

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..."

工作流程4：卫星碰撞预警

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."

______________________________________________________________________

🎨 可视化集成

React三纤维（R3F）示例

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 (
    
      
      
    
  );
}

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 (
    
      
      
    
  );
}

______________________________________________________________________

📊 轨迹数据格式

所有轨迹记录都遵循规范模式，以实现与R3F、Remion、Three.js和其他动画系统的最大互操作性。

架构定义

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示例

{
  "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
  }
}

React三纤维的使用

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 (
    
      
      
    
  );
}

远程使用

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

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

  return (
    
      
        
          
        
      
    
  );
};

设计说明

• 用于旋转的四元数： 比欧拉角更紧凑，插值更友好
• 绝对时间： 每一帧都有绝对时间 t，使擦洗更容易
• 常数dt： 帧间隔均匀，简化了播放
• 可选速度： 如果需要运动模糊或物理可视化，请包括在内
• 合格body_id： 格式为 rapier://sim-{id}/{body_id} 可追溯性

______________________________________________________________________

🛠️ 安装

先决条件

• Python 3.11+
• 模拟：Rapier服务（见 RAPIER_SERVICE.md)

- 公共服务提供地点：https://rapier.chukai.io - 或者使用Docker在本地运行（见下文）

uvx快速入门（推荐）

无需安装即可尝试chuk-mcp物理的最快方法：

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

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

安装方法

选项1：从PyPI安装（推荐）

# 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

选项2：从源代码安装

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

# Install in development mode
make dev-install

# Run the server
chuk-mcp-physics

使用克劳德桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

选项1：使用uvx（推荐-无需安装）

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

选项2：使用已安装的软件包

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

选项3：仅分析（无外部服务）

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

______________________________________________________________________

📖 可用工具

工具组织

工具分为两层，以帮助您选择正确的抽象：

1.️⃣ 分析基元（无外部服务）

最适合： 快速计算、教育、简单场景

直接基于公式的计算，返回即时结果：

特点：

• ⚡ 即时执行（\100kg/m³，则为水，否则为空气）

2. calculate_buoyancy -它会漂浮吗？

确定浮力以及物体是浮还是沉。

# 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 -最大下降速度

计算阻力等于重量时的速度。

# 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 -全流体模拟

模拟流体在阻力和浮力作用下的运动。

# 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")

使用案例：

• 海洋工程： 鱼雷轨迹，潜艇阻力
• 航空航天： 跳伞、降落伞降落、重返大气层
• 体育： 游泳、潜水、水下弹道学
• 产品设计： 阻力优化、浮动装置
• 环境的： 颗粒沉降、污染物扩散

物理模型：

• 二次阻力：F_drag=0.5\*ρ\*v²\*C_d\*A
• 浮力：F_b=ρ_流体\*V\*g（阿基米德）
• 终端速度：v_t=√（2mg/ρC_dA）
• 复杂水下运动的数值积分

请参阅： examples/10_fluid_dynamics.py 进行全面演示

______________________________________________________________________

🎉 第一阶段完整总结

状态： ✅ 所有功能均已准备就绪

测试覆盖范围： 98%（350项测试通过）

部署：

• 🌐 MCP服务器：https://physics.chukai.io/mcp
• 🦀 Rapier服务：https://rapier.chukai.io

示例： 看 examples/06_bounce_detection.py 通过 examples/10_fluid_dynamics.py

______________________________________________________________________

🚀 第2阶段功能（生产就绪）

第2阶段的所有功能都是 完成、测试（98%覆盖率）并部署 生产！

阶段2.1：旋转动力学🔄

完成旋转运动计算 包括扭矩、转动惯量、角动量和旋转动能。

可用工具：

示例-计算扭矩：

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

使用案例：

• 机械工程（齿轮系统、发动机）
• 机器人技术（关节扭矩、电机尺寸）
• 体育科学（球棒、高尔夫球杆）
• 航空航天（卫星姿态控制）

______________________________________________________________________

第2.2阶段：振荡和波动🌊

谐波运动和弹簧系统 具有阻尼效果。

可用工具：

示例-弹簧质量系统：

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

使用案例：

• 机械设计（悬架系统、隔振）
• 地震学（地震振荡）
• 电子学（LC电路、谐振）
• 钟表学（摆钟）

______________________________________________________________________

阶段2.3：圆周运动和轨道🌍

圆周运动、轨道力学和向心力.

可用工具：

示例-卫星轨道：

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)

使用案例：

• 空间任务（轨道计算、卫星部署）
• 天体物理学（行星运动、双星）
• 交通（公路曲线设计）
• 游乐园（环路、离心机）

______________________________________________________________________

阶段2.4：高级碰撞💥

三维碰撞计算 具有弹性和非弹性碰撞。

可用工具：

示例-车祸：

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)

______________________________________________________________________

第2.5阶段：保护法⚖️

验证和跟踪保护 能量、动量和角动量。

可用工具：

示例-验证碰撞：

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

______________________________________________________________________

第2.6阶段：静力学与平衡⚖️

静态平衡分析 结构和力。

可用工具：

示例-梁分析：

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

使用案例：

• 结构工程（桥梁、建筑）
• 机械设计（杠杆、天平）
• 架构（负载分析）
• 安全分析（稳定性检查）

______________________________________________________________________

第2.7阶段：运动学分析📊

分析运动数据 提取速度、加速度和轨迹。

可用工具：

示例-运动分析：

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

使用案例：

• 运动捕捉分析（运动、生物力学）
• 机器人技术（轨迹规划、运动平滑度）
• 自动驾驶汽车（轨迹优化）
• 科学研究（粒子追踪）

______________________________________________________________________

第2.8阶段：先进流体动力学💨

扩展流体计算 包括升力、马格纳斯力、伯努利和粘性流。

可用工具：

示例-飞机机翼：

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

使用案例：

• 航空航天工程（飞机设计、空气动力学）
• 海洋工程（船体设计、潜艇运动）
• 运动科学（球轨迹、游泳效率）
• 暖通空调设计（气流优化）

______________________________________________________________________

🎉 第2阶段完整总结

状态： ✅ 所有功能均已准备就绪

工具总数： 79种工具，涵盖所有类别 测试覆盖范围： 总体98%（350项测试通过）

______________________________________________________________________

下一个： 第3阶段-性能优化和可视化

• ML训练数据的批量模拟API
• 参数扫描实用程序
• 增强的可视化导出
• 性能分析和优化

______________________________________________________________________

🎓 对话示例

抛体运动

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

碰撞检测

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).

力和能量计算

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.

动量分析

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

复杂的多步骤问题

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.

刚体模拟

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...

______________________________________________________________________

💡 试试这些提示

将这些复制并粘贴到您的LLM聊天中，以查看实际使用的物理工具：

抛体运动

• 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?

碰撞检测

• 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?

力、能量和动量

• 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?

实际应用

• 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?

模拟（需要Rapier服务）

• 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

______________________________________________________________________

📝 示例脚本

这 examples/ 目录包含工作演示脚本：

准备运行（无需外部服务）

这些示例使用内置 分析提供者 并立即工作：

• 00_quick_start.py -快速演示所有5种分析工具
• 01_simple_projectile.py -炮弹轨迹、篮球投篮、角度比较
• 02_collision_detection.py -车祸、未遂事故、小行星碰撞
• 03_force_energy_momentum.py -F=ma，动能，动量守恒
• 04_r3f_visualization.py -生成React Three Fiber可视化数据

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

需要Rapier服务

这些示例演示了刚体模拟和第一阶段特征。他们需要Rapier服务运行：

• 05_rapier_simulation.py -弹跳球、碰撞、堆叠箱子
• 06_bounce_detection.py -阶段1.1：自动反弹检测和能量分析
• 07_contact_events.py -阶段1.2：实时联系人跟踪和碰撞事件
• 08_pendulum.py -阶段1.3：关节和约束（摆锤、链条）
• 09_phase1_complete.py -阶段1.4：所有阶段1功能（阻尼、反弹、接触、接头）
• 10_fluid_dynamics.py -第1.5阶段：流体计算（阻力、浮力、终端速度）
• 11_rotational_dynamics.py -阶段2.1：扭矩、角动量、陀螺仪
• 12_oscillations.py -阶段2.2：弹簧、摆锤、谐波运动、阻尼
• 13_circular_motion.py -阶段2.3：轨道力学，向心力
• 14_statics.py -第2.6阶段：静态平衡、力平衡、梁分析
• 15_kinematics_analysis.py -阶段2.7：运动分析、轨迹拟合
• 16_roulette_simulation.py - 🎰 赌场轮盘赌 -多体物理、碰撞和能量耗散的完整展示

# 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

注：

• 示例00-04立即工作（无需外部服务）
• 示例05-09展示了Rapier的先进刚体物理学
• 使用公共Rapier服务 https://rapier.chukai.io 或者自己经营

______________________________________________________________________

⚙️ 配置

环境变量

# 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配置

创建 physics.yaml 在您的工作目录中或 ~/.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

______________________________________________________________________

🛡️ 安全与限制

推荐范围

了解这些限制有助于防止超时、不稳定和混淆：

公共服务限制

Rapier公共服务 https://rapier.chukai.io 有这些限制：

• 每次呼叫的最大步数： 5,000
• 每次模拟的最大车身数： 100
• 最大并发模拟数： 每IP 10个
• 请求超时： 30秒
• 最大模拟寿命： 1小时（自动清理）

对于更大的模拟，请运行自己的Rapier服务（请参阅 RAPIER_SERVICE.md).

常见陷阱

❌ 模拟爆炸或尸体飞走

症状：

• 物体获得极高的速度
• 对象从视图中消失
• 位置中的NaN值

原因：

• dt 对所涉及的部队来说太大了
• 极高的质量比（1克物体撞击1000公斤物体）
• 极端初始速度

解决：

• 减少 dt 至0.008或更低
• 使用更相似的质量（在2-3个数量级内）
• 将初始速度限制在\10秒
• 超时错误
• CPU使用率高

原因：

• 尸体太多（>100）
• 非常小 dt (\5000）

解决：

• 减少人数或简化形状
• 增加 dt （平衡精度与速度）
• 将大步数分解为多个呼叫
• 使用基本体形状（球体、长方体）而不是网格

❌ 物体互相穿隧道

症状：

• 快速移动的物体穿过墙壁
• 未检测到碰撞
• 物体出现在彼此内部

原因：

• 非常高的速度+大 dt
• 薄型对撞机（\ 这是一个为学习和测试目的而提供的演示项目。

______________________________________________________________________

🙏 致谢

• 轻剑 -Rust中的快速2D/3D物理引擎
• 模型上下文协议 -协议规范

______________________________________________________________________

📚 另见

• RAPIER_SERVICE.md -Rapier微服务规范
• 例子 -示例使用模式
• API文档 -详细工具参考