calculate_inelastic_collision_3d

Instructions

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

Implementation Reference

• src/chuk_mcp_physics/tools/collisions.py:9-79 (handler)

  MCP tool handler: async function decorated with @tool that parses inputs (velocity as list or JSON string), creates an InelasticCollision3DRequest, delegates to the core calculate_inelastic_collision_3d, and returns the response as a dict.

  @tool  # type: ignore[arg-type]
  async def calculate_inelastic_collision_3d(
      mass1: float,
      velocity1: Union[list[float], str],
      mass2: float,
      velocity2: Union[list[float], str],
      coefficient_of_restitution: float = 0.0,
  ) -> dict:
      """Calculate 3D collision with coefficient of restitution.
  
      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
      """
      # Parse inputs
      parsed_v1 = json.loads(velocity1) if isinstance(velocity1, str) else velocity1
      parsed_v2 = json.loads(velocity2) if isinstance(velocity2, str) else velocity2
  
      from ..collisions import (
          InelasticCollision3DRequest,
          calculate_inelastic_collision_3d as calc_coll,
      )
  
      request = InelasticCollision3DRequest(
          mass1=mass1,
          velocity1=parsed_v1,
          mass2=mass2,
          velocity2=parsed_v2,
          coefficient_of_restitution=coefficient_of_restitution,
      )
      response = calc_coll(request)
      return response.model_dump()

• src/chuk_mcp_physics/tools/collisions.py:9-9 (registration)

  The @tool decorator registers calculate_inelastic_collision_3d as an MCP tool in the server.

  @tool  # type: ignore[arg-type]