add uncommitted files

2026-07-29 23:32:26 +09:00
parent fb0f8f39a0
commit f5379472ce
80 changed files with 7461 additions and 1 deletions
@@ -0,0 +1,21 @@
+{
+  "project": "FESA",
+  "phase": "deterministic-parallel-assembly",
+  "steps": [
+    {
+      "step": 0,
+      "name": "canonical-contribution-order",
+      "status": "pending"
+    },
+    {
+      "step": 1,
+      "name": "tbb-element-evaluation",
+      "status": "pending"
+    },
+    {
+      "step": 2,
+      "name": "thread-count-determinism",
+      "status": "pending"
+    }
+  ]
+}
@@ -0,0 +1,56 @@
+# Step 0: Canonical Contribution Order
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/include/fesa/assembly/`
+- `/src/fesa/assembly/`
+- `/include/fesa/model/entity_origin.hpp`
+
+## 작업
+
+serial assembly를 변경하지 않고 병렬 계산이 사용할 canonical contribution record와
+merge contract를 분리한다.
+
+```cpp
+struct MatrixContribution final {
+    std::size_t row;
+    std::size_t column;
+    ElementId element;
+    std::uint16_t local_order;
+    double value;
+};
+[[nodiscard]] std::vector<MatrixContribution> canonicalize_contributions(
+    std::span<const MatrixContribution>);
+[[nodiscard]] SymmetricCsr merge_contributions(
+    std::size_t order,
+    std::span<const MatrixContribution> canonical);
+```
+
+- 입력 순열, 같은 row/column의 여러 element, cancellation, signed zero를 포함해
+  결과 CSR이 bit-for-bit 같은 테스트를 먼저 작성한다.
+- 정렬 key는 row, column, stable element identity, local order다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "CanonicalContribution|DeterministicMerge" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. shuffled contribution 테스트의 실패를 확인한다.
+2. stable total order와 단일 merge 구현만 추가한다.
+3. serial oracle의 CSR과 bitwise 비교한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- tolerance 기반으로 assembly 값을 같다고 처리하지 마라. 이유: bitwise 재현성 계약이다.
+- parallel code를 추가하지 마라. 이유: 다음 step의 책임이다.
+- unordered concurrent accumulation을 준비하지 마라. 이유: 결정성을 깨뜨린다.
@@ -0,0 +1,54 @@
+# Step 1: TBB Element Evaluation
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/cmake/FesaDependencies.cmake`
+- `/include/fesa/assembly/assembler.hpp`
+- `/include/fesa/assembly/contribution.hpp`
+- `/include/fesa/elements/beam/beam3d2.hpp`
+
+## 작업
+
+oneTBB로 독립적인 요소 계산만 병렬화하고 contribution merge는 canonical serial
+순서를 사용한다.
+
+```cpp
+struct AssemblyOptions final {
+    std::size_t max_threads;
+    std::size_t grain_size;
+};
+[[nodiscard]] EquationSystem assemble_parallel(
+    const Domain&,
+    const DofManager&,
+    AssemblyOptions);
+```
+
+- fixed Beam chain/branched Domain에서 serial과 parallel의 row offsets, column indices,
+  values, force vector를 bit-for-bit 비교하는 실패 테스트를 먼저 작성한다.
+- worker는 thread-local contribution을 생성하고 공유 CSR values에 쓰지 않는다.
+- `max_threads=1`과 2 이상을 명시적으로 제한할 수 있어야 한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "ParallelAssembly|TbbElementEvaluation" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. parallel API 부재로 실패하는 테스트를 확인한다.
+2. element evaluation 범위에만 TBB를 적용한다.
+3. serial/parallel bitwise 결과와 TSAN 대신 구조적 race 회피 설계를 검토한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- 공유 CSR value에 atomic add하지 마라. 이유: 합산 순서가 비결정적이다.
+- PARDISO 호출을 TBB task 안에 넣지 마라. 이유: oversubscription 위험이 있다.
+- 성능을 위해 tolerance를 완화하지 마라. 이유: 검증 결정성이 우선이다.
@@ -0,0 +1,46 @@
+# Step 2: Thread Count Determinism
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/include/fesa/assembly/assembler.hpp`
+- `/tests/unit/assembly/`
+- `/tests/integration/assembly/`
+
+## 작업
+
+thread count와 반복 실행이 assembly 및 최종 선형 정적 결과를 바꾸지 않는 통합
+검증과 측정용 benchmark를 추가한다.
+
+- `tests/integration/assembly/thread_count_determinism_test.cpp`
+- `tests/performance/assembly_benchmark.cpp`
+- thread counts 1, 2, available concurrency에서 CSR, RHS, displacement, reaction을
+  bit-for-bit 비교한다.
+- 최소 10회 반복으로 scheduling 변화 회귀를 확인한다.
+- benchmark는 serial/parallel 시간과 element count를 출력하되 speedup을 assertion하지
+  않는다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R ThreadCountDeterminism --output-on-failure
+.\out\build\windows-debug\Debug\fesa_assembly_benchmark.exe
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. 다양한 thread count 통합 테스트를 먼저 실행한다.
+2. 차이가 있으면 canonical key/merge 원인을 고치고 tolerance 비교로 대체하지 않는다.
+3. benchmark output을 기록하고 전체 테스트를 실행한다.
+4. index summary에 tested thread counts를 기록한다.
+
+## 금지사항
+
+- benchmark에서 속도 향상을 pass 조건으로 만들지 마라. 이유: 환경 의존적이다.
+- MKL thread 수를 assembly test와 중첩해 키우지 마라. 이유: 측정이 오염된다.
+- release 성능 목표를 임의로 만들지 마라. 이유: 문서화된 측정만 요구된다.