Joints allow you to constrain the motion between bodies:
- FIXED: Rigid connection (glue objects together)
- REVOLUTE: Hinge rotation around an axis (doors, pendulums)
- SPHERICAL: Ball-and-socket rotation (ragdolls, gimbals)
- PRISMATIC: Sliding along an axis (pistons, elevators)

Args:
    sim_id: Simulation identifier
    joint: Joint definition with type and parameters

Returns:
    joint_id: Unique identifier for the created joint

Example - Simple Pendulum:
    # Create fixed anchor point
    add_rigid_body(
        sim_id=sim_id,
        body_id="anchor",
        body_type="static",
        shape="sphere",
        size=[0.05],
        position=[0.0, 5.0, 0.0],
    )

    # Create pendulum bob
    add_rigid_body(
        sim_id=sim_id,
        body_id="bob",
        body_type="dynamic",
        shape="sphere",
        size=[0.1],
        mass=1.0,
        position=[0.0, 3.0, 0.0],
    )

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

Creates a new physics body (static, dynamic, or kinematic) with specified
shape, mass, and initial conditions. Bodies interact via collisions.

Args:
    sim_id: Simulation ID from create_simulation
    body_id: Unique identifier for this body (user-defined string)
    body_type: "static", "dynamic", or "kinematic"
        - static: Never moves (ground, walls)
        - dynamic: Affected by forces and collisions
        - kinematic: Moves but not affected by forces (scripted motion)
    shape: Collider shape: "box", "sphere", "capsule", "cylinder", "plane"
    size: Shape dimensions:
        - box: [width, height, depth]
        - sphere: [radius]
        - capsule: [half_height, radius]
        - cylinder: [half_height, radius]
        - plane: not needed (use normal/offset instead)
    mass: Mass in kilograms (for dynamic bodies). Default 1.0
    normal: Normal vector [x, y, z] for plane shape. Default [0, 1, 0] (upward)
    offset: Offset along normal for plane. Default 0.0
    position: Initial position [x, y, z]. Default [0, 0, 0]
    orientation: Initial orientation quaternion [x, y, z, w]. Default [0, 0, 0, 1] (identity)
    velocity: Initial linear velocity [x, y, z]. Default [0, 0, 0]
    angular_velocity: Initial angular velocity [x, y, z]. Default [0, 0, 0]
    restitution: Bounciness (0.0 = no bounce, 1.0 = perfect bounce). Default 0.5
    friction: Surface friction (0.0 = ice, 1.0 = rubber). Default 0.5
    is_sensor: If true, detects collisions but doesn't respond physically. Default false
    linear_damping: Linear velocity damping (0.0-1.0) - like air resistance. Default 0.0
    angular_damping: Angular velocity damping (0.0-1.0) - like rotational friction. Default 0.0
    drag_coefficient: Base drag coefficient (Cd) for orientation-dependent drag. Optional
    drag_area: Reference cross-sectional area (m²) for drag calculation. Optional
    drag_axis_ratios: Drag variation along body axes [x, y, z]. E.g., [1.0, 0.2, 1.0] for streamlined along Y. Optional
    fluid_density: Fluid density (kg/m³). Air=1.225, Water=1000. Default 1.225

Returns:
    body_id (echo of the input ID)

Tips for LLMs:
    - Create ground FIRST: body_type="static", shape="plane", normal=[0, 1, 0]
    - Box size is full width/height/depth (not half-extents)
    - Sphere size is [radius] (array with one element)
    - Quaternions: identity = [0, 0, 0, 1] (no rotation)
    - Common restitution: steel=0.8, wood=0.5, clay=0.1
    - Common friction: ice=0.05, wood=0.4, rubber=1.0

Example:
    # Add a ground plane
    await add_rigid_body(
        sim_id=sim_id,
        body_id="ground",
        body_type="static",
        shape="plane",
        normal=[0, 1, 0]
    )

    # Add a bouncing ball
    await add_rigid_body(
        sim_id=sim_id,
        body_id="ball",
        body_type="dynamic",
        shape="sphere",
        size=[0.5],  # radius = 0.5m
        mass=1.0,
        position=[0, 10, 0],
        restitution=0.7
    )

    # Add a falling box
    await add_rigid_body(
        sim_id=sim_id,
        body_id="box",
        body_type="dynamic",
        shape="box",
        size=[1.0, 1.0, 1.0],
        mass=10.0,
        position=[0.0, 5.0, 0.0]
    )

Comprehensive orbital analysis combining period, velocity, and acceleration.

Args:
    altitude: Altitude above surface in meters
    planet_mass: Planet mass in kg
    planet_radius: Planet radius in meters
    gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)

Returns:
    Dict containing:
        - orbital_radius: r from planet center in meters
        - orbital_velocity: v in m/s
        - period_seconds: Orbital period in seconds
        - period_minutes: Orbital period in minutes
        - centripetal_acceleration: a_c in m/s²

Example - LEO satellite at 400km altitude:
    result = await analyze_circular_orbit(
        altitude=400000,  # 400 km
        planet_mass=5.972e24,  # Earth
        planet_radius=6.371e6  # Earth
    )
    # v ≈ 7,670 m/s, T ≈ 92.6 min

Uses central differences for numerical differentiation:
v[i] ≈ (r[i+1] - r[i-1]) / (2Δt)
a[i] ≈ (v[i+1] - v[i-1]) / (2Δt)

Args:
    times: Time values in seconds (or JSON string)
    positions: Position vectors [[x,y,z], ...] in meters (or JSON string)

Returns:
    Dict containing:
        - velocities: Velocity vectors [[x,y,z], ...] in m/s
        - accelerations: Acceleration vectors [[x,y,z], ...] in m/s²
        - average_velocity: Average velocity [x,y,z] in m/s
        - average_acceleration: Average acceleration [x,y,z] in m/s²

Example - Analyze recorded position data:
    result = await calculate_acceleration_from_position(
        times=[0, 1, 2, 3],
        positions=[[0,0,0], [5,0,0], [10,0,0], [15,0,0]]
    )

Angular acceleration is the rotational equivalent of linear acceleration.
Determined by net torque and moment of inertia.

Args:
    torque: Torque magnitude in N⋅m
    moment_of_inertia: Moment of inertia in kg⋅m²

Returns:
    Dict containing:
        - angular_acceleration: α in rad/s²

Tips for LLMs:
    - Rotational version of F = ma → τ = Iα
    - Larger I means slower angular acceleration for same torque
    - Use for: motor acceleration, spinning up flywheels

Example - Motor accelerating a wheel:
    result = await calculate_angular_acceleration(
        torque=10.0,  # N⋅m
        moment_of_inertia=0.5  # kg⋅m²
    )
    # α = 20 rad/s²

Angular momentum is the rotational equivalent of linear momentum.
It's conserved in the absence of external torques (like ice skater spinning).

Args:
    moment_of_inertia: Moment of inertia in kg⋅m²
    angular_velocity_x: X component of angular velocity in rad/s
    angular_velocity_y: Y component of angular velocity in rad/s
    angular_velocity_z: Z component of angular velocity in rad/s

Returns:
    Dict containing:
        - angular_momentum: L vector [x, y, z] in kg⋅m²/s
        - magnitude: L magnitude in kg⋅m²/s

Tips for LLMs:
    - Angular momentum is conserved when no external torques act
    - Ice skater pulls arms in → I decreases → ω increases (L constant)
    - Gyroscopes resist changes in angular momentum direction

Example - Spinning figure skater:
    # Arms extended: I = 3.0 kg⋅m², ω = 5 rad/s
    result = await calculate_angular_momentum(
        moment_of_inertia=3.0,
        angular_velocity_x=0.0,
        angular_velocity_y=5.0,
        angular_velocity_z=0.0
    )
    # L = 15 kg⋅m²/s (conserved when arms pulled in)

Average speed = total distance / total time
(Distance is path length, not displacement)

Args:
    positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
    times: Time values in seconds (or JSON string)

