docs: design common reference tolerance policy
This commit is contained in:
KOKO\Mimi
@@ -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 변경으로 수정하지 않는다.
|
||||
Reference in New Issue
Block a user