calculate_angular_momentum

Instructions

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)

Implementation Reference

• src/chuk_mcp_physics/rotational.py:199-217 (handler)

  Core calculation function for angular momentum. Computes L = I * ω (scalar multiplication of moment of inertia with each component of angular velocity vector), then calculates the magnitude. Returns AngularMomentumResponse with the L vector and magnitude.

  def calculate_angular_momentum(request: AngularMomentumRequest) -> AngularMomentumResponse:
      """Calculate angular momentum: L = I × ω.
  
      For simplicity, assumes angular velocity is about a principal axis.
  
      Args:
          request: Angular momentum request
  
      Returns:
          Angular momentum vector and magnitude
      """
      inertia = request.moment_of_inertia
      omega = request.angular_velocity
  
      # L = I * ω (scalar multiplication for simple case)
      L = [inertia * w for w in omega]
      magnitude = math.sqrt(sum(L_component * L_component for L_component in L))
  
      return AngularMomentumResponse(angular_momentum=L, magnitude=magnitude)

• src/chuk_mcp_physics/rotational.py:58-71 (schema)

  AngularMomentumRequest and AngularMomentumResponse Pydantic models. Request has moment_of_inertia (float > 0) and angular_velocity (list of 3 floats). Response has angular_momentum (list of 3 floats) and magnitude (float).

  class AngularMomentumRequest(BaseModel):
      """Request for angular momentum calculation."""
  
      moment_of_inertia: float = Field(..., description="Moment of inertia in kg⋅m²", gt=0.0)
      angular_velocity: list[float] = Field(..., description="Angular velocity [x, y, z] in rad/s")
  
  
  class AngularMomentumResponse(BaseModel):
      """Response for angular momentum calculation."""
  
      angular_momentum: list[float] = Field(
          ..., description="Angular momentum vector [x, y, z] in kg⋅m²/s"
      )
      magnitude: float = Field(..., description="Angular momentum magnitude in kg⋅m²/s")

• src/chuk_mcp_physics/tools/rotational.py:126-171 (handler)

  MCP tool endpoint for calculate_angular_momentum. Decorated with @tool, takes moment_of_inertia and angular_velocity components as individual float arguments, constructs an AngularMomentumRequest, delegates to the core calculation function, and returns the response dict.

  @tool  # type: ignore[arg-type]
  async def calculate_angular_momentum(
      moment_of_inertia: float,
      angular_velocity_x: float,
      angular_velocity_y: float,
      angular_velocity_z: float,
  ) -> dict:
      """Calculate angular momentum: L = I × ω.
  
      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)
      """
      from ..rotational import AngularMomentumRequest, calculate_angular_momentum as calc_L
  
      request = AngularMomentumRequest(
          moment_of_inertia=moment_of_inertia,
          angular_velocity=[angular_velocity_x, angular_velocity_y, angular_velocity_z],
      )
      response = calc_L(request)
      return response.model_dump()

• examples/11_rotational_dynamics.py:15-21 (registration)

  Import of calculate_angular_momentum from chuk_mcp_physics.tools.rotational in the example usage file.

  from chuk_mcp_physics.tools.rotational import (
      calculate_torque,
      calculate_moment_of_inertia,
      calculate_angular_momentum,
      calculate_rotational_kinetic_energy,
      calculate_angular_acceleration,
  )

• tests/test_rotational.py:158-169 (helper)

  Unit test for the core calculate_angular_momentum function. Tests with I=3.0, ω=[0,5,0] verifying L_y=15.0 and magnitude=15.0.

  class TestAngularMomentum:
      def test_simple_angular_momentum(self):
          """Test angular momentum calculation."""
          request = AngularMomentumRequest(
              moment_of_inertia=3.0,
              angular_velocity=[0.0, 5.0, 0.0],
          )
          result = calculate_angular_momentum(request)
  
          # L = I * ω
          assert abs(result.angular_momentum[1] - 15.0) < 0.01
          assert abs(result.magnitude - 15.0) < 0.01