Returns:
    Dict containing:
        - average_speed: Average speed in m/s
        - total_distance: Total path length in meters
        - total_time: Total elapsed time in seconds
        - displacement_magnitude: Straight-line displacement in meters
        - displacement: Displacement vector [x,y,z] in meters

Example - Car on winding road:
    result = await calculate_average_speed(
        positions=[[0,0,0], [10,5,0], [20,10,0], [15,20,0]],
        times=[0, 10, 20, 30]
    )

For a banked curve, the ideal angle where no friction is needed
to maintain the turn at a given speed.

Args:
    velocity: Speed in m/s
    radius: Turn radius in meters
    gravity: Gravitational acceleration in m/s² (default 9.81)

Returns:
    Dict containing:
        - angle_radians: Banking angle in radians
        - angle_degrees: Banking angle in degrees

Tips for LLMs:
    - Faster speed → steeper banking angle
    - Tighter turn → steeper banking angle
    - NASCAR tracks banked ~30° for high-speed turns
    - At ideal angle, normal force provides all centripetal force

Example - Highway exit ramp:
    result = await calculate_banking_angle(
        velocity=25,  # m/s (90 km/h)
        radius=100  # meter radius turn
    )
    # θ ≈ 32.5°

Uses moment equilibrium about supports to find reaction forces.

Args:
    beam_length: Beam length in meters
    loads: Point loads in Newtons (downward positive) (or JSON string)
    load_positions: Positions of loads from left end in meters (or JSON string)

Returns:
    Dict containing:
        - reaction_left: Reaction force at left support in Newtons
        - reaction_right: Reaction force at right support in Newtons
        - total_load: Total downward load in Newtons
        - is_balanced: Whether reactions balance loads

Example - Beam with two loads:
    result = await calculate_beam_reactions(
        beam_length=10.0,
        loads=[1000, 500],
        load_positions=[3.0, 7.0]
    )

Energy conservation for flowing fluids.

Args:
    pressure1: Pressure at point 1 in Pascals
    velocity1: Flow velocity at point 1 in m/s
    height1: Height at point 1 in meters
    velocity2: Flow velocity at point 2 in m/s (optional)
    height2: Height at point 2 in meters (optional)
    fluid_density: Fluid density in kg/m³ (default 1000 for water)
    gravity: Gravitational acceleration in m/s² (default 9.81)

Returns:
    Dict containing:
        - total_pressure_1: Total pressure at point 1
        - static_pressure_1: Static pressure component
        - dynamic_pressure_1: Dynamic pressure component
        - hydrostatic_pressure_1: Hydrostatic pressure component
        - pressure2: Pressure at point 2 (if velocity2/height2 given)

Example - Water tank with outlet:
    result = await calculate_bernoulli(
        pressure1=101325,  # Atmospheric at top
        velocity1=0,  # Still water
        height1=10,  # 10m height
        velocity2=14,  # Exit velocity
        height2=0,  # Ground level
        fluid_density=1000
    )

The buoyant force equals the weight of displaced fluid:
    F_b = ρ_fluid * V_submerged * g

Args:
    volume: Object volume in m³
    fluid_density: Fluid density in kg/m³ (water=1000, air=1.225)
    gravity: Gravitational acceleration in m/s² (default 9.81)
    submerged_fraction: Fraction submerged 0.0-1.0 (default 1.0 = fully submerged)

Returns:
    Buoyant force (upward) and displaced mass

Example - Checking if a 1kg ball will float:
    # 10cm diameter sphere: V = (4/3)πr³ = 0.000524 m³
    result = await calculate_buoyancy(
        volume=0.000524,
        fluid_density=1000  # water
    )
    # buoyant_force = 5.14 N
    # If weight (mg) < buoyant force, it floats
    # 1kg * 9.81 = 9.81 N > 5.14 N, so it sinks

Formula: r_cm = Σ(m_i × r_i) / Σm_i

Args:
    masses: List of masses in kg (or JSON string)
    positions: List of positions [[x,y,z], ...] in meters (or JSON string)

Returns:
    Dict containing:
        - center_of_mass: Position [x, y, z] in meters
        - total_mass: Total system mass in kg

Example - Three-mass system:
    result = await calculate_center_of_mass(
        masses=[1.0, 2.0, 3.0],
        positions=[[0,0,0], [1,0,0], [2,0,0]]
    )
    # center_of_mass ≈ [1.5, 0, 0]

Force required to keep an object moving in a circle.
Always points toward the center of the circular path.

Args:
    mass: Mass in kg
    velocity: Speed (velocity magnitude) in m/s
    radius: Radius of circular path in meters

Returns:
    Dict containing:
        - centripetal_force: F_c in Newtons
        - centripetal_acceleration: a_c in m/s²

Tips for LLMs:
    - Not a new force - it's the net inward force (tension, friction, gravity)
    - Faster speed → much more force needed (v² relationship)
    - Tighter turn → more force needed
    - Use for: car turns, satellite orbits, centrifuges

Example - Car turning:
    result = await calculate_centripetal_force(
        mass=1500,  # kg
        velocity=20,  # m/s (72 km/h)
        radius=50  # meter turn radius
    )
    # F_c = 12000 N (provided by friction between tires and road)

Real oscillators lose energy over time due to damping (air resistance,
friction). Three regimes: underdamped, critically damped, overdamped.

Args:
    mass: Mass in kg
    spring_constant: k in N/m
    damping_coefficient: b in kg/s (damping strength)
    time: Time t in seconds
    initial_position: Initial position in meters (default 1.0)
    initial_velocity: Initial velocity in m/s (default 0.0)

Returns:
    Dict containing:
        - position: x(t) in meters
        - velocity: v(t) in m/s
        - damping_ratio: ζ (zeta) = b/(2√(mk))
        - regime: "underdamped", "critically_damped", or "overdamped"

Damping regimes:
    - ζ < 1: Underdamped (oscillates, gradually decays)
    - ζ = 1: Critically damped (returns fastest without oscillating)
    - ζ > 1: Overdamped (slow return, no oscillation)

Example - Car suspension:
    result = await calculate_damped_oscillation(
        mass=300,  # kg (quarter car mass)
        spring_constant=20000,  # N/m
        damping_coefficient=2000,  # kg/s
        time=1.0
    )
    # Should be slightly underdamped for comfort

The drag force opposes motion and is given by:
    F_drag = 0.5 * ρ * v² * C_d * A

Common drag coefficients:
    - Sphere: 0.47
    - Streamlined shape: 0.04
    - Flat plate (perpendicular): 1.28
    - Human (standing): 1.0-1.3
    - Car: 0.25-0.35

Args:
    velocity: Velocity vector [x, y, z] in m/s (or JSON string)
    cross_sectional_area: Area perpendicular to flow in m²
    fluid_density: Fluid density in kg/m³ (water=1000, air=1.225)
    drag_coefficient: Drag coefficient (default 0.47 for sphere)
    viscosity: Dynamic viscosity in Pa·s (water=1.002e-3, air=1.825e-5, oil=0.1).
        If not provided, estimated from fluid_density for Reynolds number calculation.

Returns:
    Drag force vector, magnitude, and Reynolds number

Example - Ball falling through water:
    result = await calculate_drag_force(
        velocity=[0, -5.0, 0],
        cross_sectional_area=0.00785,  # π * (0.05m)² for 10cm diameter
        fluid_density=1000,  # water
        drag_coefficient=0.47,
        viscosity=1.002e-3  # water viscosity for accurate Reynolds number
    )
    # Returns upward drag force opposing downward motion

Example - Ball falling through motor oil:
    result = await calculate_drag_force(
        velocity=[0, -2.0, 0],
        cross_sectional_area=0.00785,
        fluid_density=900,  # oil
        drag_coefficient=0.47,
        viscosity=0.1  # motor oil is much more viscous
    )

Uses conservation of momentum and energy to solve for final velocities.
Assumes perfectly elastic collision (no energy loss).

Args:
    mass1: Mass of first object in kg
    velocity1: Initial velocity of first object in m/s (1D)
    mass2: Mass of second object in kg
    velocity2: Initial velocity of second object in m/s (1D)

