FESADev/docs/mitc4-shell-feast-eigen/PRD.md

# MITC4 Shell Mass Matrix와 FEAST 고유치해석 PRD

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `coordinator-agent`
- Input contract revision: `r2`
- 검토 상태: r2 requirements부터 implementation-planning까지 6개 gate pass; execution-prep attempt1은 지정 Hook 설정 쓰기 거부로 blocked-environment. 부분 runtime/test 변경과 미검증 test 수정을 보존하며 solver 구현·실제 reference 비교는 미실행이다.

기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md), [프로젝트 ADR](../ADR.md).
지역 지침과 문서 목록은 [FEATURED_AGENTS.md](FEATURED_AGENTS.md), 상태 원본은 [coordination.md](coordination.md)를 따른다.

## 사용자 요구

1. MITC4 Shell 요소의 Mass Matrix를 구현한다.
2. 고유치해석 procedure를 구현하며 고유치 계산 backend는 Intel MKL FEAST로 한다.
3. `reference/shellNL-eigen-meshfine`에 있는 모델과 결과를 검증 기준으로 사용한다.
4. 외부 reference 검증은 고유치만 비교한다.
5. Coordinator 주도 requirements부터 release-readiness까지 9개 stage를 수행하며 중요한 사안만 인터뷰·검토를 요청한다.
6. Consistent mass를 먼저 계산하고 이를 이용하여 lumped mass를 계산하며, 고유치해석에는 lumped mass를 사용한다.
7. `FESA_GTEST_SOURCE_DIR=C:\git\googletest`를 사용하고 작업 중 완료된 변경을 Git에 커밋한다.
8. 고유치 개수는 `.inp`의 `*FREQUENCY` data를 사용한다. 지정 모델의 요청은 `10`개이다.
9. 기존 drilling stabilization을 좌표 공변적으로 개선하고 영향받는 기존 정적해석과 고유치해석의 재검증까지 범위에 포함한다.

## 범위와 acceptance

