# 구속된 lumped pencil, FEAST와 modal 복구

> 현재 구현·검증은 [기능 요약](README.md)을 먼저 따른다. 아래 준비 상태·owner 인계와
> 옛 source 문서명은 작성 당시 이력이며, 원문은 Git 이력에서 확인한다.

Feature `mitc4-shell-feast-eigen2`, formulation r1. [기본 보고서](formulation.md)와
[질량·stabilization](formulation-mass-stabilization.md)의 기호를 사용한다.
Intel evidence는 [research R04/G01/G02](README.md)에 따른다.

## E1. 실제 BC를 먼저 적용한다

K와 M=M_L은 같은 source scatter와 stable contribution/reduction 순서로 조립한다.
활성 shell 최대 edge 길이의 최댓값 `ell>0 [L]`을 사용하여
`D=blockdiag_nodes(ell I3,I3)`, `q=D y`로 둔다. 이는 단위 정합 congruence다.
`Khat=D^T K D [ML²/T²]`, `Mhat=D^T M D [ML²]`이다.
실제 global homogeneous component BC의 stable free injection C에서

\[
y=C y_f,\quad K_f=C^TKhat C,\quad M_f=C^TMhat C. \tag{E1}
\]

Constrained 행은 0이며 nonzero prescribed base state는 이 procedure에서 허용하지 않는다.
Global UR3를 drilling으로 간주하거나 local 회전을 먼저 삭제한 뒤 BC를 적용하지 않는다.

Node i의 full analytic null은 `z_i=[0;d_i]`다. 이 방향이 실제 free space 안에 있을
필요충분조건은 **모든 constrained rotational component에 대해 해당 d_i 성분이 정확히 0**인
것이다. 그때만 `Zi=Ci^T zi`를 null basis로 둔다. 아니면 null dimension=0이다.
Translation BC는 이 조건에 영향을 주지 않는다. 작은 비영 director 성분을 0으로
분류하여 null을 늘리지 않는다. 거의 정렬된 partial BC의 작은 양의 mass도 보존한다.

Node free space에서 Zi의 직교 여공간 Pi^f를 고정 component 순서와 sign/tie로 구성한다.
세 회전 free에서는 기존 tangent a_i,b_i를 쓸 수 있고 null이 없으면 Pi^f=I다.
다른 경우도 작은 orthogonal basis construction으로 같은 공간을 만든다.
수치 고유값 cutoff로 physical rank를 결정하지 않는다. 전체 block basis P,Z에서

\[
[P\ Z]^T[P\ Z]=I,\quad M_fZ=0,\quad M_p=P^TM_fP\succ0. \tag{E2}
\]

Positive dimension `n=cols(P)`, null dimension `nz=cols(Z)`이며 `n+nz=nf`다.
Node의 finite dimension이 0이어도 다른 node는 유지한다. Global n=0 또는 requested N>n은
고유쌍 요청 실패다. 정적 해석의 유효한 0×0 Kff와 이 count 요구를 혼동하지 않는다.

## E2. 이 shell의 정확한 massless 제거

공통 nodal director와 M2의 분리 때문에 `Tp z_i=0`,
`Khat z_i=kappa_i z_i`, `kappa_i=sum_{e incident i} kd,e>0`다.
E1에서 null이 실제 free space에 있는 경우에만 다음이 성립한다.

\[
K_fZ=Z\operatorname{diag}(\kappa_i),\quad K_{pz}=P^TK_fZ=0,\quad
K_{zz}=\operatorname{diag}(\kappa_i)\succ0,\quad K_p=P^TK_fP. \tag{E3}
\]

Massless equation은 `Kzz z=0`이므로 finite mode의 z=0이다. 따라서
`Kp p=lambda Mp p`는 **개선된 실제 constrained K/M의 모든 finite spectrum**을 보존한다.
Null이 없는 partial BC에는 numerical drilling stiffness가 Kp에 그대로 남는다.
이를 제거하면 다른 pencil이 된다. Roundoff 잔차의 작은 coupling을 임의로 무시하는
것이 아니라 analytic identity로 축소하고 원 조립행렬에서 identity와 full residual을 검증한다.
불일치·conditioning 실패를 추가 DOF 삭제로 수리하지 않는다.

