modify tolerance policy

docs/TOLERANCE.md

@@ -0,0 +1,431 @@
+# 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 |r_i|\) |
+| Near-zero band \(B\) | \(0.01S\) |
+| Blocking family | 행 또는 RMS가 실패하면 전체 reference gate를 실패시키는 family |
+| Warning-only family | 동일한 실패를 warning으로 기록하지만 전체 gate를 실패시키지 않는 family |
+
+## 공통 상수
+
+모든 외부 reference comparison은 다음 세 상수를 사용한다.
+
+```text
+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를 모두 포함한다.
+
+```text
+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 |
+
+## 전체 검증 과정
+
+```mermaid
+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:
+
+```powershell
+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:
+
+```powershell
+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가 있는가?