feat: add analysis state and base

2026-06-09 15:12:41 +09:00
parent 7ea08441ed
commit 87529c811a
18 changed files with 1159 additions and 0 deletions
@@ -0,0 +1,42 @@
+{
+  "project": "FESA Structural Solver",
+  "phase": "analysis-state-analysis-base",
+  "steps": [
+    {
+      "step": 0,
+      "name": "analysis-contract-plan",
+      "status": "completed",
+      "summary": "Created the analysis state and analysis base implementation plan with scope, contracts, TDD tasks, and exclusions."
+    },
+    {
+      "step": 1,
+      "name": "analysis-state-core",
+      "status": "completed",
+      "summary": "Added AnalysisState with zero-sized and sized vector storage for displacement, forces, residual, and reaction."
+    },
+    {
+      "step": 2,
+      "name": "analysis-state-guards",
+      "status": "completed",
+      "summary": "Added AnalysisState setters, size guards, resize reset, clearForces, and time/increment/iteration counters."
+    },
+    {
+      "step": 3,
+      "name": "analysis-base-interface",
+      "status": "completed",
+      "summary": "Added the Analysis base interface with const Domain input, mutable AnalysisState, name contract, virtual deletion, and run delegation."
+    },
+    {
+      "step": 4,
+      "name": "cmake-analysis-tests",
+      "status": "completed",
+      "summary": "Registered fesa_analysis_tests and confirmed analysis, domain, model-object, and io CTest targets pass together."
+    },
+    {
+      "step": 5,
+      "name": "validation-report-handoff",
+      "status": "completed",
+      "summary": "Recorded build/test evidence, updated project progress, and marked the phase completed."
+    }
+  ]
+}
@@ -0,0 +1,62 @@
+# Step 0: analysis-contract-plan
+
+## Read First
+
+Read these files before editing:
+
+- `/AGENTS.md`
+- `/docs/PLAN.md`
+- `/docs/PROGRESS.md`
+- `/docs/WORKNOTE.md`
+- `/docs/AGENT_RULES.md`
+- `/docs/PRD.md`
+- `/docs/ADR.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/implementation-plans/analysis-model-objects-implementation-plan.md`
+- `/docs/implementation-plans/property-model-foundation-implementation-plan.md`
+- `/include/fesa/core/Domain.hpp`
+- `/include/fesa/core/ModelTypes.hpp`
+- `/include/fesa/core/StepDefinition.hpp`
+- `/CMakeLists.txt`
+
+## Task
+
+Create `/docs/implementation-plans/analysis-state-analysis-base-implementation-plan.md`.
+
+The document must define the implementation contract for:
+
+- `fesa::core::AnalysisState` as mutable analysis state storage.
+- `fesa::analysis::Analysis` as the base analysis strategy interface.
+- A dedicated CTest path for analysis-layer tests.
+
+State explicitly that this phase does not implement:
+
+- `AnalysisModel`
+- `DofManager`
+- MITC4 stiffness, stress, resultants, or force recovery
+- global assembly
+- constrained DOF elimination
+- MKL/PARDISO solve
+- HDF5 result writing beyond existing skeletons
+- reference comparison
+- Abaqus/Nastran/reference-solver execution
+
+## Tests To Write First
+
+This is a documentation planning step. Do not write C++ production code in this step.
+
+## Acceptance Criteria
+
+Run:
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+Update `/phases/analysis-state-analysis-base/index.json` step 0 with `completed`, `error`, or `blocked`.
+
+## Do Not
+
+- Do not change C++ code in this step.
+- Do not change requirements, formulations, I/O contracts, reference artifacts, or tolerance policy.
@@ -0,0 +1,69 @@
+# Step 1: analysis-state-core
+
+## Read First
+
+Read these files before editing:
+
+- `/AGENTS.md`
+- `/docs/PLAN.md`
+- `/docs/PROGRESS.md`
+- `/docs/WORKNOTE.md`
+- `/docs/AGENT_RULES.md`
+- `/docs/ADR.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/implementation-plans/analysis-state-analysis-base-implementation-plan.md`
+- `/include/fesa/core/ModelTypes.hpp`
+- `/include/fesa/core/Domain.hpp`
+- `/CMakeLists.txt`
+
+## Task
+
+Add `fesa::core::AnalysisState`.
+
+Candidate files:
+
+- Create `/include/fesa/core/AnalysisState.hpp`
+- Create `/src/core/AnalysisState.cpp`
+- Create `/tests/core/analysis_state_test.cpp`
+- Modify `/CMakeLists.txt`
+
+Required initial contract:
+
+- `AnalysisState()` starts with zero DOFs and empty vectors.
+- `explicit AnalysisState(std::size_t dof_count)` allocates zero-filled vectors.
+- `dofCount()` returns the current vector size.
+- `displacement()`, `externalForce()`, `internalForce()`, `residual()`, and `reaction()` return const vector references.
+- All state vectors have the same size as `dofCount()`.
+- State is mutable analysis data only. Do not store node ids, element ids, equation ids, sparse data, solver handles, writer handles, or references to `Domain`.
+
+## Tests To Write First
+
+Write tests in `/tests/core/analysis_state_test.cpp` before creating production code:
+
+- default state has zero DOFs and all vectors empty.
+- sized state creates zero-filled displacement, external force, internal force, residual, and reaction vectors.
+- `dofCount()` matches vector sizes.
+
+Run the targeted test and confirm it fails because `AnalysisState` does not exist:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
+```
+
+Then implement the minimum code needed to pass.
+
+## Acceptance Criteria
+
+Run:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
+python scripts/validate_workspace.py
+```
+
+Update `/phases/analysis-state-analysis-base/index.json` step 1 with `completed`, `error`, or `blocked`.
+
+## Do Not
+
+- Do not implement `AnalysisModel`, `DofManager`, assembly, solver, or result output.
+- Do not add mutable solver state to `Domain`, `Node`, `Element`, `Material`, `Property`, `Load`, or `BoundaryCondition`.
@@ -0,0 +1,65 @@
+# Step 2: analysis-state-guards
+
+## Read First
+
+Read these files before editing:
+
+- `/AGENTS.md`
+- `/docs/PLAN.md`
+- `/docs/PROGRESS.md`
+- `/docs/WORKNOTE.md`
+- `/docs/AGENT_RULES.md`
+- `/docs/implementation-plans/analysis-state-analysis-base-implementation-plan.md`
+- `/include/fesa/core/AnalysisState.hpp`
+- `/src/core/AnalysisState.cpp`
+- `/tests/core/analysis_state_test.cpp`
+- `/CMakeLists.txt`
+
+## Task
+
+Extend `AnalysisState` with mutation and guard behavior.
+
+Required contract:
+
+- `resize(std::size_t dof_count)` resets every vector to the new size and fills with zero.
+- `setDisplacement(std::vector<double>)`, `setExternalForce(std::vector<double>)`, `setInternalForce(std::vector<double>)`, `setResidual(std::vector<double>)`, and `setReaction(std::vector<double>)` replace one vector.
+- setter inputs must match `dofCount()`.
+- size mismatch throws `std::invalid_argument`.
+- a failed setter must not mutate the existing vector.
+- `clearForces()` zeros external force, internal force, residual, and reaction while leaving displacement unchanged.
+- `currentTime()`, `incrementIndex()`, and `iterationIndex()` accessors exist with setters.
+
+## Tests To Write First
+
+Add tests in `/tests/core/analysis_state_test.cpp` before production changes:
+
+- setters replace vectors when sizes match.
+- mismatched setter input throws and preserves old values.
+- resize resets all vectors to zero.
+- clearForces preserves displacement and zeros force-like vectors.
+- time, increment, and iteration counters can be updated.
+
+Run the targeted test and confirm it fails before implementation:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
+```
+
+Then implement the minimum code needed to pass.
+
+## Acceptance Criteria
+
+Run:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
+python scripts/validate_workspace.py
+```
+
+Update `/phases/analysis-state-analysis-base/index.json` step 2 with `completed`, `error`, or `blocked`.
+
+## Do Not
+
+- Do not add dynamics-only velocity or acceleration vectors in this phase.
+- Do not add thermal temperature fields in this phase.
+- Do not add equation numbering or DOF mapping responsibilities.
@@ -0,0 +1,69 @@
+# Step 3: analysis-base-interface
+
+## Read First
+
+Read these files before editing:
+
+- `/AGENTS.md`
+- `/docs/PLAN.md`
+- `/docs/PROGRESS.md`
+- `/docs/WORKNOTE.md`
+- `/docs/AGENT_RULES.md`
+- `/docs/ADR.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/implementation-plans/analysis-state-analysis-base-implementation-plan.md`
+- `/include/fesa/core/Domain.hpp`
+- `/include/fesa/core/AnalysisState.hpp`
+- `/CMakeLists.txt`
+
+## Task
+
+Add `fesa::analysis::Analysis` as a minimal base interface for future analysis strategies.
+
+Candidate files:
+
+- Create `/include/fesa/analysis/Analysis.hpp`
+- Create `/tests/analysis/analysis_base_test.cpp`
+- Modify `/CMakeLists.txt`
+
+Required contract:
+
+- `Analysis` has a virtual destructor.
+- `Analysis` exposes `const char* name() const noexcept`.
+- `Analysis` exposes `void run(const fesa::core::Domain& domain, fesa::core::AnalysisState& state)`.
+- `run` delegates to a protected pure virtual `doRun(const fesa::core::Domain&, fesa::core::AnalysisState&)`.
+- `Domain` is passed as const; `AnalysisState` is mutable.
+- The base class must not own `Domain`, `AnalysisState`, solver objects, result writers, or reference artifacts.
+
+## Tests To Write First
+
+Write tests in `/tests/analysis/analysis_base_test.cpp` before production changes:
+
+- a derived recording analysis can be used through `Analysis&`.
+- `run` forwards the const `Domain` and mutable `AnalysisState` to the derived implementation.
+- derived implementation can update `AnalysisState` without mutating `Domain`.
+- `Analysis` can be deleted through a base pointer.
+
+Run the targeted test and confirm it fails before implementation:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
+```
+
+Then implement the minimum code needed to pass.
+
+## Acceptance Criteria
+
+Run:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
+python scripts/validate_workspace.py
+```
+
+Update `/phases/analysis-state-analysis-base/index.json` step 3 with `completed`, `error`, or `blocked`.
+
+## Do Not
+
+- Do not implement `LinearStaticAnalysis`.
+- Do not add template-method hook lists for assembly, solve, boundary conditions, or output until `AnalysisModel` and `DofManager` exist.
@@ -0,0 +1,46 @@
+# Step 4: cmake-analysis-tests
+
+## Read First
+
+Read these files before editing:
+
+- `/AGENTS.md`
+- `/docs/PLAN.md`
+- `/docs/PROGRESS.md`
+- `/docs/WORKNOTE.md`
+- `/docs/AGENT_RULES.md`
+- `/docs/implementation-plans/analysis-state-analysis-base-implementation-plan.md`
+- `/CMakeLists.txt`
+- `/tests/core/analysis_state_test.cpp`
+- `/tests/analysis/analysis_base_test.cpp`
+
+## Task
+
+Make the analysis tests part of the normal MSVC CMake/CTest path.
+
+Required contract:
+
+- `fesa_core` includes `src/core/AnalysisState.cpp`.
+- `fesa_analysis_tests` builds both analysis-state and analysis-base tests.
+- CTest registers `analysis.base` or equivalent with labels `analysis;core`.
+- Existing `domain`, `model-object`, and `io` tests remain registered and unchanged except for required shared library source additions.
+
+## Tests To Write First
+
+No new behavior tests are required in this step if steps 1 through 3 already wrote them. If CMake registration is missing, the RED condition is that `ctest -R analysis` finds no registered analysis test or build fails because sources are missing.
+
+## Acceptance Criteria
+
+Run:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "analysis|domain|model-object|io"
+python scripts/validate_workspace.py
+```
+
+Update `/phases/analysis-state-analysis-base/index.json` step 4 with `completed`, `error`, or `blocked`.
+
+## Do Not
+
+- Do not modify unrelated tests.
+- Do not change dependency discovery or introduce MKL, TBB, or HDF5 linkage for this phase.
@@ -0,0 +1,48 @@
+# Step 5: validation-report-handoff
+
+## Read First
+
+Read these files before editing:
+
+- `/AGENTS.md`
+- `/docs/PLAN.md`
+- `/docs/PROGRESS.md`
+- `/docs/WORKNOTE.md`
+- `/docs/AGENT_RULES.md`
+- `/docs/implementation-plans/analysis-state-analysis-base-implementation-plan.md`
+- `/docs/build-test-reports/README.md`
+- `/phases/analysis-state-analysis-base/index.json`
+
+## Task
+
+Run final validation, record evidence, and update handoff files.
+
+Required output:
+
+- Create `/docs/build-test-reports/analysis-state-analysis-base-build-test.md`.
+- Update `/docs/PROGRESS.md` with completed work and validation evidence.
+- Update `/phases/analysis-state-analysis-base/index.json` step 5.
+- Update `/phases/index.json` phase status to `completed` only if validation passes.
+
+## Tests To Write First
+
+No new tests are required in this reporting step.
+
+## Acceptance Criteria
+
+Run:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "analysis|domain|model-object|io"
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+git diff --check
+```
+
+Record command outcomes in `/docs/build-test-reports/analysis-state-analysis-base-build-test.md`.
+
+## Do Not
+
+- Do not claim numerical correctness.
+- Do not claim release readiness.
+- Do not run Abaqus, Nastran, or any reference solver.
@@ -15,6 +15,10 @@
    {
      "dir": "property-model-foundation",
      "status": "completed"
+    },
+    {
+      "dir": "analysis-state-analysis-base",
+      "status": "completed"
    }
  ]
 }