FESADev/phases/linear-static-3d-euler-beam/step24.md

Step 24: Linear Static Orchestration and CLI

담당 역할과 필수 스킬

• 담당 역할: implementation-agent
• 필수 스킬: fesa-cpp-msvc-tdd
• 모든 C++ build/test와 최종 VERIFY는 MSVC x64 Debug 기준으로 수행한다.

읽어야 할 파일

• /AGENTS.md
• /docs/ARCHITECTURE.md
• /docs/ADR.md
• /docs/linear-static-3d-euler-beam/requirements.md
• /docs/linear-static-3d-euler-beam/formulation.md
• /docs/linear-static-3d-euler-beam/io.md
• /docs/linear-static-3d-euler-beam/reference-model.md
• /docs/linear-static-3d-euler-beam/implementation-plan.md
• /include/fesa/io/abaqus/input_reader.hpp
• /include/fesa/io/abaqus/domain_mapper.hpp
• /include/fesa/analysis/analysis_model.hpp
• /include/fesa/analysis/analysis_state.hpp
• /include/fesa/fem/dof_manager.hpp
• /include/fesa/assembly/parallel_for.hpp
• /include/fesa/assembly/sparse_assembler.hpp
• /include/fesa/constraints/essential_constraints.hpp
• /include/fesa/solvers/linear/linear_solver.hpp
• /include/fesa/assembly/load_assembler.hpp
• /include/fesa/results/result_recovery.hpp
• /include/fesa/results/results_writer.hpp
• /include/fesa/io/hdf5/hdf5_results_writer.hpp
• /src/fesa/CMakeLists.txt
• /tests/CMakeLists.txt
• /reference/cantilever beam/의 승인된 네 파일

소유 파일

• Create: /include/fesa/analysis/linear_static_analysis.hpp
• Create: /src/fesa/analysis/linear_static_analysis.cpp
• Create: /include/fesa/app/fesa_application.hpp
• Create: /src/fesa/app/fesa_application.cpp
• Create: /src/fesa/app/main.cpp
• Create: /tests/integration/analysis/linear_static_analysis_test.cpp
• Create: /tests/integration/app/fesa_application_test.cpp
• Create: /tests/reference/reference_comparison.hpp
• Create: /tests/reference/reference_comparison.cpp
• Create: /tests/reference/reference_comparison_test.cpp
• Create: /tests/reference/b33_reference_comparison_test.cpp
• Modify: /src/fesa/CMakeLists.txt
• Modify: /tests/CMakeLists.txt

작업

전체 single-step lifecycle과 fesa.exe CLI를 구현하고 Step 26이 재사용할 read-only reference comparison test utility를 완성하라.

struct AnalysisRequest { std::filesystem::path inputPath; std::filesystem::path outputPath; };
class Analysis {
public:
    virtual ~Analysis() = default;
    Status run(const AnalysisRequest& request);
protected:
    virtual Status initialize(const AnalysisRequest& request) = 0;
    virtual Status buildAnalysisModel() = 0;
    virtual Status buildDofMapAndSparsePattern() = 0;
    virtual Status assembleAndPartitionStiffness() = 0;
    virtual Status factorize() = 0;
    virtual Status assembleLoadsAndEffectiveRhs() = 0;
    virtual Status substituteAndReconstruct() = 0;
    virtual Status recoverAndWriteResults() = 0;
};
class LinearStaticAnalysis final : public Analysis { /* V0 hook implementations */ };
class FesaApplication {
public:
    int run(const std::vector<std::string>& arguments);
};

LinearStaticAnalysis::run은 다음 event order를 exact하게 고정하고 각 실패를 diagnostic/ exit category에 연결한다.

parse input -> Domain -> AnalysisModel -> DofManager/sparse pattern
-> parallel element stiffness -> deterministic COO-to-CSR
-> free/constrained partition -> factorize(Kff)
-> assemble full nodal load -> rhs=Ff-Kfc*dc
-> solve substitution -> reconstruct full displacement
-> residual/reaction/element recovery -> atomic HDF5 write

Spy/fake adapters를 사용한 orchestration test는 factorize event가 load assembly보다 먼저고 solve가 factorization을 재수행하지 않음을 검증한다. 실제 production default는 TbbParallelFor, MklPardisoSolver, Hdf5ResultsWriter를 사용한다.

CLI는 fesa.exe <model.inp> --output <results.h5>와 output 생략 시 current directory results.h5를 지원한다. Exit code는 0 success, 2 usage, 3 input syntax/semantic, 4 model validation, 5 factorization/substitution, 6 HDF5 output이다. Error diagnostics는 stderr에 deterministic order로 쓰고 warning은 output diagnostics에도 보존한다. CMake executable target은 내부 이름이 다르더라도 OUTPUT_NAME fesa를 설정해 Debug output이 실제로 fesa.exe가 되게 한다.

