FESADev/docs/PRD.md

# PRD: FESA 구조해석 솔버

## 목표
FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기반 구조해석을 수행하고, step/frame 단위 결과를 `results.h5` HDF5로 저장하며, Abaqus reference CSV rows와 비교 가능한 C++17/MSVC 솔버를 제공한다.

이 프로젝트의 성공 기준은 단순 실행 성공이 아니다. 기능은 요구조건, 정식화, I/O 계약, C++ 테스트, reference comparison, physics sanity, release readiness를 모두 통과해야 완료된다.

## 사용자
- Solver developer: C++17/MSVC/CMake/CTest 환경에서 요소, 재료, 해석 절차, solver backend를 구현한다.
- Verification reviewer: reference artifact, tolerance, physics sanity, release readiness를 검토한다.
- Analyst preparing Abaqus-compatible input subsets: FESA가 지원하는 제한된 `.inp` subset에 맞춰 입력 모델을 준비한다.
- Codex agent workflow operator: project-local agent와 skill을 사용해 요구조건부터 release까지의 gate를 운영한다.

## 핵심 기능
1. Abaqus `.inp` keyword subset parser와 내부 `Domain` semantic model 생성
2. `AnalysisModel`, `DofManager`, `AnalysisState` 기반의 step별 equation system 구성
3. 선형 정적 해석을 시작점으로 하는 `Analysis` procedure 계층
4. 요소, 재료, 경계조건, 하중의 runtime-polymorphic base interface
5. sparse matrix pattern 생성, 전역 행렬/벡터 조립, 제약조건 적용
6. `LinearSolver` adapter를 통한 MKL PARDISO backend와 향후 iterative solver 확장
7. HDF5 기반 `ResultStep` -> `ResultFrame` -> `FieldOutput`/`HistoryOutput` 저장
8. FESA HDF5 rows와 `reference/<model-id>/` 아래 Abaqus reference CSV rows의 직접 비교
9. CMake/MSVC/x64/Debug, CTest, Harness validation, TDD guard 기반 개발 검증

## V0 범위
- 선형 정적 해석 골격
- 첫 end-to-end 기능 후보: 1D truss/bar element
- 최소 Abaqus keyword subset:
  - `*HEADING`
  - `*NODE`
  - `*ELEMENT`
  - `*NSET`
  - `*ELSET`
  - `*MATERIAL`
  - `*ELASTIC`
  - section keyword
  - `*BOUNDARY`
  - `*CLOAD`
  - `*STEP`
  - `*STATIC`
  - output request subset
- displacement 중심의 최소 `AnalysisState`
- HDF5 result schema v0
- FESA HDF5 to Abaqus reference CSV comparison 계약

## V1 범위
- 2D plane stress/plane strain element
- 3D solid element
- MKL PARDISO 기반 sparse direct solve
- TBB element-local computation 병렬화
- reference model portfolio 확장
- nonlinear static, dynamic, frequency, heat transfer 해석을 위한 interface 확장점

