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

# MITC4 lumped mass·FEAST 고유치해석

## 목적과 지원 범위

원형상·무응력 MITC4의 무감쇠 선형 고유진동 `K*phi=lambda*M_L*phi`를 푼다.
Consistent moment에서 유도한 nodal block lumped mass와 실제 MKL FEAST를 사용한다.
Prestress·nonlinear eigen·damping·acoustic·modal transient·외부 mode-shape equality는 포함하지 않는다.
공통 실행·소유권은 [solver-core](../solver-core/README.md)를 따른다.
수학 원문은 [전체 정식화](formulation.md), [mass·stabilization](formulation-mass-stabilization.md),
[축소·FEAST](formulation-eigen.md)이며 [이전 유도](../mitc4-shell-feast-eigen/README.md)의 채택 경계를 구분한다.

## 채택한 설계와 이유

Mass는 `3×3×3` 적분의 scalar thickness moments를 row-sum하여 nodal `6×6` block으로 만든다.
3 병진·2 director 접평면 회전 관성과 warped geometry cross coupling을 보존한다.
Numerical drill은 analytic mass null이며 인공 drilling inertia를 넣지 않는다.
Stabilization scale은 초기 physical rotary diagonal 8개 trace 평균의 `10^-3`이다.
2026-10-20부터 모델 전체의 코드 설정은 직접 초기 director 스프링을 기본으로 하며
기존 상대 비틀림도 선택할 수 있다. 원형상 eigen의 K/M과 drilling block은 두 방식에서
같다. Artificial drilling mass를 추가하거나 서로 다른 spectrum을 만들지 않는다.
Global 실제 BC를 먼저 적용하고 analytic null과 free 공간의 교집합만 제거한다.
Partial rotational BC를 full clamp로 대체하지 않고 finite constrained spectrum을 유지한다.
Positive nodal mass space를 whitening하고 sparse symmetric 문제를 FEAST에 전달한다.
완전한 interval의 c개 결과를 검증한 후 사용자 요청 lowest N만 공개한다.
N 밖의 실패한 eigenpair를 버려 성공으로 바꾸지 않는다.
Trace convergence만으로 개별 residual을 보장하지 못해 C-index `fpm[5]=0` residual stopping을 채택했다.

## 실제 입력 subset

`S4|S4R`, centered homogeneous shell, `*ELASTIC`과 양의 상수 `*DENSITY`를 사용한다.
유일한 frequency step은 optional `NAME`, `NLGEOM=NO`, flag `PERTURBATION`을 허용한다.
`*FREQUENCY`의 `EIGENSOLVER=LANCZOS`는 source 값이며 실제 FEAST mapping warning을 남긴다.
`SIM=YES`/flag, `ACOUSTIC COUPLING=ON`은 structural-only source 의미를 보존한다.
`NORMALIZATION=MASS`만 허용하며 실제 normalization은 derived lumped mass 기준이다.
Data 첫 field N은 양의 checked int64, 뒤 2–7 field는 존재하면 모두 empty여야 한다.
Nonempty zero bounds·shift, eighth field, 여러 step·preload·load·nonzero BC는 거부한다.
Source step 이름과 canonical storage `Step-1`은 별개이며 원본 `Step-2`를 잃지 않는다.

## 결과와 reference 대응

HDF5는 `schema_version=0`, `eigen_schema_version=1`, procedure `linear-frequency`로 식별한다.
`/steps/Step-1/eigen/modes`는 mode ID·raw eigenvalue·classification·cluster ID를 가진다.
`vectors[N,node,6]`은 mass-normalized mode이며 response displacement가 아니다.
Constrained 성분은 exact zero이고 sign은 최대 scaled global component의 stable rule로 정한다.
Raw 작은 음수 lambda를 clamp하지 않는다. Frequency는 lambda>=0 mode subset만 생성한다.
`verification`에는 전체 c개 residual·Gram·null 검사와 backend call/control evidence를 보존한다.
실제 선택은 `/metadata`의 `mitc4_drilling_formulation`과 U64LE
`drilling_diagnostics_version=1`에 기록한다. Eigen에는 평형 frame이나 가상 drilling
moment dataset을 만들지 않는다. Typed 비교 report의 진단 frames도 빈 배열이다.

