# 史莱姆区块搜索与 CUDA 基准

当前可直接使用的入口是 **[bench/slime-bench](bench/README.md)**：指定中心区块、曼哈顿半径和实心 `n×n` 图案，测量全部有效种子的普通候选分支搜索时间，支持单张或多张 NVIDIA GPU。

```sh
make bench
./bench/bin/slime-bench --x 0 --z 0 --radius 512 --size 5 \
  --position-batch 128 --devices all --repeat 3
```

H100 编译：`make -C bench -B CUDA_ARCH=90`。需要 CUDA Toolkit 和 C++17 编译器。普通分支不包含拒绝重抽补扫，不能将它的结果声明为严格完整目录；参数和计时口径见 [CLI 使用说明](bench/README.md)。

## 目录导航

| 路径 | 用途 |
|---|---|
| [`bench/`](bench/README.md) | 当前 CLI、测试、已保存的本机计时样例 |
| [`include/`](include/README.md) | CLI 与研究代码共用的算法实现 |
| [`research/`](research/README.md) | 求解原型、算法实验、正确性验证和测量报告 |
| [`research/experiments/`](research/experiments/README.md) | 最近的完整覆盖、成组筛选和调度实验 |
| [`show/`](show/README.md) | 分步骤教学代码、博客/视频稿及 Manim 工程 |
| [`exp/`](exp/README.md) | 独立 SMT 逆向搜索探索 |
| [`tools/`](tools/README.md) | 单区块检查小工具与历史汇编参考 |
| `slime.cpp`、`slime.cu` | 最初的暴力扫描实现，保留原入口 |

研究现状见 [优化汇总](research/OPTIMIZATION_SUMMARY.md)。历史报告是当次源码与硬件下的记录，不应自动视为当前 CLI 性能。

## 常用命令

```sh
make help       # 查看构建入口
make bench      # 当前 CLI
make test       # CLI 范围/数学/参数检查：需要 nvcc，不需要 GPU
make test-gpu   # CLI GPU 集成验证
make legacy     # 最初 CPU/CUDA 程序；单独 make 仍保持这个行为
make tools      # 单区块检查工具
```

`make research` 和 `make show` 构建相应研究/教学程序。`make clean` 只清理各入口的编译产物，不删除实验数据或报告。

## 哪些文件应进入 Git

- 保留源代码、构建脚本、文档、依赖锁文件，以及报告引用的基准 JSON/JSONL 和确定性输入数据；部分复现脚本直接读取这些文件。
- 忽略可执行文件、对象文件、`bin/`、虚拟环境、Python 缓存、渲染输出、临时日志和本机配置。
- 临时跑分或个人导出可放在根目录 `artifacts/`，整个目录已忽略。不要把 `.gitignore` 扩大成忽略全部 JSON/TXT/汇编，否则会漏掉复现材料。

```sh
mkdir -p artifacts
./bench/bin/slime-bench --radius 64 --size 5 --output artifacts/local.json
```

历史研究和教学跑分脚本部分会直接更新各自的 `results/` 与报告，运行它们后出现 Git 修改是预期行为；日常机器测速请使用上述 CLI 和 `artifacts/`。将新结果作为正式基准保存时，应连同硬件、命令、源码版本和结论一起审核提交。

旧研究头文件路径保留为兼容转发；修改算法时请修改 `include/slime/` 中的实现。旧报告里的源文件哈希保留原测量值，后续运行的实验脚本会额外记录新共用头文件的哈希。