calculate_damped_oscillation
Compute position and velocity of a damped harmonic oscillator at a given time, and classify the damping regime as underdamped, critically damped, or overdamped.
Instructions
Calculate damped oscillation with friction/resistance.
Real oscillators lose energy over time due to damping (air resistance,
friction). Three regimes: underdamped, critically damped, overdamped.
Args:
mass: Mass in kg
spring_constant: k in N/m
damping_coefficient: b in kg/s (damping strength)
time: Time t in seconds
initial_position: Initial position in meters (default 1.0)
initial_velocity: Initial velocity in m/s (default 0.0)
Returns:
Dict containing:
- position: x(t) in meters
- velocity: v(t) in m/s
- damping_ratio: ζ (zeta) = b/(2√(mk))
- regime: "underdamped", "critically_damped", or "overdamped"
Damping regimes:
- ζ < 1: Underdamped (oscillates, gradually decays)
- ζ = 1: Critically damped (returns fastest without oscillating)
- ζ > 1: Overdamped (slow return, no oscillation)
Example - Car suspension:
result = await calculate_damped_oscillation(
mass=300, # kg (quarter car mass)
spring_constant=20000, # N/m
damping_coefficient=2000, # kg/s
time=1.0
)
# Should be slightly underdamped for comfort
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | ||
| spring_constant | Yes | ||
| damping_coefficient | Yes | ||
| time | Yes | ||
| initial_position | No | ||
| initial_velocity | No |
Implementation Reference
- MCP tool wrapper for calculate_damped_oscillation. Decorated with @tool, accepts individual float arguments, constructs a DampedOscillationRequest, calls the core function, and returns the response dict.
@tool # type: ignore[arg-type] async def calculate_damped_oscillation( mass: float, spring_constant: float, damping_coefficient: float, time: float, initial_position: float = 1.0, initial_velocity: float = 0.0, ) -> dict: """Calculate damped oscillation with friction/resistance. Real oscillators lose energy over time due to damping (air resistance, friction). Three regimes: underdamped, critically damped, overdamped. Args: mass: Mass in kg spring_constant: k in N/m damping_coefficient: b in kg/s (damping strength) time: Time t in seconds initial_position: Initial position in meters (default 1.0) initial_velocity: Initial velocity in m/s (default 0.0) Returns: Dict containing: - position: x(t) in meters - velocity: v(t) in m/s - damping_ratio: ζ (zeta) = b/(2√(mk)) - regime: "underdamped", "critically_damped", or "overdamped" Damping regimes: - ζ < 1: Underdamped (oscillates, gradually decays) - ζ = 1: Critically damped (returns fastest without oscillating) - ζ > 1: Overdamped (slow return, no oscillation) Example - Car suspension: result = await calculate_damped_oscillation( mass=300, # kg (quarter car mass) spring_constant=20000, # N/m damping_coefficient=2000, # kg/s time=1.0 ) # Should be slightly underdamped for comfort """ from ..oscillations import DampedOscillationRequest, calculate_damped_oscillation as calc_damped request = DampedOscillationRequest( mass=mass, spring_constant=spring_constant, damping_coefficient=damping_coefficient, initial_position=initial_position, initial_velocity=initial_velocity, time=time, ) response = calc_damped(request) return response.model_dump() - src/chuk_mcp_physics/tools/oscillations.py:142-142 (registration)Registration of the damped oscillation tool via the @tool decorator (from chuk_mcp_server).
@tool # type: ignore[arg-type]