ADR: translate adr-ko/ to Korean, fix ADR-0013 slug, refine Status check

Follow-up to the bilingual-structure commit: docs/adr-ko/ now holds
only Korean versions (24 files translated from English placeholders),
ADR-0013 slug uses kebab-case in both folders, and the verify tool
allows translated parenthetical commentary in the Status block.

- Translate 24 English files in docs/adr-ko/ to Korean. The previous
  bilingual-structure commit had left these as English copies because
  their source content was already English; this commit fulfills the
  policy that docs/adr-ko/ contains only Korean.
- Rename ADR-0013 in both adr/ and adr-ko/ from
  ver-verification_strategy.md to ver-verification-strategy.md
  (kebab-case consistency with other ADRs).
- CLAUDE.md (ADR Translation Discipline): clarify that only the
  Status lifecycle keyword (Accepted / Proposed / Stub / Draft /
  Superseded by ADR-NNNN / Merged into ADR-NNNN) must match across
  EN and KO; parenthetical commentary and trailing list items may be
  translated.
- tools/verify_adr_lang_pairs.py: replace byte-equal Status check
  with normalize_status_keyword() which strips parenthetical
  commentary and takes only the first non-empty line.
- tests/test_verify_adr_lang_pairs.py: update existing test names,
  add coverage for translated parenthetical, translated trailing
  list, and Superseded-by-NNNN keyword equality.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-20 08:17:56 -07:00
