docs(beam-reference-qualification): define dual validation gates

docs/ADR.md

@@ -257,7 +257,7 @@ flat `Domain`으로 정규화한다. 외부 entity는 `(instance name, part-loca
 
 ## ADR-015: 명시적 물리량 선택 기반 CSV 검증
 
-**상태:** Accepted
+**상태:** Superseded by ADR-017
 
 **상황:** 현재 캔틸레버 reference에는 변위와 반력만 있고 per-model metadata는
 요구하지 않는다. 요소 내력과 응력 비교 기능은 해당 CSV가 추가되기 전에 구현해야
@@ -297,3 +297,42 @@ toolset을 명시한다. CMake, CMake Presets, CTest 및 GoogleTest/GoogleMock
   보장 대상이 아니다.
 - 컴파일러 갱신에 따른 경고와 표준 라이브러리 동작은 전체 Debug/Release 검증에서
   다시 확인해야 한다.
+
+## ADR-017: FESA 정식화 적합성과 Abaqus 결과 상관성의 이중 gate
+
+**상태:** Accepted
+
+**상황:** FESA의 2절점 Timoshenko Beam은 선택적 감차적분과 `SCF=0`을 사용하고
+Abaqus B31의 slenderness compensation을 구현하지 않는다. 따라서 `SCF=0.25`인
+Abaqus 결과에 기본 상대오차 \(10^{-5}\)를 적용하면 FESA 정식화 결함과 의도된
+정식화 차이를 구분할 수 없다. 현재 캔틸레버 reference에는 변위, 반력 및 요소
+단면력 CSV가 있다.
+
+**결정:**
+
+- FESA 정식화 적합성 gate는 해석해, 에너지, 강체 mode, 평형 및 엄격한 tolerance로
+  FESA 자체 정식화를 검증한다.
+- Abaqus 결과 상관성 gate는 원본 Abaqus 입력과 CSV를 변경하지 않는다. FESA는
+  동일한 기하·재료·하중과 명시적 전단강성을 사용하되 `SCF=0`인 별도 입력을
+  production parser와 solver로 해석한다.
+- 상관성 gate는 요청된 모든 entity와 component가 유일하게 매칭되고 유한한
+  component별 RMSE 및 Relative L2가 생성되면 evaluable이다. 서로 다른 정식화에
+  기본 상대오차 \(10^{-5}\) pass/fail을 적용하지 않는다.
+- Relative L2의 reference norm이 영에 가까우면 해당 component의 characteristic
+  absolute scale norm을 분모 하한으로 사용한다.
+- 병진과 회전, 힘과 모멘트처럼 단위가 다른 component를 하나의 RMSE 또는 norm에
+  혼합하지 않는다.
+- Abaqus의 \((\mathbf t,\mathbf n_1,\mathbf n_2)\)와 FESA의
+  \((\mathbf e_x,\mathbf e_y,\mathbf e_z)\)를 각각 일치시킨 모델에서 Abaqus
+  `SF1,SF2,SF3,SM1,SM2,SM3`은 FESA \(N,V_y,V_z,T,M_y,M_z\) 순서로
+  `SF1,SF3,SF2,SM3,SM1,SM2`를 사용한다.
+- 현재 캔틸레버 상관성 요청은 변위, 반력 및 요소 단면력을 명시한다. 요청하지 않은
+  응력은 통과로 보고하지 않는다.
+
+**결과와 트레이드오프:**
+
+- FESA 구현 회귀와 상용 solver와의 모델 상관성을 서로 오인하지 않는다.
+- Abaqus 원본과 FESA 투영 입력을 함께 관리해야 하며 formulation 차이를
+  `docs/VALIDATION.md`에 기록해야 한다.
+- 첫 상관성 보고서는 metric을 제시하지만 관측값에 맞춘 acceptance envelope를
+  만들지 않는다. 후속 envelope에는 해석적 또는 mesh study 근거가 필요하다.

docs/PRD.md

@@ -163,8 +163,8 @@ HDF5 결과는 다음 정보를 함께 갖는 자기완결형 파일이어야
    - 여러 재료·단면과 중첩 집합
 4. Reference 테스트
    - Abaqus/Standard 2024 B31 결과
-   - 현재 캔틸레버의 변위와 반력
+   - 현재 캔틸레버의 변위, 반력 및 요소 단면력
-   - 요소 내력 및 요소 절점 단면 도심 응력 비교 계약의 synthetic CSV 검증
+   - 요소 절점 단면 도심 응력 비교 계약의 synthetic CSV 검증
 
 ### 5.2 골든 데이터
 
@@ -174,8 +174,15 @@ Abaqus는 CI나 Harness에서 자동 실행하지 않는다. 별도 Abaqus 2024
 
 비교 실행은 물리량과 해당 CSV 경로를 명시한다. 요청한 파일이 없으면 실패하고,
 요청하지 않은 물리량은 통과로 보고하지 않는다. 현재 `reference/cantilever beam`
-샘플은 변위와 반력만 비교한다. 요소 내력과 응력 CSV가 추가되기 전까지 해당
+샘플은 변위, 반력 및 요소 단면력을 비교한다. 요소 응력 CSV가 추가되기 전까지
-reader와 비교 kernel은 synthetic CSV로 검증한다.
+해당 reader와 비교 kernel은 synthetic CSV로 검증한다.
+
+FESA 정식화 적합성과 Abaqus 결과 상관성은 별도 gate로 운영한다. FESA 적합성
+gate는 `SCF=0`, 선택적 감차적분 및 문서화된 FESA 정식화를 해석해와 physics
+invariant로 엄격히 검증한다. Abaqus 상관성 gate는 `SCF=0.25`를 포함할 수 있는
+원본 Abaqus 모델과 CSV를 보존하고, 동일한 기하·재료·하중에 `SCF=0`을 적용한
+별도 FESA 입력을 production pipeline으로 해석해 결과 차이를 정량화한다. 상관성
+gate는 서로 다른 정식화의 수치 일치를 주장하지 않는다.
 
 CSV 식별 및 값 열:
 
@@ -185,17 +192,35 @@ CSV 식별 및 값 열:
   `SF-SF1..SF-SF3`, `SM-SM1..SM-SM3`
 - 요소 응력: `Part Instance Name`, `Element Label`, `Node Label`, `Sxx`
 
-단일 Instance에서는 `Part Instance Name` 열을 생략할 수 있다. 내력은
+단일 Instance에서는 `Part Instance Name` 열을 생략할 수 있다. Abaqus Beam의
-`SF1,SF2,SF3,SM1,SM2,SM3`을 각각 \(N,V_y,V_z,T,M_y,M_z\)로 비교한다.
+단면축 \((\mathbf n_1,\mathbf n_2)\)를 FESA의 \((\mathbf e_y,\mathbf e_z)\)와
-응력은 요소 절점의 단면 도심값 \(\sigma_{xx}=N/A\)를 비교한다.
+일치시킨 입력에서 요소 내력은 Abaqus CSV 순서를
+`SF1,SF3,SF2,SM3,SM1,SM2`로 재배열해 FESA의
+\(N,V_y,V_z,T,M_y,M_z\)와 비교한다. 응력은 요소 절점의 단면 도심값
+\(\sigma_{xx}=N/A\)를 비교한다.
 
 ### 5.3 허용오차
 
-- 단위·정식화 테스트는 정규화된 엄격한 tolerance를 사용한다.
+- FESA 단위·정식화 적합성 gate는 정규화된 엄격한 tolerance를 사용한다.
-- Abaqus 비교 기본 상대오차는 \(10^{-5}\)로 한다.
+- 정식화가 일치하는 reference 비교의 기본 상대오차는 \(10^{-5}\)로 한다.
-- 영에 가까운 결과는 특성 길이, 하중 및 응력에 기반한 절대오차를 함께 사용한다.
+- Abaqus B31과 FESA Beam의 정식화가 다른 상관성 gate는 component별 RMSE와
-- formulation 또는 output 위치 차이로 별도 tolerance가 필요하면 comparison
+  Relative L2를 보고한다. 물리량과 component가 다른 값을 하나의 norm으로
-  test 설정과 `docs/VALIDATION.md`에 근거를 기록한다.
+  혼합하지 않는다.
+- component \(c\)의 값 쌍을 \((F_{ic},A_{ic})\), characteristic absolute scale을
+  \(s_c\)라 하면
+
+  \[
+  \operatorname{RMSE}_c=
+  \sqrt{\frac{1}{n}\sum_i(F_{ic}-A_{ic})^2},\qquad
+  \operatorname{RelativeL2}_c=
+  \frac{\sqrt{\sum_i(F_{ic}-A_{ic})^2}}
+       {\max\left(\sqrt{\sum_iA_{ic}^2},\sqrt{n}s_c\right)}.
+  \]
+
+- Abaqus 상관성 gate의 성공은 요청된 모든 entity/component가 매칭되고 유한한
+  metric이 생성됨을 뜻한다. 관측된 단일 샘플에 맞춘 임의 pass/fail tolerance는
+  두지 않는다. 이후 acceptance envelope를 추가하려면 해석적 또는 mesh study
+  근거와 함께 `docs/VALIDATION.md`에 사전 기록한다.
 
 ## 6. 개발 워크플로우
 
@@ -235,6 +260,8 @@ CSV 식별 및 값 열:
 - 테스트 0개 수집이 아님을 확인
 - 전체 입력-해석-출력 통합 테스트 통과
 - physics sanity와 평형 잔차 기준 통과
-- 현재 Abaqus 2024 변위·반력 골든 결과의 tolerance 통과
+- FESA Beam 정식화 적합성 gate의 엄격한 tolerance 통과
+- 현재 Abaqus 2024 변위·반력·요소 단면력과의 component별 RMSE 및 Relative L2
+  상관성 보고서 생성
 - 요소 내력·도심 응력 CSV adapter와 비교 kernel의 synthetic 검증 통과
 - HDF5 schema, 입력 부분집합, 정식화 및 검증 보고서 제공

phases/beam-reference-qualification/step2.md

@@ -6,45 +6,73 @@
 - `/docs/PRD.md`
 - `/docs/ARCHITECTURE.md`
 - `/docs/ADR.md`
+- `/docs/formulation/timoshenko-beam-3d.md`
 - `/reference/cantilever beam/cantilever beam.inp`
 - `/reference/cantilever beam/cantilever beam displacements.csv`
 - `/reference/cantilever beam/cantilever beam reactions.csv`
+- `/reference/cantilever beam/cantilever beam elemental forces.csv`
 - `/include/fesa/analysis/run_solver.hpp`
-- `/include/fesa/io/hdf5/reader.hpp`
+- `/include/fesa/io/hdf5/writer.hpp`
+- `/include/fesa/validation/comparison.hpp`
 - `/include/fesa/validation/reference_csv.hpp`
 
 ## 작업
 
-제공된 계층형 캔틸레버를 production pipeline으로 해석하고 현재 존재하는 변위와
+FESA 정식화 적합성과 Abaqus 결과 상관성을 별도 gate로 검증한다.
-반력만 Abaqus 2024 결과와 비교한다.
 
-- `tests/reference/cantilever_reference_test.cpp`와 reference compare CLI를 먼저
+- Gate A는 기존 해석해, energy, rigid mode 및 equilibrium 테스트를 그대로 엄격히
-  작성한다.
+  통과시킨다. `SCF=0.25`를 kernel에 추가하거나 production parser가 무시하게 하지
-- comparison request는 Instance `Part-1-1`, relative tolerance `1e-5`,
+  않는다.
-  displacement absolute scale `1e-10`, reaction absolute scale `1e-8`을 명시한다.
+- 원본 `cantilever beam.inp`와 세 CSV는 Abaqus provenance로 보존한다. 동일한
-- HDF5 결과와 CSV를 public adapter로 읽어 `(Instance,Node Label)`로 join한다.
+  기하·재료·하중과 전단강성을 사용하되 `SCF=0`인
-- 요청하지 않은 internal force/stress 파일을 검색하거나 pass로 보고하지 않는다.
+  `reference/cantilever beam/cantilever beam fesa.inp`를 추가해 production
-- equilibrium과 finite result도 함께 assertion한다.
+  pipeline으로 해석한다.
+- `tests/unit/validation/comparison_test.cpp`에 component별 RMSE와 Relative L2의
+  실패 테스트를 먼저 추가한다. `include/fesa/validation/comparison.hpp`에는
+  `ComponentCorrelationMetric`과 `CorrelationReport`,
+  `correlate_samples(std::span<const ComparisonSample>)`를 공개한다.
+- Relative L2는 reference L2 norm과 component별 absolute-scale norm 중 큰 값을
+  분모로 사용한다. 서로 다른 component를 하나의 norm으로 합치지 않는다.
+- `tests/unit/validation/reference_csv_test.cpp`의 internal-force fixture 기대값을
+  Abaqus `SF1,SF3,SF2,SM3,SM1,SM2`에서 FESA
+  `N,Vy,Vz,T,My,Mz` 순서로 재배열하도록 먼저 변경하고 RED를 확인한다.
+- `tests/reference/cantilever_reference_test.cpp`와 reference compare CLI는 Instance
+  `PART-1_1-1`, 변위, 반력 및 요소 단면력 CSV 경로와 각 물리량의 absolute scale을
+  명시한다.
+- HDF5 결과와 CSV를 public adapter로 읽어 nodal 결과는
+  `(Instance,Node Label)`, 요소 단면력은
+  `(Instance,Element Label,End Node Label)`로 join한다.
+- correlation CLI는 요청된 결과가 모두 매칭되고 metric이 유한할 때 성공하며
+  component별 `count`, `rmse`, `relative_l2`를 출력한다. 관측값을 이용한 임의
+  pass/fail tolerance를 적용하지 않는다.
+- equilibrium과 finite result도 함께 assertion한다. 요청하지 않은 stress 파일을
+  검색하거나 pass로 보고하지 않는다.
 
 ## Acceptance Criteria
 
 ```powershell
 cmake --build --preset windows-debug
