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`는 별도 계약이 없으면 다음 식을 사용한다.

```text
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`로 관찰 차수를 기록한다.

```text
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는 완료로 간주하지 않는다.