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

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `requirement-agent`
- Input contract revision: `r2`
- 검토 상태: 사용자 승인 stabilization 개선·정적/eigen 재검증 범위를 반영한 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 의미를 재사용한다.
- Numerical drilling stabilization은 사용자 승인에 따라 좌표 공변적으로 개선한다.
  영향받는 기존 선형·비선형 정적해석과 새 eigen 해석을 재검증하며 물리 kernel의 변경으로 확대하지 않는다.
- 활성 재료마다 양의 유한한 일정 체적 밀도를 해석 모델에 연결한다. 질량은 병진과
  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 의미를 유지하고 numerical stabilization만 Requirement 027에 따라 개선해야 한다. | Physical contribution·mapping·recovery 의미 보존, source type만 다른 모델은 같은 mass·개선된 stiffness/eigen 경로와 별도 source metadata; 개선 전 전체 K의 수치 동일성을 요구하지 않음 | U r2, 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 좌표 처리는 개선된 stabilization과 lumped mass에 실제 global BC를 적용한 원 pencil의 유한 spectrum을 보존하며 FEAST admissibility를 만족해야 한다. | 지원 partial BC를 포함해 축소 전후 spectrum·constraint·원 free DOF residual 검증; 개선 전 K와의 spectrum 동일성 또는 consistent→lumped 동일성을 요구하지 않음. 인공 mass·임의 cutoff·clamp 금지 | U r2, P, L; 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 | 두 질량과 개선된 stabilized eigen 해석은 symmetry, kinetic-energy, coordinate invariance, rigid-body 및 density scaling 검증을 통과해야 한다. | 독립 mass oracle·invariants 및 동일 물리 BC를 보존하는 지원 partial-rotation 사례에서 재계산한 complete K와 eigen spectrum의 좌표 검증 필수. NR-MFE-001 반례를 필수 통과 사례로 포함하며 full-free/full-clamp만으로 대체하지 않음; density scaling 및 각 mass 고유 energy oracle 유지; NR가 기준 고정 | U r2, 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 | 새 eigen 외부 검증은 지정 원본 TXT의 `Value`만 derived lumped mass로 계산한 FESA HDF5 고유치와 비교해야 한다. | 같은 지정 `.inp`·TXT, Mode 1~10 포함; mass variant 사후 선택 금지. Eigen `Freq`·변위·회전·stress·reaction·mode shape 외부 gate를 추가하지 않음. 승인된 기존 static 회귀는 별도 Requirement 024의 기존 계약 사용 | U r1/r2, 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 | 기존 선형·비선형 정적해석은 승인된 stabilization 개선 외의 입력·출력·물리 의미를 보존하고 영향받는 correctness·reference 회귀를 통과해야 한다. | 상세 evidence의 필수 static portfolio와 기존 comparison identity·판정 정책을 유지해 새 evidence 생성; tangent/선형극한/평형·reaction/energy/state 검증. 개선 전 결과의 bitwise equality를 요구하지 않고 density 없는 기존 정적 모델도 유지 | U r2, P, L, N; Formulation, NR, Planning, Implementation, Physics |
| 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 |
| FEM-REQ-MITC4-EIGEN-027 | 개선된 numerical drilling stabilization은 같은 물리 모델의 좌표·접평면 기저 선택에 공변적이고 기존 비물리 역할을 유지해야 한다. | 독립 재계산한 stabilization/complete K의 congruence, finite·대칭·양의 numerical stabilization, 물리 rigid modes 보존, physical recovery 제외 및 결정론 검증. Partial BC의 NR-MFE-001과 대응 정적 response를 필수 통과시키며 기존 static의 동일 scale 사용 경로도 정합 검증; 수식·threshold는 Formulation/NR 소유 | U r2, L; Research, Formulation, NR, Planning, Physics |

## r2의 기존 계약 대체 범위

[MFE-ADR-007](ADR.md#mfe-adr-007--기존-stabilization과-좌표-불변성-acceptance-정합)의 승인으로
기존 `FESA-REQ-LSMITC4-034`의 basis-dependent `min(R+)` scale 선정과 `056` 중 그
옛 공식 자체를 검증하도록 한 부분을 본 feature의 `027` 및 후속 개선 수식으로 대체한다.
같은 scale을 사용하는 [nonlinear formulation §10.3](../nonlinear-static-newton-raphson/formulation.md#103-fixed-scale-and-potential)도
그 scale 선정 부분의 영향 대상이다. Nonlinear objective drilling 좌표·potential의 의미,
초기 reference에서 scale을 고정하는 lifecycle 및 일관 residual/Hessian 계약은 유지한다.
물리 strain/material/section/director, 양의 비물리 stabilization, physical recovery 제외,
기존 지원 BC·source identity·output 의미는 대체하지 않는다. 기존 feature 문서는 읽기 전용
이력으로 보존하며 상세 대체 수식과 검증 trace를 이 feature의 후속 owner가 작성한다.

필수 static 회귀의 기존 case·identity·policy는
[requirements evidence의 r2 재검증 범위](requirements-evidence.md#r2-승인-범위와-정적-재검증)를 따른다.
새 eigen reference의 Value-only를 기존 정적 reference 요구의 삭제로 해석하거나,
정적 U/UR 회귀를 eigen mode-shape 비교로 확대하지 않는다.

## 결정과 handoff

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

`MFE-OQ-003`은 사용자 명시 승인으로 해결되었다. 좌표 공변적인 stabilization 개선과
영향받는 기존 정적/eigen 재검증을 r2에 포함하며 partial BC 지원·invariance acceptance를
축소하지 않는다. [기존 반례·판단 이력과 승인 delta](requirements-evidence.md#nr-mfe-001-requirements-intent-검토)를
보존한다. 현재 요구사항의 중요한 미결정은 없고 NR 반례의 실제 해소·새 수치 통과는 아직 미검증이다.

Research/Formulation은 consistent→lumped 유도 및 각 관성 불변식, lumped 질량과 massless drilling, supported global
constraints의 양립, 실제 FEAST admissibility와 낮은 모드 추출의 완전성을 다룬다.
Stabilization의 좌표 공변성과 static scale 사용 경로를 정합시키고 개선된 pencil에서 기존
massless reduction 증명이 유지되는지 재검토한다. 이전 decoupling 증명을 그대로 승인으로 재사용하지 않는다.
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은 수행하지 않았으며 통과로 보고하지 않는다.