+ctest --preset windows-debug -R "ValidationComparison|ReferenceCsv" --output-on-failure
 ctest --preset windows-debug -R CantileverReference --output-on-failure
-.\out\build\windows-debug\Debug\fesa.exe solve "reference\cantilever beam\cantilever beam.inp" --output out\cantilever-beam.h5
+.\out\build\windows-debug\Debug\fesa.exe solve "reference\cantilever beam\cantilever beam fesa.inp" --output out\cantilever-beam.h5
-.\out\build\windows-debug\Debug\fesa-reference-compare.exe --results out\cantilever-beam.h5 --instance Part-1-1 --displacements "reference\cantilever beam\cantilever beam displacements.csv" --reactions "reference\cantilever beam\cantilever beam reactions.csv" --relative-tolerance 1e-5 --displacement-absolute-scale 1e-10 --reaction-absolute-scale 1e-8
+.\out\build\windows-debug\Debug\fesa-reference-compare.exe --results out\cantilever-beam.h5 --instance PART-1_1-1 --displacements "reference\cantilever beam\cantilever beam displacements.csv" --reactions "reference\cantilever beam\cantilever beam reactions.csv" --internal-forces "reference\cantilever beam\cantilever beam elemental forces.csv" --displacement-absolute-scale 1e-10 --reaction-absolute-scale 1e-8 --internal-force-absolute-scale 1e-8
 ctest --preset windows-debug --output-on-failure
 ```
 
 ## 검증 절차
 
-1. reference test가 실제 오차를 보고하며 실패하는 것을 확인한다.
+1. RMSE, Relative L2 및 요소력 축 재배열 테스트가 각각 의도한 이유로 실패하는
-2. discrepancy마다 가장 작은 analytical test를 추가한 뒤 근거 있는 kernel만 수정한다.
+   RED를 확인한다.
-3. tolerance를 넓혀 결함을 숨기지 않는다.
+2. 최소 comparison metric과 CSV adapter 변경으로 GREEN을 만든다.
-4. 전체 테스트와 최대 정규화 오차를 index summary에 기록한다.
+3. reference test가 production solve/HDF5/CSV/correlation 경로를 실행하고 세
+   물리량의 component metric을 출력하는지 확인한다.
+4. 전체 테스트와 component별 metric 요약을 index summary에 기록한다.
 
 ## 금지사항
 
-- reference `.inp` 또는 CSV를 수정하지 마라. 이유: 원본 golden을 보존해야 한다.
+- 원본 Abaqus `.inp` 또는 CSV를 수정하지 마라. 이유: 원본 golden과 formulation
-- 미제공 내력/응력 Abaqus 검증을 통과했다고 주장하지 마라. 이유: 증거가 없다.
+  provenance를 보존해야 한다.
+- Abaqus `SCF=0.25`를 FESA가 구현하거나 무시하지 마라. 이유: 승인된 FESA
+  정식화와 입력 계약을 바꾼다.
+- 미제공 응력 Abaqus 검증을 통과했다고 주장하지 마라. 이유: 증거가 없다.
 - test-only parser/solver 경로를 만들지 마라. 이유: production pipeline 검증이다.