常见问题#

导入失败或安装到了错误环境#

检查执行解释器与包位置：

python -c "import sys; print(sys.executable)"
python -m pip show torch evox evomo

用同一个解释器执行安装、示例和测试。源码仓库采用 src/ 布局，在根目录执行 python -m pip install -e . 后再运行示例，避免临时修改 sys.path。

CUDA 不可用或设备不一致#

torch.cuda.is_available() 为假时，先确认 PyTorch 构建和驱动，再按官方安装说明处理。计算报设备不一致时，核对边界、问题内常量、算法状态、输入与参考前沿的 .device。应在构造问题与算法之前设置默认设备。 MoRobtrol 还需要通过 jax.devices() 检查模拟器设备。

目标形状错误#

核对 n_objs 与 fitness.shape[1]，以及输入候选解的列数与问题的决策维度。使用参考向量的算法可能调整实际种群数，不要将请求的 pop_size 当成固定输出行数。

约束问题返回 tuple 导致错误#

使用 UnifiedWorkflow，并选择支持违反量选择的算法。不要通过只取 evaluate(...)[0] 来绕过错误，这会改变问题语义。检查约束优化中的完整示例。

目标出现 NaN 或 Inf#

检查问题的输入边界、除零、归一化分母、非法数学定义域和状态更新。参考向量选择可能以 NaN 表示无候选解关联的槽位；不能仅凭张量行数计算有效解数量。结果分析时配对过滤种群与目标的非有限行，但过滤不是修复评估错误的方法。所有行都无效时应停止指标计算并排查来源。

编译慢、报错或重新编译#

先运行 eager 版本，区分算法错误与编译器或工具链错误。确认 init_step() 在编译前已经执行，迭代期间输入形状与返回结构保持稳定。首次调用慢通常包含编译成本；不要将其纳入稳态步时对比。出现工具链、系统或算子支持问题时记录完整异常与版本，必要时用 eager 方式继续验证算法。

指标异常或与他人结果不同#

检查输入是否是目标值，GD/IGD 的输入是否非空，约束问题是否只用了可行解。再检查目标方向、归一化方式、参考前沿采样、HV 参考点、采样数与随机种子。当前 gd 使用固定范数除以点数的定义；不要与采用不同归一化定义的结果直接比较。

显存不足#

检查非支配排序的两两比较、GD/IGD 距离矩阵、HV 采样比较，以及监视器的完整历史。减少种群、参考点或 HV 样本数，按需关闭历史记录，并记录这些调整对评估预算和指标精度的影响。

Windows 路径过长#

编译或依赖缓存报路径相关 FileNotFoundError 时，检查实际缺失路径。如果确认涉及系统路径长度限制，可以使用较短的仓库/缓存路径或启用系统长路径支持。其他文件缺失错误仍需按其实际路径诊断。

提交问题反馈#

附上最小复现代码、实际导入路径、Python/PyTorch/EvoX 版本、设备、dtype、种群与目标数，以及完整异常。分别说明 eager 与 compiled 的运行情况。向 EvoMO Issues 提交可复现反馈。