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

# MITC4 Shell Mass Matrix와 FEAST 고유치해석 요구사항

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `requirement-agent`
- Input contract revision: `r1`
- 검토 상태: consistent→lumped→FEAST 사용자 확정 요구 반영; requirements baseline gate 검토 요청.
- 요청 outcome: `pass`; workflow 전이와 최종 gate 판정은 Coordinator 소유.

지역 입력은 [FEATURED_AGENTS](FEATURED_AGENTS.md), [PRD](PRD.md), [ADR](ADR.md)이다.
[프로젝트 지침](../../AGENTS.md), [제품 요구사항](../PRD.md),
[ARCHITECTURE](../ARCHITECTURE.md), [공통 ADR](../ADR.md),
[TOLERANCE](../TOLERANCE.md), [agent 계약](../SOLVER_AGENT_DESIGN.md),
[문서 소유권](../FEATURE_DOCUMENTATION.md)을 적용한다.
Reference 관찰, 원문 경로·hash, 중요한 결정의 대안과 명령 evidence는
[requirements-evidence.md](requirements-evidence.md)에 둔다.

## 핵심 결과와 범위

지정된 reference는 이름에 `shellNL`이 있지만 선행 정적 해석 없이 원형상에서 수행하는
단일 무감쇠 선형 고유진동 해석이다. `Step-2`에서 10개 모드를 요청하고 모든 외곽 절점의
DOF 1~6을 고정한다. 기존 TXT에는 고유치 `Value`와 주파수 `Freq`가 분리되어 있으며
Mode 1~10을 일대일 식별할 수 있다. 파일 형식 때문에 CSV를 새로 만들지 않는다.

사용자 후속 요구로 consistent mass를 먼저 계산하고 이를 이용하여 lumped mass를 계산한 뒤
FEAST 고유치해석에 lumped mass를 사용한다. 이 계산 흐름과 reference baseline이 확정되었다.
나머지는 명시된 사용자 요구, 실제 reference와 기존 승인된 shell 계약에서 도출한다.

- 원형상·무응력 상태의 단일 `*FREQUENCY` procedure, homogeneous essential constraints,
  실수 무감쇠 고유치와 이에 대응하는 내부 modal vectors.
- 기존 MITC4의 막·굽힘·횡전단, 단일층 균질 등방성 탄성, centered constant-thickness
  section, geometry-derived director, source `S4`/`S4R`와 전역 6 DOF 의미를 재사용한다.
- 활성 재료마다 양의 유한한 일정 체적 밀도를 해석 모델에 연결한다. 질량은 병진과
  director 접평면의 두 물리 회전 관성을 나타내며 drilling을 물리 관성으로 승격하지 않는다.
- Consistent mass와 그 행렬에서 유도한 lumped mass를 모두 계산·검증한다. Lumping 방식과
  좌표/회전 block 처리는 Research/Formulation이 정의하며 두 spectrum의 동일성을 요구하지 않는다.
- FEAST, modal residual·mass normalization·orthogonality와 외부 고유치 비교는 동일한
  derived lumped mass를 기준으로 한다. Consistent는 계산 원본과 내부 질량 검증에 유지한다.
- Mode count를 지정하는 최소 입력 subset과 MKL FEAST 실행을 end-to-end로 연결한다.
  Reference의 blank frequency bounds·shift·Lanczos control fields를 그대로 처리한다.
- 공식 HDF5에 식별 가능한 고유치 결과를 기록하고 내부 modal correctness 증거를 남긴다.
  외부 acceptance는 지정 reference의 고유치만 사용한다.

제외: prestress/선행 nonlinear state 전달, 다중 step, initial stress, geometric stiffness의
새 의미, 재료비선형, 감쇠·복소 고유치, 좌굴, 강제진동·시간적분, acoustic coupling,
혼합 beam/solid/shell 모델, concentrated/nonstructural mass, composite/offset/variable
thickness, 기존 미지원 shell geometry, residual modes 및 modal stress/reaction recovery.
사용자가 지정하지 않은 Lanczos/AMS 대체 backend, reference 생성·수정·복원과 외부 배포도 제외한다.
별도 frequency interval/shift 사용자 기능은 현재 최소 subset에 포함하지 않는다.

