tune-mjcf

name	tune-mjcf
description	Guidance for optimizing MuJoCo MJCF model files for simulation performance while maintaining numerical accuracy. This skill should be used when tuning physics simulation parameters, optimizing MuJoCo XML configurations, or balancing speed vs accuracy tradeoffs in robotics simulations.

MuJoCo MJCF Model Tuning

Overview

This skill provides structured guidance for optimizing MuJoCo MJCF model files to achieve performance improvements while preserving simulation accuracy. The core challenge is balancing computational speed against numerical correctness, which requires systematic analysis rather than trial-and-error parameter tweaking.

Critical Principles

Correctness Before Speed

Always prioritize accuracy requirements over speed targets. A fast but incorrect simulation is worthless. Before any optimization:

1. Understand the exact accuracy requirements (tolerance thresholds)
2. Establish a baseline for correctness verification
3. Test accuracy AFTER every parameter change
4. Never submit a solution that fails accuracy tests, even if it meets speed targets

Systematic Profiling First

Before modifying any parameters, identify WHERE computational time is actually spent:

1. Determine if the bottleneck is solver iterations, contact resolution, forward dynamics, or plugin computation
2. Test with minimal parameter changes to isolate performance factors
3. Use early results to understand which parameters actually affect runtime

Key insight: If reducing solver iterations produces perfect accuracy but no speedup, solver iterations are NOT the bottleneck. Do not continue optimizing that parameter.

Optimization Workflow

Step 1: Analyze the Reference Model

Thoroughly examine the MJCF file to understand:

• What physical systems are being simulated (robots, cables, soft bodies, etc.)
• What plugins or extensions are in use
• Default values for all performance-relevant parameters
• The complexity of the model (number of bodies, contacts, constraints)

Step 2: Establish Baselines

Before any optimization:

1. Run the reference model to establish baseline timing
2. Document the exact accuracy metric being used for comparison
3. Understand what state variables are being compared and at what tolerance

Step 3: Identify True Bottlenecks

Test each potential optimization category independently to find actual bottlenecks:

Solver Parameters:

• Test iterations="1" with default timestep
• If accuracy is perfect but no speedup occurs, solver iterations are not the bottleneck

Jacobian Computation:

• Test jacobian="sparse" or jacobian="dense"
• If accuracy is perfect but no speedup occurs, Jacobian computation is not the bottleneck

Integration:

• Test different integrators (Euler, RK4, implicit, implicitfast)
• Note: Integrator choice affects BOTH accuracy and speed

Timestep:

• This is often the most impactful but also most dangerous parameter
• Larger timesteps = faster simulation but reduced accuracy
• The relationship is often non-linear and model-dependent

Step 4: Apply Pattern Recognition

After initial tests, recognize patterns:

• If even tiny timestep increases (1%) fail accuracy tests, the model is timestep-sensitive
• If solver changes don't affect speed, the model is not solver-bound
• If multiple approaches fail, the optimization target may be mathematically impossible

Step 5: Know When to Stop

Recognize when optimization is not viable:

• If your evidence shows that achieving the speed target requires accuracy compromises beyond tolerance, stop
• Do not submit a known-failing configuration
• Report that the optimization target cannot be met under the given constraints

Parameter Categories

Timestep (timestep)

Impact: High on both speed and accuracy Risk: High - affects integration error

Guidelines:

• Doubling timestep roughly halves simulation time but squares integration error
• Test in small increments (e.g., 1%, 2%, 5%)
• If 1% increase fails accuracy, larger increases will definitely fail
• Binary search is appropriate only if you have evidence the solution space exists

Solver Settings

iterations: Maximum solver iterations per step tolerance: Convergence tolerance for solver ls_iterations: Line search iterations

Guidelines:

• Reducing iterations helps only if solver is actually iterating to maximum
• Test with iterations=1 first to determine if solver is the bottleneck
• Tolerance changes often have minimal speed impact

Integrator (integrator)

Options: Euler, RK4, implicit, implicitfast

Guidelines:

• Euler is fastest but least accurate
• RK4 is more accurate but slower
• implicit/implicitfast are for stiff systems
• Integrator choice cannot compensate for timestep discretization error

Jacobian (jacobian)

Options: dense, sparse, auto

Guidelines:

• sparse is faster for large systems with few contacts
• dense is faster for small systems or many contacts
• Test both before assuming benefit

Common Pitfalls

Fixation on Single Parameter

Repeatedly trying variations of the same parameter (e.g., different timestep values) when evidence shows that parameter cannot achieve the goal. If timestep=0.00202 fails accuracy, timestep=0.003 will fail worse.

Conflating Solver and Integration Accuracy

Solver accuracy (iterations, tolerance) affects constraint satisfaction. Integration accuracy (timestep, integrator) affects state trajectory. These are mathematically independent - better solver settings cannot compensate for timestep discretization error.

Ignoring Negative Results

When a test shows "no speedup" or "accuracy failure," this is valuable information. Use it to prune the search space rather than trying minor variations of the same approach.

Missing Model-Specific Properties

Some models have special characteristics:

• Plugin computations (cables, soft bodies) may dominate runtime
• Contact-heavy simulations may be solver-bound
• High-frequency dynamics require small timesteps regardless of other settings

Investigate these properties before assuming generic optimizations will work.

Trial-and-Error Without Learning

Each test should inform a hypothesis. After 5-10 tests, patterns should be clear:

• What parameters actually affect speed
• What parameters affect accuracy
• What tradeoff relationships exist

If patterns are not emerging, step back and reconsider the approach.

Verification Strategy

Accuracy Verification

1. Run optimized model for the required simulation duration
2. Compare final state against reference state
3. Check ALL state variables against tolerance (not just position)
4. Verify at multiple time points if possible

Speed Verification

1. Measure wall-clock time, not simulation time
2. Run multiple trials to account for variance
3. Ensure measurement includes full simulation, not just physics stepping

Combined Verification

Always verify BOTH accuracy AND speed before considering a solution complete. Meeting one requirement while failing the other is a failed solution.

Decision Tree

START
  |
  v
Analyze model structure and identify potential bottlenecks
  |
  v
Run baseline tests for each parameter category independently
  |
  +---> Solver changes give speedup with good accuracy?
  |       YES --> Optimize solver parameters
  |       NO  --> Solver is not the bottleneck
  |
  +---> Timestep increases maintain accuracy?
  |       YES --> Binary search for optimal timestep
  |       NO at even 1% increase --> Timestep optimization not viable
  |
  +---> Alternative integrators help?
  |       YES --> Use better integrator
  |       NO  --> Model requires current integrator
  |
  v
If no viable optimization path found:
  --> Report that target cannot be achieved
  --> Do NOT submit a failing configuration

Summary

Effective MJCF tuning requires:

1. Profile first - understand where time is spent
2. Test systematically - isolate each parameter's effect
3. Learn from failures - use negative results to prune search space
4. Prioritize correctness - never sacrifice accuracy for speed
5. Know when to stop - recognize mathematically impossible targets