## 기능 요구조건
| ID | 요구조건 | Acceptance Criteria | Verification Method |
| --- | --- | --- | --- |
| FESA-PRD-001 | FESA는 Abaqus `.inp` full compatibility가 아니라 승인된 keyword subset만 지원해야 한다. | 지원/미지원 keyword가 문서화되고, 미지원 keyword는 구조화된 diagnostic을 남긴다. | I/O contract review, parser unit test |
| FESA-PRD-002 | FESA는 입력 모델을 `Domain`으로 변환해야 한다. | nodes, elements, materials, properties, sets, loads, boundary conditions, step definitions가 semantic model에 보존된다. | parser integration test |
| FESA-PRD-003 | FESA는 현재 step의 실행 view를 `AnalysisModel`로 구성해야 한다. | active elements, loads, boundary conditions, properties/materials가 Domain 복사 없이 참조 또는 id view로 연결된다. | analysis model unit test |
| FESA-PRD-004 | FESA는 equation numbering과 constraint/free mapping을 `DofManager`에 집중해야 한다. | Node/Element 내부에 equation id를 분산 저장하지 않는다. | code review, DofManager unit test |
| FESA-PRD-005 | FESA는 해석 중 변하는 물리량을 `AnalysisState`에 저장해야 한다. | displacement, force, residual, increment/iteration 상태가 step/frame 출력과 연결된다. | state unit test, integration test |
| FESA-PRD-006 | FESA는 solver 결과를 HDF5 authoritative output `results.h5`로 저장해야 한다. | step/frame, field/history, metadata, diagnostics가 schema version과 함께 저장된다. | HDF5 schema test |
| FESA-PRD-007 | FESA는 Abaqus reference CSV rows와 비교 가능한 deterministic row mapping을 제공해야 한다. | displacement, reaction, internal force, stress 등 검증 물리량의 row identity와 tolerance source가 명확하다. | reference comparison report |
| FESA-PRD-008 | FESA의 production C++ 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현해야 한다. | 관련 C++ test file이 있고 Harness TDD guard를 통과한다. | hook test, CTest |
| FESA-PRD-009 | FESA는 외부 라이브러리 API를 solver core에 직접 노출하지 않아야 한다. | MKL, TBB, HDF5 의존은 adapter module에 제한된다. | architecture review, dependency review |
| FESA-PRD-010 | FESA 기능 완료는 reference comparison과 physics sanity 통과를 요구해야 한다. | 수치 tolerance와 물리 검토가 모두 pass이고 known limitation이 기록된다. | verification report, physics evaluation report |

## 비기능 요구조건
- MSVC x64 Debug 환경에서 configure, build, CTest를 검증한다.
- reference test 결과는 deterministic해야 한다.
- HDF5 schema는 versioned contract로 관리한다.
- tolerance policy는 absolute, relative, norm-based 기준을 구분한다.
- parser, solver, HDF5 writer는 실패 원인을 구조화된 diagnostic으로 보고한다.
- oneMKL, oneTBB, HDF5는 CMake에서 명시 탐지하고 실패 원인을 분류한다.
- 대규모 모델 성능 최적화보다 Phase 1 명확성, 테스트 가능성, 검증 traceability를 우선한다.

## Acceptance Gates
1. Requirements approved: 기능 범위, 제외 범위, 입력, 출력, tolerance, 검증 물리량이 정의되어 있다.
2. Research evidence complete: 정식화와 benchmark 근거가 신뢰도와 한계와 함께 정리되어 있다.
3. Formulation reviewed: 약형, shape function, B matrix, constitutive contract, 수치적분, output recovery가 검토되어 있다.
4. I/O contract approved: Abaqus keyword subset, internal model mapping, HDF5 result contract, reference CSV comparison row contract가 승인되어 있다.
5. Tests fail before implementation: 구현 전 실패해야 하는 C++/integration/reference test가 준비되어 있다.
6. CMake/CTest pass: MSVC/x64/Debug 기준 configure, build, test가 통과한다.
7. Reference comparison pass: FESA `results.h5` rows와 Abaqus reference CSV rows가 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준 안에 있다.
8. Physics sanity pass: equilibrium, reaction consistency, displacement direction, symmetry, stress sanity가 검토되어 있다.
9. Release readiness pass: acceptance traceability, known limitations, release notes draft가 준비되어 있다.

## 제외 사항
- Abaqus full parser 호환
- Abaqus, Nastran 또는 reference solver 직접 실행 자동화
- Agent가 Abaqus reference CSV 파일을 임의 생성 또는 수정하는 작업
- GUI 또는 postprocessor
- Visual Studio `.sln`/`.vcxproj` 전용 MSBuild workflow
- Explicit dynamics, contact, plasticity, shell end-to-end 구현
- JavaScript/TypeScript fallback 유지