calculate_jerk

Instructions

Jerk = da/dt is important for comfort in vehicles and mechanical design.

Args:
    times: Time values in seconds (or JSON string)
    accelerations: Acceleration vectors [[x,y,z], ...] in m/s² (or JSON string)

Returns:
    Dict containing:
        - jerks: Jerk vectors [[x,y,z], ...] in m/s³
        - average_jerk: Average jerk [x,y,z] in m/s³
        - max_jerk_magnitude: Maximum jerk magnitude in m/s³

Example:
    result = await calculate_jerk(
        times=[0, 1, 2, 3],
        accelerations=[[0,0,0], [2,0,0], [4,0,0], [6,0,0]]
    )
    # jerk_x ≈ 2 m/s³ (constant)

Implementation Reference

• src/chuk_mcp_physics/kinematics.py:296-324 (handler)

  Core handler function that calculates jerk (da/dt) from acceleration data. Uses _numerical_derivative for differentiation and _vector_magnitude for max jerk calculation. Returns JerkCalculationResponse with jerks, average_jerk, and max_jerk_magnitude.

  def calculate_jerk(request: JerkCalculationRequest) -> JerkCalculationResponse:
      """Calculate jerk (da/dt) from acceleration data.
  
      Jerk is the rate of change of acceleration.
  
      Args:
          request: Acceleration and time data
  
      Returns:
          Jerk values
      """
      if len(request.accelerations) != len(request.times):
          raise ValueError("Number of accelerations must equal number of times")
  
      if len(request.accelerations) < 2:
          raise ValueError("Need at least 2 data points for jerk calculation")
  
      # Calculate jerks
      jerks = _numerical_derivative(request.accelerations, request.times)
  
      # Calculate average and max
      avg_jerk = [sum(j[i] for j in jerks) / len(jerks) for i in range(3)]
      max_jerk = max(_vector_magnitude(j) for j in jerks)
  
      return JerkCalculationResponse(
          jerks=jerks,
          average_jerk=avg_jerk,
          max_jerk_magnitude=max_jerk,
      )

• src/chuk_mcp_physics/kinematics.py:44-51 (schema)

  JerkCalculationRequest schema: accepts accelerations (list of 3D vectors) and times (list of floats) as input fields.

  class JerkCalculationRequest(BaseModel):
      """Request for jerk (rate of change of acceleration) calculation."""
  
      accelerations: list[list[float]] = Field(
          ..., description="List of acceleration vectors [x, y, z] in m/s²"
      )
      times: list[float] = Field(..., description="Time values in seconds")

• src/chuk_mcp_physics/kinematics.py:53-58 (schema)

  JerkCalculationResponse schema: returns jerks (list of 3D vectors), average_jerk (3D vector), and max_jerk_magnitude (float).

  class JerkCalculationResponse(BaseModel):
      """Response for jerk calculation."""
  
      jerks: list[list[float]] = Field(..., description="Calculated jerk vectors [x, y, z] in m/s³")
      average_jerk: list[float] = Field(..., description="Average jerk [x, y, z] in m/s³")
      max_jerk_magnitude: float = Field(..., description="Maximum jerk magnitude in m/s³")

• src/chuk_mcp_physics/tools/kinematics_tools.py:54-93 (handler)

  MCP tool wrapper for calculate_jerk. Handles JSON string parsing, delegates to core function in kinematics.py. Decorated with @tool for MCP registration.

  @tool  # type: ignore[arg-type]
  async def calculate_jerk(
      times: Union[list[float], str],
      accelerations: Union[list[list[float]], str],
  ) -> dict:
      """Calculate jerk (rate of change of acceleration).
  
      Jerk = da/dt is important for comfort in vehicles and mechanical design.
  
      Args:
          times: Time values in seconds (or JSON string)
          accelerations: Acceleration vectors [[x,y,z], ...] in m/s² (or JSON string)
  
      Returns:
          Dict containing:
              - jerks: Jerk vectors [[x,y,z], ...] in m/s³
              - average_jerk: Average jerk [x,y,z] in m/s³
              - max_jerk_magnitude: Maximum jerk magnitude in m/s³
  
      Example:
          result = await calculate_jerk(
              times=[0, 1, 2, 3],
              accelerations=[[0,0,0], [2,0,0], [4,0,0], [6,0,0]]
          )
          # jerk_x ≈ 2 m/s³ (constant)
      """
      from ..kinematics import JerkCalculationRequest, calculate_jerk as calc_jerk
  
      # Parse inputs
      parsed_times = json.loads(times) if isinstance(times, str) else times
      parsed_accelerations = (
          json.loads(accelerations) if isinstance(accelerations, str) else accelerations
      )
  
      request = JerkCalculationRequest(
          times=parsed_times,
          accelerations=parsed_accelerations,
      )
      response = calc_jerk(request)
      return response.model_dump()

• src/chuk_mcp_physics/kinematics.py:155-178 (helper)

  _numerical_derivative helper: computes numerical derivatives using central differences (forward/backward at boundaries). Used by calculate_jerk to compute da/dt.

  def _numerical_derivative(values: list[list[float]], times: list[float]) -> list[list[float]]:
      """Calculate numerical derivative using central differences."""
      if len(values) < 2:
          return [[0.0] * len(values[0])]
  
      derivatives = []
  
      for i in range(len(values)):
          if i == 0:
              # Forward difference for first point
              dt = times[1] - times[0]
              deriv = [(values[1][j] - values[0][j]) / dt for j in range(len(values[0]))]
          elif i == len(values) - 1:
              # Backward difference for last point
              dt = times[-1] - times[-2]
              deriv = [(values[-1][j] - values[-2][j]) / dt for j in range(len(values[0]))]
          else:
              # Central difference for interior points
              dt = times[i + 1] - times[i - 1]
              deriv = [(values[i + 1][j] - values[i - 1][j]) / dt for j in range(len(values[0]))]
  
          derivatives.append(deriv)
  
      return derivatives