FESADev/docs2/TOLERANCE.md

Numerical Tolerance and Comparison Policy

1. 목적

이 문서는 구조해석 FEM feature의 solver convergence, regression test와 독립 reference comparison에 사용할 tolerance 선택 절차를 정의한다. 하나의 전역 숫자를 모든 물리량에 적용하지 않으며, 각 feature의 Numerical Review가 이 정책에 따라 구체적인 metric과 값을 자율적으로 확정한다.

Tolerance는 결과를 통과시키기 위해 사후 조정하는 값이 아니라 formulation, discretization, reference 품질과 verification 목적에서 도출하는 acceptance contract다.

2. 용어 분리

다음 값은 서로 대체할 수 없다.

• Floating-point tolerance: 같은 수학 연산의 roundoff 차이를 다룬다.
• Algebraic convergence tolerance: 선형/비선형 equation solve의 residual 또는 correction 종료 조건이다.
• Discretization acceptance: mesh/order에 따른 FEM 근사 오차와 예상 convergence를 다룬다.
• Reference comparison tolerance: 독립 결과와 quantity별 차이를 판정한다.
• Physical invariant tolerance: 평형, 대칭, 보존량 또는 rigid-body behavior를 판정한다.

Abaqus의 공개된 convergence control과 output convention은 비교 모델의 의미를 맞추는 reference로 사용할 수 있지만, 그 convergence criterion을 이 solver의 결과 acceptance tolerance로 그대로 복사하지 않는다.

3. 결정 권한

Numerical Review는 사용자에게 묻지 않고 다음을 결정할 수 있다.

• 비교 quantity, identity와 component
• absolute/relative/norm/energy/MAC 등 metric
• scale과 near-zero 처리
• blocking과 diagnostic-only quantity 구분
• analytical, convergence 또는 reference evidence에 근거한 수치 tolerance

다음 경우에만 needs-user-decision으로 올린다.

• 합리적인 두 기준이 동일 결과를 pass와 fail로 나누며 제품 acceptance 의미가 달라지는 경우
• tolerance 변경이 지원 범위 또는 공개 정확도 약속을 바꾸는 경우
• authoritative requirement/reference artifact가 서로 상충하고 기술 evidence로 우선순위를 정할 수 없는 경우

단순히 기존 결과가 실패했다는 이유는 escalation이나 tolerance 완화 근거가 아니다.

4. Tolerance 선택 우선순위

1. Requirement 또는 적용 표준이 요구하는 명시적 acceptance
2. Exact/analytical/manufactured solution의 알려진 오차와 conditioning
3. Mesh/order convergence에서 관찰된 asymptotic error와 기대 rate
4. 독립 reference model의 discretization, element formulation, integration/recovery 차이
5. 동일 알고리즘 regression의 floating-point 및 backend variation

낮은 우선순위 근거가 높은 우선순위 기준을 완화하지 않는다. 선택 근거, 단위, scale, mesh와 reference revision을 feature verification 문서에 기록한다.

5. 기본 비교식

Scalar quantity x와 reference r는 별도 계약이 없으면 다음 식을 사용한다.

abs_error = |x - r|
allowed   = atol + rtol * max(|r|, scale_floor)
pass      = finite(x) and finite(r) and abs_error <= allowed

• atol, scale_floor는 quantity 단위를 가진다.
• rtol은 무차원이다.
• scale_floor는 near-zero에서 상대오차가 무한히 커지는 것을 막기 위한 물리적 scale이며 임의의 1.0을 사용하지 않는다.
• NaN/Inf, missing, extra 또는 duplicate required identity는 tolerance 적용 전에 실패한다.
• Reference가 exact zero이면 absolute/physical scale 기준을 사용한다.

Vector 또는 field는 component별 최대오차와 적절한 norm을 함께 기록한다. RMS/평균만으로 국부 최대오차를 숨기지 않는다.

6. 검증 유형별 기준

6.1 Exact semantic 및 topology test

Entity count, connectivity, identity, component order, status code와 schema field는 exact comparison을 사용한다. Floating-point tolerance로 semantic mismatch를 허용하지 않는다.

6.2 Kernel 및 regression test

