FESADev/docs/TOLERANCE.md

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 자체는 변경하지 않는다.