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

# MITC4 Shell Mass·FEAST Eigen 2 PRD

- Feature ID: `mitc4-shell-feast-eigen2`
- Owner: 메인 assistant
- Requirement baseline revision: `r2` (022의 외부 accuracy 기준 변경)
- 상태: **사용자 승인 첫 구현 완료**. 전체 417개 검사와 모드별 외부5% 비교, 독립 수치 검토를 통과했다. S3와 후속 정확도 개선은 보류한다.

기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
[공통 ADR](../ADR.md#adr-028). 지역 지침은 [FEATURED_AGENTS](FEATURED_AGENTS.md),
결정 근거는 [Feature ADR](ADR.md)을 따른다.

## 사용자 요청과 적용 범위

2026-09-08 사용자는 기존 작업을 `mitc4-shell-feast-eigen2`라는 이름으로 requirement부터
다시 시작하고, 기존 `docs/mitc4-shell-feast-eigen/`의 유용한 문서를 참고하며 작업 중
변경사항을 Git에 커밋하도록 요청했다. 이어 **모든 단계를 진행하지 말고 requirement
단계만 진행**하도록 범위를 명시했다.

이후 사용자가 **research부터 io-definition까지** 진행하도록 요청했다. 당시 범위는 research,
formulation, 독립 numerical review, I/O 계약 문서와 단계별 커밋이다. 구현 계획·코드,
solver build/test·reference 비교와 release 감사는 포함하지 않는다.
별도 coordinator나 phase 상태기계를 만들지 않는다.

작업시간 제한은 30분이다. 시작은 2026-09-08 12:07:56 UTC이며 12:37:56 UTC에 도달하면
진행 중인 작업을 중지하고 실제 완료·미완료 항목과 지연 이유를 보고한다.

2026-09-09 KST 사용자는 **implementation 단계를 진행**하도록 요청하고 **implementation
단계의 30분 제한은 없다**고 명시했다. 현재 범위는 [구현 계획](implementation-plan.md)에 따른
코드·테스트·실제 FEAST 및 필수 reference/회귀 검증과 작업별 커밋이다. 앞의 30분 제한은
완료된 문서 작업의 이력이다. 원본 reference 생성·변경과 release는 포함하지 않는다. Push는 아래 후속 요청으로 승인되었다.

2026-09-10 사용자는 FEAST 종료 조건을 trace에서 residual로 변경하고 S3는 추후 고려하도록
명시했다. [ADR-011](ADR.md#mfe2-adr-011--feast-residual-stopping과-s3-후속-분리)에 따라 backend·저장 control 검증·관련 문서를 갱신하며,
기존 독립 잔차와 외부 tolerance, 질량·drilling 수식은 유지한다.

이어 사용자는 “5% 이내면 첫 구현이므로 Abaqus와의 고유치 정확도 향상은 추후에 진행”하고
구현을 마무리하도록 요청했다. [ADR-012](ADR.md#mfe2-adr-012--첫-구현의-외부-고유치-5-수용)의
모드별 외부5% 정책을 적용하고 나머지 필수 검증을 보강한다. S3 보류는 유지한다.

사용자는 구현과 검증 완료 후 `dev` 병합 및 push도 명시 승인했다. 관련 변경을 커밋하고
검증한 tree를 `dev`에 병합한 뒤 원격 `dev`에 반영한다. 기존 사용자 변경과 reference 원본은 보존한다.

## 솔버 기능의 요구 범위 요약

기존 사용자 결정에 기록된 다음 의미를 새 요구사항의 출발점으로 사용한다.
승계 근거와 후속 전문 판단 경계는 [ADR](ADR.md)에 기록한다.

1. MITC4 shell consistent mass를 계산하고 그 결과로부터 lumped mass를 유도한다.
2. 실제 무감쇠 선형 고유진동 해석은 derived lumped mass와 Intel MKL FEAST를 사용한다.
3. 원형상·무응력 상태와 승인된 shell/constraint 범위를 대상으로 하며, requested mode count는 `.inp`의 `*FREQUENCY`에서 얻는다.
4. 지정 `reference/shellNL-eigen-meshfine`의 기존 입력·고유치 TXT를 보존하고 외부 eigen 비교는 `Value`만 사용한다. Mode shape는 내부 검증 대상이며 외부 acceptance를 추가하지 않는다.
5. 좌표 공변적인 numerical drilling stabilization 개선과 영향받는 기존 선형·비선형 정적 및 새 eigen 검증을 포함한다. 기존 물리 kernel·source identity·output 의미·공통 tolerance는 보존한다.
6. `reference/temp`로 제외된 예제는 검증에 사용하지 않는다. 남는 정적 회귀와 내부 물리 검증 의무를 명시한다.

지속할 상세 계약이 필요하므로 요구사항과 verification matrix 원본은
[requirements.md](requirements.md)에 둔다. 이 PRD에는 수식·threshold·schema를 중복 정의하지 않는다.

## Acceptance 요약과 원본

아래 ID는 `FEM-REQ-MITC4-EIGEN2-` prefix를 생략하며 링크는 상세 matrix의 원본을 가리킨다.

| 영역 | Requirement IDs | 요구되는 결과와 검증 의도 |
| --- | --- | --- |
| 입력·물리 범위 | [001~004, 015~016](requirements.md#requirement-verification-matrix) | 밀도·section·geometry·boundary·mode 요청의 의미를 보존하고 미지원 조합을 명확히 진단 |
| 질량·stabilization | [005~008, 014, 026~027](requirements.md#requirement-verification-matrix) | 두 질량의 유도 관계, 물리 관성·drilling null, 대칭성·에너지·좌표 공변성 검증 |
| FEAST·modal evidence | [009~013](requirements.md#requirement-verification-matrix) | 실제 backend, 낮은 N개·multiplicity, 동일 사용 질량의 residual·normalization·orthogonality 및 실패 보존 |
| 결과·reference | [017~022](requirements.md#requirement-verification-matrix) | HDF5 source/mode identity, Value-only 대응, completeness·finite 사전검사와 공통 tolerance |
| 회귀·완료 | [023~025](requirements.md#requirement-verification-matrix) | 제외 예제를 사용하지 않는 남은 static·내부 물리 검증, 필요한 실제 실행 evidence와 미실행의 구분 |

각 영역의 원자적 ID·검증 방법·출처는 requirements 및 [근거 문서](requirements-evidence.md)를 따른다.
과거 문서의 `pass`, 362/352 test count나 stage 완료를 이 baseline의 실행 결과로 사용하지 않는다.

## 현재 checklist

- [x] 새 Feature ID·작업 브랜치와 requirement-only 범위를 설정한다.
- [x] 기존 자료의 참고·승계·후속 재검토 경계를 정한다.
- [x] Requirement specialist가 새 요구사항·verification matrix와 근거를 작성한다.
- [x] 메인이 사용자 요구 coverage, 전문 owner 경계와 미해결 사항을 정적으로 확인한다.
- [x] 상대 링크·ID를 검사하고 커밋 대상이 새 Feature 문서 5개뿐인지 확인한다.

- [x] Research: [연구](research.md)와 [근거](research-evidence.md)에 일차 출처·질량/축소/stabilization 후보 및 실제 runtime 확인이 필요한 FEAST 두 항목을 기록했다.
- [x] Formulation: [정식화](formulation.md)에 질량·공변 stabilization·constraint-first 축소·FEAST·복구 수학 계약을 작성했다. 독립 numerical review는 별도 항목이다.
- [x] Numerical review: [독립 검토](numerical-review.md)는 `pass-for-io-definition`이다. 새 수학 oracle 2개와 27개 verification cases, 내부 controls 및 Value-only reference family를 정의했다. 실제 solver 검증은 미실행이다.
- [x] I/O definition: [I/O 계약](io.md)에 입력·진단·additive eigen schema·source step/mode mapping·실패 보존과 검증 의무를 정의했다.
- [x] 신규 문서의 링크·계약 일관성, 27개 요구사항의 NR/I/O coverage와 변경 범위를 정적으로 확인하고 단계별 변경을 커밋한다.

이 checklist는 문서 작업 상태다. Solver 구현·실제 FEAST 실행·회귀 및 외부 reference 비교의 통과를 뜻하지 않는다.

- [x] 질량·stabilization과 독립 analytical/invariant 테스트 구현·검증. S3 public static 충돌은 아래 후속 항목으로 분리한다.
- [x] 실제 FEAST backend·count/cluster/zero/실패 controls와 runtime 검증. 실행한 대표 실패 경로와 미주입 한계는 결과 보고서에 구분한다.
- [x] Density/Frequency semantic·source identity·진단 및 입력 테스트. 기존 정적 PREPRINT 회귀를 보존했다.
- [x] Constraint-first 축소·modal recovery·별도 eigen state/procedure 구현.
- [x] HDF5 additive schema·candidate 보존·Value comparator 및 통합 테스트.
- [x] 제외 예제 사용 없이 남는 static/내부 회귀·전체 build/test·필수 reference 실행: 417/417 PASS.
- [x] 관련 독립 numerical/physics 확인과 결과·한계 기록. 첫 구현 독립 판정은 승인된 범위에서 PASS다.

- [x] 승인된 FEAST residual stopping과 HDF5 control 검증을 함께 적용하고 변경 전 실패·변경 후 검사를 확인한다.
- [x] 원본 eigen의 전체 c개 독립 잔차·복구·HDF5 생성을 확인하고 종료 제어의 독립 수치 검토를 받는다.
- [x] 원본 eigen 10개 Value가 사용자 승인 모드별5% 기준을 충족한다. 최대 상대오차는 약4.261331%다.

후속 보류 항목:

- [ ] Abaqus와의 외부 Value 정확도를 개선한다. 이전 RMS1% 기준의 Mode2–10 불일치는 이력으로 보존한다.
- [ ] S3 public static 정적 평형 계약 충돌은 사용자 요청에 따라 후속 검토한다.

현재 구현·실행은 [implementation-verification](implementation-verification.md)에 기록했다.
실제 mass/reduction/FEAST/procedure/HDF5 경로와 전체 실행을 확인했고 원본 eigen의 전체 c
residual 실패는 residual stopping으로 해소했다. [첫 구현 독립 검토](implementation-first-version-review.md)는
승인된5%·S3 보류 범위에서 PASS다. 실제512회 vendor 호출과 HDF5 close-error 주입은 수행하지
않았으며 대표 실패 경로·정적 대조의 범위를 보고서에 기록했다. 기존 nonlinear recovery 문제와
제외 pressure 예제의 coverage 부재를 해결한 것으로 해석하지 않는다.

## 이전 문서 단계의 결과와 구현 입력

Research부터 I/O까지 요청한 문서 작업과 독립 수학 검산을 30분 제한 안에 완료했다.
19개 Feature 문서의 링크·UTF-8·diff와 27개 요구/검증 case identity·coverage를 확인했다.
기존 Feature/phase의 사용자 변경 16개는 보존했다. Source·test·config·reference는 변경하지 않았다.

다음 작업의 입력은 [정식화](formulation.md), [독립 검토](numerical-review.md),
[controls](numerical-review-controls.md), [cases](numerical-review-cases.md), [I/O](io.md)다.
문서 단계 종료 당시 Density/Frequency semantic·mass/FEAST·eigen state/writer 구현, 실제
backend와 MSVC build/test·reference·물리 검증은 미실행이었다. 현재 사용자가 승인한 구현은
[implementation-plan](implementation-plan.md)에 따라 이 후속 실행을 포함하며, 진행 상태는
위 checklist를 따른다. Pressure 제외 예제의 fresh 외부 coverage 부재는 유지한다.