my/ABLATION_STUDY_GUIDE.md

🧪 Auxiliary Metrics Ablation Study Guide

实验设计：2x2 因子实验

完整实验矩阵

实验组	Vision	Auxiliary	脚本文件	目的
Baseline	❌	❌	run_circle_packing_WITHOUT_vision.py	基准线
Aux Only	❌	✅	run_circle_packing_WITHOUT_vision_WITH_auxiliary.py	关键对比
Vision Only	✅	❌	run_circle_packing_WITH_vision.py	Vision效果
Both	✅	✅	(待创建)	最优组合

---

🎯 关键对比：Baseline vs Aux Only

这是最重要的对比，因为它是纯净的ablation：

Baseline:  NO vision + NO auxiliary
Aux Only:  NO vision + WITH auxiliary

唯一差异：auxiliary metrics

如果Aux Only > Baseline，则证明auxiliary metrics有效！

---

📊 实验配置对比

相同部分（确保公平对比）

# 两个实验完全相同：
num_generations = 200
max_parallel_jobs = 4
num_islands = 2
archive_size = 40
llm_models = ["native-gemini-2.5-flash", "native-gemini-2.5-pro"]
temperatures = [0.5, 0.7, 1.0]
# ... 所有其他超参数

不同部分（唯一变量）

Baseline (WITHOUT auxiliary)

job_config = LocalJobConfig(
    eval_program_path="examples/circle_packing/evaluate.py"  # Ground truth only
)

# LLM看到：
Combined score: 2.456
centers_str: (0.123, 0.456), ...

Aux Only (WITH auxiliary)

job_config = LocalJobConfig(
    eval_program_path="examples/circle_packing/evaluate_with_auxiliary.py"  # + Auxiliary
)

# LLM看到：
Combined score: 2.456
aux_spatial_uniformity: 0.752
aux_edge_utilization: 0.681
aux_density_variance: 0.694
aux_packing_efficiency: 0.734
aux_gap_analysis: 0.812
aux_geometric_quality: 0.778

💡 Recommendations:
  1. Only 3/4 corners utilized. Place larger circles at unused corners.
  2. Detected 18.8% unused space. Consider increasing radii in sparse regions.

---

🚀 运行实验

Step 1: 运行Baseline（如果还没有）

cd /home/tengxiao/pj/ShinkaEvolve
source .venv/bin/activate

# 运行baseline
python my/run_circle_packing_WITHOUT_vision.py

预期时间：根据你的设置，可能需要几小时到几天

Step 2: 运行Aux Only

# 运行auxiliary metrics版本
python my/run_circle_packing_WITHOUT_vision_WITH_auxiliary.py

预期时间：与baseline相同（auxiliary计算很快）

Step 3: 对比结果

# 查看两个实验的结果
ls -lh examples/circle_packing/results/

---

📈 评估指标

主要指标

1. 最终最佳分数

   # Baseline
   cat examples/circle_packing/results/results_circle_packing_WITHOUT_vision_*/best/results/metrics.json | grep combined_score
   
   # Aux Only
   cat examples/circle_packing/results/results_circle_packing_NO_vision_WITH_aux_*/best/results/metrics.json | grep combined_score
   

2. 收敛速度

   • 查看每个generation的best score
   • 绘制学习曲线
   • 看哪个更快达到高分

3. 最终排名

   # 从数据库查询最佳程序
   from shinka.database import ProgramDatabase
   
   db_baseline = ProgramDatabase(config=..., db_path="baseline.sqlite")
   db_aux = ProgramDatabase(config=..., db_path="aux.sqlite")
   
   best_baseline = db_baseline.get_top_programs(n=1)[0]
   best_aux = db_aux.get_top_programs(n=1)[0]
   
   print(f"Baseline best: {best_baseline.combined_score:.4f}")
   print(f"Aux best: {best_aux.combined_score:.4f}")
   print(f"Improvement: {(best_aux.combined_score - best_baseline.combined_score):.4f}")
   

次要指标

1. 多样性

   • Archive中程序的多样性
   • 是否探索了更多不同的策略

2. 稳定性

   • 分数的方差
   • 是否更稳定地进步

3. 辅助指标的相关性（仅Aux Only）

   # 分析auxiliary metrics与primary score的相关性
   import pandas as pd
   import matplotlib.pyplot as plt
   
   # 读取所有generation的metrics
   # 绘制scatter plots
   # 看哪些auxiliary metrics最有预测性
   

---

📊 预期结果

如果Auxiliary Metrics有效

预期观察：

Baseline:  最佳分数 = 2.45
Aux Only:  最佳分数 = 2.55  ✅ 提升 ~4%

收敛曲线：
  Baseline:  较慢，plateau更早
  Aux Only:  较快，持续改进

LLM行为：
  Baseline:  随机探索，缺乏方向
  Aux Only:  针对性改进（如"improve edge_utilization"）

如果效果不明显

可能原因：

1. Auxiliary metrics与primary score不相关
2. LLM没有有效利用auxiliary信息
3. 需要调整metric权重或feedback格式

下一步：

• 分析哪些auxiliary metrics最有用
• 调整text feedback的表述
• 考虑更强的auxiliary signal

---

🔍 详细分析脚本

比较最佳解决方案

import json
from pathlib import Path

# 读取两个实验的最佳结果
baseline_metrics = json.load(open("results_baseline/best/results/metrics.json"))
aux_metrics = json.load(open("results_aux/best/results/metrics.json"))

print("=" * 60)
print("COMPARISON: Baseline vs Aux Only")
print("=" * 60)

