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

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를 구현한다.

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

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 경계다.