일반 pencil에서는 Kzz 가역일 때
`z=-Kzz^-1 Kzp p`, `Keff=Kpp-Kpz Kzz^-1 Kzp`가 필요하다.
예: `K=[[6,2],[2,4]],M=diag(2,0)`의 finite eigenvalue는 5/2, z=-p/2이며
행만 삭제한 값 3은 틀리다. 이는 독립 검증 oracle이며 이번 shell production에
일반 dense Schur fallback을 추가하라는 계약이 아니다. Singular/nonpositive Kzz,
공통 K/M null, 추가 mass null은 지원 전제 위반으로 진단한다. Pseudoinverse·epsilon
mass/stiffness를 넣지 않는다. E3를 nonlinear Hessian이나 prestress 문제로 확장하지 않는다.

## E3. 양의 nodal mass whitening

Mp는 node별 최대 6×6 SPD block이다. `Mp=L L^T`를 block Cholesky하면

\[
A=L^{-1}K_pL^{-T},\quad p=L^{-T}x,\quad Ax=\lambda x,
\qquad \phi=D C P L^{-T}x. \tag{E4}
\]

Global dense inverse 없이 nodal triangular solve로 congruence한다. Node topology를
늘리지 않으며 기존 coupling마다 작은 dense block만 생긴다. `phi^T M_L phi=x^Tx`다.
FEAST에 `(A,I)`를 넘겨도 실제 physical mass는 M_L이고 unit physical mass로 바꾼 것이 아니다.
Global physical 6 DOF와 source identity를 복구하며 constrained 성분은 정확히 0이다.
Cholesky positivity·reconstruction·conditioning 검증 실패 시 mode 후보를 만들지 않는다.

## E4. Lowest N과 FEAST의 유한 탐색

N은 입력의 positive integer count이며 reference는 현재 10이다. Reference Value/Freq는
scale·bracket·subspace·coefficient 선정에 사용하지 않는다. `s=||A||inf [T^-2]`에서
s>0이면 B=A/s다. A가 정확히 0일 때만 모델 scale
`s=min_e E_e/(rho_e ell²)>0`로 두어 B=0을 유지한다. 잘못된 scale을 1로 대체하지 않는다.
반환값은 `lambda=s mu`다.

`ri=sum_{j!=i}|Bij|`의 Gershgorin bound에 outward accumulation 또는 증명된
roundoff error bound를 포함하여 `gL<=spectrum(B)<=gU`를 만든다.
NR의 finite endpoint margin과 outward nextafter로 `a0<gL<=gU<b0`를 확보한다.
B=0에는 dimensionless outer bracket (-1,1)을 쓸 수 있다. 이는 eigenvalue clamp가 아니다.
Lower a0는 **항상 유지**한다. 독립 enclosure 자체가 a0보다 낮은 spectrum 부재의 근거다.

1. `(a0,b0)`에 성공한 count=n을 확인한다. 독립 enclosure와 total count가 불일치하면
   유한 endpoint 재시도 후 실패다. 성공한 `(a0,b0,count=n)`을 fallback으로 보존한다.
2. 선택적 upper-prefix subdivision은 `(a0,v)`만 count한다. 유효한 성공 count c>=N이면
   safe upper=v, c<N이면 search lower=v로 이동한다. 마지막 safe interval을 보존한다.
   Count-only zero가 보장되지 않으므로 실패·미정 status를 0으로 바꾸지 않는다.
3. Count=0에 대한 인증된 성공을 얻지 못하거나 endpoint/midpoint·budget 한계에 이르면
   최적화를 끝내고 마지막 safe interval, 최소한 total enclosing interval을 사용한다.
   별도의 empty-prefix 탐색이나 lower-bound 축소를 필수 경로로 두지 않는다.
