FESA/docs/PRD.md

# PRD: FESA

## 1. 제품 목표

FESA는 Abaqus `.inp` 제한 부분집합으로 정의된 유한요소 모델을 읽고 선형 정적
구조해석을 수행한 뒤, 모델과 절점·요소 결과를 자기완결형 HDF5 파일로 저장하는
C++20/MSVC 기반 내부 검증용 솔버다.

첫 배포는 Abaqus나 Nastran의 기능 범위를 재현하는 것이 아니라 다음 기반을 검증하는
데 목적이 있다.

- 입력에서 결과까지 이어지는 전체 해석 파이프라인
- FEM 정식화를 추적할 수 있는 모듈 구조
- 명시적인 입력·내부 모델·출력 계약
- MKL, TBB 및 HDF5를 격리하는 backend 경계
- 해석해, physics sanity 및 reference 비교가 가능한 TDD 구조

## 2. 대상 사용자와 배포 형태

- 주 사용자: FESA를 개발하고 검증하는 1인 개발자
- 배포 대상: 개발팀 내부 검증 환경
- 산출물: 정적 해석 코어 라이브러리, CLI, 예제 입력, HDF5 schema 문서,
  reference 데이터 및 검증 보고서
- 일정: 고정 기한보다 단계별 완료 조건과 품질 게이트를 우선한다.

## 3. Phase 1 기능 범위

### 3.1 해석

- 소변형 선형 정적 해석
- 단일 `*STEP`과 단일 `*STATIC` 하중 케이스
- 약 10만 자유도 이하
- 비영 지정 변위·회전을 포함한 essential boundary condition
- 일관 단위계 사용; FESA 내부 단위 변환 없음

### 3.2 요소와 정식화

- 2절점 직선 3D Isoparametric Timoshenko Beam
- 절점당 자유도:
  \(u_x,u_y,u_z,\theta_x,\theta_y,\theta_z\)
- 선형 형상함수와 자연좌표 \(\xi\in[-1,1]\)
- 선택적 감차적분:
  - 축·굽힘·비틀림 항: 2점 Gauss 적분
  - 전단 항: 1점 Gauss 적분
- 등방성 선형 탄성:
  - 입력: \(E,\nu\)
  - 계산: \(G=E/[2(1+\nu)]\)
- 일반 단면 semantic property:
  \(A,I_y,I_z,J,A_{sy},A_{sz}\)
- 도심과 전단중심이 일치하는 주축 단면
- \(I_{yz}=0\), 단면 오프셋과 워핑 없음
- 요소축과 평행하지 않은 국부 단면 기준 방향 벡터 필수
- 여러 재료와 여러 단면을 `ELSET`별로 할당

### 3.3 Abaqus 입력 부분집합

입력은 다음 두 조직 중 하나를 사용한다.

- 전역 절점·요소로 구성된 flat/orphan mesh
- 여러 Part 정의와 좌표변환이 없는 단일 Assembly·단일 Instance

계층형 입력에서는 Assembly의 Instance가 참조하는 Part만 해석에 사용한다. 사용되지
않는 Part는 파싱하지만 해석 `Domain`에 포함하지 않는다. 외부 entity는
`(instance name, part-local label)`로 식별하고 내부 dense index와 분리한다.

필수 지원 대상:

- `*NODE`
- `*ELEMENT, TYPE=B31`
- `*PART`, `*END PART`
- `*ASSEMBLY`, `*END ASSEMBLY`
- `*INSTANCE`, `*END INSTANCE`
- `*NSET`, `*ELSET`
  - 명시적 ID 목록
  - `GENERATE`
  - 기존 집합을 참조하는 중첩 집합
- `*MATERIAL`, `*ELASTIC`
- `*BEAM GENERAL SECTION, SECTION=GENERAL`
- `*TRANSVERSE SHEAR STIFFNESS`(선택)
- `*BOUNDARY`
- `*CLOAD`
- `*STEP`, `*STATIC`, `*END STEP`

계층형 입력은 좌표변환이 없는 단일 Instance만 허용한다. 여러 Assembly/Instance,
Instance 평행이동·회전, instance-local mesh 수정 및 flat/계층 mesh 혼합은 파일
위치와 원인을 포함한 diagnostic으로 거부한다. Part 집합과 Assembly 집합은 scope를
구분하며, Assembly의 `INSTANCE=` 집합을 활성 Part의 로컬 ID에 연결한다.

파서는 Abaqus syntax를 semantic model로 변환한다. `*HEADING`, `*PREPRINT`,
`*RESTART`, `*OUTPUT`은 명시적으로 지원하는 no-op directive로 처리한다. 그 밖의
지원하지 않는 keyword나 option을 묵시적으로 무시하지 않는다.

