KOKO\Mimi
47 lines
4.5 KiB
Markdown
47 lines
4.5 KiB
Markdown
# FESA Core Documentation Extension Playbook Design
|
|
|
|
## 목적
|
|
|
|
`AGENTS.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`를 현재 구현에 맞게 보강한다. 작업 완료 이력이나 일시적인 테스트 개수 대신, 다음 기능을 추가할 AI Agent가 바로 사용할 수 있는 해석 흐름, 소유권, 빌드 설정, 수치 불변식, 확장 경계를 기록한다.
|
|
|
|
## 문서별 책임
|
|
|
|
- `AGENTS.md`: FESA의 배경과 목적, 전체 프로젝트에서 훼손하면 안 되는 개발 원칙, 문서 탐색 순서와 기능 확장 시의 판단 기준을 제공한다. 상세 구현·빌드 매뉴얼의 대체물이 아니다.
|
|
- `docs/PRD.md`: 사용자가 관찰하는 제품 흐름, 구현된 V0 지원 경계, 신규 기능이 제품 기능으로 인정되기 위한 조건을 정의한다.
|
|
- `docs/ARCHITECTURE.md`: 실제 모듈과 target, 객체 소유권, 8단계 해석 수명주기, CMake dependency/runtime graph, 기능 유형별 확장 지점을 설명한다.
|
|
- `docs/ADR.md`: 정규화된 외부 의존성, 결정론적·failure-atomic 경계, 구속 제거와 full residual, 계층형 검증을 장기 결정으로 남긴다.
|
|
|
|
## 기록할 구현 사실
|
|
|
|
1. 입력은 syntax parse와 semantic mapping을 거쳐 불변 `Domain`이 되고, `AnalysisModel`은 이를 복사하지 않는 view이다.
|
|
2. `Analysis::run()`은 initialize, model view, DOF/pattern, stiffness/partition, factorization, load/effective RHS, solve/reconstruct, recovery/write 순서를 고정한다.
|
|
3. `DofManager`가 full/free/constrained numbering과 0-based CSR pattern을 단독 소유하며, Node/Element에는 equation ID를 저장하지 않는다.
|
|
4. assembly는 element-local buffer, stable COO order, serial ordered reduction으로 결정론적 CSR을 만든다. global sparse storage를 병렬로 직접 갱신하지 않는다.
|
|
5. essential constraints는 full K를 `Kff/Kfc/Kcf/Kcc`로 분할하고 `Ff - Kfc*dc`를 푼다. fully constrained 0x0 `Kff`도 유효하다.
|
|
6. reaction/equilibrium evidence는 full residual `K*d - F`를 사용한다. constrained 성분은 physical reaction이고 free 성분은 equilibrium residual이다.
|
|
7. 외부 API는 `LinearSolver`, `ParallelFor`, `ResultsWriter`와 math adapter 뒤에 둔다. public header에 MKL/TBB/HDF5/Win32 type을 노출하지 않는다.
|
|
8. HDF5 writer는 같은 directory의 temporary file, checked close/reopen self-check, atomic finalization을 사용한다.
|
|
9. element end action, section resultant, generalized result, stress identity와 sign convention을 섞지 않으며 station mismatch를 평균내지 않는다.
|
|
|
|
## 빌드 및 검증 설계
|
|
|
|
- direct build는 Visual Studio generator, x64, Debug를 명시한다. 상세 target graph와 runtime 설명은 `docs/ARCHITECTURE.md`에 두고, `AGENTS.md`에는 최소 검증 진입점만 둔다.
|
|
- `FESA_GTEST_SOURCE_DIR`는 필수 local source path이다. `MKL_DIR`, `TBB_DIR`, `HDF5_DIR`는 설치 환경에서 package discovery가 되지 않으면 명시한다.
|
|
- production은 `Fesa::MKL`, `Fesa::TBB`, `Fesa::HDF5` normalized target만 사용한다.
|
|
- Windows에서는 CLI와 GoogleTest discovery 전에 MKL/TBB/HDF5 및 transitive oneAPI runtime DLL이 executable 옆에 staging되어야 한다.
|
|
- 문서 작업 검증은 project hook/Harness를 실행하지 않고 `git diff --check`, 링크·경로·명령·target 이름의 정적 대조로 제한한다.
|
|
|
|
## 기능 확장 플레이북
|
|
|
|
- 새 element: 요구조건/정식화/I/O mapping을 먼저 고정하고 kernel, model mapping, DOF pattern, assembly, recovery, output, reference/physics evidence를 함께 확장한다.
|
|
- 새 load/constraint: semantic target identity, stable source order, full-space vector/matrix, partition/effective RHS, diagnostics와 output을 함께 검토한다.
|
|
- 새 analysis procedure: 기존 V0 lifecycle을 조용히 변경하지 않고 별도 orchestration/state/equation 계약과 gate를 정의한다.
|
|
- 새 numerical backend: public interface를 유지하고 adapter 내부에만 vendor API, lifecycle, runtime dependency를 격리한다.
|
|
- 새 output/reference quantity: mandatory HDF5 schema, units/coordinates/identity, recovery sign, comparison projection과 tolerance를 동시에 정의한다.
|
|
|
|
## 범위 제한
|
|
|
|
- phase 완료 이력, commit hash, 현재 테스트 총개수 같은 일시적 사실을 핵심 문서에 넣지 않는다.
|
|
- full Abaqus compatibility, B31 지원, transform/nested assembly, distributed-load parser exposure 등 승인되지 않은 범위를 암시하지 않는다.
|
|
- 문서 보강 외 production, test, CMake, reference artifact를 수정하지 않는다.
|