track_energy_dissipation
Analyze energy changes over a recorded trajectory to quantify energy loss from damping, bounces, friction, and air resistance, returning kinetic, potential, and total energy per frame along with total dissipation and average power.
Instructions
Track energy dissipation over a trajectory.
Analyzes how energy changes over time in a recorded trajectory.
Useful for understanding damping, bounces, and energy loss mechanisms.
Args:
trajectory_data: Trajectory data dict with 'frames' field
mass: Object mass in kg
gravity: Gravitational acceleration in m/s² (default 9.81)
reference_height: Reference height for PE in meters (default 0.0)
Returns:
Dict containing:
- frames: Energy data for each frame (time, KE, PE, total E)
- initial_total_energy: Initial total energy in Joules
- final_total_energy: Final total energy in Joules
- total_energy_loss: Total energy dissipated in Joules
- total_energy_loss_percent: % of energy lost
- average_power_dissipated: Average power in Watts (J/s)
Tips for LLMs:
- Use after record_trajectory or record_trajectory_with_events
- Visualize energy vs time to see where energy is lost
- Identifies bounces, friction effects, air resistance
- Power = rate of energy dissipation
Example - Bouncing ball energy analysis:
traj = await record_trajectory_with_events(sim_id, "ball", 600)
result = await track_energy_dissipation(
trajectory_data=traj.model_dump(),
mass=0.5, # 500g ball
gravity=9.81
)
# See how energy decreases with each bounce
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| trajectory_data | Yes | ||
| mass | Yes | ||
| gravity | No | ||
| reference_height | No |
Implementation Reference
- MCP tool entry point decorated with @tool. Takes trajectory_data (dict), mass, gravity, reference_height, converts frames to TrajectoryFrame models, delegates to conservation.track_energy_dissipation, and returns dict.
@tool # type: ignore[arg-type] async def track_energy_dissipation( trajectory_data: dict, mass: float, gravity: float = 9.81, reference_height: float = 0.0, ) -> dict: """Track energy dissipation over a trajectory. Analyzes how energy changes over time in a recorded trajectory. Useful for understanding damping, bounces, and energy loss mechanisms. Args: trajectory_data: Trajectory data dict with 'frames' field mass: Object mass in kg gravity: Gravitational acceleration in m/s² (default 9.81) reference_height: Reference height for PE in meters (default 0.0) Returns: Dict containing: - frames: Energy data for each frame (time, KE, PE, total E) - initial_total_energy: Initial total energy in Joules - final_total_energy: Final total energy in Joules - total_energy_loss: Total energy dissipated in Joules - total_energy_loss_percent: % of energy lost - average_power_dissipated: Average power in Watts (J/s) Tips for LLMs: - Use after record_trajectory or record_trajectory_with_events - Visualize energy vs time to see where energy is lost - Identifies bounces, friction effects, air resistance - Power = rate of energy dissipation Example - Bouncing ball energy analysis: traj = await record_trajectory_with_events(sim_id, "ball", 600) result = await track_energy_dissipation( trajectory_data=traj.model_dump(), mass=0.5, # 500g ball gravity=9.81 ) # See how energy decreases with each bounce """ from ..conservation import EnergyDissipationTrackingRequest, track_energy_dissipation as track_E from ..models import TrajectoryFrame # Extract frames from trajectory data frames_data = trajectory_data.get("frames", []) frames = [TrajectoryFrame.model_validate(f) for f in frames_data] request = EnergyDissipationTrackingRequest( frames=frames, mass=mass, gravity=gravity, reference_height=reference_height, ) response = track_E(request) return response.model_dump()