baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
FESADev/docs/superpowers/specs/2026-08-17-common-reference-tolerance-design.md
T
KOKO\Mimi 624ea4872c modify tolerance policy
2026-08-18 02:29:26 +09:00

9.7 KiB
Raw Permalink Blame History

Common Reference Tolerance Policy Design

Status

  • date: 2026-08-17
  • status: implemented-and-verified
  • verified_on: 2026-08-18
  • scope: 모든 FESA 외부 reference comparison
  • production_solver_behavior: 변경 없음
  • reference_artifact_mutation: 금지

현재 운영 상수, 검증 순서, report schema와 변경 관리는 docs/TOLERANCE.md를 source of truth로 사용한다. 이 문서는 승인 결정의 설계 근거와 대안 검토를 보존한다.

목적

B33, MITC4 및 이후 추가되는 기능이 서로 다른 수치 tolerance 식을 만들지 않도록 공통 reference comparison 규칙을 정의한다. 이 정책은 Abaqus CSV와 FESA HDF5에서 결정적으로 대응된 행을 비교하는 외부 reference gate에만 적용한다. Element formulation, analytical solution, matrix symmetry, residual 및 physics sanity tolerance는 이 정책의 범위가 아니다.

결정

모든 reference comparison은 다음 세 개의 무차원 상수를 사용한다.

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를 자동으로 합치지 않는다.

B33 element-endpoint identity amendment

2026-08-18에 사용자가 다시 생성한 reference/cantilever beam/cantilever beam elemental forces.csv는 Element Label과 Node Label을 모두 포함하고 B33 요소마다 두 endpoint 행을 제공한다. Section-resultant comparison은 다음 key로 각 CSV 행을 HDF5 [element, endpoint, component] 행에 직접 대응시킨다.

(model_id, step/frame, instance_name, source_element_label,
 source_node_label, quantity, component)

Component mapping은 SF-SF1 -> N, SM-SM1 -> My, SM-SM2 -> Mz, SM-SM3 -> T다. Comparator는 이 CSV를 source-node station으로 collapse하거나 인접 endpoint를 평균하지 않는다. Missing, extra, duplicate 또는 connectivity-mismatched element-endpoint identity는 tolerance 전에 실패한다. Production ResultRecovery::NormalizeSectionResultantsToNodeStations 계약과 그 단위 테스트는 이 외부 reference identity 변경의 범위가 아니다.

행별 판정

각 대응 행에 대해 다음 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

MSVC Debug build와 214개 CTest를 통과한 현재 comparator가 다음 ledger를 생성했다. Reference artifact는 수정하지 않았으며 B33은 regenerated 20-row element-endpoint identity를 직접 비교한다.

  • .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 direct endpoint 모든 212 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 View Git Blame Copy Permalink