FESADev/docs/hex8-structural-analysis/numeric-controls.md

# Hex8 numeric controls

행동/외부 acceptance 원본은 [PRD](PRD.md), 식은 [formulation](formulation.md)이다.
여기의 내부 tuning default는 독립 numerical review와 영향 재검증을 기록해 조정할 수 있다.
외부 [common-reference-tolerance](../TOLERANCE.md) 및 승인 physics/schema는 변경하지 않는다.

## 계산·형상 인증

모든 input/파생 값/결과를 finite 검증하고 positive Jacobian·밀도·material capability를 확인한다.
Production 계산 precision은 Float64다. Whole-cell 인증은 outward interval coefficient bounds와
subdivision이며 estimate-only positive 검사와 abs(det J)를 허용하지 않는다.
Depth default10, 처리한 cell budget default65536이며 uncertain 시 fail-closed다. 이 값은
resource/precision tuning이고 accepted geometry의 positive 조건을 완화하는 tolerance가 아니다.
현재 Xa+ua를 인증할 때 addition uncertainty도 포함한다. Failed trial은 immutable cache를 보존한다.

## 정적 Newton

Force residual numerator는 free residual infinity norm이다. 기존
`nonlinear_static_control.cpp::EvaluateResidualChannel`과 같이 free external infinity norm이
exact0이면 denominator=0의 absolute branch를 선택한다. External이 nonzero이면 같은 trial의
free internal/external infinity norm maximum을 relative denominator로 사용한다.
Translation correction numerator는 fresh free correction infinity norm, scale은 현재 증분의
free translation increment infinity norm이다. 기존 force/translation norm·branch 의미를 유지한다.
순수 prescribed 변위 문제에서 fint_free 자체를 denominator로 사용해 residual ratio가 항상1이
되게 만들지 않는다. Nonfinite/크기 불일치는 branch와 관계없이 실패다.
Relative branch limit1e-2, exact-zero scale branch absolute1e-3의 force 또는 length 단위다.
Max iteration100/increment가 default다. Moment/rotation dummy channel은 없다.
Raw norms·branch·threshold unit·iteration·passed를 기록한다. 수렴은 recovery/geometry까지
검증한 candidate에만 적용하며 normalized residual만 수정해 accept하지 않는다.

## 동적 Newton와 update

Residual은 physical free endpoint에서 평가한다. Componentwise uncancelled scale
Si=|(Ma)i|+|finti|+|Fi|, normalized metric은 max_i(|ri|/Si)다. Si=0은 ri=0을 요구하며
그 외의 zero branch는 failure다. Internal cancellation으로 작은 residual이 나온 것만 평가하지 않는다.
Weighted residual을 사용할 때도 physical endpoint와 동일한 scale/판정을 함께 기록한다.

L은 reference nodal bounding-box 대각 길이로 finite positive다. Correction u/L, h·dv/L,
h²·da/L, h²·dA/L를 모두 확인한다. Residual/correction limit1e-10, update equality1e-12,
max iteration100이 default다. Update scale은 동일 단위의 uncancelled formula term 합이며 scale0은
exact-zero다. 빈 free vector는 vacuous convergence이며 required prescribed/recovery validation은 유지한다.

### 표현 가능한 변위에서의 내부 정제

검토된 별도 동적 구현 `f661864`는 위 판정을 유지하며 다음 정제를 사용한다.
관련76개 검사와 독립 코드 검토는 통과했고 두 동적 원본의 새 실행은 진행 중이다.
이전 구현 `b394ae7`의 원본 실패와 변경 근거는 [lessons](lessons.md)에 기록한다.

물리 잔차가 통과한 좌표에서 sub-ULP 갱신 소실이 발생하면, 물리 잔차와 각 좌표의
fresh correction4개가 모두 통과한 좌표를 hold한다. 다음 반복부터 원래 effective tangent의
나머지 principal block을 푼다.
Holding은 새 BC나 equation 제거가 아니다. 다음 반복에서 해당 성분이 원래 물리 기준을
실패하면 즉시 다시 solve에 포함한다. 최종 판정은 항상 모든 원래 free 성분을 사용한다.

정체 판별은 잔차 최대 점수의 증가 대신 이미 실패한 Newton 진입 상태로의 복귀를 사용한다.
진입 tuple은 전체3N 변위·reactivation 전 holding mask·incoming correction4개다.
Physical FAIL 및 finite correction4개가 각각 PASS인 진입만 저장한다. 실제 다음 Newton의
전체 변위·freeze 후 mask가 정확히 같고 fresh correction4개도 각각 finite/PASS이면
동등한 실패 상태로 판별한다. Correction 숫자의 차이는 진단으로 남기지만 동일성을 요구하지
않는다. 숫자 자체는 정상 Newton의 rates·tangent·rhs에 사용되지 않는다는 검토에 근거한다.
고정 증분의 M·하중·이전 accepted state·predictor 및 결정적인 fresh solve/탄성 local
recovery가 전제다. History는 증분 시작에만 초기화하고 실제 ULP 이동 후에도 유지한다.
Prospective physical PASS, correction FAIL 또는 새로운 전체 변위/mask는 정상 Newton을
유지한다. 별도 history cap이나 threshold는 없으며 기존100회 제한으로 기록 수가 제한된다.
이는 알려진 실패 상태의 재방문을 감지해 내부 정제를 시도하는 선택이며 전체 알고리즘의
수렴 보장은 아니다. 실제로 개선하는 이웃이 없으면 기존 Newton 경로를 유지한다.

