FESADev/docs/TOLERANCE.md

FESA Reference Tolerance Policy

문서 정보

• policy_id: common-reference-tolerance
• status: approved-and-implemented
• effective_date: 2026-08-18
• scope: Abaqus CSV와 FESA HDF5 사이의 외부 reference comparison
• decision_record: docs/ADR.md의 ADR-022
• design_record: docs/superpowers/specs/2026-08-17-common-reference-tolerance-design.md

목적

이 문서는 FESA의 외부 reference tolerance를 관리하는 운영 기준이다. 공통 tolerance 상수뿐 아니라 row identity 사전검사, family 구성, 행별 판정, relative RMS, 최종 verdict, 보고서 evidence와 변경 절차를 하나의 source of truth로 제공한다.

이 정책은 Abaqus와 FESA의 내부 알고리즘 동등성을 판단하지 않는다. 승인된 같은 입력 모델에서 나온 외부 수치 결과가 합의된 오차 범위 안에 있는지만 검증한다.

적용 범위

적용 대상

• Abaqus reference CSV와 FESA results.h5의 deterministic comparison
• B33 displacement, rotation, reaction, section resultant
• MITC4 displacement 및 rotation
• 이후 requirements에서 family와 row identity가 승인된 reference quantity

적용하지 않는 대상

다음 검증은 이 문서의 0.01/0.05/0.01 값을 사용하지 않는다. 각 feature의 formulation, requirements, numerical-review 또는 physics contract가 별도 tolerance를 정한다.

• element stiffness symmetry, rank, rigid-body mode
• analytical solution, patch test와 mesh convergence
• linear-system residual과 global equilibrium
• energy, stress/strain sanity
• geometry, Jacobian과 director validation
• parser, HDF5 schema와 exact identity 검증

Schema와 identity 검증은 수치 tolerance보다 먼저 수행하며 tolerance로 완화할 수 없다.

용어

