FESADev/docs/superpowers/specs/2026-08-17-common-reference-tolerance-design.md

# Common Reference Tolerance Policy Design

## Status

- date: `2026-08-17`
- status: `implemented-and-verified`
- verified_on: `2026-08-18`
- scope: 모든 FESA 외부 reference comparison
- production_solver_behavior: 변경 없음
- reference_artifact_mutation: 금지

현재 운영 상수, 검증 순서, report schema와 변경 관리는 `docs/TOLERANCE.md`를 source of
truth로 사용한다. 이 문서는 승인 결정의 설계 근거와 대안 검토를 보존한다.

## 목적

B33, MITC4 및 이후 추가되는 기능이 서로 다른 수치 tolerance 식을 만들지 않도록 공통
reference comparison 규칙을 정의한다. 이 정책은 Abaqus CSV와 FESA HDF5에서 결정적으로
대응된 행을 비교하는 외부 reference gate에만 적용한다. Element formulation, analytical
solution, matrix symmetry, residual 및 physics sanity tolerance는 이 정책의 범위가 아니다.

## 결정

모든 reference comparison은 다음 세 개의 무차원 상수를 사용한다.

```text
near_zero_ratio = 0.01
relative_tolerance = 0.05
relative_rms_tolerance = 0.01
```

독립적인 absolute-error gate는 두지 않는다. Absolute error는 reference 값이 0에 가까워
행별 상대오차를 안정적으로 계산할 수 없는 경우의 대체 판정과 진단에만 사용한다.

## Comparison Family와 Scale

Tolerance scale은 개별 component가 아니라 동일한 물리 차원의 component family마다
계산한다. 하나의 family는 최소한 다음 identity가 모두 같은 행으로 제한한다.

- model/reference case
- step 및 frame
- logical quantity
- unit dimension
- coordinate system
- blocking 또는 warning-only behavior

서로 다른 quantity나 단위 차원의 값은 scale을 공유하지 않는다. Family scale은 대응된
reference 값만 사용해 계산한다.

\[
S_g = \max_{i \in g}|R_i|
\]

여기서 \(g\)는 comparison family, \(R_i\)는 원본 reference 값이다. Reference 값은 scale
계산 전후에 clamp, rewrite 또는 생략하지 않는다.

현재 기능의 family mapping은 다음과 같다.

| feature | logical quantity / dimension | components | behavior |
| --- | --- | --- | --- |
| B33 | displacement / length | `UX`, `UY`, `UZ` | blocking |
| B33 | displacement / rotation | `URX`, `URY`, `URZ` | blocking |
| B33 | reaction / force | `RF1`, `RF2`, `RF3` | blocking |
| B33 | reaction / moment | `RM1`, `RM2`, `RM3` | blocking |
| B33 | section resultant / force | `N` | blocking |
| B33 | section resultant / moment | `T`, `My`, `Mz` | blocking |
| MITC4 | displacement / length | `U1`, `U2`, `U3` | blocking |
| MITC4 | displacement / rotation | `UR1`, `UR2`, `UR3` | warning-only |

새 quantity는 해당 기능의 requirements와 reference-model 계약에서 logical quantity,
dimension, components 및 behavior를 명시해 family에 배치한다. 물리 차원이 같다는 이유만으로
서로 다른 logical quantity를 자동으로 합치지 않는다.

### B33 element-endpoint identity amendment

2026-08-18에 사용자가 다시 생성한
`reference/cantilever beam/cantilever beam elemental forces.csv`는 `Element Label`과
`Node Label`을 모두 포함하고 B33 요소마다 두 endpoint 행을 제공한다. Section-resultant
comparison은 다음 key로 각 CSV 행을 HDF5 `[element, endpoint, component]` 행에 직접
대응시킨다.

```text
(model_id, step/frame, instance_name, source_element_label,
 source_node_label, quantity, component)
```

Component mapping은 `SF-SF1 -> N`, `SM-SM1 -> My`, `SM-SM2 -> Mz`,
`SM-SM3 -> T`다. Comparator는 이 CSV를 source-node station으로 collapse하거나 인접
endpoint를 평균하지 않는다. Missing, extra, duplicate 또는 connectivity-mismatched
element-endpoint identity는 tolerance 전에 실패한다. Production
`ResultRecovery::NormalizeSectionResultantsToNodeStations` 계약과 그 단위 테스트는 이 외부
reference identity 변경의 범위가 아니다.

## 행별 판정

각 대응 행에 대해 다음 absolute error를 계산한다.

\[
E_i = |F_i-R_i|
\]

Family scale이 양수이면 near-zero band는 다음과 같다.

\[
Z_g = 0.01S_g
\]

행은 다음 두 분기 중 정확히 하나로 판정한다.

1. \(|R_i| \le Z_g\)이면 near-zero 행이다. 이 행은 \(E_i \le Z_g\)일 때 통과한다.
2. \(|R_i| > Z_g\)이면 일반 상대오차 행이다. 이 행은
   \(E_i/|R_i| \le 0.05\)일 때 통과한다.

따라서 absolute error는 모든 행에 적용되는 별도 acceptance gate가 아니다. Near-zero
분기는 0 또는 0에 가까운 reference 행에서 정의되지 않거나 과도하게 증폭되는 raw relative
error를 대체한다.

### Zero-scale family

\(S_g=0\)이면 해당 family의 모든 reference 값이 정확히 0이다. 사용자가 독립 absolute
floor를 제외했으므로 이 경우에는 다음 fail-closed 규칙을 사용한다.