• Integer/topological 결과는 exact다.
• Floating-point 결과는 operation count, magnitude, conditioning과 backend variation에서 tolerance를 도출한다.
• 같은 backend/ordering의 deterministic regression은 넓은 engineering tolerance를 쓰지 않는다.
• 수치 연산 순서가 의도적으로 바뀌면 이전 tolerance를 자동 확대하지 않고 expected envelope를 다시 분석한다.

6.3 Analytical, patch와 manufactured solution

• Polynomial reproduction과 patch-test invariant는 이론상 exact한 차수와 허용 roundoff를 구분한다.
• Displacement, strain/stress, reaction과 energy 중 formulation을 독립적으로 검출할 수 있는 quantity를 선택한다.
• Boundary singularity 또는 recovery가 지배하는 지점을 전체 field criterion과 분리한다.

6.4 Mesh/order convergence

단일 mesh의 우연한 일치보다 최소 세 수준의 refinement가 권장된다. Characteristic size h와 error e로 관찰 차수를 기록한다.

p_observed = log(e_coarse / e_fine) / log(h_coarse / h_fine)

기대 rate와 asymptotic range는 formulation 및 quantity norm에 맞춰 feature contract에서 정한다. 서로 다른 mesh의 nodal row를 단순 index로 비교하지 않는다.

6.5 Equilibrium과 nonlinear convergence

• External force/reaction과 internal residual은 동일 좌표계·sign·constraint convention으로 정규화한다.
• Force residual, displacement correction와 energy check는 각기 다른 failure mode를 보므로 하나만으로 대체하지 않는다.
• Zero-load 또는 작은-load case는 별도 physical scale을 사용한다.
• Solver convergence 성공은 discretization/reference accuracy 성공을 의미하지 않는다.

6.6 Eigenproblem

• Eigenvalue는 scale-aware absolute/relative error로 비교한다.
• Eigenvector는 sign 또는 complex phase 불변성을 고려하고 normalized correlation 또는 MAC을 사용한다.
• Clustered/repeated eigenvalue는 vector 한 개가 아니라 invariant subspace로 비교한다.
• Mode ordering을 frequency index만으로 강제하지 않고 correlation과 multiplicity를 확인한다.

6.7 Dynamic history

• Time/frequency grid와 interpolation policy를 먼저 계약한다.
• Peak, phase, energy, norm과 selected sample을 목적에 맞게 조합한다.
• 서로 다른 adaptive increment의 raw frame index를 직접 identity로 사용하지 않는다.

6.8 Stress와 recovered field

• Integration point, centroid, node extrapolation/averaging 등 output location을 먼저 일치시킨다.
• Tensor convention, local orientation와 section point를 key에 포함한다.
• Singular point는 regular field tolerance와 분리해 convergence trend 또는 exclusion 근거를 명시한다.

7. External reference comparison

외부 result를 사용하기 전에 다음 equivalence를 확인한다.

• geometry, mesh와 source identity
• element family, order, integration와 stabilization
• material/section 및 units
• loads, constraints, amplitude와 analysis step
• geometric/nonlinear option과 convergence state
• result location, coordinate system, averaging와 component convention

Stored input과 expected result는 read-only다. Reference format은 feature contract가 선택하며 특정 CSV/HDF5 layout을 이 정책이 강제하지 않는다. Matching은 semantic key로 수행하고, identity precheck가 통과한 뒤에만 수치 tolerance를 적용한다.

8. 승인 및 변경 규칙

Feature tolerance record에는 다음을 포함한다.

• quantity와 physical purpose
• metric 식, atol, rtol, scale 및 units
• blocking 여부
• 근거 source 또는 convergence evidence
• 적용 mesh, formulation, backend와 artifact digest
• known exclusions와 diagnostic-only checks

Implementation Agent는 tolerance를 변경할 수 없다. Numerical Review가 새 evidence로 contract revision을 올리고 영향을 재검토해야 한다. 변경 전 실패 결과와 변경 이유를 보존하며 새 기준으로 모든 관련 case를 다시 실행한다.

9. 보고 최소값

Comparison report는 pass/fail만 기록하지 않고 다음을 남긴다.

• matched/missing/extra/duplicate/nonfinite 개수
• quantity별 최대 absolute/relative error와 발생 identity
• 사용한 norm 또는 invariant 값
• 허용값과 pass/fail
• command, exit code, duration과 input/output digest
• 미실행 검사와 제한

이 evidence가 없으면 tolerance gate는 완료로 간주하지 않는다.