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

# MITC4 질량행렬·FEAST eigen 요구사항

- Feature ID: `mitc4-shell-feast-eigen2`
- Requirement baseline revision: `r1`
- Owner: `requirement-agent`
- 상태: 요구사항 기준선 작성. 구현·수치 검증 또는 readiness 통과 기록이 아니다.

기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
[ADR-028](../ADR.md#adr-028), [ARCHITECTURE](../ARCHITECTURE.md),
[TOLERANCE](../TOLERANCE.md). 현재 작업·checklist는 [PRD](PRD.md),
소유권은 [FEATURED_AGENTS](FEATURED_AGENTS.md), 결정은 [ADR](ADR.md)을 따른다.
근거 구분·기존 ID 대응·미결정은 [requirements-evidence](requirements-evidence.md)에 둔다.

## 범위와 해석 의미

Consistent mass를 계산하고 그 결과로부터 lumped mass를 유도하며 실제 무감쇠 선형
고유진동 해석은 **derived lumped mass와 MKL FEAST**를 사용한다. 같은 lumped mass를
modal residual·normalization·orthogonality와 외부 고유치 비교의 기준으로 사용한다.
Consistent와 lumped의 모든 속도장 energy 또는 spectrum 동일성은 요구하지 않는다.

원형상·무응력 상태의 단일 `*FREQUENCY`, homogeneous essential constraints와 기존
지원 partial rotation BC를 대상으로 한다. 기존 MITC4의 막·굽힘·횡전단, 단일층 균질
등방성 탄성, centered constant-thickness section, geometry-derived director, source
`S4`/`S4R`, 전역 6 DOF 의미를 유지한다. FESA는 독립 솔버이며 Abaqus 내부 정식화·적분·
stabilization·결과 생성의 동등성을 주장하지 않는다.

좌표 공변적인 numerical drilling stabilization 개선 및 영향받는 선형·비선형 정적/eigen
재검증은 범위에 포함한다. 기존 basis-dependent scale 선정과 그 공식 자체의 검사만
대체 대상이다. 물리 kernel·지원 BC·physical recovery·source identity와 결과 의미는
보존한다. Nonlinear objective drilling potential, 초기 reference에서 scale을 고정하는
lifecycle, 일관 residual/Hessian 의미도 유지한다. 상세 대체 공식은 이 문서에서 채택하지 않는다.

| 물리량 | 단위·좌표·identity 의미 |
| --- | --- |
| `rho`, thickness | mass/length³, length; 양의 유한한 일정 값, 사용자 일관 단위계이며 SI 추론·자동 변환 없음 |
| 병진 질량·회전 관성 | mass, mass·length²; 3 병진과 director 접평면 2 물리 회전, drilling은 물리 관성 없음 |
| 고유치 `lambda` | `omega²`, 1/time², 좌표계 불변 scalar; 원본 `Value`와 직접 비교 |
| 주파수 `f` | 양의 lambda에서 `sqrt(lambda)/(2*pi)`, cycles/time; 의미 확인용 파생량이며 외부 acceptance 대체량 아님 |
| Modal vector | Global physical DOF와 source instance/node/component에 연결; 진폭은 정규화된 모드이며 응답변위가 아님 |
| 결과 identity | Source step·mode와 scalar quantity를 식별; equation index·row 위치·source label을 혼동하지 않음 |

제외: 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.
별도 frequency interval/shift 사용자 기능, Lanczos/AMS 대체 backend, reference
생성·수정·복원과 외부 배포도 제외한다. Eigen 기능의 밀도 필수 조건을 기존 static에 확대하지 않는다.

## Requirement verification matrix

각 행은 하나의 관찰 의무이며 acceptance는 해당 요구와 검증 조건을 충족하는 것이다.
현재 요청은 이 의무를 정의하는 **requirement 단계만** 수행한다. 아래 검증은 후속 솔버
작업의 의도이며 이번에 실행하지 않는다. 구체적인 수식·내부 수치 기준·FEAST controls와
I/O layout은 후속 전문 owner가 필요한 시점에 정의한다. 외부 tolerance는 공통 정책을 따른다.

출처: `U`=[새 Feature ADR](ADR.md)의 기존 명시 사용자 결정 적용,
`R`=[근거 문서](requirements-evidence.md)의 reference 관찰,
`P`=위 프로젝트 기준, `L`=[기존 shell 요구](../linear-static-mitc4-shell/requirements.md),
`N`=[기존 nonlinear I/O](../nonlinear-static-newton-raphson/io.md)의 공통 경로·실패 의미.
`Formulation`, `NR`, `I/O`, `Implementation`, `Physics`는 전문 책임이며 고정 호출 단계가 아니다.
각 행은 [기존 r3](../mitc4-shell-feast-eigen/requirements.md)의 같은 번호에 대응한다.

| Requirement ID | Shall statement | 측정 가능한 acceptance / verification method | 출처·후속 owner |
| --- | --- | --- | --- |
| FEM-REQ-MITC4-EIGEN2-001 | 솔버는 선행 상태 없는 원형상 무응력 모델의 단일 무감쇠 선형 고유진동 procedure를 실행해야 한다. | 지정 reference가 한 frequency step으로 선택되고 static/nonlinear preload 경로를 호출하지 않음; procedure 통합 테스트 | U, R, P; Formulation, I/O |
| FEM-REQ-MITC4-EIGEN2-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, L; Formulation, I/O |
| FEM-REQ-MITC4-EIGEN2-003 | 모든 활성 shell의 밀도는 해당 section이 참조하는 material에서 하나의 finite `rho > 0`로 결정되어야 한다. | 여러 material의 올바른 연결 및 missing/duplicate/unresolved/nonpositive/nonfinite/dependent density 거부; semantic 양성·음성 테스트 | U, R, P; I/O |
| FEM-REQ-MITC4-EIGEN2-004 | 질량 계산은 기존 shell의 유효한 geometry·director와 양의 centered constant thickness를 사용해야 한다. | 기존 geometry/material/section 검증 재사용과 서로 다른 두께·밀도 연결 테스트; 부적합 요소를 질량 zero로 우회하지 않음 | L, P; Formulation, I/O |
| FEM-REQ-MITC4-EIGEN2-005 | 솔버는 MITC4 보간에 일관된 consistent mass를 계산하고 derived lumped mass 계산의 원본으로 제공해야 한다. | 독립 consistent mass/kinetic-energy oracle와 일치하고 같은 geometry/material/section의 consistent 결과가 Requirement 026의 입력임을 확인; 원본을 lumping으로 덮어쓰지 않음 | U, P; Formulation, NR |
| FEM-REQ-MITC4-EIGEN2-006 | 질량은 3개 병진 및 2개 director-tangent 회전의 물리 관성을 포함하고 numerical drilling에 물리 관성을 부여하지 않아야 한다. | Rigid translation의 총질량, 회전 관성·kinetic energy, director-parallel null action을 독립 검사; NR의 scale-aware 기준 | L, P; Formulation, NR |
| FEM-REQ-MITC4-EIGEN2-007 | 질량·강성은 동일한 physical DOF와 constraint 의미로 결정적으로 조립되어야 한다. | Scatter/source order, 대칭 구조, sequential/병렬 reduction 및 constrained motion 검증; 행렬 및 재실행 테스트 | P, L; Formulation, Implementation |
| FEM-REQ-MITC4-EIGEN2-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, P, L; Formulation, NR |
| FEM-REQ-MITC4-EIGEN2-009 | Mode-count 요청은 물리 spectrum의 낮은 순서에서 지정 개수의 고유쌍을 계산해야 한다. | Reference는 10개; 작은 독립 spectrum에서 첫 N개·multiplicity·zero rigid-mode case·요청수 초과/빈 물리계의 명시적 실패 확인. 부적합 음수 spectrum을 양수화하지 않음 | U, R; Formulation, NR, I/O |
| FEM-REQ-MITC4-EIGEN2-010 | 고유치 결과는 오름차순의 고유한 mode identity를 가지고 반복 고유값의 multiplicity를 보존해야 한다. | Repeated/clustered spectrum에서 row 수·순위·identity 및 재현성 확인; 같은 eigenvalue 값은 duplicate identity 오류가 아님 | R, P; NR, I/O |
| FEM-REQ-MITC4-EIGEN2-011 | 실제 고유치 계산은 consistent mass에서 유도한 lumped mass를 MKL FEAST에 사용해야 한다. | Consistent→lumped→FEAST 연결과 real adapter의 질량 입력·backend identity 확인; source Lanczos가 backend를 변경하지 않고 consistent나 다른 질량으로 reference에 맞추지 않음 | U; Formulation, Implementation |
| FEM-REQ-MITC4-EIGEN2-012 | FEAST 실패·미수렴·불충분 모드·비유한 eigenpair를 성공 결과로 반영해서는 안 된다. | 각 failure injection에서 안정된 diagnostic과 불완전 result 미공개 확인; bounded termination 테스트 | P; Formulation, I/O, Implementation |
| FEM-REQ-MITC4-EIGEN2-013 | 성공 eigenpair는 FEAST에서 사용한 동일 lumped mass로 modal residual·mass normalization·orthogonality 검증을 통과해야 한다. | 내부 modal vectors로 독립 residual/Gram 검사를 수행하고 잘못된 mass variant·eigenvector·mode pairing을 검출; NR가 내부 기준·scale 정의 | U, P, R; Formulation, NR, Physics |
| FEM-REQ-MITC4-EIGEN2-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, P, L; Formulation, NR, Physics |
| FEM-REQ-MITC4-EIGEN2-015 | 지정 `.inp`의 `*FREQUENCY` 요청과 부수 옵션은 보존된 입력에서 명시적으로 mapping되어야 한다. | 원본 파일 변경 없이 실행; requested count와 mass normalization 유지; Lanczos/SIM 옵션의 FESA 처리 및 acoustic-free 모델에서 `ACOUSTIC COUPLING=ON`의 무해성/진단을 I/O에 명시 | U, R, P; I/O |
| FEM-REQ-MITC4-EIGEN2-016 | 승인 subset 밖의 모델·절차·옵션은 의미를 삭제하거나 근사해 실행하지 않고 진단해야 한다. | Exclusion inventory의 양성/음성 테스트; acoustic 요소, preload, damping, 비영 prescribed base state, 미지원 frequency fields 등의 silent no-op 없음 | P, R; I/O, Implementation |
| FEM-REQ-MITC4-EIGEN2-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-EIGEN2-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-EIGEN2-019 | State와 final HDF5는 검증된 candidate만 반영하고 제어된 실패에서 기존 유효 결과를 보존해야 한다. | Solve·validation·writer/finalization 실패 후 이전 state/final hash 보존; live log는 기존 `<stem>_log.txt` 독립 lifecycle 유지 | P, N; Formulation, I/O, Implementation |
| FEM-REQ-MITC4-EIGEN2-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, R; NR, I/O |
| FEM-REQ-MITC4-EIGEN2-021 | 비교기는 required identity의 missing/extra/duplicate/nonfinite와 quantity/schema 오류를 tolerance 전에 거부해야 한다. | 행 재정렬은 같은 mapping, mode label 중복·누락·추가·비유한 `Value`는 실패; 같은 값의 다른 mode는 허용; comparator 음성 테스트 | P, R; NR, I/O, Implementation |
| FEM-REQ-MITC4-EIGEN2-022 | 외부 고유치 acceptance는 공통 `docs/TOLERANCE.md`의 scale·row·RMS·zero-scale 정책을 적용해야 한다. | NR/I/O가 공통 정책의 같은 step/frame 규칙 안에서 mode identity·family를 정의하고 모든 요청 Value의 blocking 비교 통과; frequency로 대체하거나 tolerance를 조정하지 않음 | U, P; NR, I/O |
| FEM-REQ-MITC4-EIGEN2-023 | 변경 동작은 의미 있는 테스트와 구성된 MSVC x64 Debug CMake/CTest 검증으로 확인해야 한다. | 가능한 버그 재현, 변경 중 관련 검사, 기능 완료 시 전체 build/test와 필수 reference 비교 1회; 새 warning 없음과 실제 FEAST runtime evidence. 아래 제외 예제 사용 0건 및 남은 필수 coverage와 실행 identity 대조; 형식적 RED·수동/자동 중복 실행을 요구하지 않음 | U, P; Implementation |
| FEM-REQ-MITC4-EIGEN2-024 | 기존 선형·비선형 정적해석은 승인된 stabilization 개선 외의 입력·출력·물리 의미를 보존하고 영향받는 correctness·reference 회귀를 통과해야 한다. | 아래 portfolio의 `shell`·`shellNL` 및 linear-limit 역할을 fresh solve로 검증하고 기존 comparison identity·판정 정책 유지; tangent/선형극한/평형·reaction/energy/state 검증. 제외 예제는 복사본·cache로도 재사용하지 않음. 개선 전 bitwise equality를 요구하지 않고 density 없는 기존 정적 모델도 유지 | U, P, L, N; Formulation, NR, Implementation, Physics |
| FEM-REQ-MITC4-EIGEN2-025 | 솔버 기능 완료 판단은 적용 계약과 모든 필수 검증 evidence를 추적하여 내려야 한다. | 각 요구와 독립 numerical review·analytical/invariant·필요한 physics/reference evidence 연결; 필수 실패·미실행·stale를 통과로 집계하지 않음. 사용자 제외·과거 결과·현재 실행 구분; 기존 명시 감사 요청은 아래 범위 경계대로 보존 | U, P; 메인, NR, Physics |
| FEM-REQ-MITC4-EIGEN2-026 | 솔버는 계산된 consistent mass에서 lumped mass를 유도하고 승인된 질량·관성 보존 계약을 검증해야 한다. | 유도 관계·독립 lumping oracle·총 병진 질량 보존, 차원/대칭성/물리 kinetic-energy 비음성, 물리 회전 관성과 drilling nullspace 의미 검사. Lumping 수식·좌표 block 처리·정확한 관성 불변식과 threshold는 Formulation/NR가 고정 | U, P, L; Formulation, NR |
| FEM-REQ-MITC4-EIGEN2-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, L; Formulation, NR, Implementation, Physics |

## 지정 reference와 남는 검증 범위

Eigen input은 `reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp`, 외부 reference는
같은 폴더의 `shellNL-eigen-meshfine eigenvalues.txt`를 그대로 사용한다. 입력의
`*FREQUENCY`가 requested count의 권위이며 현재 `N=10`이다. TXT `Mode 1~10`의 `Value`만
비교한다. 이름 `shellNL`·`Step-2`로 preload를 추정하지 않는다. TXT를 CSV로 변환하거나
canonical 이름·보조 metadata·provenance를 새 readiness 조건으로 요구하지 않는다.
Source의 blank bounds/shift/control fields, Lanczos/SIM 및 acoustic-free 모델 옵션은
최소 subset의 의미와 진단으로 다뤄야 하며 정확한 allowlist는 I/O 책임이다.

| 남는 대상 | 필수 관찰·비교 의미 |
| --- | --- |
| `reference/shell/shell.inp` + `shell displacements.csv` | Linear `shell-s4` 및 `shell-s4-linear-limit` 역할. Source instance/node/component와 해당 static step/frame, global U1/U2/U3 blocking·UR1/UR2/UR3 warning-only. 같은 fresh solve를 사용해도 두 역할의 evidence를 유지 |
| `reference/shellNL/shellNL.inp` + `shellNL displacements.csv` | `shellnl-s4-final`의 factor-one accepted state와 source identity; U blocking·UR warning-only, 기존 좌표 의미 유지 |
| `reference/shellNL/shellNL reactions.csv` | Local RF1/RF2/RF3와 physical spatial RM1/RM2의 source-key·finite·inventory·error 보고는 review-only 유지; RM3/stress를 새 numerical gate로 추가하지 않음 |
| Element·linear static 내부 검사 | Kernel/patch·rigid mode·physical recovery·partition/full residual·reaction·energy·source mapping; 같은 물리 BC/loads를 유지하는 좌표 변환에서 complete K와 partial-BC static response |
| Nonlinear 내부 검사 | 선형극한·tangent consistency·objectivity·factor-one 전역 force/moment balance·free residual·commit/rollback; Newton·convergence·하중·reaction 의미 유지 |
| 새 eigen 내부 검사 | 두 mass의 독립 oracle·질량/관성·drilling null·density scaling·rigid modes, 실제 constraints·finite spectrum·modal residual/Gram·순위/multiplicity·실패 보존; 알려진 `NR-MFE-001` partial-BC 반례를 포함한 좌표 검증 |
| 기타 기존 coverage | Pressure synthetic kernel/하중/평형·schema/comparator 및 무관한 beam 등 회귀 유지. 제외된 복합 시험에 남은 모델 검사가 섞여 있으면 retained fixture/evidence로 해당 관찰을 보존 |

모든 외부 수치 비교는 [TOLERANCE](../TOLERANCE.md)를 적용한다. 회귀는 개선 전 숫자의
bitwise equality가 아니라 승인된 물리·identity·공통 정책으로 판단한다. 내부 평형 acceptance와
reaction의 local distribution 검토는 별개다. 알려진 partial-BC 반례를 full-free/full-clamp
사례만으로 대체하거나 실패 수치를 기대값으로 재생성해 정당화하지 않는다.

## 사용자 제외 예제

다음 네 예제는 `reference/temp/` 아래 원본뿐 아니라 옛 경로, 복사 input, cached HDF5·log·
추출 결과를 통한 검증에서도 제외한다. 원본 열람·artifact audit·solve·비교·복원 또는
새 fixture로 위장한 재사용을 하지 않는다. 과거 기록은 이력이며 현재 성공 evidence가 아니다.

| 제외 예제 | 제외되는 외부 coverage |
| --- | --- |
| `shellNL-meshfine` | Fine static solve·변위 비교·reaction review |
| `shellNL-meshfine-pressure` | 해당 pressure 예제의 artifact audit·solve·결과 비교 |
| `shellNL-meshfine_02` | 별도 post-closure 예제의 검증 |
| `shellNL-dyn-meshfine` | 해당 예제의 검증 |

`reference/shellNL-eigen-meshfine`는 이 목록에 포함되지 않는다. 제외는 지원 기능과 내부
물리 검증 의무 삭제를 뜻하지 않는다. Pressure 예제에 대한 fresh 외부 coverage 부재는
명시적으로 보고한다. 과거 test 수 `362/352`를 새 완료 조건으로 사용하지 않고 실제 남은
의무·선택·실행·사용자 제외를 구분한다.

## 이번 완료와 후속 판단의 경계

이번 완료는 요구·출처·coverage·링크의 정적 확인까지다. 구현/FEAST/build/test/reference,
독립 numerical/physics review와 release-readiness는 미실행이다. 기존 명시 release-readiness
감사 요청은 후속 요구 기록으로 보존하되 이번 요청의 실행 범위나 모든 기능의 고정 단계
의무로 확대하지 않는다. 메인이 필요한 후속 전문 작업과 evidence를 판단한다.
공통 문서·기존 Feature·source·test·reference는 읽기 전용이며 Git은 메인이 소유한다.