## 의미·단위·소유권

| 항목 | 요구되는 의미와 경계 |
| --- | --- |
| 질량 입력 | `rho`: mass/length³; `t`: length. 단위계는 사용자 일관 단위이며 SI 추론·자동 변환 없음 |
| 질량/관성 | 병진 질량 차원 mass, 회전 관성 mass·length²; 혼합 DOF block의 차원은 Formulation이 명시 |
| 고유치 | `lambda = omega²`, 차원 1/time²; 좌표계에 불변인 scalar, cycle frequency와 별개 |
| 주파수 | `f = sqrt(lambda)/(2*pi)`, cycles/time; 양의 고유치에서 의미 확인용 파생량이며 외부 비교 대체량 아님 |
| 모드 | Scalar mode identity와 global DOF/modal vector identity 분리; 진폭은 응답변위가 아닌 normalization convention |
| 모델과 equation | Domain은 density·section·step 정의, AnalysisModel은 non-owning view, DofManager는 DOF·equation·pattern 소유 |
| procedure/backend | Eigen procedure는 자체 state·solve·검증·commit 소유; FEAST vendor 타입과 자원은 private adapter 소유 |
| 결과 | Results는 물리량·identity, I/O Definition은 additive HDF5 schema·modal evidence projection과 진단 소유 |

요구사항은 stiffness/질량 조립식, massless drilling 처리식, FEAST 탐색 구간·subspace 및
solver parameter를 선결정하지 않는다. 특히 기존 선형 정적 `Run()`에 eigen 분기를 누적하거나
정적 reaction 의미를 modal 결과로 재사용해서는 안 된다.

## Requirement Verification Matrix

모든 행은 `must`이고 acceptance는 해당 행의 요구와 검증 조건을 모두 만족하는 것이다.
출처 `U`는 [Feature PRD](PRD.md)의 사용자 요구, `R`은 [관찰 evidence](requirements-evidence.md),
`P`는 위 공통 기준, `L`은 [기존 MITC4 요구사항](../linear-static-mitc4-shell/requirements.md)과
[정식화](../linear-static-mitc4-shell/formulation.md), `N`은
[기존 nonlinear I/O](../nonlinear-static-newton-raphson/io.md)의 공통 경로·failure 계약을 뜻한다.
`NR`은 Numerical Review를 뜻하며 numerical threshold/metric/family 결정은 NR 소유이다.
아래에서 “승인 기준”은 구현 전에 해당 owner가 명시해 gate를 통과해야 하며 실행 결과로 조정하지 않는다.