parent a796c1d2f7
commit 168b0c89f0
29 changed files with 2631 additions and 2651 deletions
+132 -133
View File
@@ -1,4 +1,4 @@
# ADR-0032: Intercube All-Reduce — pe0 cube-mesh reduce + multi-SIP exchange
# ADR-0032: 큐브 간 All-Reduce — pe0 큐브-메시 리듀스 + 다중-SIP 교환
## Status
@@ -6,112 +6,109 @@ Accepted (supersedes ADR-0029).
## Context
### Goal
### 목표
Define a single all-reduce algorithm that exploits the topology hierarchy:
cube mesh within each SIP (intercube) + inter-SIP exchange. One kernel,
one SFR configuration path, driven by `topology.yaml` and `ccl.yaml`.
토폴로지 계층을 활용하는 단일 all-reduce 알고리즘을 정의한다: 각 SIP
내부의 큐브 메시(큐브 간) + SIP 간 교환. 단일 커널, 단일 SFR 구성
경로이며 `topology.yaml` `ccl.yaml`로 구동된다.
### Why replace ADR-0029 (hierarchical 3-level)
### ADR-0029(계층적 3-레벨)를 대체하는 이유
ADR-0029 proposed a 3-level (intra-cube → inter-cube → inter-SIP) algorithm
where every PE in the system participates. In practice this adds the
intra-cube PE-to-PE stage complexity (bidirectional reduce + chain broadcast)
without matching the common workload pattern where the tensor is sharded
**per cube** (not per PE within a cube).
ADR-0029는 시스템의 모든 PE가 참여하는 3-레벨(큐브 내 → 큐브 간 →
SIP 간) 알고리즘을 제안했다. 실제로는 텐서가 큐브 내 PE 단위가 아니라
**큐브 단위로 샤딩되는** 일반적 워크로드 패턴과 맞지 않으면서, 큐브 내
PE-PE stage 복잡성(양방향 reduce + 체인 브로드캐스트)을 추가한다.
Moreover, the hierarchical design required:
- per-PE neighbor graph installation (`_build_pe_installs` multi-level)
- multi-level topology schema (`hierarchical_3level`)
- `all_pes` mapper + `multi_pe_sip_local` validator infrastructure
또한 계층적 설계는 다음을 요구했다:
- PE별 이웃 그래프 설치 (`_build_pe_installs` 다중 레벨)
- 다중 레벨 토폴로지 스키마 (`hierarchical_3level`)
- `all_pes` 매퍼 + `multi_pe_sip_local` 검증자 인프라
The intercube algorithm below removes all of that: **pe0-only same-lane
intercube reduce on the 4×4 cube mesh**, then inter-SIP exchange on the
root cube, then broadcast back. Simpler kernel, simpler wiring, same
bandwidth characteristics for the common per-cube DP workload.
아래의 큐브 간 알고리즘은 이 모든 것을 제거한다: **4×4 큐브 메시 위에서
pe0만의 same-lane 큐브 간 reduce**, 그 다음 루트 큐브에서 SIP 간 교환,
그 다음 다시 브로드캐스트. 더 단순한 커널, 더 단순한 와이어링,
일반적인 큐브당 DP 워크로드에 대해 동일한 대역폭 특성을 갖는다.
### Current state
### 현재 상태
- `src/kernbench/ccl/algorithms/intercube_allreduce.py`kernel
- `src/kernbench/ccl/algorithms/intercube_allreduce.py`커널
- `src/kernbench/ccl/sfr_config.py``configure_sfr_intercube_multisip`
- `src/kernbench/runtime_api/distributed.py``AhbmCCLBackend` wires this
automatically at `init_process_group` time.
- Old `ring_allreduce`, `mesh_allreduce`, `tree_allreduce`,
`hierarchical_allreduce` modules and their tests are **removed**.
- `src/kernbench/runtime_api/distributed.py``AhbmCCLBackend`
`init_process_group` 시점에 자동으로 와이어링한다.
- 기존 `ring_allreduce`, `mesh_allreduce`, `tree_allreduce`,
`hierarchical_allreduce` 모듈과 그 테스트는 **제거됨**.
---
## Decision
### D1. Algorithm structure — 5 phases
### D1. 알고리즘 구조 — 5단계
For each SIP (launched concurrently by `mp.spawn`):
각 SIP에 대해 (`mp.spawn`으로 동시에 launch):
```
Phase 1 — Row reduce W → E (cube mesh, pe0 only):
col=0 sends E → col=1 accumulates, sends E → ... → col=3 holds row sum.
Phase 1 — Row reduce W → E (큐브 메시, pe0만):
col=0이 E로 송신 → col=1이 누적, E로 송신 → ... → col=3 row sum 보유.
Phase 2 — Col reduce N → S on rightmost column (pe0, col = mesh_w-1):
row=0 sends S → row=1 accumulates, sends S → ... → root cube (15)
holds the full SIP sum.
Phase 2 — 최우측 열에서 Col reduce N → S (pe0, col = mesh_w-1):
row=0이 S로 송신 → row=1이 누적, S로 송신 → ... → 루트 큐브 (15)
전체 SIP sum 보유.
Phase 3 — Inter-SIP exchange on root cube (pe0 of root cube only):
Phase 3 — 루트 큐브에서 SIP 간 교환 (루트 큐브의 pe0만):
Ring / torus-2d row+col ring / mesh-2d chain reduce+broadcast —
selected by sip_topo_kind (from topology.yaml sips.topology).
sip_topo_kind(topology.yaml sips.topology)로 선택.
Phase 4 — Col broadcast S → N on rightmost column.
Phase 4 — 최우측 열에서 Col 브로드캐스트 S → N.
Phase 5 — Row broadcast E → W across the cube mesh.
Phase 5 — 큐브 메시 전반에 걸친 Row 브로드캐스트 E → W.
```
After all phases every cube's pe0 holds the global sum.
모든 단계가 끝나면 모든 큐브의 pe0이 전역 sum을 보유한다.
The kernel is a single function parameterised by `sip_topo_kind ∈ {0, 1, 2}`
(ring_1d, torus_2d, mesh_2d_no_wrap). Phases 1-2 and 4-5 are identical
across topologies; only phase 3 branches. Helper functions
`_inter_sip_ring`, `_inter_sip_torus_2d`, `_inter_sip_mesh_2d` encode the
three exchange patterns.
커널은 `sip_topo_kind ∈ {0, 1, 2}`(ring_1d, torus_2d, mesh_2d_no_wrap)로
파라미터화된 단일 함수이다. Phase 1-2와 4-5는 토폴로지 전반에서 동일하며,
phase 3만 분기한다. 헬퍼 함수 `_inter_sip_ring`, `_inter_sip_torus_2d`,
`_inter_sip_mesh_2d`가 세 가지 교환 패턴을 인코딩한다.
### D2. Tensor layout (rank = SIP, per-worker)
### D2. 텐서 레이아웃 (rank = SIP, 워커별)
Per ADR-0024 rank = SIP at the process-group level. Each worker allocates
its own cube-mesh-spanning tensor:
ADR-0024에 따라 프로세스 그룹 레벨에서 rank = SIP이다. 각 워커가
자신의 큐브-메시 전체 텐서를 할당한다:
```python
dp = DPPolicy(cube="row_wise", pe="replicate", num_cubes=16, num_pes=1)
tensor = torch.zeros((n_cubes, n_elem), dtype="f16", dp=dp)
```
Shard layout: 16 shards per SIP, one per cube on pe0. The kernel addresses
each cube's shard as `pe_addr = t_ptr + cube_id * n_elem * 2`.
샤드 레이아웃: SIP당 16개 샤드, 큐브별 pe0에 하나씩. 커널은 각 큐브의
샤드를 `pe_addr = t_ptr + cube_id * n_elem * 2`로 주소 지정한다.
### D3. SFR / IPCQ wiring — `configure_sfr_intercube_multisip`
### D3. SFR / IPCQ 와이어링 — `configure_sfr_intercube_multisip`
Replaces the rank-to-2-PE install from ADR-0024. Wires PE_IPCQ neighbor
tables for **every cube's pe0 across every SIP** — regardless of which
cube is the root or which SIP topology is selected. This lets the kernel
elect the root cube at runtime and supports topology switches without
re-wiring.
ADR-0024의 rank-to-2-PE 설치를 대체한다. 어느 큐브가 루트인지 또는 어느
SIP 토폴로지가 선택되었는지와 무관하게 **모든 SIP의 모든 큐브의 pe0**에
대해 PE_IPCQ 이웃 테이블을 와이어링한다. 이를 통해 커널이 런타임에 루트
큐브를 선출할 수 있고, 재와이어링 없이 토폴로지 전환을 지원한다.
| Level | Direction labels | Scope |
|---|---|---|
| Intercube within SIP | N / S / E / W | pe0 of every cube → pe0 of mesh neighbors (no wrap) |
| Inter-SIP (all cubes) | global_E / global_W / global_N / global_S | pe0 of cube c on sip A → pe0 of cube c on peer SIP per `sips.topology` |
| SIP 내부 큐브 간 | N / S / E / W | 모든 큐브의 pe0 → 메시 이웃의 pe0 (랩어라운드 없음) |
| SIP 간 (모든 큐브) | global_E / global_W / global_N / global_S | sip A의 큐브 c의 pe0 → `sips.topology`에 따른 피어 SIP의 큐브 c의 pe0 |
Inter-SIP directions use the `global_*` prefix to keep the namespace
disjoint from intercube directions. ADR-0025's `_OPPOSITE_DIR` is extended
with `global_E ↔ global_W` and `global_N ↔ global_S` so the reverse-
direction resolver handles 2-SIP bidirectional rings correctly.
SIP 간 방향은 `global_*` 접두사를 사용하여 큐브 간 방향과 네임스페이스를
분리한다. ADR-0025 `_OPPOSITE_DIR``global_E ↔ global_W`
`global_N ↔ global_S`로 확장되어, 2-SIP 양방향 ring에 대한 역방향
리졸버가 올바르게 처리되도록 한다.
Internally the function calls `install_ipcq` with:
내부적으로 이 함수는 다음 인자로 `install_ipcq`를 호출한다:
- `world_size = n_sips × n_cubes`
- `rank_to_pe = [(sip, cube, 0) for sip in range(n_sips) for cube in range(n_cubes)]`
- A closure-captured `neighbors()` function that builds the map above.
- 위 매핑을 생성하는 클로저로 캡처된 `neighbors()` 함수.
This `world_size` is internal to IPCQ wiring and does not leak to the
process-group rank.
`world_size`는 IPCQ 와이어링 내부적이며 프로세스-그룹 rank로 유출되지
않는다.
### D4. SIP topology — from `topology.yaml`
### D4. SIP 토폴로지 — `topology.yaml`에서
```yaml
system:
@@ -120,35 +117,36 @@ system:
topology: ring_1d # or torus_2d, mesh_2d_no_wrap
```
- `ring_1d`: n_sips-1 rounds of `send global_E / recv global_W`.
- `torus_2d`: sqrt(n_sips)×sqrt(n_sips) wrapping mesh. Row ring on
`global_E/W` then col ring on `global_S/N`.
- `mesh_2d_no_wrap`: square mesh without wrap-around. Chain reduce +
broadcast per dimension.
- `ring_1d`: n_sips-1 라운드의 `send global_E / recv global_W`.
- `torus_2d`: sqrt(n_sips)×sqrt(n_sips) 랩핑 메시. `global_E/W`에서
row ring, 이어서 `global_S/N`에서 col ring.
- `mesh_2d_no_wrap`: 랩어라운드 없는 정사각형 메시. 차원별 chain
reduce + 브로드캐스트.
2D variants require `n_sips` to be a perfect square.
2D 변형은 `n_sips`가 완전 제곱수여야 한다.
### D5. Process-group integration — `AhbmCCLBackend`
### D5. 프로세스-그룹 통합 — `AhbmCCLBackend`
At `init_process_group` time the backend:
`init_process_group` 시점에 백엔드는:
1. Loads `ccl.yaml` + `topology.yaml`.
2. Derives `sip_topo_kind, sip_topo_w, sip_topo_h` from
`system.sips.topology` using the algorithm module's `TOPO_NAME_TO_KIND`.
3. Calls `configure_sfr_intercube_multisip(engine, spec, cfg)` — one-time
SFR wiring, mirrors NCCL communicator creation.
1. `ccl.yaml` + `topology.yaml`을 로드한다.
2. 알고리즘 모듈의 `TOPO_NAME_TO_KIND`를 사용하여
`system.sips.topology`로부터 `sip_topo_kind, sip_topo_w, sip_topo_h`
도출한다.
3. `configure_sfr_intercube_multisip(engine, spec, cfg)`를 호출한다 —
일회성 SFR 와이어링, NCCL 커뮤니케이터 생성을 모방한다.
At each `dist.all_reduce(tensor)` call:
`dist.all_reduce(tensor)` 호출 시:
1. Resolves `kernel_fn` from `cfg["module"]`.
2. Builds args: `(n_elem, cube_w, cube_h, n_sips)` from
`kernel_args(world_size, n_elem)`.
3. Appends `(sip_rank, sip_topo_kind, sip_topo_w, sip_topo_h)` where
`sip_rank` is the current greenlet's bound rank.
4. Launches with `_defer_wait=True`; the main scheduler drains pending
handles after all workers submit (per ADR-0027 D0.4).
1. `cfg["module"]`로부터 `kernel_fn`을 해석한다.
2. `kernel_args(world_size, n_elem)`로부터 인자
`(n_elem, cube_w, cube_h, n_sips)`를 구성한다.
3. `(sip_rank, sip_topo_kind, sip_topo_w, sip_topo_h)`를 추가하며,
여기서 `sip_rank`는 현재 greenlet에 바인딩된 rank이다.
4. `_defer_wait=True`로 launch; 모든 워커가 제출한 후 메인 스케줄러가
pending 핸들을 드레인한다 (ADR-0027 D0.4).
### D6. Config schema
### D6. 구성 스키마
`ccl.yaml`:
@@ -178,38 +176,39 @@ sip:
cube_mesh: { w: 4, h: 4 }
```
### D7. Algorithm module contract
### D7. 알고리즘 모듈 계약
Modules loaded via `cfg["module"]` must export:
`cfg["module"]`로 로드되는 모듈은 다음을 export해야 한다:
| Name | Purpose |
|---|---|
| `kernel` | callable, signature `(t_ptr, n_elem, cube_w, cube_h, n_sips, sip_rank, sip_topo_kind, sip_topo_w, sip_topo_h, tl)` |
| `kernel_args(world_size, n_elem) -> tuple` | returns the first 4 scalar args (per-tensor) |
| `TOPO_NAME_TO_KIND: dict[str, int]` | maps `system.sips.topology` name to kernel branch code |
| `SIP_TOPO_RING`, `SIP_TOPO_TORUS`, `SIP_TOPO_MESH` | integer constants (0, 1, 2) |
| `kernel` | callable, 시그니처 `(t_ptr, n_elem, cube_w, cube_h, n_sips, sip_rank, sip_topo_kind, sip_topo_w, sip_topo_h, tl)` |
| `kernel_args(world_size, n_elem) -> tuple` | 처음 4개의 scalar 인자(텐서별) 반환 |
| `TOPO_NAME_TO_KIND: dict[str, int]` | `system.sips.topology` 이름을 커널 분기 코드로 매핑 |
| `SIP_TOPO_RING`, `SIP_TOPO_TORUS`, `SIP_TOPO_MESH` | 정수 상수 (0, 1, 2) |
---
## Dependencies
- **ADR-0023**: IPCQ protocol (neighbor table, send/recv, credit return).
- **ADR-0024**: rank = SIP launcher, `mp.spawn`, greenlet-local rank.
- **ADR-0025**: Address-based IPCQ direction matching; extended
`_OPPOSITE_DIR` with `global_*` pairs.
- **ADR-0027**: Worker-wait / collective-pending drain in main scheduler.
- **ADR-0023**: IPCQ 프로토콜 (이웃 테이블, 송수신, credit 반환).
- **ADR-0024**: rank = SIP launcher, `mp.spawn`, greenlet-로컬 rank.
- **ADR-0025**: 주소 기반 IPCQ 방향 매칭; `global_*` 쌍으로 확장된
`_OPPOSITE_DIR`.
- **ADR-0027**: 메인 스케줄러에서의 worker-wait / 집합 통신 pending
드레인.
## Non-goals
- **Per-PE allreduce** (intra-cube PE-to-PE reduce). Out of scope — the
workload for this algorithm is per-cube DP.
- **Asymmetric SIP topologies** (non-square mesh/torus). `torus_2d` and
`mesh_2d_no_wrap` require `n_sips = k²`.
- **Pipelined chunks**: single-tile per cube, no pipelining yet.
- **Root cube runtime election**: the kernel currently uses
`root_cube = (mesh_h - 1) * mesh_w + (mesh_w - 1)` hardcoded to the SE
corner. SFR wiring covers all cubes, so runtime election is a pure kernel
change when needed.
- **PE allreduce** (큐브 내 PE-PE reduce). 범위 밖 — 본 알고리즘의
워크로드는 큐브당 DP이다.
- **비대칭 SIP 토폴로지** (정사각형이 아닌 메시/토러스).
`torus_2d``mesh_2d_no_wrap` `n_sips = k²`를 요구한다.
- **파이프라인 청크**: 큐브당 단일 타일, 아직 파이프라이닝 없음.
- **루트 큐브의 런타임 선출**: 커널은 현재 SE 코너로 하드코딩된
`root_cube = (mesh_h - 1) * mesh_w + (mesh_w - 1)`을 사용한다. SFR
와이어링이 모든 큐브를 커버하므로, 필요해질 때 런타임 선출은 순수
커널 변경이다.
---
@@ -217,24 +216,24 @@ Modules loaded via `cfg["module"]` must export:
### Positive
- **Single kernel, single install path** for all-reduce — replaces four
removed modules (`ring`, `mesh`, `tree`, `hierarchical`).
- **Topology-agnostic kernel**: ring / torus / mesh selected via one
integer param, no kernel duplication.
- **Automatic via `dist.all_reduce`**: no bench-level or user-level
algorithm selection needed; config-driven end-to-end.
- **Full SFR wiring**: every cube on every SIP has inter-SIP links
available — supports future dynamic root-cube election.
- **단일 커널, 단일 설치 경로**로 all-reduce를 처리 — 제거된 네 개의
모듈(`ring`, `mesh`, `tree`, `hierarchical`)을 대체한다.
- **토폴로지 무관 커널**: ring / torus / mesh를 정수 파라미터 하나로
선택, 커널 중복 없음.
- **`dist.all_reduce`를 통한 자동화**: 벤치 레벨이나 사용자 레벨의
알고리즘 선택 불필요; end-to-end 구성 기반.
- **완전한 SFR 와이어링**: 모든 SIP의 모든 큐브가 SIP 간 링크를 보유 —
향후 동적 루트 큐브 선출을 지원한다.
### Negative
- **Not suitable for per-PE sharded tensors**: TP-layer-style tensors that
shard within one cube across 8 PEs are not addressable by this kernel.
Such workloads would need a separate intra-cube all-reduce path (not
yet implemented).
- **`configure_sfr_intercube_multisip` always wires all pe0s**: even if a
given run only needs a subset (e.g. 1 SIP, ring only). Install cost is
small but not zero.
- **PE별 샤딩된 텐서에 부적합**: 큐브 하나 내부에서 8개 PE에 걸쳐
샤딩되는 TP-레이어 스타일 텐서는 본 커널로 주소 지정할 수 없다. 이러한
워크로드에는 별도의 큐브 내 all-reduce 경로가 필요하다 (아직 구현되지
않음).
- **`configure_sfr_intercube_multisip`는 항상 모든 pe0을 와이어링**:
주어진 실행이 부분집합(예: 1 SIP, ring만)만 필요하더라도. 설치 비용은
작지만 영(zero)은 아니다.
---
@@ -242,15 +241,15 @@ Modules loaded via `cfg["module"]` must export:
| File | Change |
|---|---|
| `src/kernbench/ccl/algorithms/intercube_allreduce.py` (new) | Kernel + `_inter_sip_*` helpers + `TOPO_NAME_TO_KIND` |
| `src/kernbench/ccl/sfr_config.py` (new) | `configure_sfr_intercube_multisip` |
| `src/kernbench/ccl/topologies.py` | Added `torus_2d`, `mesh_2d_no_wrap` |
| `src/kernbench/ccl/install.py` | Extended `_OPPOSITE_DIR` with `global_*` pairs |
| `src/kernbench/runtime_api/distributed.py` | `AhbmCCLBackend` uses `configure_sfr_intercube_multisip` + appends sip_rank/topo args |
| `ccl.yaml` | Single `intercube_allreduce` entry |
| `topology.yaml` | Added `system.sips.topology` |
| `benches/ccl_allreduce.py` | Row-wise cube-mesh tensor layout |
| `tests/test_allreduce_multidevice.py` (new) | Config-driven ring/torus/mesh |
| `tests/test_distributed_intercube_allreduce.py` (new) | Full `dist.all_reduce` path |
| `tests/test_intercube_sfr_config.py` (new) | SFR wiring verification |
| Removed | `ring_allreduce.py`, `mesh_allreduce.py`, `tree_allreduce.py`, `hierarchical_allreduce.py`, `hello_send.py`, `testing.py` and their tests |
| `src/kernbench/ccl/algorithms/intercube_allreduce.py` (신규) | 커널 + `_inter_sip_*` 헬퍼 + `TOPO_NAME_TO_KIND` |
| `src/kernbench/ccl/sfr_config.py` (신규) | `configure_sfr_intercube_multisip` |
| `src/kernbench/ccl/topologies.py` | `torus_2d`, `mesh_2d_no_wrap` 추가 |
| `src/kernbench/ccl/install.py` | `_OPPOSITE_DIR` `global_*` 쌍으로 확장 |
| `src/kernbench/runtime_api/distributed.py` | `AhbmCCLBackend` `configure_sfr_intercube_multisip` 사용 + sip_rank/topo 인자 추가 |
| `ccl.yaml` | 단일 `intercube_allreduce` 항목 |
| `topology.yaml` | `system.sips.topology` 추가 |
| `benches/ccl_allreduce.py` | Row-wise 큐브-메시 텐서 레이아웃 |
| `tests/test_allreduce_multidevice.py` (신규) | 구성 기반 ring/torus/mesh |
| `tests/test_distributed_intercube_allreduce.py` (신규) | 전체 `dist.all_reduce` 경로 |
| `tests/test_intercube_sfr_config.py` (신규) | SFR 와이어링 검증 |
| 제거 | `ring_allreduce.py`, `mesh_allreduce.py`, `tree_allreduce.py`, `hierarchical_allreduce.py`, `hello_send.py`, `testing.py` 및 그 테스트 |