calculate_banking_angle

Instructions

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°

Implementation Reference

• src/chuk_mcp_physics/circular_motion.py:156-173 (handler)

  Core implementation of calculate_banking_angle. Computes the ideal banking angle using θ = arctan(v² / (r*g)). Returns both radians and degrees.

  def calculate_banking_angle(request: BankingAngleRequest) -> BankingAngleResponse:
      """Calculate ideal banking angle for a turn: θ = arctan(v² / (rg)).
  
      Args:
          request: Banking angle request
  
      Returns:
          Banking angle in radians and degrees
      """
      v = request.velocity
      r = request.radius
      g = request.gravity
  
      # θ = arctan(v² / (rg))
      theta_rad = math.atan((v * v) / (r * g))
      theta_deg = math.degrees(theta_rad)
  
      return BankingAngleResponse(angle_radians=theta_rad, angle_degrees=theta_deg)

• src/chuk_mcp_physics/circular_motion.py:50-55 (schema)

  BankingAngleRequest Pydantic model with velocity, radius, and gravity fields.

  class BankingAngleRequest(BaseModel):
      """Request for banking angle calculation."""
  
      velocity: float = Field(..., description="Velocity in m/s", gt=0.0)
      radius: float = Field(..., description="Radius of turn in meters", gt=0.0)
      gravity: float = Field(default=9.81, description="Gravitational acceleration in m/s²", gt=0.0)

• src/chuk_mcp_physics/circular_motion.py:58-62 (schema)

  BankingAngleResponse Pydantic model with angle_radians and angle_degrees fields.

  class BankingAngleResponse(BaseModel):
      """Response for banking angle calculation."""
  
      angle_radians: float = Field(..., description="Banking angle in radians")
      angle_degrees: float = Field(..., description="Banking angle in degrees")

• src/chuk_mcp_physics/tools/circular_motion.py:100-142 (handler)

  MCP tool-decorated async wrapper for calculate_banking_angle. Acts as the public endpoint, validates via BankingAngleRequest, delegates to core calculate_banking_angle, and returns dict.

  @tool  # type: ignore[arg-type]
  async def calculate_banking_angle(
      velocity: float,
      radius: float,
      gravity: float = 9.81,
  ) -> dict:
      """Calculate ideal banking angle: θ = arctan(v² / (rg)).
  
      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°
      """
      from ..circular_motion import BankingAngleRequest, calculate_banking_angle as calc_bank
  
      request = BankingAngleRequest(
          velocity=velocity,
          radius=radius,
          gravity=gravity,
      )
      response = calc_bank(request)
      return response.model_dump()

• src/chuk_mcp_physics/server.py:38-50 (registration)

  Registration: server.py imports tools.circular_motion module which triggers @tool decorator registration of the calculate_banking_angle endpoint.

  # Import all tools modules to register their @tool decorated functions
  from .tools import (
      basic,
      rotational,
      oscillations,
      circular_motion,
      collisions,
      conservation,
      fluid as fluid_tools,
      kinematics_tools,
      statics,
      convert_units as unit_conversion_tools,
  )