docs: add linear static beam harness phase

2026-08-09 01:35:44 +09:00
parent 3410828736
commit 6d6da7545c
36 changed files with 3524 additions and 54 deletions
@@ -0,0 +1,103 @@
+# Step 15: AnalysisState
+
+## 담당 역할과 필수 스킬
+
+- 담당 역할: `implementation-agent`
+- 필수 스킬: `fesa-cpp-msvc-tdd`
+- 모든 C++ build/test와 최종 VERIFY는 MSVC x64 Debug 기준으로 수행한다.
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/requirements/linear-static-3d-euler-beam.md`
+- `/docs/io-definitions/linear-static-3d-euler-beam-io.md`
+- `/docs/implementation-plans/linear-static-3d-euler-beam.md`
+- `/include/fesa/math/vector.hpp`
+- `/include/fesa/analysis/analysis_model.hpp`
+- `/include/fesa/fem/dof_manager.hpp`
+- `/src/fesa/fem/dof_manager.cpp`
+
+## 소유 파일
+
+- Create: `/include/fesa/results/result_records.hpp`
+- Create: `/include/fesa/analysis/analysis_state.hpp`
+- Create: `/src/fesa/analysis/analysis_state.cpp`
+- Create: `/tests/unit/results/result_records_test.cpp`
+- Create: `/tests/unit/analysis/analysis_state_test.cpp`
+- Modify: `/src/fesa/CMakeLists.txt`
+- Modify: `/tests/CMakeLists.txt`
+
+## 작업
+
+V0에서 실제 할당하는 mutable analysis quantities와 output row identity를 소유하는
+`AnalysisState`를 위 exact paths에 구현하라. 최소 계약은 다음 의미를 가진다.
+
+```cpp
+struct StepFrameIdentity { std::string stepName; std::size_t frameIndex; };
+struct EndpointResultRow { EntityIndex element; int endpoint; SourceEntityId node;
+                           std::array<double, 6> endAction;
+                           std::array<double, 4> sectionResultant; };
+struct GaussResultRow { EntityIndex element; int gaussPoint;
+                        std::array<double, 4> generalizedStrain;
+                        std::array<double, 4> generalizedResultant; };
+struct StressS11Row { EntityIndex element; int gaussPoint; std::size_t sectionPoint;
+                      double x1; double x2; double s11; std::string source; };
+class AnalysisState {
+public:
+    static AnalysisState create(const DofManager& dofs, StepFrameIdentity identity);
+    Vector& displacement() noexcept;
+    Vector& externalForce() noexcept;
+    Vector& internalForce() noexcept;
+    Vector& residual() noexcept;
+    Vector& reaction() noexcept;
+    // const overloads and owned element-recovery row accessors
+};
+```
+
+각 full vector 크기는 `fullDofCount()`이고 zero-initialized다. Reaction은 constrained value를
+동일 full-index space에 두며 free component는 residual sanity에 사용할 수 있어야 한다.
+Endpoint/Gauss/stress row는 stable element/point order로 저장한다. Velocity, acceleration,
+temperature, iteration history, nonlinear state storage를 만들지 않는다.
+
+Tests는 allocation/zero initialization, independent ownership, step/frame identity, row ordering,
+copy/move policy, forbidden-state API 부재 review를 포함하고 `AnalysisState` regex로 등록한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build .harness/build --config Debug --target fesa_tests
+ctest --test-dir .harness/build -C Debug -R AnalysisState --output-on-failure
+```
+
+RED 후 GREEN/VERIFY:
+
+```powershell
+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 AnalysisState --output-on-failure
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+## 검증 절차
+
+1. state ownership tests를 먼저 작성하고 RED를 확인한다.
+2. V0에서 필요한 field만 최소 구현해 GREEN을 만든다.
+3. 전체 VERIFY와 output row identity/order를 확인한다.
+4. `/docs/implementation-plans/linear-static-3d-euler-beam-implementation-report.md`의
+   Step 15 section에 실제 RED/GREEN/VERIFY command, exit code,
+   핵심 output과 변경 파일을 기록한다.
+5. Step 15를 `completed`로 갱신하고 allocated fields/omitted fields를 summary에 기록한다.
+
+## 금지사항
+
+- velocity, acceleration, temperature, nonlinear iteration history를 할당하지 마라. 이유: V0 범위 밖이다.
+- Domain 정의를 state에 복사하지 마라. 이유: model/state ownership을 분리해야 한다.
+- HDF5 API를 state에 노출하지 마라. 이유: ResultsWriter adapter 책임이다.
+- 직접 commit하지 마라. 이유: Harness executor가 담당한다.