# simul

OpenMM(C++ 분자동역학 라이브러리)의 비-플러그인 핵심을 Rust 로 학습용으로 재구현하는 crate.

> AI 가 코드를 짜지 않는다. 한 사람이 학습 목적으로 직접 작성한다는 제약 위에서 설계됐다.

---

## 단일 진실 원천 (Single Source of Truth)

| 우선순위 | 문서 | 용도 | 충돌 시 |
|---:|---|---|---|
| 1 | **`ROADMAP.md`** | 마일스톤 (M0+ ~ M8), 6개월 / 1년 / 2년 컷라인, 명시적 NEVER 리스트, 정책 결정 8건. *WHY / WHERE-TO*. | 다른 문서가 ROADMAP 과 충돌하면 ROADMAP 우선. |
| 2 | **`PROGRESS.md`** | 학습자 대시보드. 마일스톤별 체크박스, 학습 자산 카운터, 4중 방어선 status, "지금 다음 한 단위". *WHERE-AM-I / WHAT-NEXT*. 매 단위 / 마일스톤 종료 시 갱신. | ROADMAP 의 미러. |
| 3 | **`learning/`** | AI 협업 워크플로 디렉토리: `M{N}.md` (마일스톤별 디테일 패키지), `todo-generator.md` (새 단위 todo prompt), `review-rubric.md` (구현 평가 rubric), `canary-check.md` (4중 방어선 게이트). | — |
| 4 | **`DESIGN.md`** | Rust workspace 구조, trait 설계, 단위 시스템 등 *기술 설계*. | ROADMAP 의 결정에 따라 갱신. 갱신 패치는 `.team-output/DESIGN_PATCH.md` 참조. |
| 5 | **`MIGRATION_CHEATSHEET.md`** | OpenMM ↔ simul 1페이지 빠른 참조. 학습자가 코드 작성 *시작 전* 펼쳐볼 표. | ROADMAP §1.2 원칙 위에서 해석. |
| 6 | **`tests/UPSTREAM_TESTS.md`** | Tier-3 (의도적 미번역) OpenMM 테스트의 인용 카탈로그. 학습자의 인지 함정 ("나는 7%밖에 안 옮겼다") 방지. | — |
| 7 | **`todo.md`** | 초기 마일스톤 체크리스트 (PROGRESS.md 도입 전). PROGRESS.md 와 점차 통합 권고. | ROADMAP 갱신 시 동기화. |

---

## 분석 산출물 (`.team-output/`)

agent team `simul-roadmap` (team-lead + openmm-analyst + test-translator + rust-architect + devil-advocate) 의 산물. T1~T13 분석 파일 + 보강 + DESIGN_PATCH 까지 총 ~15 파일. ROADMAP / MIGRATION_CHEATSHEET / UPSTREAM_TESTS / DESIGN_PATCH 의 *근거 문서*. 별도 인덱스는 `ROADMAP.md` §13.

---

## 학습 원칙 (ROADMAP §1.2 요약)

1. **알고리즘 먼저, GPU 나중**. M0–M3 는 ndarray + rayon 호스트 serial. CubeCL 은 작동하는 reference 가 있은 후 도입.
2. **OpenMM 은 truth-source 지 mirror 가 아니다**. 모든 OpenMM 클래스를 1:1 옮기지 않는다.
3. **명시적 NEVER 가 인지부하를 줄인다**. "언젠가 해야지" 의 부담은 실패 신호.
4. **학습 가치 ÷ 분량** 을 극대화하는 단위만 우선.

---

## 다음 행동

`ROADMAP.md` §14 "다음 행동 (학습자 첫 1주)" 참조. 첫 PR 권고는 `Interaction` ↔ `ForceInteraction` trait 정렬 fix (한나절).

---

## 라이선스

MIT (`Cargo.toml` 참조).