| 单墙绕行 | 双路径 |
|---|---|
 |
 |
一个使用 Python、NumPy 和 Pygame 实现的二维蚁群觅食仿真。每只蚂蚁只根据局部三探针、随机游走、障碍物和两类信息素做决策，不使用 A* 或 Dijkstra 直接控制路线。群体会从随机探索逐渐形成可观察的运输路径。
- 连续坐标蚂蚁与低分辨率 NumPy 信息素栅格
SEARCHING/RETURNING状态机- 搜索蚂蚁铺设回巢信息素，返巢蚂蚁铺设食物信息素
- 非环绕、障碍无通量的扩散和按秒蒸发
- 矩形/圆形障碍物、边界碰撞、墙角脱困
- 食物拾取、搬运、卸货和严格资源守恒
- 三个内置场景：无遮挡、单墙绕行、双路径
- 暂停、单步、重置、新随机种子、速度倍率
- 运行中拖动蚁穴、食物源和矩形/圆形障碍物，观察动态环境适应
- 双信息素热力图、探针调试和实时统计
- 固定随机种子、无头 CLI、pytest 测试和性能基准
- Python 3.11+
- 桌面运行支持 macOS、Windows 和 Linux
uv sync --extra dev
uv run python -m ant_foragingpython -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install -e '.[dev]'
python -m ant_foragingpython -m ant_foraging
python -m ant_foraging --scenario wall --seed 42
ant-foraging --scenario double无窗口运行并输出 JSON：
python -m ant_foraging --headless --seconds 60 --seed 42 --json读取、覆盖或保存 JSON 配置：
python -m ant_foraging --config configs/default.json --scenario wall
python -m ant_foraging --config configs/default.json --seed 99 --headless --seconds 30 --json
python -m ant_foraging --headless --save-config my-config.json命令行中的 --seed、--max-ants 和 --spawn-rate 会覆盖配置文件中的对应值。
常用参数：
--config FILE
--save-config FILE
--scenario {open,wall,double}
--seed N
--max-ants N
--spawn-rate N
--headless
--steps N
--seconds N
--json
--debug-checks
| 操作 | 键盘 | 界面 |
|---|---|---|
| 暂停/继续 | Space |
暂停按钮 |
| 单步 | N |
单步按钮 |
| 同种子重置当前编辑布局 | R |
重置按钮 |
| 新种子重置当前编辑布局 | Shift+R |
新种子按钮 |
| 恢复当前场景预设 | Ctrl+R |
Seed 旁“还原”按钮 |
| 速度 0.25×/1×/2×/4× | 1/2/3/4 |
倍率按钮 |
| 信息素图层 | P |
隐藏/回巢/食物/叠加 |
| 调试探针 | D |
调试按钮 |
| 场景 | F1/F2/F3 |
场景按钮 |
| 移动场景实体 | — | 按住并拖动蚁穴、食物或障碍物 |
| 选择蚂蚁 | — | 点击未被场景实体覆盖的蚂蚁 |
| 取消拖动/退出 | Esc |
拖动时取消，否则退出 |
侧栏滑块可即时调整种群上限、生成率、速度、随机转向、探针、双信息素沉积、扩散和蒸发。Seed 输入框按 Enter 后使用该种子和当前编辑布局重置。拖动场景实体时仿真会临时暂停；绿色轮廓表示可以放置，红色表示越界、重叠或覆盖蚂蚁等非法位置。移动目标后旧信息素不会瞬间消失，而会按原有蒸发规则自然衰减。
- 浅色：搜索蚂蚁
- 橙色：携食返巢蚂蚁
- 青蓝：回巢信息素
- 橙红：食物信息素
- 绿色：食物源
- 棕色圆形：蚁穴
- 灰色：障碍物
- 搜索蚂蚁读取左、前、右三个探针的食物信息素。
- 有信号时通过 softmax 概率偏向高浓度方向；无信号时保持惯性并随机游走。
- 搜索路径沉积随路程衰减的回巢信息素。
- 找到食物后拾取一个单位、掉头，并在返巢途中铺设食物信息素。
- 返巢蚂蚁优先跟随回巢信息素；低信号或卡死时使用弱回巢后备。
- 信息素以固定频率扩散、蒸发并受障碍掩码约束。
完整方程和工程取舍见 docs/algorithm.md，详细控制见 docs/controls.md。
uv run pytest -m 'not slow'
uv run pytest -m slow
uv run ruff check src tests benchmarks
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy uv run pytest tests/test_app_smoke.pyuv run python benchmarks/benchmark_simulation.py
uv run python benchmarks/benchmark_simulation.py --steps 600 --output benchmark-results.json报告包含 500、1000、2000 只蚂蚁的无头吞吐量。真实窗口 FPS 还会受到分辨率、热力图缩放和显示驱动影响。
src/ant_foraging/
config.py 参数与校验
entities.py 蚂蚁、蚁穴、食物和障碍物
editing.py 可编辑实体引用、放置结果和几何相交判断
fields.py 双信息素场
collision.py 障碍栅格与碰撞
behavior.py 探针、转向和脱困
simulation.py 确定性领域编排
scenarios.py 内置场景
renderer.py Pygame 世界渲染
ui.py 控制栏和控件
app.py 固定步长应用循环
metrics.py 统计与 CSV 支持
configs/default.json 默认参数文件
- 目标是教学和工程演示，不追求真实昆虫生物学精度。
- 蚂蚁之间不发生实体碰撞。
- 可以移动现有场景实体，但暂不支持新增、删除、缩放或旋转障碍物，也未提供自定义场景文件保存。
- 规模扩大到数千只时，Python 逐代理更新会成为主要瓶颈；可在基准证明必要后改为结构化数组或批量探针计算。
- Pygame 字体取决于操作系统；程序会优先匹配常见中文字体并回退到可用字体。
测试环境：macOS 26.5.2 arm64、Python 3.11.15。
| 验证 | 结果 |
|---|---|
| 快速测试 | 通过 |
| 完整测试（含 slow） | 通过 |
| 500 只、300 步无头 | 228.6 steps/s |
| 1000 只、300 步无头 | 113.9 steps/s |
| 2000 只、300 步无头 | 56.8 steps/s |
| 500 只、1260×720 dummy SDL 应用循环 | 168.2 FPS |
| 默认配置 30 分钟仿真 | 108000 步通过，峰值 RSS 39.328 MiB |
基准文件位于 benchmarks/baseline.json、benchmarks/render-baseline.json 和 benchmarks/stability-baseline.json。dummy SDL 数字用于验证应用循环余量，不等价于特定显示器/GPU 的真实窗口 FPS；若窗口性能不足，可关闭热力图或降低场更新率。