- 모든 FESA 값도 정확히 0이면 모든 행과 family relative RMS가 통과한다.
- 하나라도 0이 아닌 FESA 값이 있으면 해당 행과 family가 실패한다.

Comparator는 이 경우 infinity 또는 NaN을 report에 기록하지 않고
`zero-reference-scale-nonzero-error` 진단을 기록한다.

## Scale-relative RMS

Family 전체의 평균적인 오차 수준은 scale-relative RMS로 판정한다.

\[
\operatorname{relative\_rms}_g =
\frac{\sqrt{\frac{1}{N_g}\sum_{i \in g} E_i^2}}{S_g}
\]

\[
\operatorname{relative\_rms}_g \le 0.01
\]

이 값은 raw row-relative error의 RMS가 아니다. Error RMS를 같은 family의 reference 최대
scale로 정규화한 무차원 값이다. 행별 gate가 국부적인 큰 오차를 검출하고, relative RMS
gate가 family 전체의 평균 오차를 검출한다. 두 gate를 모두 통과해야 한다.

## 판정 순서

1. 필요한 artifact와 schema를 확인한다.
2. Source identity 및 component를 결정적으로 대응시킨다.
3. Missing, extra, duplicate, identity-mismatched 또는 nonfinite required row를 tolerance 전에
   실패시킨다.
4. Comparison family와 reference-only scale을 계산한다.
5. 모든 행에 near-zero 또는 일반 상대오차 판정을 적용한다.
6. Family scale-relative RMS를 계산한다.
7. Blocking family는 모든 행과 RMS가 통과해야 reference gate를 통과한다.
8. Warning-only family의 동일한 실패는 deterministic warning을 생성하지만 전체 reference
   verdict를 실패시키지 않는다.

Tolerance 정책은 feature별 blocking/warning-only quantity 선택을 변경하지 않는다.

## Report Contract

Comparator report는 최소한 다음 항목을 보존한다.

- family identity와 component 목록
- reference scale와 near-zero band
- 전체 행 수와 near-zero 행 수
- 각 행의 원본 FESA/reference 값, absolute error, 적용된 분기 및 판정
- 일반 상대오차 행의 relative error
- family scale-relative RMS와 판정
- maximum absolute error와 worst row를 진단 정보로 기록하되 독립 gate로 사용하지 않음
- blocking 실패와 warning-only exceedance의 구분

## 현재 B33/MITC4 Evidence

MSVC Debug build와 214개 CTest를 통과한 현재 comparator가 다음 ledger를 생성했다.
Reference artifact는 수정하지 않았으며 B33은 regenerated 20-row element-endpoint identity를
직접 비교한다.

- `.harness/build/reference/cantilever-beam-b33/comparison.json`
- `.harness/build/reference/mitc4-shell-s4-comparison/comparison.json`

| case | row gate | maximum family relative RMS | RMS gate | verdict |
| --- | --- | ---: | --- | --- |
| B33 direct endpoint | 모든 212 blocking 행 통과 | 약 `1.17e-8` | 통과 | 통과 |
| MITC4 U | 모든 blocking 행 통과 | 약 `1.03e-3` | 통과 | 통과 |
| MITC4 UR | 모든 warning-only 행 통과 | 약 `2.98e-3` | 통과 | warning 없음 |

개별 component scale을 사용하면 MITC4 `U1/U2`의 최대 reference가 약 `3.12e-23`이어서
near-zero 행 판정과 relative RMS가 실패한다. Translation family의 `U1/U2/U3`가 공통
scale을 사용하면 물리적으로 zero-like인 in-plane residue를 실제 translational response와
같은 차원에서 판정할 수 있다.

## 검토한 대안

### Component별 scale

규칙은 단순하지만 component 전체가 zero-like이면 수치 residue 자체가 scale이 된다. 현재
MITC4 `U1/U2`가 실패하므로 채택하지 않는다.

### Reference RMS를 분모로 한 relative L2 norm

`sqrt(sum(error^2)/sum(reference^2))`는 일반적인 상대 norm이지만 zero-dominant component나
family에서 분모가 불안정하거나 정의되지 않는다. Near-zero 행 규칙과 동일한 scale 의미를
공유하지 않으므로 공통 정책으로 채택하지 않는다.

### Near-zero 보정 row-relative error의 RMS

각 행의 분모를 `max(abs(reference), near_zero_band)`로 바꿔 RMS를 계산할 수 있다. 그러나
행별 near-zero 판정을 다시 집계해 같은 오차를 중복 평가하고 해석이 복잡해지므로 채택하지
않는다.

## 구현 및 계약 정렬 범위

이 문서의 승인은 목표 tolerance 정책을 고정하지만 기존 comparator와 기능 문서를 즉시
변경하지 않는다. 후속 implementation plan은 TDD로 다음을 함께 정렬해야 한다.

- 공통 comparison policy와 metric 구현
- B33 및 MITC4 comparator의 공통 정책 사용
- positive, boundary, zero-scale, near-zero, nonfinite 및 row-identity 테스트
- B33와 MITC4 requirements, numerical review, reference model, I/O 및 reference comparison
  문서의 tolerance 부분
- `AGENTS.md`와 `docs/ADR.md`의 기존 B33/MITC4 tolerance 결정을 새 공통 정책으로 대체

기존 reference input과 CSV는 생성, rename, rewrite 또는 보정하지 않는다. Production solver
formulation, HDF5 output schema, component mapping, blocking/warning-only 분류 및 physics gate도
이 tolerance 변경으로 수정하지 않는다.