Returns:
    Dict containing:
        - final_velocity1: Final velocity of object 1 in m/s
        - final_velocity2: Final velocity of object 2 in m/s
        - initial_kinetic_energy: Total KE before (J)
        - final_kinetic_energy: Total KE after (J) - should equal initial
        - initial_momentum: Total momentum before (kg⋅m/s)
        - final_momentum: Total momentum after (kg⋅m/s) - should equal initial

Example - Pool ball collision:
    result = await calculate_elastic_collision(
        mass1=0.17,      # kg (pool ball)
        velocity1=2.0,   # m/s (moving right)
        mass2=0.17,      # kg (pool ball)
        velocity2=0.0    # m/s (stationary)
    )
    # Result: ball 1 stops, ball 2 moves at 2.0 m/s

Special case of collision where no kinetic energy is lost (e = 1.0).
Both momentum and energy are conserved.

Args:
    mass1: Mass of object 1 in kg
    velocity1: Velocity of object 1 [x, y, z] in m/s (or JSON string)
    mass2: Mass of object 2 in kg
    velocity2: Velocity of object 2 [x, y, z] in m/s (or JSON string)

Returns:
    Dict containing:
        - final_velocity1: Final velocity [x, y, z] in m/s
        - final_velocity2: Final velocity [x, y, z] in m/s
        - initial_momentum: Total momentum [x, y, z]
        - final_momentum: Total momentum [x, y, z]
        - initial_kinetic_energy: Total KE in Joules
        - final_kinetic_energy: Total KE in Joules

Tips for LLMs:
    - Ideal approximation for billiard balls, Newton's cradle
    - Both momentum and energy conserved
    - Equal masses + head-on → velocities exchange
    - Use for educational examples, idealized systems

Example - Pool balls:
    result = await calculate_elastic_collision_3d(
        mass1=0.17,  # kg (pool ball)
        velocity1=[2, 0, 0],  # 2 m/s
        mass2=0.17,  # kg
        velocity2=[0, 0, 0]  # stationary
    )
    # Result: ball 1 stops, ball 2 moves at 2 m/s

Minimum speed needed to escape a celestial body's gravitational pull.
Independent of the escaping object's mass.

Args:
    mass: Mass of celestial body in kg
    radius: Radius of celestial body in meters
    gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)

Returns:
    Dict containing:
        - escape_velocity: v_escape in m/s
        - escape_velocity_kmh: v_escape in km/h (for convenience)

Tips for LLMs:
    - Earth: v_escape ≈ 11,200 m/s (40,320 km/h)
    - Moon: v_escape ≈ 2,380 m/s
    - Sun: v_escape ≈ 617,500 m/s
    - Independent of escape direction or mass of escaping object

Example - Earth escape velocity:
    result = await calculate_escape_velocity(
        mass=5.972e24,  # Earth mass (kg)
        radius=6.371e6  # Earth radius (meters)
    )
    # v_escape ≈ 11,186 m/s

Computes the force vector required to produce a given acceleration on a mass.
Fundamental for dynamics, engineering, and understanding motion.

Args:
    mass: Mass in kilograms (must be positive)
    acceleration_x: X component of acceleration in m/s²
    acceleration_y: Y component of acceleration in m/s²
    acceleration_z: Z component of acceleration in m/s²

Returns:
    ForceCalculationResponse containing:
        - force: Force vector [x, y, z] in Newtons
        - magnitude: Force magnitude in Newtons

Tips for LLMs:
    - 1 Newton = force to accelerate 1 kg at 1 m/s²
    - On Earth, weight force = mass × 9.81 N (vertical)
    - Use magnitude to compare total force regardless of direction
    - Common accelerations: car braking ~10 m/s², elevator ~2 m/s²

Example:
    # Force to accelerate a 1500kg car at 3 m/s² forward
    result = await calculate_force(
        mass=1500.0,
        acceleration_x=3.0,
        acceleration_y=0.0,
        acceleration_z=0.0
    )
    print(f"Required force: {result.magnitude:.0f} N")

The restoring force is proportional to displacement from equilibrium.
Fundamental for springs, elastic materials, and simple harmonic motion.

Args:
    spring_constant: Spring constant k in N/m (stiffness)
    displacement: Displacement from equilibrium in meters

Returns:
    Dict containing:
        - force: Restoring force magnitude in Newtons
        - potential_energy: Elastic potential energy in Joules

Tips for LLMs:
    - Stiffer spring → larger k → more force for same displacement
    - Potential energy stored in spring: PE = (1/2)kx²
    - Negative sign in F = -kx means force opposes displacement

Example - Compressing a car spring:
    result = await calculate_hookes_law(
        spring_constant=10000,  # N/m (stiff car spring)
        displacement=0.05  # 5cm compression
    )
    # Force = 500 N, PE = 12.5 J

Models realistic collisions where some kinetic energy is lost.
Coefficient of restitution (e) determines how much energy is retained.

Args:
    mass1: Mass of object 1 in kg
    velocity1: Velocity of object 1 [x, y, z] in m/s (or JSON string)
    mass2: Mass of object 2 in kg
    velocity2: Velocity of object 2 [x, y, z] in m/s (or JSON string)
    coefficient_of_restitution: e (0.0 = perfectly inelastic, 1.0 = perfectly elastic)

Returns:
    Dict containing:
        - final_velocity1: Final velocity [x, y, z] in m/s
        - final_velocity2: Final velocity [x, y, z] in m/s
        - initial_momentum: Total initial momentum [x, y, z]
        - final_momentum: Total final momentum [x, y, z]
        - initial_kinetic_energy: Total initial KE in Joules
        - final_kinetic_energy: Total final KE in Joules
        - energy_loss: Energy lost in Joules
        - energy_loss_percent: % of energy lost

Coefficient of restitution values:
    - e = 0.0: Perfectly inelastic (clay, putty) - objects stick
    - e = 0.5: Very inelastic (wet clay)
    - e = 0.7: Moderately elastic (basketball)
    - e = 0.9: Highly elastic (Super Ball)
    - e = 1.0: Perfectly elastic (ideal, no energy loss)

Tips for LLMs:
    - Momentum is always conserved (regardless of e)
    - Energy lost = (1 - e²) × initial KE in center-of-mass frame
    - Use e=1.0 for billiard balls, e=0.0 for car crashes

Example - Car crash:
    result = await calculate_inelastic_collision_3d(
        mass1=1500,  # kg
        velocity1=[20, 0, 0],  # 20 m/s east
        mass2=1200,  # kg
        velocity2=[-15, 0, 0],  # 15 m/s west
        coefficient_of_restitution=0.1  # very inelastic
    )
    # Massive energy loss, objects nearly stick together

Uses interpolation if target_time is between data points,
otherwise uses numerical differentiation.

Args:
    positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
    times: Time values in seconds (or JSON string)
    target_time: Time at which to calculate velocity in seconds

Returns:
    Dict containing:
        - velocity: Velocity vector [x,y,z] in m/s
        - speed: Speed magnitude in m/s
        - interpolated: Whether interpolation was used
        - time: Target time (echo)

Example:
    result = await calculate_instantaneous_velocity(
        positions=[[0,0,0], [3,4,0], [6,8,0]],
        times=[0, 1, 2],
        target_time=1.0
    )
    # speed = 5 m/s

Jerk = da/dt is important for comfort in vehicles and mechanical design.

Args:
    times: Time values in seconds (or JSON string)
    accelerations: Acceleration vectors [[x,y,z], ...] in m/s² (or JSON string)

Returns:
    Dict containing:
        - jerks: Jerk vectors [[x,y,z], ...] in m/s³
        - average_jerk: Average jerk [x,y,z] in m/s³
        - max_jerk_magnitude: Maximum jerk magnitude in m/s³

Example:
    result = await calculate_jerk(
        times=[0, 1, 2, 3],
        accelerations=[[0,0,0], [2,0,0], [4,0,0], [6,0,0]]
    )
    # jerk_x ≈ 2 m/s³ (constant)