| 원본 | 비교 계약 |
| --- | --- |
| `reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp` | 유일한 source frequency step `Step-2`, N=10 |
| 같은 폴더 `shellNL-eigen-meshfine eigenvalues.txt` | `Frame: Mode <id>: Value = ... Freq = ... (cycles/time)` |

Step·mode ID·Value·time^-2를 직접 대응하며 TXT Freq로 lambda를 재구성하지 않는다.
Duplicate/missing/extra mode·malformed/nonfinite·unit/mass/backend/schema 오류는 tolerance 전에 실패한다.
동일 Value의 서로 다른 mode는 합치거나 평균하지 않는다.
승인된 named policy `mitc4-eigen-first-implementation`은 mode별 singleton의
relative row error와 relative RMS를 각각 `<=5%` inclusive로 검사한다.
Report는 policy_id와 relative_rms_tolerance를 기록한다.
이 예외는 다른 공통 family의 row 5%·RMS 1%를 바꾸지 않는다.
전체 c개 독립 내부 residual·Gram 등 `1e-10` 기준도 그대로다.

## 구현·데이터 흐름·수명

[Mitc4Shell::Mass](../../include/fesa/elements/mitc4_shell.h)와 [kernel](../../src/fesa/elements/mitc4_shell.cpp)이 local mass를 만든다.
[LinearFrequencyProcedureExecutor::Execute](../../include/fesa/analysis/linear_frequency_procedure.h)는
[실제 procedure](../../src/fesa/analysis/linear_frequency_procedure.cpp)에서 stable assembly·modal candidate를 소유한다.
[BuildEigenReduction](../../src/fesa/analysis/eigen_reduction.h)은 constrained lift·null split·whitening을 만든다.
[MklFeastEigenSolver::Solve](../../include/fesa/solvers/eigen/mkl_feast_eigen_solver.h)는 private vendor adapter다.
Domain→local K/M→ordered assembly→reduced solve→global phi 복원→all-c 검증→N 선택 순서다.
[EigenHdf5ResultsWriter](../../include/fesa/io/hdf5/eigen_hdf5_results_writer.h)는 검증 state를 직렬화한다.
출력 close/self-check/atomic replace 실패는 candidate를 폐기하고 기존 final을 보존한다.

## 실제 evidence와 미해결 범위

2026-10-20 source `6bbbb2b`의 두 방식 별도 실행에서 정식10-mode 생성·비교를 통과했고
실제 eigen table은 정확히 같았다. 전체 Debug Native/CTest는 각각1035개 중
1024 PASS·기존10 FAIL·1 INCONCLUSIVE SKIP이다. 해당 Value 비교 통과와 전체 물리 검증을 구분한다.

2026-09-10 사용자 승인 첫 구현에서 전체 417/417 PASS와 원본 10 Value의 모드별5% 통과 기록이 있다.
최대 외부 상대차는 약 `4.261331%`다. 이전 RMS1% 불일치 이력은 소급 PASS로 고치지 않는다.
이 기록은 당시 revision의 evidence이며 이번 문서 정리는 새 build/test를 실행하지 않았다.
Rational mass oracle·Jensen energy·좌표 재계산 공변성·density scaling·all-c 실패 주입이 보완 근거다.
S3 partial-BC의 public static은 직접 방식에서 인공 모멘트 차감 후 기존 gate를 통과한다.
기존 방식의 raw gate 실패는 명시적 검사로 보존했다. 이는 partial BC를 full clamp로
바꾸거나 Value 허용치를 완화한 해결이 아니다. Abaqus Value 정확도 개선은 후속 보류다.
실제 512회 vendor 호출 또는 실제 HDF5 close-error의 모든 조합을 주입한 것은 아니다.
Retained shell/shellNL 회귀와 내부 검증 의무를 유지하며 `reference/temp` 제외 예제를 재사용하지 않는다.