docs: add FESA extension guidance

This commit is contained in:
KOKO\Mimi
2026-08-10 16:34:20 +09:00
parent 05f11943a5
commit 4bb05d23eb
6 changed files with 487 additions and 154 deletions
+27 -3
View File
@@ -15,13 +15,26 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
1. Abaqus `.inp` keyword subset parser와 내부 `Domain` semantic model 생성
2. `AnalysisModel`, `DofManager`, `AnalysisState` 기반의 step별 equation system 구성
3. 선형 정적 해석을 시작점으로 하는 `Analysis` procedure 계층
4. 요소, 재료, 경계조건, 하중의 runtime-polymorphic base interface
4. Stable source identity를 보존하는 concrete V0 node, B33 element, material, section, boundary, load record
5. sparse matrix pattern 생성, 전역 행렬/벡터 조립, 제약조건 적용
6. `LinearSolver` adapter를 통한 MKL PARDISO backend와 향후 iterative solver 확장
6. `LinearSolver`, `ParallelFor`, `ResultsWriter` interface를 통한 MKL PARDISO, oneTBB, HDF5 backend 격리
7. HDF5 기반 versioned step/frame field-result 저장과 향후 history-output 확장 경계
8. FESA HDF5 rows와 `reference/<model-id>/` 아래 Abaqus reference CSV rows의 직접 비교
9. CMake/MSVC/x64/Debug, CTest 기반 개발 검증
Element/material 계층의 일반적인 runtime polymorphism, iterative solver, history output은 장기 확장 방향이다. 현재 제품 계약으로 간주하지 않으며, 실제 사용 사례와 성능·수명 요구가 승인되기 전에 추상 base class를 미리 추가하지 않는다.
## 사용자 관점 제품 흐름
1. 사용자는 승인된 Abaqus `.inp` subset으로 모델과 단일 analysis step을 기술한다.
2. FESA는 syntax를 읽은 뒤 semantic mapping과 model validation을 수행한다. 지원하지 않는 모델 의미는 구조화된 diagnostic과 안정된 exit code로 거부한다.
3. 해석 procedure는 active model view, DOF/equation map과 sparse system을 만들고, essential constraint elimination을 적용해 선형계를 factorize하고 substitution한다.
4. FESA는 full displacement를 복구하고 equilibrium residual/reaction과 element 결과를 계산한다.
5. 성공 시 output request와 무관한 mandatory 결과, metadata와 diagnostic을 versioned `results.h5`에 기록한다. 실패 시 불완전한 최종 결과 파일을 정상 결과처럼 남기지 않는다.
6. 검증 workflow는 HDF5 row를 승인된 Abaqus reference CSV identity에 투영해 tolerance를 판정하고, 별도로 equilibrium과 물리적 타당성을 검토한다.
Parser keyword, element kernel, solver backend 또는 output dataset 중 하나만 추가된 상태는 end-to-end 제품 기능이 아니다. 같은 기능의 입력 의미부터 외부 결과와 검증까지 연결되어야 한다.
## V0 범위
- 선형 정적 해석 파이프라인 구현
- 승인된 첫 end-to-end 기능: 2절점 3D EulerBernoulli beam, Abaqus `TYPE=B33`
@@ -59,6 +72,17 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
- 승인된 `reference/cantilever beam/` B33 결과와 displacement, reaction, section resultant
comparison; beam stress reference comparison은 N/A
## 신규 기능의 제품 완료 정의
새로운 element, load, constraint, material, analysis procedure 또는 output quantity는 다음 조건을 모두 만족할 때 FESA 제품 기능으로 취급한다.
1. 지원 범위와 제외 범위, 실패 category, units/coordinates/identity, tolerance가 요구조건과 I/O 계약에 명시되어 있다.
2. 필요한 FEM 정식화와 recovery/sign convention이 검토되었고, 수치 위험과 검증 문제를 numerical review가 다룬다.
3. Syntax와 semantic mapping이 내부 모델에 안정된 source identity로 연결되며 잘못된 입력을 fail-closed로 거부한다. Kernel만 제공하는 기능은 parser/CLI 지원 여부를 별도로 표시한다.
4. DOF, sparse pattern, assembly, constraint, solver lifecycle과 mutable state ownership이 기존 아키텍처에 연결되거나 승인된 새 procedure 경계를 가진다.
5. Mandatory HDF5 schema와 diagnostic, CLI 실패 의미가 정의되고 failure path가 기존 state 또는 최종 output을 오염시키지 않는다.
6. Unit test가 local 수식과 validation을, integration test가 orchestration과 외부 계약을, reference comparison과 physics sanity가 수치·물리 타당성을 각각 증명한다. Reference가 N/A이면 그 이유와 대체 evidence를 명시한다.
## 기능 요구조건
| ID | 요구조건 | Acceptance Criteria | Verification Method |
| --- | --- | --- | --- |
@@ -91,7 +115,7 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
`1e-3`이며 relative coefficient는 `1e-6`이다.
- parser, solver, HDF5 writer는 실패 원인을 구조화된 diagnostic으로 보고한다.
- oneMKL, oneTBB, HDF5는 CMake에서 명시 탐지하고 실패 원인을 분류한다.
- 대규모 모델 성능 최적화보다 Phase 1 명확성, 테스트 가능성, 검증 traceability를 우선한다.
- 대규모 모델 성능 최적화보다 V0의 명확성, 테스트 가능성, 검증 traceability를 우선한다.
## Acceptance Gates
1. Requirements approved: 기능 범위, 제외 범위, 입력, 출력, tolerance, 검증 물리량이 정의되어 있다.