Computes the energy of motion for a moving object. Energy is scalar
(direction doesn't matter, only speed). Useful for collision analysis,
vehicle safety, and understanding energy transfer.

Args:
    mass: Mass in kilograms (must be positive)
    velocity_x: X component of velocity in m/s
    velocity_y: Y component of velocity in m/s
    velocity_z: Z component of velocity in m/s

Returns:
    KineticEnergyResponse containing:
        - kinetic_energy: Energy in Joules (J)
        - speed: Velocity magnitude in m/s

Tips for LLMs:
    - 1 Joule = 1 kg⋅m²/s² = energy to lift 102g by 1m on Earth
    - Kinetic energy doubles mass → doubles energy, doubles speed → 4× energy
    - Car at highway speed (~30 m/s, 1500 kg) ≈ 675,000 J
    - Use to compare impact severity or stopping distances

Example:
    # Energy of a 0.145kg baseball at 40 m/s
    result = await calculate_kinetic_energy(
        mass=0.145,
        velocity_x=40.0,
        velocity_y=0.0,
        velocity_z=0.0
    )
    print(f"Kinetic energy: {result.kinetic_energy:.1f} J")

Based on Bernoulli's principle and wing aerodynamics.

Args:
    velocity: Flow velocity in m/s
    wing_area: Wing area in m²
    lift_coefficient: Lift coefficient C_L (dimensionless)
    fluid_density: Fluid density in kg/m³ (air=1.225)

Returns:
    Dict containing:
        - lift_force: Lift force in Newtons
        - dynamic_pressure: Dynamic pressure (q) in Pascals

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
    )

The Magnus force is perpendicular to both velocity and spin axis.
Causes curve balls in sports.

Args:
    velocity: Ball velocity [x, y, z] in m/s (or JSON string)
    angular_velocity: Angular velocity [x, y, z] in rad/s (or JSON string)
    radius: Ball radius in meters
    fluid_density: Fluid density in kg/m³ (air=1.225)

Returns:
    Dict containing:
        - magnus_force: Magnus force vector [x, y, z] in Newtons
        - magnus_force_magnitude: Force magnitude in Newtons
        - spin_rate: Spin rate (angular velocity magnitude) in rad/s

Example - Soccer ball curve:
    result = await calculate_magnus_force(
        velocity=[20, 0, 0],  # 20 m/s forward
        angular_velocity=[0, 0, 50],  # 50 rad/s topspin
        radius=0.11,  # Soccer ball
        fluid_density=1.225
    )

Moment of inertia (I) is the rotational equivalent of mass. It determines
how difficult it is to change an object's rotation. Depends on both mass
distribution and rotation axis.

Args:
    shape: Shape type - "sphere", "solid_sphere", "hollow_sphere", "rod", "disk", "cylinder", "box"
    mass: Mass in kilograms
    radius: Radius for sphere/disk/cylinder (meters)
    length: Length for rod (meters)
    width: Width for box (meters)
    height: Height for box/cylinder (meters)
    depth: Depth for box (meters)
    axis: Rotation axis - "center", "end" (for rod), "x", "y", "z" (for box)

Returns:
    Dict containing:
        - moment_of_inertia: I in kg⋅m²
        - shape: Shape type
        - axis: Rotation axis

Common formulas:
    - Solid sphere (center): I = (2/5)mr²
    - Hollow sphere (center): I = (2/3)mr²
    - Rod (center): I = (1/12)mL²
    - Rod (end): I = (1/3)mL²
    - Disk (center): I = (1/2)mr²

Example - Spinning wheel:
    result = await calculate_moment_of_inertia(
        shape="disk",
        mass=5.0,  # 5kg wheel
        radius=0.3  # 30cm radius
    )
    # I = 0.225 kg⋅m²

Computes the momentum vector, which represents "quantity of motion."
Momentum is conserved in collisions, making it crucial for analyzing
impacts, explosions, and rocket propulsion.

Args:
    mass: Mass in kilograms (must be positive)
    velocity_x: X component of velocity in m/s
    velocity_y: Y component of velocity in m/s
    velocity_z: Z component of velocity in m/s

Returns:
    MomentumResponse containing:
        - momentum: Momentum vector [x, y, z] in kg⋅m/s
        - magnitude: Momentum magnitude in kg⋅m/s

Tips for LLMs:
    - Momentum is a vector (has direction), unlike kinetic energy
    - Total momentum before collision = total momentum after (conservation)
    - Large mass × small velocity can equal small mass × large velocity
    - Use to analyze: collisions, recoil, rocket thrust

Example:
    # Momentum of a 70kg person running at 5 m/s
    result = await calculate_momentum(
        mass=70.0,
        velocity_x=5.0,
        velocity_y=0.0,
        velocity_z=0.0
    )
    print(f"Momentum: {result.magnitude:.1f} kg⋅m/s")

On an incline at angle θ:
- N = mg cos(θ) + F_additional
- Weight component perpendicular: mg cos(θ)
- Weight component parallel: mg sin(θ)

Args:
    mass: Object mass in kg
    gravity: Gravitational acceleration in m/s² (default 9.81)
    angle_degrees: Incline angle in degrees (0 = horizontal)
    additional_force: Additional perpendicular force in Newtons (optional)

Returns:
    Dict containing:
        - normal_force: Normal force in Newtons
        - weight_component_perpendicular: Weight component ⊥ to surface
        - weight_component_parallel: Weight component ∥ to surface

Example - Box on 30° ramp:
    result = await calculate_normal_force(
        mass=10.0,
        angle_degrees=30.0
    )
    # normal_force ≈ 84.9 N

Kepler's Third Law for circular orbits. Period depends on orbital
radius and central body mass.

Args:
    orbital_radius: Orbital radius in meters (from center of central body)
    central_mass: Mass of central body in kg
    gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)

Returns:
    Dict containing:
        - period: Orbital period in seconds
        - orbital_velocity: v in m/s
        - period_hours: Period in hours (for convenience)
        - period_days: Period in days (for convenience)

Tips for LLMs:
    - Higher orbit → longer period
    - More massive central body → shorter period
    - Earth: M = 5.972e24 kg, R = 6.371e6 m
    - Moon orbit: r ≈ 384,400 km, T ≈ 27.3 days
    - ISS orbit: r ≈ 6,771 km (altitude 400 km), T ≈ 90 minutes

Example - ISS orbit:
    result = await calculate_orbital_period(
        orbital_radius=6.771e6,  # meters
        central_mass=5.972e24  # Earth mass (kg)
    )
    # T ≈ 5,558 seconds ≈ 92.6 minutes

Period of a simple pendulum depends only on length and gravity
(for small amplitudes). Includes correction for large amplitudes.

Args:
    length: Pendulum length in meters (pivot to center of mass)
    gravity: Gravitational acceleration in m/s² (default 9.81)
    amplitude_degrees: Amplitude in degrees (optional, for large angle correction)

Returns:
    Dict containing:
        - period: T in seconds
        - frequency: f in Hz
        - angular_frequency: ω in rad/s
        - small_angle_approximation: Whether small angle formula was used

