calculate_hookes_law

Instructions

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

Implementation Reference

• src/chuk_mcp_physics/oscillations.py:113-128 (handler)

  Core calculation function that implements Hooke's Law F = |kx| and potential energy PE = 0.5*k*x^2. Takes a HookesLawRequest pydantic model and returns a HookesLawResponse.

  def calculate_hookes_law(request: HookesLawRequest) -> HookesLawResponse:
      """Calculate spring force using Hooke's Law: F = -kx.
  
      Args:
          request: Hooke's Law request
  
      Returns:
          Restoring force and potential energy
      """
      k = request.spring_constant
      x = request.displacement
  
      force = k * abs(x)  # Magnitude only
      potential_energy = 0.5 * k * x * x
  
      return HookesLawResponse(force=force, potential_energy=potential_energy)

• src/chuk_mcp_physics/tools/oscillations.py:8-46 (handler)

  MCP tool wrapper for calculate_hookes_law. Decorated with @tool, accepts spring_constant and displacement as float parameters, delegates to the core calculation function via the 'from ..oscillations import' path.

  @tool  # type: ignore[arg-type]
  async def calculate_hookes_law(
      spring_constant: float,
      displacement: float,
  ) -> dict:
      """Calculate spring force using Hooke's Law: F = -kx.
  
      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
      """
      from ..oscillations import HookesLawRequest, calculate_hookes_law as calc_hookes
  
      request = HookesLawRequest(
          spring_constant=spring_constant,
          displacement=displacement,
      )
      response = calc_hookes(request)
      return response.model_dump()

• src/chuk_mcp_physics/oscillations.py:17-21 (schema)

  HookesLawRequest pydantic model with spring_constant (gt=0.0) and displacement float fields for input validation.

  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")

• src/chuk_mcp_physics/oscillations.py:24-28 (schema)

  HookesLawResponse pydantic model with force and potential_energy float fields for the output.

  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")