FESA/phases/beam-reference-qualification/step2.md

Step 2: Cantilever Reference Comparison

읽어야 할 파일

• /AGENTS.md
• /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/writer.hpp
• /include/fesa/validation/comparison.hpp
• /include/fesa/validation/reference_csv.hpp

작업

FESA 정식화 적합성과 Abaqus 결과 상관성을 별도 gate로 검증한다.

• 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<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

cmake --build --preset windows-debug
ctest --preset windows-debug -R "CorrelationMetric|ReferenceCsv|InternalForceCsv" --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 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. 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에 기록한다.

금지사항

• 원본 Abaqus .inp 또는 CSV를 수정하지 마라. 이유: 원본 golden과 formulation provenance를 보존해야 한다.
• Abaqus SCF=0.25를 FESA가 구현하거나 무시하지 마라. 이유: 승인된 FESA 정식화와 입력 계약을 바꾼다.
• 미제공 응력 Abaqus 검증을 통과했다고 주장하지 마라. 이유: 증거가 없다.
• test-only parser/solver 경로를 만들지 마라. 이유: production pipeline 검증이다.