calculate_orbital_period

Instructions

Kepler's Third Law for circular orbits. Period depends on orbital
radius and central body mass.

Args:
    orbital_radius: Orbital radius in meters (from center of central body)
    central_mass: Mass of central body in kg
    gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)

Returns:
    Dict containing:
        - period: Orbital period in seconds
        - orbital_velocity: v in m/s
        - period_hours: Period in hours (for convenience)
        - period_days: Period in days (for convenience)

Tips for LLMs:
    - Higher orbit → longer period
    - More massive central body → shorter period
    - Earth: M = 5.972e24 kg, R = 6.371e6 m
    - Moon orbit: r ≈ 384,400 km, T ≈ 27.3 days
    - ISS orbit: r ≈ 6,771 km (altitude 400 km), T ≈ 90 minutes

Example - ISS orbit:
    result = await calculate_orbital_period(
        orbital_radius=6.771e6,  # meters
        central_mass=5.972e24  # Earth mass (kg)
    )
    # T ≈ 5,558 seconds ≈ 92.6 minutes

Implementation Reference

• src/chuk_mcp_physics/circular_motion.py:129-153 (handler)

  Core calculation function implementing Kepler's Third Law: T = 2π√(r³/GM). Computes orbital period, velocity, and convenience conversions to hours/days.

  def calculate_orbital_period(request: OrbitalPeriodRequest) -> OrbitalPeriodResponse:
      """Calculate orbital period using Kepler's Third Law: T = 2π√(r³/GM).
  
      Args:
          request: Orbital period request
  
      Returns:
          Orbital period and velocity
      """
      r = request.orbital_radius
      M = request.central_mass
      G = request.gravitational_constant
  
      # T = 2π√(r³/GM)
      T = 2.0 * math.pi * math.sqrt((r * r * r) / (G * M))
  
      # Orbital velocity: v = 2πr/T
      v = (2.0 * math.pi * r) / T
  
      T_hours = T / 3600.0
      T_days = T / 86400.0
  
      return OrbitalPeriodResponse(
          period=T, orbital_velocity=v, period_hours=T_hours, period_days=T_days
      )

• src/chuk_mcp_physics/tools/circular_motion.py:52-97 (handler)

  MCP tool endpoint decorated with @tool. Accepts orbital_radius, central_mass, and optional gravitational_constant. Delegates to core calculation function and returns dict.

  @tool  # type: ignore[arg-type]
  async def calculate_orbital_period(
      orbital_radius: float,
      central_mass: float,
      gravitational_constant: float = 6.674e-11,
  ) -> dict:
      """Calculate orbital period: T = 2π√(r³/GM).
  
      Kepler's Third Law for circular orbits. Period depends on orbital
      radius and central body mass.
  
      Args:
          orbital_radius: Orbital radius in meters (from center of central body)
          central_mass: Mass of central body in kg
          gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)
  
      Returns:
          Dict containing:
              - period: Orbital period in seconds
              - orbital_velocity: v in m/s
              - period_hours: Period in hours (for convenience)
              - period_days: Period in days (for convenience)
  
      Tips for LLMs:
          - Higher orbit → longer period
          - More massive central body → shorter period
          - Earth: M = 5.972e24 kg, R = 6.371e6 m
          - Moon orbit: r ≈ 384,400 km, T ≈ 27.3 days
          - ISS orbit: r ≈ 6,771 km (altitude 400 km), T ≈ 90 minutes
  
      Example - ISS orbit:
          result = await calculate_orbital_period(
              orbital_radius=6.771e6,  # meters
              central_mass=5.972e24  # Earth mass (kg)
          )
          # T ≈ 5,558 seconds ≈ 92.6 minutes
      """
      from ..circular_motion import OrbitalPeriodRequest, calculate_orbital_period as calc_orbit
  
      request = OrbitalPeriodRequest(
          orbital_radius=orbital_radius,
          central_mass=central_mass,
          gravitational_constant=gravitational_constant,
      )
      response = calc_orbit(request)
      return response.model_dump()

• src/chuk_mcp_physics/circular_motion.py:31-38 (schema)

  Pydantic request model with orbital_radius, central_mass (both > 0), and optional gravitational_constant (default 6.674e-11).

  class OrbitalPeriodRequest(BaseModel):
      """Request for orbital period calculation."""
  
      orbital_radius: float = Field(..., description="Orbital radius in meters", gt=0.0)
      central_mass: float = Field(..., description="Mass of central body in kg", gt=0.0)
      gravitational_constant: float = Field(
          default=6.674e-11, description="Gravitational constant G in m³/(kg⋅s²)"
      )

• src/chuk_mcp_physics/circular_motion.py:41-47 (schema)

  Pydantic response model with period (seconds), orbital_velocity, period_hours, and period_days.

  class OrbitalPeriodResponse(BaseModel):
      """Response for orbital period calculation."""
  
      period: float = Field(..., description="Orbital period in seconds")
      orbital_velocity: float = Field(..., description="Orbital velocity in m/s")
      period_hours: float = Field(..., description="Orbital period in hours (for convenience)")
      period_days: float = Field(..., description="Orbital period in days (for convenience)")

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

  Server imports the circular_motion tools module, which triggers registration of the @tool-decorated calculate_orbital_period function.

  # 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,
  )
  
  # Silence unused import warnings - these imports register @tool decorated functions
  _ = (
      basic,
      unit_conversion_tools,
      rotational,
      oscillations,
      circular_motion,
      collisions,
      conservation,