# Step 2: Cantilever Reference Comparison

## 읽어야 할 파일

- `/AGENTS.md`
- `/docs/PRD.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- `/reference/cantilever beam/cantilever beam.inp`
- `/reference/cantilever beam/cantilever beam displacements.csv`
- `/reference/cantilever beam/cantilever beam reactions.csv`
- `/include/fesa/analysis/run_solver.hpp`
- `/include/fesa/io/hdf5/reader.hpp`
- `/include/fesa/validation/reference_csv.hpp`

## 작업

제공된 계층형 캔틸레버를 production pipeline으로 해석하고 현재 존재하는 변위와
반력만 Abaqus 2024 결과와 비교한다.

- `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한다.

## Acceptance Criteria

```powershell
cmake --build --preset windows-debug
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
ctest --preset windows-debug --output-on-failure
```

## 검증 절차

1. reference test가 실제 오차를 보고하며 실패하는 것을 확인한다.
2. discrepancy마다 가장 작은 analytical test를 추가한 뒤 근거 있는 kernel만 수정한다.
3. tolerance를 넓혀 결함을 숨기지 않는다.
4. 전체 테스트와 최대 정규화 오차를 index summary에 기록한다.

## 금지사항

- reference `.inp` 또는 CSV를 수정하지 마라. 이유: 원본 golden을 보존해야 한다.
- 미제공 내력/응력 Abaqus 검증을 통과했다고 주장하지 마라. 이유: 증거가 없다.
- test-only parser/solver 경로를 만들지 마라. 이유: production pipeline 검증이다.