재현이 확인된 경우에만 각 free 좌표의 양·음 방향 한 ULP 이웃을 예측한다.
물리 관성력 변화는 `M*delta_u/((1+alpha)*beta*h^2)`, 내력 변화는 `Kt*delta_u`로
분리하여 모든 free 성분의 예측 Si를 계산한다. 유한하며 원래 최대 점수를 줄이는 이웃을
점수·source DOF 순서로 검사하고 방향 tie는 음 방향을 먼저 둔다. 예측 성공은 수용이 아니다.
각 trial은 같은 원래 candidate에서 실제 rates·형상·내력·모든 원래 Si·update·weighted
identity를 재계산한다. 앞의 trial이 개선하지 못해도 이후 후보를 검사하며 evaluator 실패는
그대로 실패다. 실제 전체 최대 점수의 엄격 감소를 확인한 이동만 local candidate에 반영한다.
이동량의 correction4개를 기록하고 다음 정상 반복에서 모든 원래 최종 조건을 다시 검사한다.
원래100회 제한을 유지하며 별도 residual floor·clamp·projection을 두지 않는다.

## Eigen 검증과 분류

Vector norm은 Euclidean, matrix norm은 Frobenius로 original free pencil을 평가한다.
eta_r=||Kphi−lambda Mphi||/((||K||F+|lambda|||M||F)||phi||2),
eta_norm=|phiᵀMphi−1|,
eta_energy=|phiᵀKphi−lambda phiᵀMphi|/((||K||F+|lambda|||M||F)||phi||2²)다.
Zero denominator는 numerator exact0이면0, 아니면 failure다. All returned-pair limits는1e-10.
eta_gram은 ||PhiᵀM Phi−I||F, max_eta_orth는 normalized off-diagonal maximum이고 limit1e-10다.

분류 scale=max_i |Kii|/Mii는 finite positive여야 하며 default normalized near-zero1e-9,
인접 cluster gap1e-8이다. 유의한 negative lambda는 실패한다. Near-zero negative는 원 값으로
남기고 frequency를 만들지 않는다. 이 분류 scale은 FEAST interval upper bound가 아니다.
실제 search/count·SPD/roundoff budget은 backend 연결에서 검증하며 최저 N 보장 근거를 기록한다.

## 독립 local/temporal 검사의 수치 기준

Zero 기대량에는 임의 absolute floor 대신 same-unit uncancelled term scale 또는 수식에 따른
strain/force/energy scale을 사용한다. Initial invariant budget은 double eps와 연산 길이·geometry
condition 추정에 비례하는512 eps scale이다. Scale0은 exact-zero다. Conditioning 때문에 budget이
물리 결함을 가릴 정도로 커지면 검사를 통과시키지 않고 모델/검사 유효 범위를 보고한다.

Directional difference는 signed direction과 h sweep으로 truncation/roundoff 구간을 확인한다.
기본 목표는 유의한 nonzero oracle scale에 대해 gradient/tangent 최적 구간 relative1e-7 이하다.
한 h에서 가까운 값만 고르지 않고 예상 error curve·analytic affine 사례·zero-state linear limit를
함께 확인한다. 필요 budget 수정은 oracle conditioning과 independent review evidence로 설명한다.

HHT temporal case는 analytic/manufactured u/v/physical a를 각각 평가한다. Smooth forcing 구간의
기본 목표는 h/h2/h4에서 observed order1.8 이상이며 noise floor에 가까운 quantity는 다른 유의한
case/time/step 범위로 검사한다. Knot를 가로지른 비매끄러운 forcing을 smooth-order 증거로 쓰지 않는다.
Spatial refinement·locking은 수렴 경향과 적용 한계의 검사이며 reference tolerance를 재정의하지 않는다.

## 원본 비교

Reference-only S/B, row5%, RMS1%, exact-zero는 common policy를 따른다. Identity/finite/completeness
오류를 tolerance로 처리하지 않는다. Stress point 좌표는 출력 precision에 따른 auxiliary convention
검사이며 ID matching은 element/IntPt다. Input/CSV raw SHA는 현재 working-tree byte 기준이며
Git LF blob과 Windows CRLF bytes를 혼동하지 않는다. 실제 읽은 원본 byte identity를 evidence에 남긴다.