Tips for LLMs:
    - Period independent of mass (Galileo's discovery)
    - Period independent of amplitude (for small angles < 15°)
    - Longer pendulum → longer period
    - Use for: clocks, playground swings, seismometers

Example - Grandfather clock:
    result = await calculate_pendulum_period(
        length=0.994,  # meters (for 2-second period)
        gravity=9.81
    )
    # T = 2.0 seconds

Computes PE = mgh (mass × gravity × height).
Also returns the equivalent velocity if the object falls from that height.

Args:
    mass: Object mass in kilograms
    height: Height above reference point in meters
    gravity: Gravitational acceleration in m/s² (default 9.81 for Earth)

Returns:
    Dict containing:
        - potential_energy: PE in Joules
        - equivalent_kinetic_velocity: Speed if dropped from height (m/s)

Example - Object at 10m height:
    result = await calculate_potential_energy(mass=2.0, height=10.0)
    # PE = 196.2 J
    # Velocity if dropped = 14.0 m/s

Hydrostatic pressure increases with depth.

Args:
    depth: Depth below surface in meters
    fluid_density: Fluid density in kg/m³ (water=1000, seawater=1025)
    atmospheric_pressure: Pressure at surface in Pascals (default 101325)
    gravity: Gravitational acceleration in m/s² (default 9.81)

Returns:
    Dict containing:
        - total_pressure: Total pressure in Pascals
        - gauge_pressure: Pressure above atmospheric in Pascals
        - pressure_atmospheres: Pressure in atmospheres (1 atm = 101325 Pa)

Example - Scuba diving at 30m:
    result = await calculate_pressure_at_depth(
        depth=30,  # meters
        fluid_density=1025,  # seawater
        atmospheric_pressure=101325
    )
    # Result: ~4 atmospheres

Computes the complete trajectory of a projectile launched at an angle,
including maximum height, range, time of flight, and sample trajectory points.
Perfect for ballistics, sports analysis, or educational demonstrations.

Args:
    initial_velocity: Initial velocity in meters per second (m/s). Must be positive.
    angle_degrees: Launch angle in degrees from horizontal (0-90).
        0° = horizontal, 45° = maximum range, 90° = straight up
    initial_height: Initial height above ground in meters. Default 0.0 (ground level).
    gravity: Gravitational acceleration in m/s². Default 9.81 (Earth surface).
        Use 1.62 for Moon, 3.71 for Mars, etc.

Returns:
    ProjectileMotionResponse containing:
        - max_height: Maximum height reached (meters)
        - range: Horizontal distance traveled (meters)
        - time_of_flight: Total time in air (seconds)
        - trajectory_points: List of [x, y] sample points for plotting

Tips for LLMs:
    - 45° gives maximum range on flat ground (no air resistance)
    - For R3F visualization: convert trajectory_points to 3D by adding z=0
    - trajectory_points are evenly spaced in time (50 samples)
    - Air resistance is NOT modeled - this is ideal ballistic motion
    - Use for: cannon balls, baseballs, basketball shots, water fountains

Example:
    # Calculate trajectory of a cannonball fired at 50 m/s at 30°
    result = await calculate_projectile_motion(
        initial_velocity=50.0,
        angle_degrees=30.0,
        initial_height=2.0
    )
    print(f"Range: {result.range:.1f}m, Max height: {result.max_height:.1f}m")

Uses numerical integration (RK4) to solve motion equations with:
- Quadratic drag force: F_drag = 0.5 * ρ * v² * Cd * A
- Magnus force (spin effects): F_magnus = 0.5 * ρ * Cl * A * ω * r * v
- Wind effects (constant wind vector)
- Variable air density (altitude and temperature effects)

This provides REALISTIC trajectories for sports balls, projectiles,
and other objects moving through air or water. Compare with
calculate_projectile_motion (no drag) to see dramatic differences!

Common drag coefficients (Cd):
    - Sphere: 0.47 (default)
    - Baseball: 0.4
    - Golf ball: 0.25 (dimples reduce drag)
    - Football (American): 0.05-0.15 (orientation-dependent)
    - Basketball: 0.55
    - Soccer ball: 0.25
    - Skydiver (belly-down): 1.0-1.3
    - Streamlined car: 0.25-0.35

Args:
    initial_velocity: Launch velocity in m/s
    angle_degrees: Launch angle in degrees (0-90)
    mass: Object mass in kg
    cross_sectional_area: Cross-section perpendicular to motion in m²
    initial_height: Launch height in meters (default 0)
    drag_coefficient: Drag coefficient Cd (default 0.47 for sphere)
    fluid_density: Fluid density in kg/m³ (air=1.225, water=1000)
    gravity: Gravitational acceleration m/s² (default 9.81)
    time_step: Integration time step in seconds (default 0.01)
    max_time: Maximum simulation time in seconds (default 30)
    spin_rate: Spin rate in rad/s for Magnus force (default 0, no spin)
    spin_axis: Spin axis unit vector [x, y, z] (default [0, 0, 1] = vertical)
    wind_velocity: Wind velocity [vx, vy] in m/s (default [0, 0], no wind)
    altitude: Altitude above sea level in meters (default 0, affects air density)
    temperature: Air temperature in Celsius (default 15, affects air density)

Returns:
    Dict containing:
        - max_height: Maximum altitude reached (m)
        - range: Horizontal distance traveled (m)
        - time_of_flight: Total flight time (s)
        - impact_velocity: Speed at landing (m/s)
        - impact_angle: Angle at landing (degrees below horizontal)
        - trajectory_points: [[x, y], ...] for plotting
        - energy_lost_to_drag: Energy dissipated by drag (J)
        - initial_kinetic_energy: Initial KE (J)
        - final_kinetic_energy: Final KE (J)
        - lateral_deflection: Lateral deflection from spin/wind (m)
        - magnus_force_max: Maximum Magnus force magnitude (N)
        - wind_drift: Total wind drift (m)
        - effective_air_density: Effective air density used (kg/m³)

Example - Baseball curveball (2500 rpm backspin):
    result = await calculate_projectile_with_drag(
        initial_velocity=40.23,  # 90 mph
        angle_degrees=10,
        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]  # Backspin (vertical axis)
    )
    # Backspin increases range and height!

Example - Golf ball at altitude (Denver, 1600m):
    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,  # Denver elevation
        temperature=20  # Summer day
    )
    # Less air resistance = longer drive!

Example - Soccer free kick with wind:
    result = await calculate_projectile_with_drag(
        initial_velocity=25,
        angle_degrees=15,
        mass=0.43,
        cross_sectional_area=0.0388,
        drag_coefficient=0.25,
        wind_velocity=[5, 0],  # 5 m/s tailwind
        spin_rate=50,  # Sidespin for curve
        spin_axis=[0, 1, 0]  # Horizontal axis
    )
    # Wind drift + Magnus curve!

Determines flow regime (laminar, transitional, turbulent).

Args:
    velocity: Flow velocity in m/s
    characteristic_length: Characteristic length in meters (pipe diameter, etc.)
    fluid_density: Fluid density in kg/m³
    dynamic_viscosity: Dynamic viscosity in Pa·s (water=0.001, air=1.8e-5)

Returns:
    Dict containing:
        - reynolds_number: Re (dimensionless)
        - flow_regime: "laminar" (Re<2300), "transitional" (2300-4000), "turbulent" (Re>4000)

Example - Water in pipe:
    result = await calculate_reynolds_number(
        velocity=2.0,  # m/s
        characteristic_length=0.05,  # 5cm diameter
        fluid_density=1000,  # water
        dynamic_viscosity=0.001
    )
    # Re = 100,000 → turbulent

Energy of rotation. A spinning object has kinetic energy even if
its center of mass is stationary.

Args:
    moment_of_inertia: Moment of inertia in kg⋅m²
    angular_velocity: Angular velocity magnitude in rad/s

Returns:
    Dict containing:
        - rotational_ke: Rotational kinetic energy in Joules

Tips for LLMs:
    - Total KE = translational KE + rotational KE
    - Rolling object has both types of kinetic energy
    - Flywheel energy storage uses this principle

Example - Car wheel at highway speed:
    result = await calculate_rotational_kinetic_energy(
        moment_of_inertia=0.5,  # kg⋅m²
        angular_velocity=100.0  # rad/s (fast spinning)
    )
    # KE_rot = 2500 J

Position, velocity, and acceleration for sinusoidal oscillation.
Models ideal springs, pendulums, and many other oscillating systems.

Args:
    amplitude: Amplitude A in meters (maximum displacement)
    angular_frequency: ω in rad/s (ω = 2πf)
    time: Time t in seconds
    phase: Phase shift φ in radians (default 0)

Returns:
    Dict containing:
        - position: x(t) in meters
        - velocity: v(t) = -Aω sin(ωt + φ) in m/s
        - acceleration: a(t) = -Aω² cos(ωt + φ) in m/s²

Tips for LLMs:
    - Position and acceleration are 180° out of phase
    - Maximum velocity occurs at equilibrium (x = 0)
    - Maximum acceleration occurs at maximum displacement