4. 최종 interval의 성공 count c>=N을 재확인한다. Capacity는 `c<=m0<=n`이며 padding,
   탐색 중단 목표 및 유한 횟수는 NR가 고정한다. c=n이면 m0=n이다.
   N번째가 반복 cluster 안이어도 cluster 일부를 강제로 잘라 count하지 않는다.
5. FEAST로 c개 전체 eigenpair를 계산·검증하고 lambda 오름차순 첫 N개를 선택한다.
   같은 eigenvalue의 multiplicity를 평균·merge·deduplicate하지 않는다.

모든 count/solve·endpoint 재시도를 합친 유한 call budget을 NR가 고정한다.
Safe bracket으로 fallback해도 workspace 부족이나 넓은 interval의 실패 가능성은 남는다.
Allocation·integer range·미수렴·count 불일치에 bounded failure로 종료하며 다른 backend,
작은 N 또는 유효성 검사를 생략한 부분 결과로 성공하지 않는다. Endpoint 근접을 해결할
수 없으면 실패다. 최적화 실패를 성공 count evidence로 기록하지 않는다.

Count monotonicity·solve returned m=c·Gram rank c·모든 값의 interval 내부성과 endpoint
분리·모든 pair residual을 확인한다. Total enclosure, count, rank와 residual은 별도 evidence다.
Floating-point FEAST를 모든 conditioning에서 완전성 theorem으로 확대하지 않는다.
알려진 zero/negative/repeated/clustered spectrum, n=1, N=n, endpoint 근접 및 설치 runtime
probe가 필수 후속 연결점이다. Significant negative mode를 건너뛰어 양수 N개를 내지 않는다.

## E5. Vendor call 경계와 재현성

실제 eigenpairs는 MKL `dfeast_scsrgv`의 real symmetric `(B,I)`로 계산한다.
Strict finite `emin<emax`, `n>0`, `0<m0<=n`, SPD second matrix를 만족한다.
Upper triangle·1-based CSR에서 sorted unique indices, terminal nnz+1, finite values를 검증한다.
K와 identity의 pattern이 같을 필요는 없다. Vendor types와 workspace는 private backend다.

매 call마다 `feastinit` 후 명시 controls를 채운다. C-index `fpm[49]=1`은 CSR count를
m0로 반환하고 flag가 0으로 reset된다. Count output m0·solve requested m0·allocated capacity를
분리한다. CSR/SPD 검사를 켜고 subspace-only를 끈다.
[MFE2-ADR-011](README.md)의 사용자 승인으로
`fpm[5]=0` residual stopping을 사용한다. 내부 목표 `1e-12`와 전체 c개 독립 residual
기준 `1e-10`을 유지하며 zero/mixed-zero mode에도 실제 backend 회귀를 수행한다. `epsout`은
`|trace_i-trace_previous|/max(|emin|,|emax|)`이며 eigenpair 상대오차가 아니다.

`info=1`은 certified empty count가 아니다. 넓은 interval의 isolated cluster를 놓친
상태일 수 있다. `info=0,m0=0`의 empty-count 성공이나 count-only 작은/null scratch
면제는 공식 문서가 보장하지 않는다. 이 설계는 보수적으로 count용 m0=n,
x[n*n], e[n], res[n]을 준비하되 이를 vendor의 최소 workspace 의무라고 부르지 않는다.
Count scratch는 재사용·solve 전에 해제할 수 있다. O(n²) 비용, shifted sparse fill,
checked n*m0/nnz/index 변환 및 실제 peak memory를 후속 구현에서 검증한다.

Fixed initial subspace 생성법·seed·QR 순서·thread 설정·contour·loop·stopping controls는
NR가 고정하고 evidence에 남긴다. Full capacity m0=n에서는 identity initial basis를 쓸 수 있다.
Seed를 바꿔 통과할 때까지 반복하지 않는다. 고정 source 입력의 assembly/reduction·row·
diagnostic 순서를 유지하되 repeated eigenvectors의 유일한 방향을 주장하지 않는다.

## E6. Original-global recovery와 검증식

복구된 `yf=C^T D^-1 phi`, `k=||Kf||F`, `m=||Mf||F`에서

