docs: add shell pressure feature workflow

2026-09-01 02:34:04 +09:00
parent c54a528709
commit 2d071069b9
17 changed files with 4835 additions and 1 deletions
@@ -0,0 +1,165 @@
+# Step 4: integrate-linear-shell-pressure
+
+## 실행 범위와 상태 소유권
+
+이 Step의 single responsibility는 Step 3 local evaluator를 deterministic full-space pressure assembler와 linear-static reference-configuration path에 연결하고 existing schema-0/CLI/reaction/equilibrium behavior를 검증하는 것이다. Nonlinear follower procedure는 Step 5 범위다.
+
+Complete test-first RED, expected failure, minimal GREEN, focused and full VERIFY in this Step. Update only Step 4's selected status and one-line Codex-owned payload. Executor owns branch, retry, timestamps, commit, advancement, top-level phase status and output JSON.
+
+## 읽어야 할 파일
+
+- `AGENTS.md`
+- `docs/ARCHITECTURE.md`
+- `docs/ADR.md`
+- `docs/CODINGSTYLE.md`
+- `docs/HARNESS.md`
+- `docs/HARNESS_WORKFLOW.md`
+- `.codex/hooks.json`
+- `docs/shell-surface-pressure-load/requirements.md`
+- `docs/shell-surface-pressure-load/formulation.md` §§9, 11–14
+- `docs/shell-surface-pressure-load/numerical-review.md` §6
+- `docs/shell-surface-pressure-load/io.md` §§6–7, 9–10
+- `docs/shell-surface-pressure-load/implementation-plan.md`
+- Prior semantic outputs: `include/fesa/model/model_types.h`, `include/fesa/model/domain.h`, `src/fesa/model/domain.cpp`, `include/fesa/analysis/analysis_model.h`, `src/fesa/analysis/analysis_model.cpp`
+- Prior evaluator outputs: `include/fesa/loads/shell_surface_pressure.h`, `src/fesa/loads/shell_surface_pressure.cpp`, `tests/unit/loads/shell_surface_pressure_test.cpp`
+- `include/fesa/assembly/load_assembler.h`
+- `src/fesa/assembly/load_assembler.cpp`
+- `include/fesa/assembly/sparse_assembler.h`
+- `src/fesa/assembly/sparse_assembler.cpp`
+- `include/fesa/assembly/parallel_for.h`
+- `src/fesa/assembly/parallel_for.cpp`
+- `include/fesa/fem/dof_manager.h`
+- `src/fesa/fem/dof_manager.cpp`
+- `src/fesa/analysis/linear_static_procedure.cpp`
+- `include/fesa/analysis/analysis_state.h`
+- `src/fesa/analysis/analysis_state.cpp`
+- `include/fesa/results/result_recovery.h`
+- `src/fesa/results/result_recovery.cpp`
+- `src/fesa/results/global_equilibrium_recovery.h`
+- `src/fesa/results/global_equilibrium_recovery.cpp`
+- `include/fesa/io/hdf5/hdf5_results_writer.h`
+- `src/fesa/io/hdf5/hdf5_results_writer.cpp`
+- `src/fesa/io/hdf5/hdf5_self_check.h`
+- `src/fesa/io/hdf5/hdf5_self_check.cpp`
+- `src/fesa/app/fesa_application.cpp`
+- `tests/unit/assembly/load_assembler_test.cpp`
+- `tests/unit/assembly/sparse_assembler_test.cpp`
+- `tests/integration/analysis/linear_static_analysis_test.cpp`
+- `tests/integration/app/fesa_application_test.cpp`
+- `tests/unit/io/hdf5/hdf5_results_writer_test.cpp`
+- `src/fesa/CMakeLists.txt`
+- `tests/CMakeLists.txt`
+
+## 소유 파일과 인터페이스
+
+- Create test first: `tests/unit/assembly/surface_pressure_assembler_test.cpp`
+- Create test first: `tests/integration/analysis/shell_surface_pressure_linear_test.cpp`
+- Create test first: `tests/integration/app/shell_surface_pressure_application_test.cpp`
+- Create: `include/fesa/assembly/surface_pressure_assembler.h`
+- Create: `src/fesa/assembly/surface_pressure_assembler.cpp`
+- Modify: `src/fesa/analysis/linear_static_procedure.cpp`
+- Modify/Test assertions only: `tests/unit/io/hdf5/hdf5_results_writer_test.cpp`
+- Modify: `src/fesa/CMakeLists.txt`
+- Modify: `tests/CMakeLists.txt`
+
+HDF5 production writer and `fesa_application.cpp` are expected no-change verification targets. Modify them only if a new RED test proves a direct approved-contract gap, and record that evidence and minimal reason.
+
+Assembler contract:
+
+```cpp
+struct SurfacePressureAssemblyCandidate {
+  Vector full_external_force;
+  SparseMatrix full_external_tangent;
+  std::vector<Diagnostic> diagnostics;
+};
+
+Result<SurfacePressureAssemblyCandidate> AssembleSurfacePressure(
+    const AnalysisModel& model,
+    const DofManager& dofs,
+    const Vector& full_generalized_coordinates,
+    double load_factor,
+    SurfacePressureConfiguration configuration,
+    const ParallelFor& parallel_for);
+```
+
+The input vector is stable full-DOF `[u1,u2,u3,phi1,phi2,phi3]`. Produce local candidates in `(load_ordinal, facet_ordinal, instance declaration ordinal, element label, local row[,column])`, use worker-local buffers and reduce in that exact serial order. Workers never update global vector/CSR directly.
+
+## RED
+
+Write/register first:
+
+- `SurfacePressureAssembly.AssemblesFullDofsInPressureFacetAndRecordOrder`
+- `SurfacePressureAssembly.AddsRepeatedRecordsAndAppliesUnitFactorExactlyOnce`
+- `SurfacePressureAssembly.IsBitwiseStableForSerialAndParallelLocalEvaluation`
+- `LinearShellSurfacePressure.UsesReferenceNormalAndAreaAfterPrescribedDisplacement`
+- `LinearShellSurfacePressure.AssemblesBeforeProjectionAndIncludesConstrainedReaction`
+- `LinearShellSurfacePressure.SatisfiesFreeResidualGlobalResultantAndMoment`
+- `LinearShellSurfacePressure.PreservesS4S4rMeshAndCyclicOrderInvariance`
+- `LinearShellSurfacePressure.WritesSchemaZeroWithoutPressureDataset`
+- `ShellSurfacePressureApplication.LinearFailurePreservesExistingFinalAndNoCandidate`
+- `ShellSurfacePressureApplication.InputWithoutPressureRetainsExistingLinearBehavior`
+
+Run before production implementation:
+
+```powershell
+cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -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 --target fesa_unit_tests fesa_integration_tests
+ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(SurfacePressureAssembly|LinearShellSurfacePressure|ShellSurfacePressureApplication)\."
+```
+
+Expected RED: assembler compile/link failure, or linear procedure assembles only CLOAD so pressure resultant/reaction remains zero and pressure CLI assertions fail. Record command, exit, duration and output tail. Unexpected pass is evidence-gap; unrelated failure is regression.
+
+## Minimal GREEN
+
+- Create evaluator inputs from immutable Domain source identity and stable DofManager scatter. Evaluate every `(load_ordinal, facet_ordinal)`, including zero pressure/factor geometry validation.
+- Keep worker-local force/tangent contributions. Validate all candidates before fixed serial reduction; no global concurrent writes.
+- In `LinearStaticProcedureExecutor`, preserve element stiffness assembly, `Kff/Kfc` partition and `Kff` factorization-before-load order.
+- Assemble existing CLOAD and reference pressure separately, checked-finite add their full-space forces, and assign `AnalysisState::ExternalForce()` exactly once before free/constrained projection.
+- Call pressure assembler with load factor exactly `1.0`, reference configuration and a full generalized-coordinate vector of the required size. Linear pressure tangent is exact zero and does not change stiffness.
+- Preserve `EffectiveFreeRhs(Ff-Kfc*dc)`, valid `0x0 Kff`, full displacement reconstruction and `K*d-F` recovery. Constrained residual is reaction; free residual is equilibrium evidence.
+- Preserve current schema version `0`, mandatory result inventory, CLI sibling naming and atomic candidate finalization. Add no surface/load/pressure dataset or metadata.
+
+## VERIFY and Acceptance Criteria
+
+Use `.harness/config.json` first if present; otherwise:
+
+```powershell
+cmake --build .harness/build --config Debug --target fesa_unit_tests fesa_integration_tests
+ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(SurfacePressureAssembly|LinearShellSurfacePressure|ShellSurfacePressureApplication)\."
+ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(LoadAssembly|SparseAssembly|LinearStaticCli|Mitc4ShellCli|Hdf5ResultsWriter)\."
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+Acceptance:
+
+- normalized analytical force/moment/reaction/mesh/order errors `<=1e-12`;
+- global force and moment balance `<=1e-8` and approved existing free-residual gates;
+- serial/parallel external vectors, diagnostics and row order exact;
+- schema `0`, existing mandatory datasets only, no pressure-specific path;
+- failed pressure candidate leaves prior final bytes unchanged or no misleading final;
+- inputs without pressure retain current results;
+- nonzero CTest inventory, full pass, no new MSVC warning and runtime staging succeeds.
+
+## 불변식, 실패 처리와 증거
+
+- Full-space completion precedes projection; source/internal/equation IDs remain distinct.
+- Load factor is applied exactly once; repeated pressure records remain additive.
+- Any local/nonfinite/assembly/recovery failure returns before state/result publication.
+- Record RED/GREEN/VERIFY commands, exits, durations/tails, contribution order, external/reaction/residual/resultant values, schema inventory and final-file snapshots.
+- Failure classification: `configure | compile | link | test | harness | environment | upstream-contract | regression | evidence-gap`.
+
+Trace: `FESA-REQ-SHELL-PRESSURE-005`–`007`, `010`–`013`, `016`–`020`; io §§6–7, 9–10; formulation §§9, 11–14; numerical-review linear/resultant/balance checks.
+
+## 금지사항
+
+- Do not implement nonlinear follower procedure, change the linear solver backend, HDF5 schema or output inventory.
+- Do not refactor existing load hierarchy beyond the new pressure assembler or expose MKL/TBB/HDF5 in public core.
+- Do not modify upstream docs, tolerance/reference artifacts or Abaqus files.
+- Do not run Abaqus, create output JSON, invoke Executor, advance Step 5, commit or push.
+