입력 semantic model, 질량행렬과 equation 구성, FEAST adapter, procedure state, HDF5 결과 및 고유치 comparison의 end-to-end 기능이 대상이다.
구체적인 질량 정식화, 해석 기준 상태, 모드 요청 의미, 출력량 및 지원 subset은 Requirement Agent가 evidence를 조사하고 후속 owner와 critical decision 절차로 고정한다.
외부 mode-shape 비교, reference 생성·수정·복원과 외부 배포는 요청된 범위에 포함되지 않는다.
MSVC x64 Debug CMake/CTest, TDD, common tolerance, failure preservation과 독립 physics 검토를 적용한다.
Requirement ID별 원본 계약과 검증 matrix는 [requirements.md](requirements.md#requirement-verification-matrix)가 소유한다.

| Requirement IDs (`FEM-REQ-MITC4-EIGEN-`) | Acceptance 요약 및 원본 계약 |
| --- | --- |
| `001`~`004` | [원형상 procedure, 기존 shell mapping, material density와 section 연결](requirements.md#requirement-verification-matrix) |
| `005`~`008` | [질량 이산화 선택, 물리 관성, 조립, massless 좌표 admissibility](requirements.md#requirement-verification-matrix) |
| `009`~`014` | [낮은 모드, multiplicity, FEAST, 실패 처리, 내부 eigenpair 및 physics evidence](requirements.md#requirement-verification-matrix) |
| `015`~`019` | [입력 subset, 진단, HDF5, source/modal identity 및 candidate 보존](requirements.md#requirement-verification-matrix) |
| `020`~`022` | [고유치-only 외부 비교, identity 사전검사 및 common tolerance](requirements.md#requirement-verification-matrix) |
| `023`~`025` | [TDD·MSVC 검증, 기존 정적 회귀 및 동일 revision의 독립 closure](requirements.md#requirement-verification-matrix) |
| `026` | [Consistent에서 lumped 유도 및 질량·관성 불변식](requirements.md#requirement-verification-matrix) |
| `027` | [좌표 공변적인 numerical stabilization 및 영향받는 static/eigen 검증](requirements.md#requirement-verification-matrix) |

Reference는 선행 preload 없는 단일 frequency step의 10모드이며 상세 관찰과 단위 의미는
[requirements evidence](requirements-evidence.md#원본-reference-관찰)에 있다.
두 질량 계산의 연결에 관한 [MFE-ADR-002](ADR.md#mfe-adr-002--mitc4-질량-이산화)는 사용자 후속 요구로 확정되었다.
실제 FEAST mass는 [MFE-ADR-004](ADR.md#mfe-adr-004--feast에-사용하는-질량행렬)에 따라 lumped로 승인되었다. 상세 lumping 수식은 Research/Formulation owner가 정의한다.
Primary-source 근거와 적용 한계는 [research](research.md), 상세 근거는 [research-evidence](research-evidence.md)에 있으며 최종 수식·수치 기준의 승인을 대신하지 않는다.
구현용 수학 계약과 상세 문서의 연결은 [formulation](formulation.md), 고정된 내부 수치 기준은 [NR controls](numerical-review-controls.md), 필수 검증은 [27개 cases](numerical-review-cases.md)에 있다.
[Reference artifact·logical readiness](reference-model.md)와 독립 수학/controls evidence를 함께 확인하여 r2 NR gate를 통과했다.
[I/O 계약](io.md)은 [exact 입력 subset](io-input.md), [additive HDF5와 내부 modal evidence](io-schema.md), [책임·failure·Value projection](io-mapping.md)을 정의했다. Source Step-2와 canonical storage Step-1, 입력 요청 N과 전체 검증 c를 구분하며 기존 static 계약은 보존한다. 구현 계획은 27개 요구와 I/O 검증 obligation을 실제 TDD·full VERIFY·fresh reference 경로에 연결해야 한다.
[실행 계획](implementation-plan.md)은 운영 준비 1개와 main 8개 step으로 구체화했고 [verification mapping](implementation-verification.md)에 요구27/NR27/I/O11 및 필수 test40개를 연결했다. 정확한 owned paths·actual backend·유한 실행시간·fresh solve·등록 Stop 사후 확인은 [환경 계약](implementation-environment.md)과 각 phase step을 따른다. 실제 실행 성공과 독립 physics/release gate는 아직 남아 있다.
r1의 [NR-MFE-001 실패 이력](numerical-review-evidence.md)은 기존 `002/008`의 stabilized pencil 보존과 `014`의 eigen coordinate-invariance evidence 관계였다.
Requirement owner는 알려진 partial-BC 반례를 단순 clarification으로 제외할 수 없다고 판단했다.
[MFE-OQ-003 대안·영향](requirements-evidence.md#nr-mfe-001-requirements-intent-검토) 중 좌표 공변적인 stabilization 개선과 영향받는 정적/eigen 재검증 범위 추가가 사용자에게 승인되었다. 단순 한계 수용 및 acceptance 축소안은 선택되지 않았다.
사용자가 확정한 질량 계산 흐름·FEAST 사용 mass·입력 N·외부 Value-only 범위는 유지한다. 개선 수식과 실제 구현·검증은 해당 owner의 후속 gate를 거쳐야 한다.
기존 fixed scale의 [대체 경계](requirements.md#r2의-기존-계약-대체-범위)와 [필수 static 회귀 포트폴리오](requirements-evidence.md#r2-승인-범위와-정적-재검증)는 Requirement owner r2에 명시되어 있다. 과거 정적 reference의 U/UR 및 reaction 검토 정책은 해당 기존 계약으로 재검증하고 새 eigen 비교량은 Value로 유지한다.
[r2 research delta](research-evidence.md#r07--r2-stabilization-근거와-영향)는 기저 불변 scale 후보, 초기 고정 nonlinear lifecycle 및 linear massless 처리의 조건을 구분한다. 최종 수식 채택과 반례 해소 판정은 후속 owner 소유이다.
[r2 stabilization 정식화](formulation-stabilization.md)는 `k_ref=sum_i trace(R_i)/8`, `k_d=10^-3 k_ref`를 채택하고 양성 inventory·complete K의 공변성·nonlinear 고정 lifecycle 및 반례의 고유치/정적 exact target을 정의한다. NR는 반례를 독립 직접 적분으로 재검산해 r2 수학 계약의 해소를 확인했다. 실제 C++/FEAST 구현 및 fresh reference 재검증은 후속 필수 gate다.