Test-only reference support를 tests/reference/ 아래 구현하라.

• approved input으로 .harness/build/reference/cantilever-beam-b33/results.h5를 생성한다.
• legacy displacement/reaction/elemental-force CSV를 read-only로 parse하고 실제 CAE header U-U*, UR-UR*, RF-RF*, RM-RM*, SF-SF1, SM-SM*을 canonical component로 normalize한다.
• row matching 전에 expected header, B33 input, unique identity, missing/extra/nonfinite를 검사한다.
• same model/step/frame/quantity/component의 Abaqus-only scale과 absolute_floor + 1e-6*reference_scale로 모든 row를 판정한다.
• section resultants는 node station과 SF1->N, SM1->My, SM2->Mz, SM3->T로 비교한다.
• Stress comparison은 N/A로 기록하되 HDF5 stress dataset/test 통과를 요구한다.
• max absolute, component-scale normalized, RMS, norm, worst row/component를 .harness/build/reference/cantilever-beam-b33/comparison.json에 결정적으로 기록한다.
• 같은 JSON에 matched FESA/reference rows, full free residual norm, applied/reaction force와 origin 기준 moment 합, endpoint consistency를 physics_evidence로 기록해 Step 27이 source/test 변경 없이 물리 sanity를 독립 검토할 수 있게 한다.

Tests는 orchestration order, CLI default/explicit output, all exit codes, output-request no-op, approved input end-to-end, reference tolerance zero/near-zero/failure cases를 포함한다. CTest regex/label은 LinearStaticCli, ReferenceComparisonContract, B33ReferenceComparison으로 실행 가능하게 한다.

Acceptance Criteria

cmake --build .harness/build --config Debug --target fesa_tests
ctest --test-dir .harness/build -C Debug -R "LinearStaticCli|ReferenceComparisonContract|B33ReferenceComparison" --output-on-failure

위 command에서 missing orchestration/CLI/reference utility RED를 확인한 후 구현한다.

cmake -S . -B .harness/build -A x64 `
  -DFESA_GTEST_SOURCE_DIR=C:/git/googletest `
  "-DMKL_DIR=C:/Program Files (x86)/Intel/oneAPI/mkl/2026.1/lib/cmake/mkl" `
  "-DTBB_DIR=C:/Program Files (x86)/Intel/oneAPI/tbb/2023.1/lib/cmake/tbb" `
  "-DHDF5_DIR=C:/Program Files/HDF_Group/HDF5/2.1.1/cmake"
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug -R "LinearStaticCli|ReferenceComparisonContract|B33ReferenceComparison" --output-on-failure
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
if (-not (Test-Path '.harness/build/reference/cantilever-beam-b33/results.h5')) { throw 'Missing reference-run HDF5' }
if (-not (Test-Path '.harness/build/reference/cantilever-beam-b33/comparison.json')) { throw 'Missing comparison metrics' }
git diff --exit-code -- reference/

검증 절차

1. orchestration/CLI/reference contract tests를 먼저 작성하고 targeted RED를 확인한다.
2. exact lifecycle과 minimal CLI/test utility로 targeted GREEN을 만든다.
3. approved input end-to-end, comparison metrics, CTest discovery/full VERIFY를 실행한다.
4. reference artifacts가 unchanged인지 확인한다.
5. /docs/linear-static-3d-euler-beam/implementation-report.md의 Step 24 section에 실제 RED/GREEN/VERIFY command, exit code, 핵심 output, 변경 파일과 generated HDF5/comparison evidence를 기록한다.
6. Step 24를 completed로 갱신하고 CLI path, exit codes, generated HDF5/metrics와 RED/GREEN/VERIFY evidence를 summary에 기록한다.

금지사항

• load assembly를 factorization 앞으로 옮기지 마라. 이유: 승인 runtime order와 반대다.
• factorize와 substitution을 합치지 마라. 이유: solver contract와 repeated RHS 검증을 깨뜨린다.
• B31/multiple-step/transform/*DLOAD를 지원하지 마라. 이유: V0 범위 밖이다.
• reference CSV를 보정·rename·rewrite하지 마라. 이유: comparison baseline을 오염시킨다.
• stress reference comparison을 만들어내지 마라. 이유: 승인 범위에서 명시적 N/A다.
• 직접 commit하지 마라. 이유: Harness executor가 담당한다.