\[
r_f=K_fy_f-\lambda M_fy_f,\qquad
\eta_r=\frac{\|r_f\|_2}{(k+|\lambda|m)\|y_f\|_2}. \tag{E5}
\]

원 조립행렬의 **모든 original free DOF**에서 검사한다. 축소 residual만으로 복원 오류를
숨기지 않는다. M은 항상 actual lumped다. 제약 성분의 modal residual을 reaction으로 출력하지 않는다.
`Mf Z`, `Kf Z-Z diag(kappa)`, `P^T Z`, Cholesky reconstruction 및 constraint 복원도 검사한다.
Nz=0이면 null 검사는 N/A이며 zero metric의 통과를 만들어내지 않는다.

`gi=phi_i^T M phi_i`가 finite positive일 때만 `phi_i/=sqrt(gi)`로 정규화한다.
정규화 후 최종 phi에서 `gi=phi_i^T M phi_i`와 `yf_i=C^T D^-1 phi_i`를 다시 계산한다.
이후 모든 residual·Gram·Rayleigh·energy 검사는 이 재계산 값만 사용한다.
전체 c개에 대해 `Gij=phi_i^T M phi_j`, `G≈I`, Gram rank c를 검사한다.
Rayleigh quotient `Ri=(yf_i^T Kf yf_i)/gi`와

\[
\eta_{energy,i}=\frac{|y_{f,i}^TK_fy_{f,i}-\lambda_i g_i|}
{(k+|\lambda_i|m)\|y_{f,i}\|_2^2} \tag{E6}
\]

를 검사한다. 같은 단위 norm에서 symmetry·congruence error를 평가한다.
모든 ratio는 분모>0에서만 계산하며 numerator=denominator=0이면 해당 zero identity metric=0,
denominator=0,numerator!=0이면 실패다. Zero eigenvector 자체는 정규화 전 실패다.
임의 `max(1,scale)`·floor·zero clamp는 없다. 실제 수치 한계는 NR가 정한다.

Lambda를 pair와 함께 stable 정렬하고 exact tie는 solver column order로 둔다.
최대 절댓값의 scaled global component가 양수가 되게 sign을 정하며 tie는 source DOF 순서다.
Gram을 맞추려고 서로 다른 eigenvalue의 vectors를 섞지 않는다. Repeated group은 동일
mass metric의 projector로 비교하며 한 벡터의 방향을 external acceptance로 요구하지 않는다.
Mass-normalized phi_u 차원은 `M^-1/2`, phi_theta는 `M^-1/2 L^-1`이고 응답변위가 아니다.

모든 density를 c_rho>0배 하면 두 mass는 c_rho배, lambda는 1/c_rho배,
normalized repeated eigenspace는 1/sqrt(c_rho)배와 내부 orthogonal mixing 관계다.
여섯 rigid motions와 same-physical-BC covariance는 질량·stabilization 상세의 field를 쓴다.

Raw lambda의 부호를 보존한다. NR 기준의 significant negative는 spectrum 실패,
near-zero는 raw value를 유지한 분류다. 양수일 때만 `f=sqrt(lambda)/(2pi)`, 정확한 0이면
f=0이고 음수에는 실수 f를 만들지 않는다. 저장 validity·schema는 I/O가 정의한다.

## E7. Candidate와 실패 lifecycle

Geometry/density→consistent moments→lumped→K/M assembly→실제 BC→analytic split→
SPD whitening→count/FEAST→global 복원·전체 c개 독립 검증→N개 candidate 순서다.
검증 전 accepted state를 바꾸지 않는다. Writer는 candidate를 완성·self-check·close한 뒤
final HDF5를 교체하고, 준비된 state 교환은 이후 실패하지 않도록 한다. 제어된 solve/
validation/write/finalization 실패에서 이전 state·final output을 보존한다.
Live log는 별도 lifecycle이며 crash/power-loss 원자성을 새로 주장하지 않는다.
추가 nonlinear/material history나 modal stress/reaction state를 만들지 않는다.