| Requirement ID | Shall statement | 측정 가능한 acceptance / verification method | 출처·후속 owner |
| --- | --- | --- | --- |
| FEM-REQ-MITC4-EIGEN-001 | 솔버는 선행 상태 없는 원형상 무응력 모델의 단일 무감쇠 선형 고유진동 procedure를 실행해야 한다. | 지정 reference가 한 frequency step으로 선택되고 static/nonlinear preload 경로를 호출하지 않음; procedure 통합 테스트 | U, R, P; Formulation, I/O |
| FEM-REQ-MITC4-EIGEN-002 | `S4`와 `S4R`는 기존의 동일한 FESA MITC4 물리 kernel·director·전역 6 DOF 의미를 유지해야 한다. | 동일 모델의 source type만 변경한 경우 같은 질량·고유치 경로와 별도 source metadata; mapping/kernel 테스트 | L; Formulation, I/O |
| FEM-REQ-MITC4-EIGEN-003 | 모든 활성 shell의 밀도는 해당 section이 참조하는 material에서 하나의 finite `rho > 0`로 결정되어야 한다. | 여러 material의 올바른 연결 및 missing/duplicate/unresolved/nonpositive/nonfinite/dependent density 거부; semantic 양성·음성 테스트 | U, R, P; I/O |
| FEM-REQ-MITC4-EIGEN-004 | 질량 계산은 기존 shell의 유효한 geometry·director와 양의 centered constant thickness를 사용해야 한다. | 기존 geometry/material/section 검증 재사용과 서로 다른 두께·밀도 연결 테스트; 부적합 요소를 질량 zero로 우회하지 않음 | L, P; Formulation, I/O |
| FEM-REQ-MITC4-EIGEN-005 | 솔버는 MITC4 보간에 일관된 consistent mass를 계산하고 derived lumped mass 계산의 원본으로 제공해야 한다. | 독립 consistent mass/kinetic-energy oracle와 일치하고 같은 geometry/material/section의 consistent 결과가 Requirement 026의 입력임을 확인; 원본을 lumping으로 덮어쓰지 않음 | U r1, P; Research, Formulation, NR |
| FEM-REQ-MITC4-EIGEN-006 | 질량은 3개 병진 및 2개 director-tangent 회전의 물리 관성을 포함하고 numerical drilling에 물리 관성을 부여하지 않아야 한다. | Rigid translation의 총질량, 회전 관성·kinetic energy, director-parallel null action을 독립 검사; NR의 scale-aware 기준 | L, P; Research, Formulation, NR |
| FEM-REQ-MITC4-EIGEN-007 | 질량·강성은 동일한 physical DOF와 constraint 의미로 결정적으로 조립되어야 한다. | Scatter/source order, 대칭 구조, sequential/병렬 reduction 및 constrained motion 검증; 행렬 및 재실행 테스트 | P, L; Formulation, Planning |
| FEM-REQ-MITC4-EIGEN-008 | Massless numerical 좌표 처리는 FEAST의 admissible matrix 조건을 만족시키면서 선택된 질량의 유한 물리 spectrum을 보존해야 한다. | Formulation의 좌표 처리 전후 spectrum·경계조건 보존과 admissibility 검사 통과; consistent→lumped의 spectrum 동일성을 뜻하지 않음. 임의 mass floor, diagonal epsilon, eigenvalue clamp 금지 | P, L, R; Research, Formulation, NR |
| FEM-REQ-MITC4-EIGEN-009 | Mode-count 요청은 물리 spectrum의 낮은 순서에서 지정 개수의 고유쌍을 계산해야 한다. | Reference는 10개; 작은 독립 spectrum에서 첫 N개·multiplicity·zero rigid-mode case·요청수 초과/빈 물리계의 명시적 실패 확인. 부적합 음수 spectrum을 양수화하지 않음 | U, R; Formulation, NR, I/O |
| FEM-REQ-MITC4-EIGEN-010 | 고유치 결과는 오름차순의 고유한 mode identity를 가지고 반복 고유값의 multiplicity를 보존해야 한다. | Repeated/clustered spectrum에서 row 수·순위·identity 및 재현성 확인; 같은 eigenvalue 값은 duplicate identity 오류가 아님 | R, P; NR, I/O |
| FEM-REQ-MITC4-EIGEN-011 | 실제 고유치 계산은 consistent mass에서 유도한 lumped mass를 MKL FEAST에 사용해야 한다. | Consistent→lumped→FEAST 연결과 real adapter의 질량 입력·backend identity 확인; source Lanczos가 backend를 변경하지 않고 consistent나 다른 질량으로 reference에 맞추지 않음 | U r1; Research, Formulation, Planning |
| FEM-REQ-MITC4-EIGEN-012 | FEAST 실패·미수렴·불충분 모드·비유한 eigenpair를 성공 결과로 반영해서는 안 된다. | 각 failure injection에서 안정된 diagnostic과 불완전 result 미공개 확인; bounded termination 테스트 | P; Formulation, I/O, Planning |
| FEM-REQ-MITC4-EIGEN-013 | 성공 eigenpair는 FEAST에서 사용한 동일 lumped mass로 modal residual·mass normalization·orthogonality 검증을 통과해야 한다. | 내부 modal vectors로 독립 residual/Gram 검사를 수행하고 잘못된 mass variant·eigenvector·mode pairing을 검출; NR가 threshold·scale 고정 | U r1, P, R; Formulation, NR, Physics |
| FEM-REQ-MITC4-EIGEN-014 | 두 질량 계산과 선택된 질량의 eigen 해석은 symmetry, kinetic-energy, coordinate invariance, rigid-body 및 density scaling evidence를 제공해야 한다. | 각 질량의 독립 oracle·invariant suite와 작은 analytical/manufactured case 통과; 선택된 spectrum의 density scaling 검사. Lumping이 모든 속도장의 consistent energy를 그대로 보존한다고 가정하지 않음; NR가 기준 확정 | U r1, P, L; Research, Formulation, NR, Physics |
| FEM-REQ-MITC4-EIGEN-015 | 지정 `.inp`의 `*FREQUENCY` 요청과 부수 옵션은 보존된 입력에서 명시적으로 mapping되어야 한다. | 원본 파일 변경 없이 실행; requested count와 mass normalization 유지; Lanczos/SIM 옵션의 FESA 처리 및 acoustic-free 모델에서 `ACOUSTIC COUPLING=ON`의 무해성/진단을 I/O에 명시 | U, R, P; Research, I/O |
| FEM-REQ-MITC4-EIGEN-016 | 승인 subset 밖의 모델·절차·옵션은 의미를 삭제하거나 근사해 실행하지 않고 진단해야 한다. | Exclusion inventory의 양성/음성 테스트; acoustic 요소, preload, damping, 비영 prescribed base state, 미지원 frequency fields 등의 silent no-op 없음 | P, R; I/O, Planning |
| FEM-REQ-MITC4-EIGEN-017 | 공식 HDF5는 source step·mode identity와 고유치의 물리량·단위·실제 backend·사용 질량 variant를 식별할 수 있어야 한다. | 입력 sibling `<stem>_results.h5`에서 10개 reference 대응 고유치와 선택 질량을 복원; additive schema/self-check 테스트. Mode-vector 영속 projection 필요성·layout은 I/O 소유 | U, P, N; I/O |
| FEM-REQ-MITC4-EIGEN-018 | 내부 modal vectors는 global physical DOF·source identity와 연결되고 외부 mode-shape acceptance로 사용되지 않아야 한다. | Constraint 복원·source renumbering·mass normalization과 내부 verification evidence 재현; 비교기가 vector reference 파일을 요구하지 않음 | U, P; Formulation, NR, I/O |
| FEM-REQ-MITC4-EIGEN-019 | State와 final HDF5는 검증된 candidate만 반영하고 제어된 실패에서 기존 유효 결과를 보존해야 한다. | Solve·validation·writer/finalization 실패 후 이전 state/final hash 보존; live log는 기존 `<stem>_log.txt` 독립 lifecycle 유지 | P, N; Formulation, I/O, Planning |
| FEM-REQ-MITC4-EIGEN-020 | 외부 검증은 지정 원본 TXT의 `Value` 고유치만 derived lumped mass로 계산한 FESA HDF5 고유치와 비교해야 한다. | 같은 지정 `.inp`, 기존 TXT 경로 그대로 사용; Mode 1~10 포함. 두 질량 중 결과가 가까운 쪽을 사후 선택하지 않음. `Freq`, 변위·회전·stress·reaction·mode shape를 추가 외부 gate로 사용하지 않음 | U r1, R; NR, I/O |
| FEM-REQ-MITC4-EIGEN-021 | 비교기는 required identity의 missing/extra/duplicate/nonfinite와 quantity/schema 오류를 tolerance 전에 거부해야 한다. | 행 재정렬은 같은 mapping, mode label 중복·누락·추가·비유한 `Value`는 실패; 같은 값의 다른 mode는 허용; comparator 음성 테스트 | P, R; NR, I/O, Planning |
| FEM-REQ-MITC4-EIGEN-022 | 외부 고유치 acceptance는 공통 `docs/TOLERANCE.md`의 scale·row·RMS·zero-scale 정책을 적용해야 한다. | NR가 mode/frame identity·family·blocking 분류를 고정하고 승인된 모든 고유치 비교 통과; frequency로 대체하거나 tolerance를 조정하지 않음 | U, P; NR, I/O |
| FEM-REQ-MITC4-EIGEN-023 | 새로운 동작은 관찰된 RED 이후 구현하고 MSVC x64 Debug CMake/CTest에서 검증해야 한다. | 대응 C++ tests, RED/GREEN/focused/full evidence, 새 warning 없음, 실제 FEAST runtime/reference evidence. 사용자 지정 `FESA_GTEST_SOURCE_DIR=C:\git\googletest`를 검증 환경에 사용 | U r1, P; Planning, Implementation |
| FEM-REQ-MITC4-EIGEN-024 | 기존 선형·비선형 정적 procedure의 입력·출력·수치 계약을 보존해야 한다. | 승인된 회귀 suite와 영향받은 reference 검증; 기존 model에 density가 없다고 정적 해석을 새로 거부하지 않음 | P, L, N; Planning, Implementation |
| FEM-REQ-MITC4-EIGEN-025 | 완료 판정은 동일 revision의 implementation·독립 physics·release evidence를 요구해야 한다. | Requirement 전 행에 evidence 연결, 필수 미실행/실패/stale 항목 0, 내부 readiness와 외부 release 권한 구분 | U, P; Coordinator, Physics, Release |
| FEM-REQ-MITC4-EIGEN-026 | 솔버는 계산된 consistent mass에서 lumped mass를 유도하고 승인된 질량·관성 보존 계약을 검증해야 한다. | 유도 관계·독립 lumping oracle·총 병진 질량 보존, 차원/대칭성/물리 kinetic-energy 비음성, 물리 회전 관성과 drilling nullspace 의미 검사. Lumping 수식·좌표 block 처리·정확한 관성 불변식과 threshold는 Formulation/NR가 고정 | U r1, P, L; Research, Formulation, NR |

