FESADev/docs/mitc4-shell-feast-eigen/reference-model.md

# MITC4 FEAST 고유치 reference-model 계약

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `numerical-review-agent`
- Input contract revision: `r2`
- 검토일: `2026-09-06`
- Artifact·logical comparison readiness: 필요한 입력과 비교값 확인 완료.
- Numerical comparison result: 미실행.
- Stage의 I/O handoff 요청은 [numerical-review](numerical-review.md#numerical-review)의 `pass`를 따른다.

지역 범위는 [FEATURED_AGENTS](FEATURED_AGENTS.md), [PRD](PRD.md), [ADR](ADR.md),
`FEM-REQ-MITC4-EIGEN-009/011/015/020/021/022`는 [requirements](requirements.md#requirements),
공통 판정은 [TOLERANCE](../TOLERANCE.md)의 `common-reference-tolerance`,
effective date `2026-08-18`, ADR-022를 따른다.

## Case와 원본 artifact

| Role | 지정 경로 | SHA-256 |
| --- | --- | --- |
| Input | [shellNL-eigen-meshfine.inp](../../reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp) | `913b1abc604e62bc5f995bf5523924e17ea03925102a7bd22d39226ba0ea7339` |
| 외부 reference | [shellNL-eigen-meshfine eigenvalues.txt](../../reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine%20eigenvalues.txt) | `20d97ca3fd51f5b956f2c1ed7565557c68f74e61e41b913748515ef43a0f7f0b` |

Case identity는 `shellNL-eigen-meshfine`다. 원형상 `729` nodes, `676` S4 elements,
면적 `100`, `t=0.5`, `rho=2700`, `E=2.1e11`, `nu=0.3`인 평판의 외곽 `104`개
절점이 DOF 1~6 모두 고정된다. Interior nodes `625`, 예상 `nf=3750`, `nz=625`,
finite dimension `3125`다. 이 수는 구현의 실제 rank/count 검증을 대신하지 않는다.

유일한 source step은 `Step-2`, 무응력·무하중·무감쇠이며 preload가 없다.
Requested `N=10`의 권위는 `.inp *FREQUENCY` data다. TXT의 행수에서 N을 얻지 않는다.
목적은 동일 입력을 사용하는 derived lumped-mass FEAST 결과의 첫 10개 고유치를 외부
수치값에 대조하는 것이다. Original TXT를 직접 읽으며 CSV 변환, rename, metadata,
provenance, version file 또는 mode-shape reference를 새 readiness 조건으로 추가하지 않는다.

## Quantity와 deterministic identity

| 항목 | Logical 계약 |
| --- | --- |
| Quantity / component | `eigenvalue` / `Value`, `lambda=omega²` |
| 차원 / 좌표계 | `T^-2` / coordinate-invariant scalar 의미; SI 자동 추론 없음 |
| Source row identity | `(case, source step name, modal frame mode id, component)` |
| 현재 expected identity | `case=shellNL-eigen-meshfine`, `step=Step-2`, `mode=1..10`, `component=Value` |
| FESA 대응 | 같은 source step의 검증된 오름차순 eigenvalue rank `1..N`; source mode identity로 대응 |
| Actual analysis mass | Consistent에서 유도한 lumped; backend `MKL FEAST` |
| 판정 영향 | 모든 10개 mode `blocking`; warning-only quantity 없음 |

TXT의 `Frame: Mode i`는 mode-domain frame identity를 준다. TXT에 step 이름이 없는 것은
지정 input에 frequency step이 정확히 하나인 사실로 결정적으로 해소한다. 이 예외를 다중
step이나 step이 모호한 artifact에 일반화하지 않는다. Modal frame id와 임의의 ODB
storage frame index를 같은 정수라고 추정하지 않는다.
공개 의미의 근거는 [연구 S10/S11](research.md#research-evidence--source-inventory)이다.

물리 eigenvalue가 같아도 다른 mode identity는 보존한다. 현재 표시값의 `(2,3)`,
`(7,8)`, `(9,10)` 쌍을 평균·merge하지 않는다. 같은 표시값만으로 exact degeneracy를
추정하거나 mode vector로 행을 재배치하지 않는다. FESA 값 자체를 재정렬해 가까운 TXT
값에 임의 matching하지 않고, 승인된 solver rank와 source mode를 연결한다.

공식 FESA 결과는 input의 lexical sibling `shellNL-eigen-meshfine_results.h5`다.
실제 dataset path, field type, persistent vector 및 comparison-view layout은 I/O owner가
정한다. 이 문서는 HDF5 schema를 대신 선택하지 않는다.

## Tolerance 전 사전검사

1. 지정 두 artifact와 FESA 공식 결과가 존재하며 같은 input/case/source step이다.
   FESA 결과의 quantity·unit dimension·backend·actual mass가 위 계약과 맞아야 한다.
2. TXT의 모든 비어 있지 않은 행이 명시적인 `Frame: Mode <id>: Value = <number>`와
   기존 `Freq = <number> (cycles/time)` 표기에 맞아야 한다. Malformed 행을 건너뛰지
   않는다. Freq는 구조 식별에만 쓰고 Value를 재계산하거나 tolerance 대상으로 쓰지 않는다.
3. Required row identity set이 양쪽 모두 정확히 `1..10`이다. Missing/extra/duplicate,
   잘못된 mode label·step·component·quantity/schema는 실패다. 입력 N과 따로 검사한다.
4. 모든 required `Value`가 finite여야 한다. `NaN/Inf`를 누락처럼 무시하거나 0으로
   바꾸지 않는다. Required FESA dataset/component 누락도 먼저 실패한다.
5. 유일 identity로 대응한 뒤 increasing mode 순서로 검사·보고한다. TXT 행 순서 변경은
   결과를 바꾸지 않으며 duplicate 검사 전에 dictionary overwrite하지 않는다.

## Comparison family와 고정 판정

Family identity는 `(case=shellNL-eigen-meshfine, step=Step-2,
modal-frame=mode i, quantity=eigenvalue, units=T^-2, coordinates=scalar,
impact=blocking)`이며 `i=1..10`이다. **10개의 singleton family**이고 각 component는
`Value` 하나다. 서로 다른 source modal frame을 저장 table이 같다는 이유로 합치지 않는다.

각 family에 공통 정책을 그대로 적용한다. `S=max|r|`, `B=0.01S`,
`e=|f-r|`; `|r|<=B`이면 `e<=B`, 그 외에는 `e/|r|<=0.05`다.
Family relative RMS도 반드시 계산하여 `sqrt(mean(e²))/S<=0.01`을 함께 요구한다.
모든 경계는 inclusive다. 현재 각 reference가 양수인 singleton이므로 RMS는
`e/|r|`이고 **모든 mode의 실효 상대 한계는 1%**다. 이것은 NR가 새로 고른 tighter
tolerance가 아니라 공통 same-frame family와 RMS 규칙의 직접 결과다.

`S=0`이면 대응 FESA도 정확히 0인 경우만 통과한다. 그렇지 않으면
`zero-reference-scale-nonzero-error`를 기록한다. Arbitrary absolute floor,
`max(1,S)`, frequency로 대체한 오차, engineering zero clamp는 허용하지 않는다.
Freq·mode shape·stress·reaction·다른 mass variant를 별도 외부 판정에 추가하지 않는다.

보고서는 input/reference/result identity, prechecks, 각 family/component/row count/S,
원본 r/f/e, 적용 row branch·판정, RMS·판정, blocking failure 및 전체 verdict를 남긴다.
Internal FEAST count/잔차와 외부 singleton reference 판정은 별도 evidence다.

## 검증 coverage와 제한

Comparator의 필수 음성/경계 사례는 missing/extra/duplicate/nonfinite/malformed row,
wrong step/quantity/mass, 행 순서 변경, 같은 Value의 서로 다른 mode,
정확한 1% RMS 경계·그 초과·5% row 경계, zero-scale 양성·음성이다.
Generic policy 테스트에는 near-zero `|r|=B`와 그 양옆도 포함한다.
이 reference singleton의 양수 데이터에 실제 near-zero row가 있다고 주장하지 않는다.

실제 read-only `Get-Content`, `Get-FileHash`, `python -B -` inventory/identity script는
exit `0`: `729/676/104/625` nodes/elements/boundary/interior, 단일 `Step-2`, input N=10,
유일 finite positive Values `10`, 위 두 hash 일치를 확인했다.
명령·검토 evidence는 [수치 상세](numerical-review.md#numerical-review-evidence--실행-evidence)에 연결한다.
단일 clamped flat case는 curved/partial-BC/null/zero-mode correctness를 검증하지 않는다.
원본 Abaqus 결과와 내부 정식화의 동등성, 구현의 수치 통과 또는 release를 주장하지 않는다.

## r2 영향 확인과 기존 static 회귀

r2는 numerical stiffness의 초기 scalar만 개선한다. 이 reference의 input/TXT,
Value=omega² 의미, N의 입력 권위, source step/mode/frame, actual lumped mass 및 모든
10개 singleton family의 공통 판정은 변경되지 않는다. r1의 파일 내용·identity inventory를
재사용했고 r2에서 두 원본 SHA-256이 위와 동일함을 확인했다(`Get-FileHash`, exit `0`).
과거 reference readiness를 r2 FESA 수치 비교 성공으로 바꾸지 않는다.

승인된 기존 static 회귀는 [Requirement의 단일 portfolio](requirements.md#requirements-evidence--필수-회귀-포트폴리오와-identity),
[C26](numerical-review.md#numerical-review-cases) 및
[C7](numerical-review.md#numerical-review-controls--c7-승인된-정적-회귀-기준)을 따른다.
그 static U blocking/UR warning-only·nonlinear local reaction review-only와 기존
step/accepted-state/source-node/component identity는 유지한다. Eigen의 Value-only와
서로 바꾸지 않는다. Static의 최신 common-policy projection을 적용하고 옛 파일명/schema
이력으로 현재 HDF5 경로를 대체하지 않는다. 최종 dataset 정의는 I/O owner다.