Example - Oscillating mass:
    result = await calculate_simple_harmonic_motion(
        amplitude=0.1,  # 10cm amplitude
        angular_frequency=5.0,  # rad/s
        time=1.0  # at t = 1s
    )

Natural oscillation frequency of a mass attached to a spring.
Independent of amplitude (for ideal springs).

Args:
    mass: Mass in kg
    spring_constant: Spring constant k in N/m

Returns:
    Dict containing:
        - period: T in seconds
        - frequency: f in Hz
        - angular_frequency: ω in rad/s

Tips for LLMs:
    - Heavier mass → longer period (slower oscillation)
    - Stiffer spring → shorter period (faster oscillation)
    - ω = 2πf = √(k/m)

Example - Mass on spring:
    result = await calculate_spring_mass_period(
        mass=0.5,  # 500g mass
        spring_constant=20.0  # N/m
    )
    # T ≈ 0.99s, f ≈ 1.01 Hz

Determines whether an object will slip under applied force.

Args:
    normal_force: Normal force in Newtons
    coefficient_static_friction: Coefficient of static friction μ_s
    applied_force: Applied horizontal force in Newtons (optional)

Returns:
    Dict containing:
        - max_static_friction: Maximum static friction in Newtons
        - will_slip: Whether object will slip (if applied_force provided)
        - friction_force: Actual friction force (if applied_force provided)

Example - Box on floor:
    result = await calculate_static_friction(
        normal_force=100,
        coefficient_static_friction=0.5,
        applied_force=40
    )
    # will_slip = False (40N < 50N max)

At terminal velocity, forces balance:
    F_drag = F_weight
    v_terminal = √(2mg / ρC_dA)

Args:
    mass: Object mass in kg
    cross_sectional_area: Area perpendicular to fall direction in m²
    fluid_density: Fluid density in kg/m³ (air=1.225, water=1000)
    drag_coefficient: Drag coefficient (sphere=0.47, skydiver=1.0)
    gravity: Gravitational acceleration in m/s² (default 9.81)

Returns:
    Terminal velocity, time to 95%, and drag force at terminal

Example - Skydiver terminal velocity:
    result = await calculate_terminal_velocity(
        mass=70,  # kg
        cross_sectional_area=0.7,  # m² (belly-down position)
        fluid_density=1.225,  # air
        drag_coefficient=1.0,  # human
    )
    # v_terminal ≈ 54 m/s (120 mph)

Torque is the rotational equivalent of force. It causes angular acceleration
and depends on both the force magnitude and the distance from the pivot point.

Args:
    force_x: X component of force in Newtons
    force_y: Y component of force in Newtons
    force_z: Z component of force in Newtons
    position_x: X component of position vector from pivot to force application (meters)
    position_y: Y component of position vector from pivot to force application (meters)
    position_z: Z component of position vector from pivot to force application (meters)

Returns:
    Dict containing:
        - torque: Torque vector [x, y, z] in N⋅m
        - magnitude: Torque magnitude in N⋅m

Tips for LLMs:
    - Torque direction follows right-hand rule (perpendicular to force and position)
    - Maximum torque when force is perpendicular to position vector
    - Zero torque when force is parallel to position vector
    - Use for: wrenches, door hinges, motors, gears

Example - Opening a door:
    result = await calculate_torque(
        force_x=50.0,  # Push perpendicular to door
        force_y=0.0,
        force_z=0.0,
        position_x=0.0,
        position_y=0.0,
        position_z=0.8  # 0.8m from hinge
    )
    # Torque = 40 N⋅m

Uses continuity equation and Bernoulli's principle.

Args:
    inlet_diameter: Inlet diameter in meters
    throat_diameter: Throat (constriction) diameter in meters
    inlet_velocity: Inlet velocity in m/s
    fluid_density: Fluid density in kg/m³

Returns:
    Dict containing:
        - throat_velocity: Velocity at throat in m/s
        - pressure_drop: Pressure drop from inlet to throat in Pascals
        - flow_rate: Volumetric flow rate in m³/s

Example - Venturi meter:
    result = await calculate_venturi_effect(
        inlet_diameter=0.1,  # 10 cm
        throat_diameter=0.05,  # 5 cm
        inlet_velocity=2.0,  # m/s
        fluid_density=1000  # water
    )
    # throat_velocity = 8 m/s (4x area reduction)

Work is the dot product: W = F · d
Power (if time given): P = W / t

Args:
    force: Force vector [x, y, z] in Newtons (or JSON string)
    displacement: Displacement vector [x, y, z] in meters (or JSON string)
    time: Time taken in seconds (optional, for power calculation)

Returns:
    Dict containing:
        - work: Work done in Joules
        - power: Power in Watts (if time provided, else None)

Example - Pushing box 5m with 100N force:
    result = await calculate_work_power(
        force=[100, 0, 0],
        displacement=[5, 0, 0],
        time=10.0
    )
    # Work = 500 J, Power = 50 W

Checks whether total angular momentum is conserved. Angular momentum
is conserved when no external torques act on the system.

Args:
    initial_angular_momentum: Initial L [x, y, z] in kg⋅m²/s (or JSON string)
    final_angular_momentum: Final L [x, y, z] in kg⋅m²/s (or JSON string)
    tolerance: Tolerance (fraction, default 0.01 = 1%)

Returns:
    Dict containing:
        - initial_L_magnitude: Initial |L| in kg⋅m²/s
        - final_L_magnitude: Final |L| in kg⋅m²/s
        - L_difference: Difference [x, y, z]
        - L_difference_magnitude: |ΔL|
        - L_difference_percent: % difference
        - is_conserved: Whether L is conserved within tolerance

Tips for LLMs:
    - Conserved when no external torques (isolated rotation)
    - Ice skater spinning: pull arms in → I decreases → ω increases (L constant)
    - Gyroscope: resists changes to L direction
    - Planets orbiting: L conserved → elliptical orbits

Example - Figure skater:
    # Arms extended → Arms pulled in
    result = await check_angular_momentum_conservation(
        initial_angular_momentum=[0, 15, 0],  # kg⋅m²/s
        final_angular_momentum=[0, 15.05, 0],
        tolerance=0.01
    )

Predicts whether two moving spheres will collide within a time window,
and if so, calculates when and where the collision occurs. Uses analytic
relative motion to find exact collision time (if any).

Args:
    body1_position: Position of first object [x, y, z] in meters
    body1_velocity: Velocity of first object [x, y, z] in m/s
    body1_radius: Radius of first object in meters (must be positive)
    body2_position: Position of second object [x, y, z] in meters
    body2_velocity: Velocity of second object [x, y, z] in m/s
    body2_radius: Radius of second object in meters (must be positive)
    max_time: Maximum time to check in seconds. Default 10.0.

Returns:
    CollisionCheckResponse containing:
        - will_collide: True if collision will occur
        - collision_time: Time until collision in seconds (if collision occurs)
        - collision_point: Approximate collision location [x, y, z] (if collision occurs)
        - impact_speed: Relative velocity at impact in m/s (if collision occurs)
        - closest_approach_distance: Minimum distance between objects
        - closest_approach_time: Time of closest approach

Tips for LLMs:
    - Objects are modeled as spheres (point masses with radius)
    - Collision detection is exact for constant velocity motion
    - Returns earliest collision time if multiple intersections
    - If no collision, check closest_approach_distance to see how close they get
    - Use for: asteroid tracking, car crash prediction, sports ball interactions
    - For complex shapes or forces, use create_simulation instead

Example:
    # Check if two cars will collide
    result = await check_collision(
        body1_position=[0.0, 0.0, 0.0],
        body1_velocity=[10.0, 0.0, 0.0],
        body1_radius=2.0,
        body2_position=[50.0, 1.0, 0.0],
        body2_velocity=[-8.0, 0.0, 0.0],
        body2_radius=2.0
    )
    if result.will_collide:
        print(f"Collision in {result.collision_time:.2f} seconds at {result.impact_speed:.1f} m/s")

Checks whether total mechanical energy is conserved (or correctly dissipated).
Useful for validating simulation results and understanding energy transfer.