## 결정과 handoff

`MFE-OQ-001`은 사용자 후속 결정으로 해결되었다. Consistent를 계산하고 이로부터 lumped를
계산하므로 두 계산은 모두 필수다. 기존 양자택일 요구는 대체되었다.
`MFE-OQ-002`도 사용자 명시 결정으로 해결되었다. **Consistent→lumped→FEAST** 흐름을
사용하며 external eigenvalue baseline과 내부 residual·normalization·orthogonality는
동일 lumped mass에 대응한다. [사용자 결정 근거](requirements-evidence.md#중요한-결정)를 따른다.
현재 requirements의 중요한 미결정은 없다.

Research/Formulation은 consistent→lumped 유도 및 각 관성 불변식, lumped 질량과 massless drilling, supported global
constraints의 양립, 실제 FEAST admissibility와 낮은 모드 추출의 완전성을 다룬다.
NR는 independent physics portfolio와 모든 수치 기준, TXT readiness, mode/frame/family mapping을
확정한다. 특히 각 mode가 별도 Abaqus frame인 사실을 공통 family 규칙과 함께 검토한다.
I/O는 필요한 최소 syntax, no-op/diagnostic, source/result identity와 additive output을 정의한다.
기존 영속 계약의 비호환 변경이나 새로운 물리 근사가 필요한 경우만 다시 critical로 반환한다.

사용자는 작업 중 Git 커밋을 승인했다. Root가 사용자 수정 `AGENTS.md`와 완료 문서 checkpoint를,
Harness Executor가 기존 계약에 따라 구현·phase 커밋을 소유하며 이 specialist는 커밋하지 않는다.

이번 산출물은 문서 요구사항과 read-only evidence 조사이다. 구현·CMake·CTest·Harness·외부
solver·수치 reference comparison은 수행하지 않았으며 통과로 보고하지 않는다.