용어	정의
FESA 값 (f_i)	Authoritative results.h5에서 deterministic projection으로 얻은 값
Reference 값 (r_i)	승인된 read-only Abaqus CSV에서 얻은 값
Matched row	Model/case, step/frame, source identity, quantity와 component가 정확히 대응된 한 행
Family	같은 logical quantity, unit dimension, coordinate system과 blocking behavior를 공유하는 component 집합
Reference scale (S)	Family reference 값만으로 계산한 (\max_i
Near-zero band (B)	(0.01S)
Blocking family	행 또는 RMS가 실패하면 전체 reference gate를 실패시키는 family
Warning-only family	동일한 실패를 warning으로 기록하지만 전체 gate를 실패시키지 않는 family

공통 상수

모든 외부 reference comparison은 다음 세 상수를 사용한다.

near_zero_ratio = 0.01
relative_tolerance = 0.05
relative_rms_tolerance = 0.01

• near_zero_ratio: family 최대 reference 크기의 1% 이하를 near-zero row로 분류
• relative_tolerance: 일반 row의 최대 상대오차 5%
• relative_rms_tolerance: family error RMS가 reference scale의 1% 이하

독립적인 absolute-error gate는 사용하지 않는다. Maximum absolute error는 진단 정보이며 그 자체로 pass/fail을 결정하지 않는다.

Comparison family

Family는 다음 identity를 모두 포함한다.

model_or_case
step_and_frame
logical_quantity
unit_dimension
coordinate_system
blocking_behavior

서로 다른 물리 차원, 좌표계 또는 blocking behavior는 같은 scale을 공유하지 않는다. Component가 작다는 이유만으로 별도 family로 분리하지 않는다.

현재 승인된 family

Feature	Family	Components	Dimension	Coordinates	Behavior
B33	displacement-translation	UX, UY, UZ	length	global Cartesian	blocking
B33	displacement-rotation	URX, URY, URZ	rotation	global Cartesian	blocking
B33	reaction-force	RF1, RF2, RF3	force	global Cartesian	blocking
B33	reaction-moment	RM1, RM2, RM3	force × length	global Cartesian	blocking
B33	section-force	N	force	beam local	blocking
B33	section-moment	T, My, Mz	force × length	beam local	blocking
MITC4	displacement-translation	U1, U2, U3	length	global Cartesian	blocking
MITC4	displacement-rotation	UR1, UR2, UR3	rotation	global Cartesian	warning-only

전체 검증 과정

flowchart TD
  A[승인 input과 read-only reference CSV 확인] --> B[FESA로 같은 input 해석]
  B --> C[authoritative results.h5 생성]
  C --> D[CSV와 HDF5를 canonical row로 projection]
  D --> E{row identity, schema, finite precheck}
  E -- fail --> X[수치 비교 전 hard failure]
  E -- pass --> F[comparison family 구성]
  F --> G[reference-only scale S와 near-zero band 계산]
  G --> H[모든 row에 near-zero 또는 relative gate 적용]
  H --> I[family scale-relative RMS 계산]
  I --> J[blocking 또는 warning-only behavior 적용]
  J --> K[deterministic JSON과 report 기록]

1. Reference artifact 확인

기능별 reference-model.md와 io.md가 지정한 정확한 input/CSV 경로만 사용한다. Comparator와 agent는 reference artifact를 rename, rewrite, 보정 또는 zero-clamp하지 않는다. Metadata, README 또는 canonical filename은 feature requirement가 수치 계약으로 명시하지 않는 한 readiness 조건이 아니다.

2. FESA 결과 생성

Reference와 같은 .inp를 FESA로 해석하고 authoritative results.h5를 생성한다. CSV로 다시 내보낸 FESA 값은 디버깅용 view일 뿐 authoritative comparison source가 아니다.

3. Canonical row projection

CSV와 HDF5 값을 기능 계약의 stable source identity와 component로 canonical row에 투영한다. Internal index 또는 equation index를 source identity 대신 사용하지 않는다.

• B33 displacement/reaction: (model, Step-1, frame 0, instance, source node label, quantity, component)
• B33 section resultant: (model, Step-1, frame 0, instance, source element label, endpoint source node label, quantity, component)
• MITC4 displacement/rotation: (case, Step-1, frame 0, instance, source node label, quantity, component)

B33 section mapping은 SF1 -> N, SM1 -> My, SM2 -> Mz, SM3 -> T다. Element endpoint를 node station으로 collapse하거나 대표 endpoint를 선택하거나 평균하지 않는다.

4. 수치 비교 전 hard precheck

다음 중 하나라도 발견되면 tolerance 계산을 시작하지 않고 comparison을 실패시킨다.

• required file 또는 dataset 누락
• CSV/HDF5 header, shape, component inventory 불일치
• missing 또는 extra canonical row
• duplicate row identity
• source instance/node/element/endpoint identity 불일치
• element endpoint와 input connectivity 불일치
• nonfinite FESA/reference 값 또는 계산 중 nonfinite error

이 오류는 warning-only family에 속하더라도 hard failure다. Tolerance는 schema나 identity 문제를 숨기는 수단이 아니다.

5. Reference scale과 near-zero band

각 family (g)에 대해 read-only reference 값만 사용한다.

[ S_g = \max_i |r_i| ]

[ B_g = 0.01S_g ]

FESA 값을 scale 계산에 사용하지 않는다. max(1, ...), 임의 floor, unit별 absolute tolerance 또는 reference zero clamp를 추가하지 않는다.

6. 행별 판정

먼저 absolute error를 계산한다.

[ e_i = |f_i-r_i| ]

Near-zero row

[ |r_i| \le B_g ]

이면 다음을 만족할 때 통과한다.

[ e_i \le B_g ]

일반 relative row

[ |r_i| > B_g ]

이면 다음을 만족할 때 통과한다.

[ \frac{e_i}{|r_i|} \le 0.05 ]

Near-zero 분류와 두 threshold는 경계값을 포함한다. 모든 matched row를 판정하며 작은 reference 값이나 zero row를 삭제하지 않는다.

7. Zero-scale family

(S_g=0)이면 family의 모든 reference 값이 정확히 0이다. 독립 absolute floor가 없으므로 다음 fail-closed 규칙을 적용한다.

• 모든 FESA 값도 정확히 0이면 모든 row와 family RMS가 통과한다.
• 하나라도 0이 아닌 FESA 값이 있으면 해당 row와 family가 실패한다.
• Report에는 NaN/Inf 대신 zero-reference-scale-nonzero-error를 기록한다.

8. Family scale-relative RMS

Family의 모든 absolute error로 error RMS를 계산하고 같은 reference scale로 정규화한다.

[ \operatorname{relative_rms}_g = \frac{\sqrt{\frac{1}{n_g}\sum_i e_i^2}}{S_g} ]

[ \operatorname{relative_rms}_g \le 0.01 ]

이 값은 row-relative error들의 RMS가 아니다. Family의 모든 row gate와 RMS gate가 모두 통과해야 family가 통과한다.

9. 최종 verdict

상태	전체 reference verdict
Precheck failure	항상 실패
Blocking family row failure	실패
Blocking family RMS failure	실패
Warning-only family row failure	전체 verdict 유지, row warning 생성
Warning-only family RMS failure	전체 verdict 유지, RMS warning 생성
Warning-only row와 RMS 동시 실패	두 종류의 deterministic warning을 모두 생성
모든 blocking family 통과	Reference gate 통과

Warning-only family도 동일한 수치 규칙과 report schema를 사용한다. 차이는 전체 verdict에 미치는 영향뿐이다.

10. Evidence report

Report는 사람이 원본 값에서 판정을 재현할 수 있어야 한다.

Row별 필수 항목

• model/case와 feature contract가 정한 step/frame
• instance와 source node/element/endpoint identity
• quantity와 component
• FESA 값, reference 값, absolute error
• reference scale과 near-zero band
• 적용 branch: near-zero, relative 또는 zero-scale-exact
• 적용 threshold와, 해당되는 경우 row relative error
• blocking 여부와 row pass/fail

Units와 coordinate system은 family와 feature reference/I/O contract에 반드시 정의한다. Row JSON이 이를 직접 반복하지 않더라도 report가 해당 contract와 family identity를 결정적으로 가리켜야 한다.

Family별 필수 항목

• family identity와 component 목록
• total row_count와 near_zero_count
• reference scale과 near-zero band
• maximum absolute error와 deterministic worst row
• scale-relative RMS와 RMS pass/fail
• family pass/fail과 diagnostic code

전체 필수 항목

• missing/extra/duplicate/nonfinite precheck 결과
• blocking failure와 warning-only warning 목록
• overall passed verdict
• 사용한 input/reference/HDF5 identity

Report에는 nonfinite metric을 기록하지 않는다. Historical report의 수치나 판정을 새 정책에 맞춰 소급 수정하지 않고 새 comparison evidence를 별도 생성한다.

계산 예시

일반 relative row

Family scale이 (S=100)이면 near-zero band는 (B=1)이다.

• (r=50), (f=52.4): 상대오차 (2.4/50=0.048), 통과
• (r=50), (f=52.6): 상대오차 (2.6/50=0.052), 실패

Near-zero row

같은 family에서 (S=100), (B=1)일 때:

• (r=0.2), (e=0.9): (0.9 \le 1), 통과
• (r=0.2), (e=1.1): (1.1 > 1), 실패

RMS gate

네 reference 값이 모두 (100)이고 (S=100)일 때, 각 error가 (0.8)이면 relative RMS는 (0.008)로 통과한다. 각 error가 (1.1)이면 각 row의 상대오차는 (0.011)로 통과하지만 relative RMS도 (0.011)이므로 family는 실패한다.

Zero-scale family

• Reference [0,0,0], FESA [0,0,0] → 통과
• Reference [0,0,0], FESA [0,1e-12,0] → exact-zero 규칙 실패, zero-reference-scale-nonzero-error

구현 위치와 검증 진입점

책임	위치
공통 evaluator	tests/reference/reference_tolerance_policy.h/.cpp
공통 boundary tests	tests/reference/reference_tolerance_policy_test.cpp
B33 comparator와 JSON	tests/reference/reference_comparison.h/.cpp
B33 tests	tests/reference/reference_comparison_test.cpp, tests/reference/b33_reference_comparison_test.cpp
MITC4 comparator와 JSON	tests/reference/mitc4_reference_comparison.h/.cpp
MITC4 tests	tests/reference/mitc4_reference_comparison_test.cpp, tests/reference/mitc4_reference_cases_test.cpp

Focused verification:

cmake --build .harness/build --config Debug --target fesa_reference_tests
ctest --test-dir .harness/build -C Debug -R 'ReferenceTolerancePolicy|ReferenceComparisonContract|B33ReferenceComparison|Mitc4ReferenceComparison|Mitc4S4Reference' --output-on-failure

전체 verification:

cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure

Generated JSON ledger는 .harness/build/reference/ 아래에 두며 Git에 commit하지 않는다. Feature별 current evidence는 해당 docs/<feature-id>/reference-comparison.md에 기록한다.

규범 요구조건

• FESA-TOL-001 — Comparator shall use only the exact feature-approved read-only reference artifacts and authoritative FESA HDF5 values.
• FESA-TOL-002 — Comparator shall reject missing, extra, duplicate, nonfinite, schema- or identity-mismatched rows before numerical tolerance evaluation.
• FESA-TOL-003 — Comparator shall group matched rows only by the approved family identity, unit dimension, coordinate system and blocking behavior.
• FESA-TOL-004 — Every nonzero-scale family shall use near-zero ratio 0.01, row relative tolerance 0.05 and scale-relative RMS tolerance 0.01.
• FESA-TOL-005 — A zero-scale family shall pass only when every FESA value is exactly zero and shall otherwise report zero-reference-scale-nonzero-error without NaN/Inf.
• FESA-TOL-006 — Every matched row and family RMS shall be evaluated; no row shall be clamped, omitted, averaged or hidden by an independent absolute-error gate.
• FESA-TOL-007 — Blocking-family failure shall fail the reference gate; warning-only failure shall emit deterministic row/RMS warnings without changing the blocking verdict.
• FESA-TOL-008 — The report shall contain every row decision, family row count, scale, near-zero inventory, worst error, relative RMS, diagnostic and overall verdict.
• FESA-TOL-009 — Repeated comparison of the same artifacts and HDF5 shall preserve row, family, diagnostic and JSON ordering.
• FESA-TOL-010 — Tolerance constants, family membership, row identity or blocking behavior shall not change without explicit approval and fresh comparison evidence.

Requirement Verification Matrix

ID	Verification method	Acceptance criteria	Evidence
FESA-TOL-001	Reference integration tests and run-local before/after content audit	Exact declared paths used; comparison run이 reference를 변경하지 않음	Feature reference tests; run-local hash/diff evidence
FESA-TOL-002	Missing/extra/duplicate/nonfinite/identity negative tests	Deterministic failure before row metrics	Comparator contract tests
FESA-TOL-003	Family membership and component tests	Exact approved components, units, coordinates and behavior	JSON family metrics
FESA-TOL-004	Inclusive boundary, near-zero and RMS tests	0.01/0.05/0.01 gates match this document	Common evaluator tests
FESA-TOL-005	All-zero and one-nonzero zero-scale tests	Finite metrics and exact diagnostic	Common evaluator and JSON tests
FESA-TOL-006	Row inventory and no-clamp/no-average tests	Every canonical row has one decision	Comparator row-count/identity tests
FESA-TOL-007	Blocking, row-warning, RMS-warning and combined-warning tests	Correct verdict and deterministic warnings	MITC4 comparator tests
FESA-TOL-008	JSON schema assertions	Required row/family/overall fields present and finite	B33/MITC4 deterministic JSON tests
FESA-TOL-009	Repeated writer/comparison tests	Byte-stable ordering for the same inputs	Deterministic report tests
FESA-TOL-010	ADR/doc/diff/revalidation review	All affected contracts and evidence updated together	ADR-022, feature reports, review record

새 reference quantity 추가 절차

새 기능이나 quantity는 comparator code부터 추가하지 않는다.

1. Feature requirements에 exact input/CSV paths와 blocking/warning-only quantity를 정의한다.
2. Units, coordinate system, source row identity, component mapping과 result location을 정의한다.
3. Existing family에 포함할지 새 family를 만들지 dimension/behavior 기준으로 결정한다.
4. Numerical review와 reference-model에서 row precheck와 readiness를 승인한다.
5. I/O 문서에서 CSV column을 authoritative HDF5 dataset/component에 연결한다.
6. RED test로 identity, family, boundary, zero-scale, RMS와 report contract를 고정한다.
7. Comparator를 구현하고 focused/full MSVC CTest를 통과한다.
8. Fresh reference-comparison report를 생성하고 이후 physics/release gate를 진행한다.

Tolerance 변경 관리

Tolerance 상수, 수식, family membership, row identity 또는 blocking behavior를 변경하려면 다음 항목을 함께 처리한다.

1. 사용자 명시 승인
2. 이 문서와 ADR의 decision, rationale과 tradeoff 갱신
3. Common design 및 영향받는 feature requirements/reference-model/I/O 문서 갱신
4. Boundary와 failure semantics를 먼저 고정한 RED test
5. 공통 evaluator 및 영향받는 comparator의 최소 수정
6. Focused reference tests와 전체 MSVC/CTest
7. 모든 영향 feature의 fresh reference comparison
8. 기존 physics/release evidence의 유효성 재검토

과거 report의 원본 hash, command, row count와 metric table은 소급 수정하지 않는다. Historical status를 보존하고 새 정책으로 생성한 evidence를 별도 섹션 또는 새 report에 추가한다. Reference CSV는 tolerance 변경을 맞추기 위해 수정하지 않는다.

검토 체크리스트

• Exact reference input/CSV와 authoritative HDF5를 사용했는가?
• Canonical row identity와 component mapping이 기능 계약과 일치하는가?
• Missing/extra/duplicate/nonfinite row를 tolerance 전에 거부했는가?
• Family가 units, coordinates와 blocking behavior를 섞지 않는가?
• Scale을 reference 값만으로 계산했는가?
• 모든 row에 near-zero 또는 relative branch가 기록됐는가?
• Zero-scale에서 exact-zero와 finite diagnostic을 보장하는가?
• 모든 family의 scale-relative RMS를 판정했는가?
• Warning-only row/RMS failure를 deterministic warning으로 기록했는가?
• Report에 row count, scale, worst row, RMS와 overall verdict가 있는가?
• Reference artifact와 historical evidence를 변경하지 않았는가?
• Focused 및 full verification evidence가 있는가?