analyze_circular_orbit

Instructions

Comprehensive orbital analysis combining period, velocity, and acceleration.

Args:
    altitude: Altitude above surface in meters
    planet_mass: Planet mass in kg
    planet_radius: Planet radius in meters
    gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)

Returns:
    Dict containing:
        - orbital_radius: r from planet center in meters
        - orbital_velocity: v in m/s
        - period_seconds: Orbital period in seconds
        - period_minutes: Orbital period in minutes
        - centripetal_acceleration: a_c in m/s²

Example - LEO satellite at 400km altitude:
    result = await analyze_circular_orbit(
        altitude=400000,  # 400 km
        planet_mass=5.972e24,  # Earth
        planet_radius=6.371e6  # Earth
    )
    # v ≈ 7,670 m/s, T ≈ 92.6 min

Implementation Reference

• src/chuk_mcp_physics/circular_motion.py:196-231 (handler)

  Core calculation function for analyzing circular orbit. Takes CircularOrbitRequest, computes orbital radius (r = R + h), orbital velocity (v = sqrt(GM/r)), orbital period (T = 2π sqrt(r³/GM)), period in minutes, and centripetal acceleration (a_c = v²/r). Returns CircularOrbitResponse.

  def analyze_circular_orbit(request: CircularOrbitRequest) -> CircularOrbitResponse:
      """Analyze a circular orbit at given altitude.
  
      Combines multiple orbital calculations into a comprehensive analysis.
  
      Args:
          request: Circular orbit request
  
      Returns:
          Complete orbital analysis
      """
      h = request.altitude
      R = request.planet_radius
      M = request.planet_mass
      G = request.gravitational_constant
  
      # Orbital radius (from planet center)
      r = R + h
  
      # Orbital velocity: v = √(GM/r)
      v = math.sqrt((G * M) / r)
  
      # Period: T = 2π√(r³/GM)
      T = 2.0 * math.pi * math.sqrt((r * r * r) / (G * M))
      T_min = T / 60.0
  
      # Centripetal acceleration
      a_c = (v * v) / r
  
      return CircularOrbitResponse(
          orbital_radius=r,
          orbital_velocity=v,
          period_seconds=T,
          period_minutes=T_min,
          centripetal_acceleration=a_c,
      )

• src/chuk_mcp_physics/tools/circular_motion.py:190-232 (handler)

  MCP @tool decorated async wrapper for analyze_circular_orbit. Accepts altitude, planet_mass, planet_radius, gravitational_constant as parameters. Delegates to the core calculation function in circular_motion.py and returns model_dump dict.

  @tool  # type: ignore[arg-type]
  async def analyze_circular_orbit(
      altitude: float,
      planet_mass: float,
      planet_radius: float,
      gravitational_constant: float = 6.674e-11,
  ) -> dict:
      """Analyze circular orbit at given altitude above planet surface.
  
      Comprehensive orbital analysis combining period, velocity, and acceleration.
  
      Args:
          altitude: Altitude above surface in meters
          planet_mass: Planet mass in kg
          planet_radius: Planet radius in meters
          gravitational_constant: G in m³/(kg⋅s²) (default 6.674e-11)
  
      Returns:
          Dict containing:
              - orbital_radius: r from planet center in meters
              - orbital_velocity: v in m/s
              - period_seconds: Orbital period in seconds
              - period_minutes: Orbital period in minutes
              - centripetal_acceleration: a_c in m/s²
  
      Example - LEO satellite at 400km altitude:
          result = await analyze_circular_orbit(
              altitude=400000,  # 400 km
              planet_mass=5.972e24,  # Earth
              planet_radius=6.371e6  # Earth
          )
          # v ≈ 7,670 m/s, T ≈ 92.6 min
      """
      from ..circular_motion import CircularOrbitRequest, analyze_circular_orbit as analyze_orbit
  
      request = CircularOrbitRequest(
          altitude=altitude,
          planet_mass=planet_mass,
          planet_radius=planet_radius,
          gravitational_constant=gravitational_constant,
      )
      response = analyze_orbit(request)
      return response.model_dump()

• src/chuk_mcp_physics/circular_motion.py:82-91 (schema)

  CircularOrbitRequest Pydantic model with fields: altitude (meters, >= 0), planet_mass (kg, > 0), planet_radius (meters, > 0), gravitational_constant (default 6.674e-11).

  class CircularOrbitRequest(BaseModel):
      """Request for circular orbit analysis."""
  
      altitude: float = Field(..., description="Altitude above surface in meters", ge=0.0)
      planet_mass: float = Field(..., description="Planet mass in kg", gt=0.0)
      planet_radius: float = Field(..., description="Planet radius in meters", 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:93-102 (schema)

  CircularOrbitResponse Pydantic model with fields: orbital_radius (meters), orbital_velocity (m/s), period_seconds, period_minutes, centripetal_acceleration (m/s²).

  class CircularOrbitResponse(BaseModel):
      """Response for circular orbit analysis."""
  
      orbital_radius: float = Field(..., description="Orbital radius (from planet center) in meters")
      orbital_velocity: float = Field(..., description="Orbital velocity in m/s")
      period_seconds: float = Field(..., description="Orbital period in seconds")
      period_minutes: float = Field(..., description="Orbital period in minutes")
      centripetal_acceleration: float = Field(
          ..., description="Centripetal acceleration at this orbit in m/s²"
      )