KOKO\Mimi
180 lines
6.3 KiB
Markdown
180 lines
6.3 KiB
Markdown
# FESA Reference Tolerance Policy
|
|
|
|
## 문서 정보
|
|
|
|
- policy_id: `common-reference-tolerance`
|
|
- status: `approved-and-implemented`
|
|
- effective_date: `2026-08-18`
|
|
- decision_record: `docs/ADR.md`의 ADR-022
|
|
|
|
## 목적
|
|
|
|
이 문서는 FESA 결과와 외부 reference 결과를 비교할 때 사용하는 공통 tolerance 값과
|
|
검증 방법을 정의한다. 현재 기능뿐 아니라 앞으로 추가되는 요소, 재료, 해석, 하중 및
|
|
경계조건의 reference comparison에도 같은 규칙을 적용한다.
|
|
|
|
이 문서는 공통 수치 판정만 정의한다. 각 기능의 비교 대상, 단위, 좌표계, row identity,
|
|
component 구성과 최종 판정 영향은 해당 기능의 `requirements.md`, `reference-model.md`와
|
|
`io.md`에서 정의한다.
|
|
|
|
## 적용 범위
|
|
|
|
이 정책은 승인된 외부 reference 값과 FESA 공식 결과인 `results.h5`의 값을 비교하는 데
|
|
사용한다. Parser schema, row identity, 물리 평형, 수렴성 및 정식화 검증에는 각각의 별도
|
|
계약을 적용한다. 이러한 검증 실패를 수치 tolerance로 완화해서는 안 된다.
|
|
|
|
## 공통 tolerance 값
|
|
|
|
| 항목 | 값 | 의미 |
|
|
| --- | ---: | --- |
|
|
| Near-zero 비율 | `0.01` | Reference family 최대값의 1% 이하를 near-zero로 분류 |
|
|
| 상대오차 tolerance | `0.05` | 일반 행의 상대오차를 5% 이하로 제한 |
|
|
| Relative RMS tolerance | `0.01` | Family 전체 RMS 오차를 reference scale의 1% 이하로 제한 |
|
|
|
|
독립적인 absolute-error tolerance는 사용하지 않는다. Absolute error는 near-zero 행을
|
|
판정하고 결과를 진단하기 위해서만 사용한다.
|
|
|
|
## Comparison family
|
|
|
|
수치 scale은 개별 행이나 component마다 만들지 않고 comparison family마다 계산한다.
|
|
하나의 family에는 다음 조건이 같은 값만 포함한다.
|
|
|
|
- 같은 model 또는 reference case
|
|
- 같은 step과 frame
|
|
- 같은 logical quantity
|
|
- 같은 단위 차원
|
|
- 같은 좌표계
|
|
- 같은 최종 판정 영향(`blocking` 또는 `warning-only`)
|
|
|
|
각 기능 문서는 family 이름, 포함 component와 위 항목을 명시해야 한다. 서로 다른 단위,
|
|
좌표계 또는 판정 영향을 가진 값은 같은 family에 포함할 수 없다.
|
|
|
|
## 검증 방법
|
|
|
|
### 1. 비교 입력 확정
|
|
|
|
기능 문서가 승인한 reference artifact와 FESA `results.h5`를 사용한다. Reference artifact는
|
|
비교를 통과시키기 위해 이름을 바꾸거나 값을 수정, 보정 또는 zero-clamp하지 않는다.
|
|
|
|
### 2. Row 대응 및 사전검사
|
|
|
|
Reference와 FESA 값을 기능 문서가 정의한 stable source identity와 component로 일대일
|
|
대응시킨다. 다음 오류는 tolerance 계산 전에 comparison을 실패시킨다.
|
|
|
|
- 필요한 파일, dataset 또는 component 누락
|
|
- missing, extra 또는 duplicate row
|
|
- source identity 불일치
|
|
- 비유한 값(`NaN`, `Inf`)
|
|
|
|
Tolerance는 schema 또는 identity 오류를 허용하는 수단이 아니다.
|
|
|
|
### 3. Reference scale 계산
|
|
|
|
Family의 reference 값 `r_i`만 사용해 scale `S`와 near-zero band `B`를 계산한다.
|
|
|
|
\[
|
|
S = \max_i |r_i|
|
|
\]
|
|
|
|
\[
|
|
B = 0.01S
|
|
\]
|
|
|
|
FESA 값은 scale 계산에 사용하지 않는다. 임의의 absolute floor나 `max(1, S)`도 추가하지
|
|
않는다.
|
|
|
|
### 4. 행별 오차 판정
|
|
|
|
FESA 값 `f_i`와 reference 값 `r_i`의 absolute error를 계산한다.
|
|
|
|
\[
|
|
e_i = |f_i-r_i|
|
|
\]
|
|
|
|
Reference 값이 near-zero band 안에 있으면 absolute error로 판정한다.
|
|
|
|
\[
|
|
|r_i| \le B \quad\Rightarrow\quad e_i \le B
|
|
\]
|
|
|
|
그 외 행은 상대오차로 판정한다.
|
|
|
|
\[
|
|
|r_i| > B \quad\Rightarrow\quad \frac{e_i}{|r_i|} \le 0.05
|
|
\]
|
|
|
|
경계값은 통과에 포함하며 모든 대응 행을 검사한다.
|
|
|
|
### 5. Family Relative RMS 판정
|
|
|
|
Family의 모든 absolute error로 RMS를 계산하고 reference scale로 정규화한다.
|
|
|
|
\[
|
|
\operatorname{relative\_rms} =
|
|
\frac{\sqrt{\frac{1}{n}\sum_i e_i^2}}{S}
|
|
\]
|
|
|
|
다음을 만족해야 RMS 판정을 통과한다.
|
|
|
|
\[
|
|
\operatorname{relative\_rms} \le 0.01
|
|
\]
|
|
|
|
Family가 통과하려면 모든 행과 Relative RMS가 모두 통과해야 한다.
|
|
|
|
### 6. Reference scale이 0인 경우
|
|
|
|
`S = 0`이면 family의 모든 reference 값이 정확히 0이다.
|
|
|
|
- 모든 FESA 값도 정확히 0이면 통과한다.
|
|
- 하나라도 0이 아니면 실패한다.
|
|
- 결과에는 비유한 metric 대신 `zero-reference-scale-nonzero-error`를 기록한다.
|
|
|
|
### 7. 최종 판정
|
|
|
|
- 사전검사 실패는 항상 전체 comparison을 실패시킨다.
|
|
- `blocking` family의 행 또는 RMS 실패는 전체 comparison을 실패시킨다.
|
|
- `warning-only` family의 실패는 warning을 기록하되 전체 blocking 판정은 변경하지 않는다.
|
|
- Warning은 행 실패와 RMS 실패를 구분해 결정적인 순서로 기록한다.
|
|
|
|
## 결과 기록
|
|
|
|
Comparison 결과는 원본 값에서 판정을 재현할 수 있어야 한다. 최소한 다음 정보를
|
|
기록한다.
|
|
|
|
- 사용한 input, reference artifact와 FESA 결과 identity
|
|
- 사전검사 결과
|
|
- Family identity, component, row 수와 reference scale
|
|
- 각 행의 FESA 값, reference 값, error, 적용 판정과 통과 여부
|
|
- Family Relative RMS와 통과 여부
|
|
- Blocking failure, warning과 전체 verdict
|
|
|
|
동일한 입력을 반복 비교하면 row, family, warning과 결과 출력 순서가 같아야 한다.
|
|
|
|
## 새 기능에 적용하는 방법
|
|
|
|
새 기능의 comparator를 구현하기 전에 기능 문서에서 다음 항목을 승인한다.
|
|
|
|
1. 사용할 input, reference artifact와 FESA HDF5 위치
|
|
2. 비교할 quantity와 component
|
|
3. 단위와 좌표계
|
|
4. Stable source row identity와 일대일 mapping
|
|
5. Comparison family 구성
|
|
6. `blocking` 또는 `warning-only` 판정 영향
|
|
|
|
구현 시에는 사전검사, tolerance 경계값, zero-scale, 행별 판정, Relative RMS와 결과 기록을
|
|
테스트한다. 이후 기능별 reference comparison을 다시 실행해 evidence를 남긴다.
|
|
|
|
## 변경 관리
|
|
|
|
Tolerance 값, 계산식 또는 family 구성 규칙을 변경하려면 다음 절차를 따른다.
|
|
|
|
1. 변경 이유와 영향을 검토하고 사용자 승인을 받는다.
|
|
2. 이 문서와 ADR을 갱신한다.
|
|
3. 경계값과 실패 동작을 테스트로 먼저 고정한다.
|
|
4. 영향받는 comparator와 기능 문서를 수정한다.
|
|
5. 전체 테스트와 영향받는 reference comparison을 다시 실행한다.
|
|
|
|
기존 comparison report의 과거 수치를 소급 수정하지 않는다. 변경된 정책으로 새 evidence를
|
|
생성하며 reference artifact 자체는 변경하지 않는다.
|