add uncommitted files

2026-07-29 23:32:26 +09:00
parent fb0f8f39a0
commit f5379472ce
80 changed files with 7461 additions and 1 deletions
@@ -0,0 +1,26 @@
+{
+  "project": "FESA",
+  "phase": "beam-reference-qualification",
+  "steps": [
+    {
+      "step": 0,
+      "name": "comparison-metric-and-entity-matching",
+      "status": "pending"
+    },
+    {
+      "step": 1,
+      "name": "reference-csv-adapters",
+      "status": "pending"
+    },
+    {
+      "step": 2,
+      "name": "cantilever-reference-comparison",
+      "status": "pending"
+    },
+    {
+      "step": 3,
+      "name": "qualification-report",
+      "status": "pending"
+    }
+  ]
+}
@@ -0,0 +1,69 @@
+# Step 0: Comparison Metric and Entity Matching
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/superpowers/specs/2026-07-29-abaqus-assembly-reference-design.md`
+- `/include/fesa/results/result_database.hpp`
+- `/include/fesa/model/entity_origin.hpp`
+
+## 작업
+
+CSV와 독립적인 reference comparison metric, entity position과 report를 구현한다.
+
+```cpp
+enum class ReferenceQuantity {
+    displacement,
+    reaction,
+    internal_force,
+    centroid_stress
+};
+struct Tolerance final { double relative; double absolute_scale; };
+struct ResultPosition final {
+    std::string instance_name;
+    std::int64_t entity_label;
+    std::optional<std::int64_t> end_node_label;
+};
+struct ComparisonSample final {
+    ReferenceQuantity quantity;
+    ResultPosition position;
+    std::vector<double> reference;
+    std::vector<double> actual;
+    Tolerance tolerance;
+};
+struct ComparisonReport final {
+    bool passed;
+    double maximum_normalized_error;
+    std::vector<Diagnostic> failures;
+};
+[[nodiscard]] ComparisonReport compare_samples(
+    std::span<const ComparisonSample>);
+```
+
+각 scalar는 \(e_n=|a-r|/(a_{scale}+r_{tol}|r|)\)이며 \(e_n\le1\)만 통과한다.
+nonfinite, duplicate position, component mismatch, unknown origin, invalid element-node
+pair를 실패 테스트로 먼저 작성한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "ComparisonMetric|EntityMatching" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. near-zero와 큰 값의 실패 테스트를 먼저 실행한다.
+2. report에 quantity/entity/component/reference/actual/error를 기록한다.
+3. unit-free metric과 명시 tolerance만 사용한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- NaN 비교를 통과시키지 마라. 이유: 수치 실패를 숨긴다.
+- 모든 물리량에 하나의 absolute scale을 강제하지 마라. 이유: 규모가 다르다.
+- CSV parsing을 이 파일에 넣지 마라. 이유: 다음 adapter 경계다.
@@ -0,0 +1,63 @@
+# Step 1: Reference CSV Adapters
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/superpowers/specs/2026-07-29-abaqus-assembly-reference-design.md`
+- `/include/fesa/validation/comparison.hpp`
+- `/reference/cantilever beam/cantilever beam displacements.csv`
+- `/reference/cantilever beam/cantilever beam reactions.csv`
+
+## 작업
+
+네 물리량의 명시적 CSV schema를 읽어 canonical reference row로 변환한다.
+
+```cpp
+struct ReferenceRow final {
+    ReferenceQuantity quantity;
+    ResultPosition position;
+    std::vector<double> values;
+};
+struct ReferenceCsvReadResult final {
+    std::vector<ReferenceRow> rows;
+    std::vector<Diagnostic> diagnostics;
+};
+[[nodiscard]] ReferenceCsvReadResult read_reference_csv(
+    ReferenceQuantity,
+    const std::filesystem::path&,
+    std::string_view single_instance_name);
+```
+
+- displacement/reaction은 제공된 whitespace 포함 Abaqus header를 읽는다.
+- internal force schema:
+  `Part Instance Name, Element Label, Node Label, SF-SF1..SF-SF3,
+  SM-SM1..SM-SM3`
+- stress schema:
+  `Part Instance Name, Element Label, Node Label, Sxx`
+- 단일 Instance에서는 Instance 열 생략을 허용하고 request 이름으로 보완한다.
+- `tests/fixtures/reference`에 synthetic internalforce/stress CSV를 먼저 만들고,
+  6개 내력 component와 centroid stress row를 실패 테스트로 고정한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "ReferenceCsv|InternalForceCsv|StressCsv" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. four-schema parser test 실패를 확인한다.
+2. header/value trim과 선택적 UTF-8 BOM만 허용한다.
+3. missing column, duplicate row, invalid number를 진단한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- metadata.json을 요구하지 마라. 이유: 승인된 reference 계약과 다르다.
+- unknown column으로 필수 column 누락을 숨기지 마라. 이유: 잘못된 비교를 만든다.
+- 내력/응력 파일이 없다는 이유로 adapter 구현을 생략하지 마라. 이유: 필수 루틴이다.
@@ -0,0 +1,50 @@
+# 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 검증이다.
@@ -0,0 +1,51 @@
+# Step 3: Qualification Report
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/formulation/timoshenko-beam-3d.md`
+- `/docs/HDF5_SCHEMA.md`
+- `/tests/unit/elements/`
+- `/tests/reference/`
+- `/tests/fixtures/reference/`
+
+## 작업
+
+`docs/VALIDATION.md`에 Phase 1의 실제 검증 증거와 제한을 기록한다.
+
+- analytical: axial, torsion, bending y/z, biaxial, shear-dominant, rigid body,
+  rotated frame, slenderness sweep
+- physics: equilibrium, symmetry, reaction, nonzero prescribed DOF
+- determinism: tested thread counts와 repeated runs
+- Abaqus: 현재 cantilever displacement/reaction의 tolerance와 maximum error
+- contract-only: synthetic internal-force/stress CSV schema와 component mapping
+- 미제공 Abaqus internal-force/stress는 `not yet Abaqus-qualified`라고 명시한다.
+
+보고서 수치를 새 test output에서 수집하며 수동 추정값을 쓰지 않는다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug --output-on-failure
+ctest --preset windows-debug -R "Reference|Beam3D2|Determinism" --output-on-failure
+```
+
+모든 실행이 통과하고 보고서의 test 이름, tolerance, 최대오차와 disposition이 실제
+출력과 일치해야 한다.
+
+## 검증 절차
+
+1. 전체 suite를 새로 실행한다.
+2. 결과를 benchmark/quantity별 표에 기록한다.
+3. synthetic coverage와 Abaqus-backed qualification을 명확히 분리한다.
+4. index summary에 보고서 경로와 test counts를 기록한다.
+
+## 금지사항
+
+- 실행하지 않은 결과를 보고서에 쓰지 마라. 이유: 검증 증거가 아니다.
+- Abaqus 내력/응력 qualification을 추론하지 마라. 이유: CSV가 아직 없다.
+- 실패 테스트를 제외하거나 disable하지 마라. 이유: release gate를 약화한다.