Args:
    initial_kinetic_energy: Initial KE in Joules
    final_kinetic_energy: Final KE in Joules
    initial_potential_energy: Initial PE in Joules
    final_potential_energy: Final PE in Joules
    expected_energy_loss: Expected energy loss (from friction, etc.) in Joules
    tolerance: Tolerance for conservation check (fraction, default 0.01 = 1%)

Returns:
    Dict containing:
        - initial_total_energy: Initial total energy in Joules
        - final_total_energy: Final total energy in Joules
        - energy_difference: Energy difference in Joules
        - energy_difference_percent: % difference
        - is_conserved: Whether energy is conserved within tolerance
        - expected_loss: Expected energy loss in Joules
        - actual_loss: Actual energy loss in Joules

Tips for LLMs:
    - In isolated systems, total energy is conserved
    - With friction/damping, expect energy loss
    - Small numerical errors are normal in simulations
    - Use to validate simulation accuracy

Example - Bouncing ball with energy loss:
    result = await check_energy_conservation(
        initial_kinetic_energy=0,
        final_kinetic_energy=0,
        initial_potential_energy=10,  # J (at 1m height)
        final_potential_energy=6.4,  # J (bounced to 0.64m)
        expected_energy_loss=3.6,  # 36% loss (e=0.8)
        tolerance=0.01
    )

For static equilibrium, both force and torque must be balanced.

Args:
    forces: List of force vectors [[x,y,z], ...] in N (or JSON string)
    force_positions: Positions where forces applied [[x,y,z], ...] (or JSON string)
    pivot_point: Pivot point for torque calculation [x,y,z] (default [0,0,0])
    tolerance: Tolerance for equilibrium check (default 0.01)

Returns:
    Dict containing:
        - force_balanced: Whether ΣF = 0
        - torque_balanced: Whether Στ = 0
        - in_equilibrium: Whether system is in static equilibrium
        - net_force: Net force [x, y, z] in N
        - net_torque: Net torque [x, y, z] in N⋅m

Example - Beam with two forces:
    result = await check_equilibrium(
        forces=[[0, 100, 0], [0, -100, 0]],
        force_positions=[[1, 0, 0], [2, 0, 0]]
    )

Verifies whether a system of forces is balanced (net force = 0).
Essential for statics problems and structural analysis.

Args:
    forces: List of force vectors [[x,y,z], ...] in Newtons (or JSON string)
    tolerance: Tolerance for equilibrium check (fraction, default 0.01)

Returns:
    Dict containing:
        - net_force: Net force vector [x, y, z] in Newtons
        - net_force_magnitude: Net force magnitude in Newtons
        - is_balanced: Whether forces are in equilibrium
        - individual_magnitudes: Magnitude of each force

Example - Bridge support forces:
    result = await check_force_balance(
        forces=[[0, 1000, 0], [0, 500, 0], [0, -1500, 0]],
        tolerance=0.01
    )
    # is_balanced = True if net force ≈ 0

Checks whether total momentum is conserved in a collision or interaction.
Momentum should be conserved in isolated systems (no external forces).

Args:
    initial_momentum: Initial total momentum [x, y, z] in kg⋅m/s (or JSON string)
    final_momentum: Final total momentum [x, y, z] in kg⋅m/s (or JSON string)
    tolerance: Tolerance for conservation check (fraction, default 0.01 = 1%)

Returns:
    Dict containing:
        - initial_momentum_magnitude: Initial |p| in kg⋅m/s
        - final_momentum_magnitude: Final |p| in kg⋅m/s
        - momentum_difference: Difference [x, y, z]
        - momentum_difference_magnitude: |Δp|
        - momentum_difference_percent: % difference
        - is_conserved: Whether momentum is conserved within tolerance

Tips for LLMs:
    - Momentum is ALWAYS conserved in isolated systems
    - Vector quantity - direction matters
    - Use to validate collision calculations
    - External forces (friction, etc.) can change total momentum

Example - Collision verification:
    result = await check_momentum_conservation(
        initial_momentum=[3000, 0, 0],  # kg⋅m/s
        final_momentum=[2995, 5, 0],  # slightly off
        tolerance=0.01
    )

Verifies whether a system of torques is balanced (net torque = 0).
Essential for rotational equilibrium and lever problems.

Args:
    torques: List of torque vectors [[x,y,z], ...] in N⋅m (or JSON string)
    tolerance: Tolerance for equilibrium check (fraction, default 0.01)

Returns:
    Dict containing:
        - net_torque: Net torque vector [x, y, z] in N⋅m
        - net_torque_magnitude: Net torque magnitude in N⋅m
        - is_balanced: Whether torques are in equilibrium
        - individual_magnitudes: Magnitude of each torque

Example - Seesaw balance:
    result = await check_torque_balance(
        torques=[[0, 0, 100], [0, 0, -100]],
        tolerance=0.01
    )

Convert a value from one unit to another.

Supports 62 unit types across 16 categories:
- 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

Enables natural language queries like:
- "Convert 60 mph to m/s"
- "How fast is 100 km/h in mph?"
- "Convert 10 kg to pounds"

Args:
    value: The numeric value to convert
    from_unit: Source unit (e.g., 'mph', 'kg', 'J')
    to_unit: Target unit (e.g., 'm/s', 'lb', 'kWh')

Returns:
    Dictionary with:
    - original_value: Input value
    - original_unit: Input unit
    - converted_value: Result value
    - converted_unit: Result unit
    - formatted: Human-readable string

Examples:
    >>> convert_unit(100, 'm/s', 'mph')
    {
        "original_value": 100,
        "original_unit": "m/s",
        "converted_value": 223.694,
        "converted_unit": "mph",
        "formatted": "100 m/s = 223.694 mph"
    }

    >>> convert_unit(60, 'mph', 'km/h')
    {
        "original_value": 60,
        "original_unit": "mph",
        "converted_value": 96.56064,
        "converted_unit": "km/h",
        "formatted": "60 mph = 96.56 km/h"
    }

Initializes a new rigid-body physics world with configurable gravity and
timestep. Returns a simulation ID used for all subsequent operations.

Args:
    gravity_x: X component of gravity vector (m/s²). Default 0.0
    gravity_y: Y component of gravity vector (m/s²). Default -9.81 (Earth down)
    gravity_z: Z component of gravity vector (m/s²). Default 0.0
    dimensions: 2 or 3 for 2D/3D simulation. Default 3.
    dt: Simulation timestep in seconds. Default 0.016 (60 FPS).
        Smaller = more accurate but slower, larger = faster but less stable
    integrator: Integration method. Options: "euler", "verlet", "rk4". Default "verlet".

Returns:
    SimulationCreateResponse containing:
        - sim_id: Unique simulation identifier (use for all other sim calls)
        - config: Echo of the configuration used

Tips for LLMs:
    - Keep simulation IDs in memory for the conversation session
    - Default gravity is Earth standard (9.81 m/s² down = -Y direction)
    - dt=0.016 ≈ 60 FPS, dt=0.008 ≈ 120 FPS (higher accuracy)
    - "verlet" integrator is good default (stable, energy-conserving)
    - Remember to destroy_simulation when done to free resources

Requires:
    - Rapier provider must be configured (see config.py)
    - Rapier service must be running (see RAPIER_SERVICE.md)

Example:
    # Create simulation with Earth gravity
    sim = await create_simulation(
        gravity_y=-9.81,
        dt=0.016
    )
    # Use sim.sim_id for add_body, step_simulation, etc.

Cleanup when done with a simulation. Important for long-running servers
to avoid memory leaks.

Args:
    sim_id: Simulation ID to destroy

Returns:
    Success message

Tips for LLMs:
    - Always destroy simulations when conversation ends or changes topic
    - Rapier service keeps simulations in memory until explicitly destroyed
    - Good practice: destroy after recording trajectory or final state

Example:
    await destroy_simulation(sim_id)

Useful for smoothing noisy data or finding trajectory equations.
Default fit_type="quadratic" fits parabolic trajectory (constant acceleration).

