Back to Details

tune-mjcf

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MuJoCo MJCF Model Tuning

MuJoCo MJCF模型调优

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.
本技能提供结构化指南，指导你在保持仿真精度的同时优化MuJoCo MJCF模型文件以提升性能。核心挑战是在计算速度与数值正确性之间取得平衡，这需要系统性的分析而非反复试错式的参数调整。

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
始终将精度要求置于速度目标之上。一个速度快但结果错误的仿真是毫无价值的。在进行任何优化前：
  1. 明确具体的精度要求（容差阈值）
  2. 建立正确性验证的基准
  3. 每次修改参数后都测试精度
  4. 即使满足速度目标，也绝不要提交未通过精度测试的方案

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.
在修改任何参数前，先确定计算时间实际消耗在何处：
  1. 判断瓶颈是求解器迭代、接触求解、正向动力学还是插件计算
  2. 通过最小化参数变化来隔离影响性能的因素
  3. 利用初期结果了解哪些参数真正影响运行时间
关键见解：如果减少求解器迭代次数后精度完美但速度无提升，说明求解器迭代并非瓶颈，无需继续优化该参数。

Optimization Workflow

优化工作流

Step 1: Analyze the Reference Model

步骤1：分析参考模型

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)
全面检查MJCF文件，以了解：
  • 正在仿真的物理系统类型（机器人、线缆、软体等）
  • 使用的插件或扩展
  • 所有与性能相关参数的默认值
  • 模型的复杂度（刚体数量、接触点数量、约束数量）

Step 2: Establish Baselines

步骤2：建立基准

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
在进行任何优化前：
  1. 运行参考模型以建立时间基准
  2. 记录用于对比的具体精度指标
  3. 明确要对比的状态变量以及对应的容差

Step 3: Identify True Bottlenecks

步骤3：识别真正的瓶颈

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
独立测试每个潜在的优化类别，找出实际瓶颈：
求解器参数：
  • 在默认时间步长下测试
    iterations="1"
  • 如果精度完美但速度无提升，说明求解器迭代并非瓶颈
雅可比矩阵计算：
  • 测试
    jacobian="sparse"
    或
    jacobian="dense"
  • 如果精度完美但速度无提升，说明雅可比矩阵计算并非瓶颈
积分器：
  • 测试不同的积分器（Euler、RK4、implicit、implicitfast）
  • 注意：积分器的选择会同时影响精度和速度
时间步长：
  • 这通常是影响最大但也最危险的参数
  • 更大的时间步长意味着更快的仿真，但精度会下降
  • 这种关系通常是非线性的，且依赖于模型本身

Step 4: Apply Pattern Recognition

步骤4：应用模式识别

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
完成初始测试后，识别规律：
  • 即使时间步长仅增加1%就无法通过精度测试，说明模型对时间步长敏感
  • 如果修改求解器参数不影响速度，说明模型并非受求解器限制
  • 如果多种方法都失败，说明优化目标在数学上可能无法实现

Step 5: Know When to Stop

步骤5：知道何时停止

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
)

时间步长 (
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
影响： 对速度和精度都有高影响 风险： 高 - 会影响积分误差
指南：
  • 时间步长翻倍大约会使仿真时间减半，但积分误差会平方级增加
  • 以小增量进行测试（如1%、2%、5%）
  • 如果增加1%就无法通过精度测试，更大的增量肯定也会失败
  • 只有当你有证据表明解空间存在时，才适合使用二分查找

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
iterations
： 每步的最大求解器迭代次数 
tolerance
： 求解器的收敛容差 
ls_iterations
： 线搜索迭代次数
指南：
  • 只有当求解器实际运行到最大迭代次数时，减少迭代次数才有用
  • 先测试iterations=1以确定求解器是否为瓶颈
  • 修改容差通常对速度影响极小

Integrator (
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
选项：Euler、RK4、implicit、implicitfast
指南：
  • Euler速度最快但精度最低
  • RK4精度更高但速度更慢
  • implicit/implicitfast适用于刚性系统
  • 积分器的选择无法弥补时间步长离散化误差

Jacobian (
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
选项：dense、sparse、auto
指南：
  • 对于大型且接触点少的系统，sparse速度更快
  • 对于小型系统或接触点多的系统，dense速度更快
  • 在假设其有益前，先测试两种选项

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.
当证据表明某个参数无法实现目标时，仍反复尝试该参数的不同变体（如不同的时间步长值）。如果timestep=0.00202无法通过精度测试，timestep=0.003的结果会更差。

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.
每次测试都应验证一个假设。经过5-10次测试后，规律应该清晰：
  • 哪些参数真正影响速度
  • 哪些参数影响精度
  • 存在怎样的权衡关系
如果规律未显现，应退一步重新考虑方法。

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
  1. 运行优化后的模型至所需的仿真时长
  2. 将最终状态与参考状态对比
  3. 检查所有状态变量是否符合容差要求（不只是位置）
  4. 尽可能在多个时间点进行验证

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
  1. 测量挂钟时间，而非仿真时间
  2. 运行多次测试以消除方差影响
  3. 确保测量包含完整仿真过程，而非仅物理步进部分

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
开始
  |
  v
分析模型结构并识别潜在瓶颈
  |
  v
独立运行每个参数类别的基准测试
  |
  +---> 修改求解器参数能在保证精度的同时提升速度？
  |       是 --> 优化求解器参数
  |       否  --> 求解器并非瓶颈
  |
  +---> 增加时间步长能保持精度？
  |       是 --> 使用二分查找寻找最优时间步长
  |       即使仅增加1%也无法通过 --> 时间步长优化不可行
  |
  +---> 使用替代积分器有帮助？
  |       是 --> 使用更合适的积分器
  |       否  --> 模型需要当前积分器
  |
  v
如果未找到可行的优化路径：
  --> 报告无法实现目标
  --> 不要提交失败的配置

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
有效的MJCF调优需要：
  1. 先分析 - 了解时间消耗在何处
  2. 系统性测试 - 隔离每个参数的影响
  3. 从失败中学习 - 利用负面结果缩小搜索范围
  4. 优先考虑正确性 - 绝不为了速度牺牲精度
  5. 知道何时停止 - 识别数学上无法实现的目标