명시적 전단강성이 있으면 FESA의 \(A_{sy},A_{sz}\)를 재료의 \(G\)와 일관되게
구성한다. 생략되면 \(A_{sy}=A_{sz}=5A/6\)과 `SCF=0`을 Phase 1 기본값으로
적용한다. 명시된 `SCF`가 0이 아니면 미지원 입력으로 거부한다.

### 3.4 하중과 경계조건

- `*BOUNDARY`: 6개 절점 자유도의 0 또는 비영 지정값
- `*CLOAD`: 절점 집중력과 집중모멘트
- 지정값이 중복되거나 충돌하면 semantic validation 오류
- 분포하중, 중력, 압력 및 follower load는 제외

### 3.5 결과

절점 결과는 전역좌표계로 출력한다.

- 변위와 회전
- 반력과 반력모멘트

요소 결과는 요소 국부좌표계로 출력한다.

- 단면력 \(N,V_y,V_z,T,M_y,M_z\)
- 대응 단면변형률
- 사용자 지정 단면 회복점 \((y,z)\)에서 축력과 이축 굽힘에 의한
  \(\sigma_{xx}\)
- 요소별 국부 기저 벡터
- 계층형 입력의 Part/Instance 이름과 part-local ID

점별 전단응력과 비틀림응력은 단면 형상 정보 없이는 유일하게 복원할 수 없으므로
Phase 1에서 출력하지 않는다.

HDF5 결과는 다음 정보를 함께 갖는 자기완결형 파일이어야 한다.

- schema와 FESA 버전
- 원본 입력 식별 정보
- 절점, 요소, 집합, 재료 및 단면
- 외부 ID와 내부 dense index mapping
- step과 solver 설정
- 적용된 전단강성과 입력값/기본값 출처
- 절점·요소 결과
- 수렴·평형·solver diagnostic

## 4. 수치해법과 병렬화 요구사항

- 지정 자유도 소거 후 reduced equation system을 구성한다.
- 소거 전 평형식 \(r=Ku-f\)를 이용해 반력을 복원한다.
- 전역 강성행렬은 대칭 CSR로 저장한다.
- MKL PARDISO 대칭 양정치 직접해법을 기본 backend로 사용한다.
- oneTBB는 요소 강성·하중·결과 계산과 조립 전처리에 사용한다.
- 선형해법 실행 중에는 외부 TBB 작업을 중첩하지 않고 MKL 내부 병렬화를 사용한다.
- 부동소수점 contribution의 병합 순서를 고정해 같은 설정에서 재현 가능한 결과를 낸다.

## 5. 검증 요구사항

### 5.1 검증 계층

1. 단위 테스트
   - 형상함수 partition of unity
   - Jacobian과 Gauss 적분
   - 국부 기저 직교성
   - 좌표변환
   - 요소 강성 대칭성
2. 정식화 테스트
   - 강체운동에서 무변형
   - 축력, 비틀림, 단축 및 이축 굽힘
   - 전단 지배 문제
   - 세장비 변화와 shear locking
3. 통합 테스트
   - 입력 파싱부터 HDF5 출력까지 전체 파이프라인
   - 평형 \(Ku-f-r\)
   - 비영 지정 변위
   - 여러 재료·단면과 중첩 집합
4. Reference 테스트
   - Abaqus/Standard 2024 B31 결과
   - 현재 캔틸레버의 변위, 반력 및 요소 단면력
   - 요소 절점 단면 도심 응력 비교 계약의 synthetic CSV 검증

### 5.2 골든 데이터

Abaqus는 CI나 Harness에서 자동 실행하지 않는다. 별도 Abaqus 2024 환경에서 수동으로
생성한 입력과 CSV 결과를 `reference/<model-id>/`에 보관하며 per-model metadata
파일은 요구하지 않는다.

비교 실행은 물리량과 해당 CSV 경로를 명시한다. 요청한 파일이 없으면 실패하고,
요청하지 않은 물리량은 통과로 보고하지 않는다. 현재 `reference/cantilever beam`
샘플은 변위, 반력 및 요소 단면력을 비교한다. 요소 응력 CSV가 추가되기 전까지
해당 reader와 비교 kernel은 synthetic CSV로 검증한다.

FESA 정식화 적합성과 Abaqus 결과 상관성은 별도 gate로 운영한다. FESA 적합성
gate는 `SCF=0`, 선택적 감차적분 및 문서화된 FESA 정식화를 해석해와 physics
invariant로 엄격히 검증한다. Abaqus 상관성 gate는 `SCF=0.25`를 포함할 수 있는
원본 Abaqus 모델과 CSV를 보존하고, 동일한 기하·재료·하중에 `SCF=0`을 적용한
별도 FESA 입력을 production pipeline으로 해석해 결과 차이를 정량화한다. 상관성
gate는 서로 다른 정식화의 수치 일치를 주장하지 않는다.

CSV 식별 및 값 열:

- 변위: `Part Instance Name`, `Node Label`, `U-U1..U-U3`, `UR-UR1..UR-UR3`
- 반력: `Part Instance Name`, `Node Label`, `RF-RF1..RF-RF3`, `RM-RM1..RM-RM3`
- 요소 내력: `Part Instance Name`, `Element Label`, `Node Label`,
  `SF-SF1..SF-SF3`, `SM-SM1..SM-SM3`
- 요소 응력: `Part Instance Name`, `Element Label`, `Node Label`, `Sxx`

단일 Instance에서는 `Part Instance Name` 열을 생략할 수 있다. Abaqus Beam의
단면축 \((\mathbf n_1,\mathbf n_2)\)를 FESA의 \((\mathbf e_y,\mathbf e_z)\)와
일치시킨 입력에서 요소 내력은 Abaqus CSV 순서를
`SF1,SF3,SF2,SM3,SM1,SM2`로 재배열해 FESA의
\(N,V_y,V_z,T,M_y,M_z\)와 비교한다. 응력은 요소 절점의 단면 도심값
\(\sigma_{xx}=N/A\)를 비교한다.

### 5.3 허용오차

- FESA 단위·정식화 적합성 gate는 정규화된 엄격한 tolerance를 사용한다.
- 정식화가 일치하는 reference 비교의 기본 상대오차는 \(10^{-5}\)로 한다.
- Abaqus B31과 FESA Beam의 정식화가 다른 상관성 gate는 component별 RMSE와
  Relative L2를 보고한다. 물리량과 component가 다른 값을 하나의 norm으로
  혼합하지 않는다.
- component \(c\)의 값 쌍을 \((F_{ic},A_{ic})\), characteristic absolute scale을
  \(s_c\)라 하면

  \[
  \operatorname{RMSE}_c=
  \sqrt{\frac{1}{n}\sum_i(F_{ic}-A_{ic})^2},\qquad
  \operatorname{RelativeL2}_c=
  \frac{\sqrt{\sum_i(F_{ic}-A_{ic})^2}}
       {\max\left(\sqrt{\sum_iA_{ic}^2},\sqrt{n}s_c\right)}.
  \]

- Abaqus 상관성 gate의 성공은 요청된 모든 entity/component가 매칭되고 유한한
  metric이 생성됨을 뜻한다. 관측된 단일 샘플에 맞춘 임의 pass/fail tolerance는
  두지 않는다. 이후 acceptance envelope를 추가하려면 해석적 또는 mesh study
  근거와 함께 `docs/VALIDATION.md`에 사전 기록한다.

## 6. 개발 워크플로우

각 기능은 다음 게이트를 순서대로 통과한다.

1. 요구조건과 완료 기준 정의
2. 책, 논문 및 공식 문서 조사
3. FEM 정식화, 가정, 좌표계, 부호 및 적분 규칙 작성
4. 입력·semantic model·HDF5 데이터 계약 정의
5. 실패하는 테스트와 개발 솔버/Abaqus 모델 작성
6. 테스트를 통과하는 최소 코드 구현
7. 현재 Abaqus 변위·반력 비교와 요소 내력·응력 비교 루틴 검증
8. tolerance 및 physics sanity 통과
9. 내부 배포

파이프라인 수직 슬라이스를 먼저 완성하지만, 이는 수치적으로 자격이 검증된 배포를
의미하지 않는다. 요소 정확도와 Abaqus 비교 게이트까지 통과해야 Phase 1이 완료된다.

## 7. 제외 범위

- Truss, bar, plane, solid, shell 및 다른 Beam 요소
- 여러 step과 하중 이력
- 여러 Assembly/Instance, Instance 평행이동·회전 및 instance-local mesh 수정
- 분포하중, 압력, 중력 및 체적력
- MPC, RBE2, RBE3, penalty 및 Lagrange multiplier constraint
- 기하·재료 비선형, 접촉, 좌굴, 모달, 동적 및 열전달
- 소성, 직교이방성 및 사용자 재료
- 단면 오프셋, 곱관성모멘트, 전단중심 편심 및 워핑
- 점별 전단·비틀림 응력
- 단위 변환
- 외부 고객용 installer와 API 호환성 보장

## 8. 내부 배포 수용 조건

- MSVC Debug와 Release 구성에서 새 경고 없이 빌드
- 모든 GoogleTest/CTest와 Harness 검증 통과
- 테스트 0개 수집이 아님을 확인
- 전체 입력-해석-출력 통합 테스트 통과
- physics sanity와 평형 잔차 기준 통과
- FESA Beam 정식화 적합성 gate의 엄격한 tolerance 통과
- 현재 Abaqus 2024 변위·반력·요소 단면력과의 component별 RMSE 및 Relative L2
  상관성 보고서 생성
- 요소 내력·도심 응력 CSV adapter와 비교 kernel의 synthetic 검증 통과
- HDF5 schema, 입력 부분집합, 정식화 및 검증 보고서 제공