Args:
    times: Time values in seconds (or JSON string)
    positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
    fit_type: Polynomial type - "linear", "quadratic", or "cubic" (default "quadratic")

Returns:
    Dict containing:
        - coefficients_x: Polynomial coefficients for x(t)
        - coefficients_y: Polynomial coefficients for y(t)
        - coefficients_z: Polynomial coefficients for z(t)
        - r_squared: R² goodness of fit (0-1)
        - predicted_positions: Fitted positions [[x,y,z], ...]

Example - Projectile motion:
    result = await fit_trajectory(
        times=[0, 1, 2, 3],
        positions=[[0,0,0], [10,15,0], [20,20,0], [30,15,0]],
        fit_type="quadratic"
    )
    # Fits x(t) = c0 + c1*t + c2*t²

Calculates velocity and acceleration from position data and extracts
the specified component for graphing.

Args:
    times: Time values in seconds (or JSON string)
    positions: Position vectors [[x,y,z], ...] in meters (or JSON string)
    component: Which component to analyze - "x", "y", "z", or "magnitude" (default)

Returns:
    Dict containing:
        - times: Time values
        - positions: Position values (selected component)
        - velocities: Velocity values (selected component)
        - accelerations: Acceleration values (selected component)
        - max_velocity: Maximum velocity magnitude
        - max_acceleration: Maximum acceleration magnitude
        - component: Which component was analyzed

Example:
    result = await generate_motion_graph(
        times=[0, 1, 2, 3],
        positions=[[0,0,0], [5,0,0], [20,0,0], [45,0,0]],
        component="x"
    )
    # Automatically calculates v and a

List all supported unit conversions.

Returns a dictionary mapping category names to lists of supported units.

Returns:
    Dictionary with supported unit categories:
    - velocity: Speed units
    - distance: Length units
    - mass: Weight units
    - force: Force units
    - energy: Energy units
    - power: Power units
    - temperature: Temperature scales
    - angle: Angular units
    - pressure: Pressure units
    - area: Area units
    - volume: Volume units

Example:
    >>> list_unit_conversions()
    {
        "velocity": ["m/s", "km/h", "mph", "ft/s", "knots"],
        "distance": ["m", "km", "mi", "ft", "yd", "in"],
        "mass": ["kg", "g", "lb", "oz"],
        ...
    }

Steps the simulation and records position/orientation/velocity at each
timestep for one body. Perfect for generating animation data for R3F.

Args:
    sim_id: Simulation ID
    body_id: ID of the body to track
    steps: Number of timesteps to record
    dt: Optional timestep override. If None, uses config default.

Returns:
    TrajectoryResponse containing:
        - body_id: Tracked body identifier
        - frames: List of trajectory frames with time, position, orientation, velocity
        - total_time: Total simulated time in seconds
        - num_frames: Number of frames recorded

Tips for LLMs:
    - Each frame has: time, position [x,y,z], orientation [x,y,z,w], velocity [x,y,z]
    - Frames are evenly spaced in time (every dt seconds)
    - Output is R3F-compatible: use position/orientation directly in Three.js
    - For 60 FPS video: record at dt=1/60 ≈ 0.0167
    - Typical recording: 100-1000 frames (1.6-16 seconds at 60 FPS)

Example:
    # Record 5 seconds of a falling ball
    traj = await record_trajectory(
        sim_id=sim_id,
        body_id="ball",
        steps=300  # 300 × 0.016 ≈ 5 seconds
    )
    # Use traj.frames in React Three Fiber for animation

This is an enhanced version of record_trajectory that analyzes the motion
and detects important events like bounces and collisions. Perfect for
answering questions like "how many times did the ball bounce?"

Args:
    sim_id: Simulation ID
    body_id: Body to track
    steps: Number of simulation steps to record
    dt: Optional custom timestep (overrides simulation default)
    detect_bounces: Whether to detect bounce events (default True)
    bounce_height_threshold: Maximum height to consider as "on ground" in meters (default 0.01)

Returns:
    TrajectoryWithEventsResponse containing:
        - frames: Trajectory frames (positions, velocities)
        - bounces: Detected bounce events with energy loss
        - contact_events: Contact/collision events (future)

Tips for LLMs:
    - Use this instead of record_trajectory when you need event detection
    - Bounces are detected from velocity reversals near the ground
    - Each bounce includes: time, position, speeds before/after, energy loss
    - Use `trajectory.bounces` to count or analyze bounces
    - Adjust bounce_height_threshold for different ground shapes

Example:
    # Record ball bouncing and count bounces
    traj = await record_trajectory_with_events(
        sim_id=sim_id,
        body_id="ball",
        steps=600,
        detect_bounces=True,
        bounce_height_threshold=0.01  # 1cm threshold
    )
    print(f"Detected {len(traj.bounces)} bounces")
    for bounce in traj.bounces:
        print(f"Bounce #{bounce.bounce_number} at t={bounce.time:.2f}s")

Uses numerical integration to simulate motion under:
- Gravity (downward)
- Buoyancy (upward, from displaced fluid)
- Drag (opposes motion)

Args:
    initial_velocity: Initial velocity [x, y, z] in m/s
    mass: Object mass in kg
    volume: Object volume in m³
    cross_sectional_area: Cross-sectional area in m²
    fluid_density: Fluid density in kg/m³ (default 1000 for water)
    fluid_viscosity: Fluid viscosity in Pa·s (default 1.002e-3 for water)
    initial_position: Initial position [x, y, z] in m (default [0,0,0])
    drag_coefficient: Drag coefficient (default 0.47 for sphere)
    gravity: Gravitational acceleration in m/s² (default 9.81)
    duration: Simulation duration in seconds (default 10.0)
    dt: Time step in seconds (default 0.01)

Returns:
    Complete trajectory, final state, max depth, and total distance

Example - Torpedo launch:
    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
    )

Advances the physics simulation by running the integrator for N steps.
Returns the complete state of all bodies after stepping.

Args:
    sim_id: Simulation ID
    steps: Number of timesteps to simulate. Default 1.
        Example: steps=600 with dt=0.016 = 9.6 seconds of simulation
    dt: Optional timestep override (seconds). If None, uses config default.

Returns:
    SimulationStepResponse containing:
        - sim_id: Simulation identifier
        - time: Current simulation time in seconds
        - bodies: List of all body states with positions, velocities, contacts

Tips for LLMs:
    - Each body state includes position, orientation (quaternion), velocities
    - contacts array shows active collisions with impulse magnitudes
    - For real-time preview: steps=1, call repeatedly
    - For final result: steps=1000+, call once
    - Large step counts may timeout - limit to ~10,000 steps per call

Example:
    # Simulate 10 seconds at 60 FPS
    result = await step_simulation(
        sim_id=sim_id,
        steps=600  # 600 steps × 0.016s = 9.6s
    )
    for body in result.bodies:
        print(f"{body.id}: position={body.position}")

Analyzes how energy changes over time in a recorded trajectory.
Useful for understanding damping, bounces, and energy loss mechanisms.

Args:
    trajectory_data: Trajectory data dict with 'frames' field
    mass: Object mass in kg
    gravity: Gravitational acceleration in m/s² (default 9.81)
    reference_height: Reference height for PE in meters (default 0.0)

Returns:
    Dict containing:
        - frames: Energy data for each frame (time, KE, PE, total E)
        - initial_total_energy: Initial total energy in Joules
        - final_total_energy: Final total energy in Joules
        - total_energy_loss: Total energy dissipated in Joules
        - total_energy_loss_percent: % of energy lost
        - average_power_dissipated: Average power in Watts (J/s)

Tips for LLMs:
    - Use after record_trajectory or record_trajectory_with_events
    - Visualize energy vs time to see where energy is lost
    - Identifies bounces, friction effects, air resistance
    - Power = rate of energy dissipation

Example - Bouncing ball energy analysis:
    traj = await record_trajectory_with_events(sim_id, "ball", 600)
    result = await track_energy_dissipation(
        trajectory_data=traj.model_dump(),
        mass=0.5,  # 500g ball
        gravity=9.81
    )
    # See how energy decreases with each bounce