calculate_spring_mass_period

Instructions

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

Implementation Reference

• src/chuk_mcp_physics/oscillations.py:131-147 (handler)

  Core calculation function: computes period T = 2π√(m/k), frequency f = 1/T, and angular frequency ω = √(k/m) for a spring-mass system.

  def calculate_spring_mass_period(request: SpringMassPeriodRequest) -> SpringMassPeriodResponse:
      """Calculate period of spring-mass system: T = 2π√(m/k).
  
      Args:
          request: Spring-mass period request
  
      Returns:
          Period, frequency, and angular frequency
      """
      m = request.mass
      k = request.spring_constant
  
      omega = math.sqrt(k / m)
      T = 2.0 * math.pi / omega
      f = 1.0 / T
  
      return SpringMassPeriodResponse(period=T, frequency=f, angular_frequency=omega)

• src/chuk_mcp_physics/oscillations.py:31-43 (schema)

  SpringMassPeriodRequest: Pydantic model for input validation (mass > 0, spring_constant > 0).

  class SpringMassPeriodRequest(BaseModel):
      """Request for spring-mass period calculation."""
  
      mass: float = Field(..., description="Mass in kg", gt=0.0)
      spring_constant: float = Field(..., description="Spring constant k in N/m", gt=0.0)
  
  
  class SpringMassPeriodResponse(BaseModel):
      """Response for spring-mass period calculation."""
  
      period: float = Field(..., description="Period T in seconds")
      frequency: float = Field(..., description="Frequency f in Hz")
      angular_frequency: float = Field(..., description="Angular frequency ω in rad/s")

• src/chuk_mcp_physics/oscillations.py:38-43 (schema)

  SpringMassPeriodResponse: Pydantic model defining output fields (period, frequency, angular_frequency).

  class SpringMassPeriodResponse(BaseModel):
      """Response for spring-mass period calculation."""
  
      period: float = Field(..., description="Period T in seconds")
      frequency: float = Field(..., description="Frequency f in Hz")
      angular_frequency: float = Field(..., description="Angular frequency ω in rad/s")

• src/chuk_mcp_physics/tools/oscillations.py:49-88 (registration)

  @tool-decorated async wrapper that registers 'calculate_spring_mass_period' as an MCP tool endpoint. Converts function params to request model, calls core calculation, returns dict.

  @tool  # type: ignore[arg-type]
  async def calculate_spring_mass_period(
      mass: float,
      spring_constant: float,
  ) -> dict:
      """Calculate period of spring-mass system: T = 2π√(m/k).
  
      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
      """
      from ..oscillations import SpringMassPeriodRequest, calculate_spring_mass_period as calc_period
  
      request = SpringMassPeriodRequest(
          mass=mass,
          spring_constant=spring_constant,
      )
      response = calc_period(request)
      return response.model_dump()

• src/chuk_mcp_physics/oscillations.py:6-44 (helper)

  Imports math and Pydantic BaseModel used by the spring-mass period calculation.

  import math
  from typing import Literal
  
  from pydantic import BaseModel, Field
  
  
  # ============================================================================
  # Request/Response Models
  # ============================================================================
  
  
  class HookesLawRequest(BaseModel):
      """Request for Hooke's Law calculation."""
  
      spring_constant: float = Field(..., description="Spring constant k in N/m", gt=0.0)
      displacement: float = Field(..., description="Displacement from equilibrium in meters")
  
  
  class HookesLawResponse(BaseModel):
      """Response for Hooke's Law calculation."""
  
      force: float = Field(..., description="Restoring force magnitude in Newtons")
      potential_energy: float = Field(..., description="Elastic potential energy in Joules")
  
  
  class SpringMassPeriodRequest(BaseModel):
      """Request for spring-mass period calculation."""
  
      mass: float = Field(..., description="Mass in kg", gt=0.0)
      spring_constant: float = Field(..., description="Spring constant k in N/m", gt=0.0)
  
  
  class SpringMassPeriodResponse(BaseModel):
      """Response for spring-mass period calculation."""
  
      period: float = Field(..., description="Period T in seconds")
      frequency: float = Field(..., description="Frequency f in Hz")
      angular_frequency: float = Field(..., description="Angular frequency ω in rad/s")