print(f"\nPrimary Score:")
print(f"  Baseline: {baseline_metrics['combined_score']:.4f}")
print(f"  Aux Only: {aux_metrics['combined_score']:.4f}")
print(f"  Δ: {aux_metrics['combined_score'] - baseline_metrics['combined_score']:.4f}")

if 'public' in aux_metrics:
    print(f"\nAuxiliary Metrics (Aux Only):")
    for key, value in aux_metrics['public'].items():
        if key.startswith('aux_'):
            print(f"  {key}: {value:.3f}" if isinstance(value, float) else f"  {key}: {value}")

绘制学习曲线

import matplotlib.pyplot as plt
import sqlite3

def get_best_scores_per_gen(db_path):
    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()
    
    cursor.execute("""
        SELECT generation, MAX(combined_score) as best_score
        FROM programs
        WHERE correct = 1
        GROUP BY generation
        ORDER BY generation
    """)
    
    data = cursor.fetchall()
    conn.close()
    
    return [row[0] for row in data], [row[1] for row in data]

# 获取数据
gens_baseline, scores_baseline = get_best_scores_per_gen("baseline.sqlite")
gens_aux, scores_aux = get_best_scores_per_gen("aux.sqlite")

# 绘图
plt.figure(figsize=(12, 6))
plt.plot(gens_baseline, scores_baseline, label="Baseline (No Aux)", marker='o', alpha=0.7)
plt.plot(gens_aux, scores_aux, label="Aux Only", marker='s', alpha=0.7)
plt.xlabel("Generation")
plt.ylabel("Best Combined Score")
plt.title("Learning Curves: Baseline vs Auxiliary Metrics")
plt.legend()
plt.grid(True, alpha=0.3)
plt.savefig("learning_curves_comparison.png", dpi=150)
print("Saved: learning_curves_comparison.png")

---

🎯 成功标准

最小成功标准

• Aux Only 最佳分数 > Baseline 最佳分数
• 统计显著性（p < 0.05，如果运行多次重复）

理想成功标准

• Aux Only 提升 > 5%
• 收敛速度提升 > 20%
• 辅助指标与primary score有明显相关性

额外洞察

• 识别出最有用的auxiliary metrics
• 发现LLM如何利用auxiliary信息
• 验证programmatic gap detection的效果

---

📝 实验日志模板

# Experiment Log

## Baseline (WITHOUT vision, WITHOUT aux)
- Start: YYYY-MM-DD HH:MM
- End: YYYY-MM-DD HH:MM
- Best Score: X.XXXX
- Notes: ...

## Aux Only (WITHOUT vision, WITH aux)
- Start: YYYY-MM-DD HH:MM
- End: YYYY-MM-DD HH:MM
- Best Score: X.XXXX
- Improvement over Baseline: +X.XXXX (+X.X%)
- Notes: ...

## Key Observations
1. ...
2. ...

## Auxiliary Metrics Analysis
- Most useful metrics: ...
- Correlations: ...
- LLM behavior changes: ...

## Conclusions
- Auxiliary metrics效果: [有效/无效/部分有效]
- 下一步: ...

---

🔮 后续实验（如果Aux有效）

Phase 2: 完整2x2矩阵

# 1. WITH vision + WITHOUT aux (已有)
python my/run_circle_packing_WITH_vision.py

# 2. WITH vision + WITH aux (新建)
# 创建这个版本来测试vision + auxiliary的组合效果

Phase 3: 参数调优

• 调整auxiliary metrics权重
• 优化text feedback格式
• 尝试不同的metric组合

Phase 4: LLM生成Metrics

• 让LLM提出新的auxiliary metrics
• 自动筛选有用的metrics
• Co-evolution

---

💡 Pro Tips

1. 先跑短实验验证

# 修改num_generations = 20 做快速测试
num_generations = 20  # Instead of 200

目的：快速验证系统工作正常

2. 监控进度

# 实时查看最新generation的分数
watch -n 60 'tail -20 examples/circle_packing/results/results_*/evolution_run.log | grep "best program"'

3. 中期检查

# 50代后检查趋势
python -c "
from shinka.database import ProgramDatabase, DatabaseConfig
db = ProgramDatabase(config=DatabaseConfig(...), db_path='...')
db.print_summary()
"

4. 保存检查点

# 定期备份数据库
cp evolution_db.sqlite evolution_db_backup_gen50.sqlite

---

✅ Checklist

开始前

• 确认baseline脚本存在
• 确认aux脚本创建成功
• 确认auxiliary eval系统测试通过
• 确认有足够的磁盘空间（~1GB per run）
• 确认有足够的时间（可能数小时）

运行中

• Baseline已启动
• Aux Only已启动（可并行或串行）
• 监控日志确认正常运行
• 检查auxiliary_analysis.json正确生成（Aux Only）

完成后

• 两个实验都成功完成
• 收集最佳分数
• 绘制学习曲线
• 分析auxiliary metrics相关性
• 记录实验日志
• 得出结论

---

📚 相关文件

• run_circle_packing_WITHOUT_vision.py - Baseline
• run_circle_packing_WITHOUT_vision_WITH_auxiliary.py - Aux Only
• examples/circle_packing/auxiliary_eval.py - Auxiliary metrics实现
• examples/circle_packing/evaluate_with_auxiliary.py - 集成evaluator
• AUXILIARY_EVAL_README.md - 完整文档

---

Good luck with your ablation study! 🚀

这是一个非常clean的实验设计，应该能清楚地证明auxiliary metrics的价值。