From b68f6ee14325d38cf5c473d46cce61b5c5c3a0d7 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Mon, 3 Aug 2026 01:08:54 +0900 Subject: [PATCH] docs(beam-reference-qualification): define dual validation gates --- docs/ADR.md | 41 ++++++++++++- docs/PRD.md | 53 ++++++++++++---- phases/beam-reference-qualification/step2.md | 64 ++++++++++++++------ 3 files changed, 126 insertions(+), 32 deletions(-) diff --git a/docs/ADR.md b/docs/ADR.md index 72ec937..8da0769 100644 --- a/docs/ADR.md +++ b/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 근거가 필요하다. diff --git a/docs/PRD.md b/docs/PRD.md index 8ff1902..b1c2810 100644 --- a/docs/PRD.md +++ b/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가 추가되기 전까지 해당 -reader와 비교 kernel은 synthetic CSV로 검증한다. +샘플은 변위, 반력 및 요소 단면력을 비교한다. 요소 응력 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` 열을 생략할 수 있다. 내력은 -`SF1,SF2,SF3,SM1,SM2,SM3`을 각각 \(N,V_y,V_z,T,M_y,M_z\)로 비교한다. -응력은 요소 절점의 단면 도심값 \(\sigma_{xx}=N/A\)를 비교한다. +단일 Instance에서는 `Part Instance Name` 열을 생략할 수 있다. Abaqus Beam의 +단면축 \((\mathbf n_1,\mathbf n_2)\)를 FESA의 \((\mathbf e_y,\mathbf e_z)\)와 +일치시킨 입력에서 요소 내력은 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를 사용한다. -- Abaqus 비교 기본 상대오차는 \(10^{-5}\)로 한다. -- 영에 가까운 결과는 특성 길이, 하중 및 응력에 기반한 절대오차를 함께 사용한다. -- formulation 또는 output 위치 차이로 별도 tolerance가 필요하면 comparison - test 설정과 `docs/VALIDATION.md`에 근거를 기록한다. +- FESA 단위·정식화 적합성 gate는 정규화된 엄격한 tolerance를 사용한다. +- 정식화가 일치하는 reference 비교의 기본 상대오차는 \(10^{-5}\)로 한다. +- Abaqus B31과 FESA Beam의 정식화가 다른 상관성 gate는 component별 RMSE와 + Relative L2를 보고한다. 물리량과 component가 다른 값을 하나의 norm으로 + 혼합하지 않는다. +- 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, 입력 부분집합, 정식화 및 검증 보고서 제공 diff --git a/phases/beam-reference-qualification/step2.md b/phases/beam-reference-qualification/step2.md index 98f4c7a..8622057 100644 --- a/phases/beam-reference-qualification/step2.md +++ b/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으로 해석하고 현재 존재하는 변위와 -반력만 Abaqus 2024 결과와 비교한다. +FESA 정식화 적합성과 Abaqus 결과 상관성을 별도 gate로 검증한다. -- `tests/reference/cantilever_reference_test.cpp`와 reference compare CLI를 먼저 - 작성한다. -- comparison request는 Instance `Part-1-1`, relative tolerance `1e-5`, - displacement absolute scale `1e-10`, reaction absolute scale `1e-8`을 명시한다. -- HDF5 결과와 CSV를 public adapter로 읽어 `(Instance,Node Label)`로 join한다. -- 요청하지 않은 internal force/stress 파일을 검색하거나 pass로 보고하지 않는다. -- equilibrium과 finite result도 함께 assertion한다. +- Gate A는 기존 해석해, energy, rigid mode 및 equilibrium 테스트를 그대로 엄격히 + 통과시킨다. `SCF=0.25`를 kernel에 추가하거나 production parser가 무시하게 하지 + 않는다. +- 원본 `cantilever beam.inp`와 세 CSV는 Abaqus provenance로 보존한다. 동일한 + 기하·재료·하중과 전단강성을 사용하되 `SCF=0`인 + `reference/cantilever beam/cantilever beam fesa.inp`를 추가해 production + pipeline으로 해석한다. +- `tests/unit/validation/comparison_test.cpp`에 component별 RMSE와 Relative L2의 + 실패 테스트를 먼저 추가한다. `include/fesa/validation/comparison.hpp`에는 + `ComponentCorrelationMetric`과 `CorrelationReport`, + `correlate_samples(std::span)`를 공개한다. +- 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-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.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-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가 실제 오차를 보고하며 실패하는 것을 확인한다. -2. discrepancy마다 가장 작은 analytical test를 추가한 뒤 근거 있는 kernel만 수정한다. -3. tolerance를 넓혀 결함을 숨기지 않는다. -4. 전체 테스트와 최대 정규화 오차를 index summary에 기록한다. +1. RMSE, Relative L2 및 요소력 축 재배열 테스트가 각각 의도한 이유로 실패하는 + RED를 확인한다. +2. 최소 comparison metric과 CSV adapter 변경으로 GREEN을 만든다. +3. reference test가 production solve/HDF5/CSV/correlation 경로를 실행하고 세 + 물리량의 component metric을 출력하는지 확인한다. +4. 전체 테스트와 component별 metric 요약을 index summary에 기록한다. ## 금지사항 -- reference `.inp` 또는 CSV를 수정하지 마라. 이유: 원본 golden을 보존해야 한다. -- 미제공 내력/응력 Abaqus 검증을 통과했다고 주장하지 마라. 이유: 증거가 없다. +- 원본 Abaqus `.inp` 또는 CSV를 수정하지 마라. 이유: 원본 golden과 formulation + provenance를 보존해야 한다. +- Abaqus `SCF=0.25`를 FESA가 구현하거나 무시하지 마라. 이유: 승인된 FESA + 정식화와 입력 계약을 바꾼다. +- 미제공 응력 Abaqus 검증을 통과했다고 주장하지 마라. 이유: 증거가 없다. - test-only parser/solver 경로를 만들지 마라. 이유: production pipeline 검증이다.