diff --git a/docs/superpowers/specs/2026-08-17-common-reference-tolerance-design.md b/docs/superpowers/specs/2026-08-17-common-reference-tolerance-design.md new file mode 100644 index 0000000..a102962 --- /dev/null +++ b/docs/superpowers/specs/2026-08-17-common-reference-tolerance-design.md @@ -0,0 +1,202 @@ +# Common Reference Tolerance Policy Design + +## Status + +- date: `2026-08-17` +- status: `approved-design-pending-implementation` +- scope: 모든 FESA 외부 reference comparison +- production_solver_behavior: 변경 없음 +- reference_artifact_mutation: 금지 + +## 목적 + +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를 자동으로 합치지 않는다. + +## 행별 판정 + +각 대응 행에 대해 다음 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 + +기존 solver를 재실행하거나 reference artifact를 수정하지 않고 다음 생성 ledger의 원본 +FESA/reference 값을 새 규칙으로 재계산했다. + +- `.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 | 모든 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 변경으로 수정하지 않는다.