# 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

```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 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 검증이다.