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,147 @@
+# Step 5: integrate-nonlinear-follower-pressure
+
+## 실행 범위와 상태 소유권
+
+이 Step의 단일 책임은 current-configuration follower pressure force와 generally nonsymmetric exact external tangent를 nonlinear full-Newton trial/commit lifecycle과 existing schema-1 output에 연결하는 것이다. Same Step에서 test-first RED, expected failure, minimal GREEN, focused/full VERIFY를 완료한다.
+
+Implementation Agent는 Executor-selected Step 5만 수행하고 Step 5 `status`와 한 줄 `summary`/`error_message`/`blocked_reason`만 기록한다. Executor가 branch, retry, timestamps, commits, advancement, top-level 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.2–9.4, 11–14
+- `docs/shell-surface-pressure-load/numerical-review.md` §6 nonlinear suite
+- `docs/shell-surface-pressure-load/io.md` §§6–7, 9–10
+- `docs/shell-surface-pressure-load/implementation-plan.md`
+- Prior 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/assembler: `include/fesa/loads/shell_surface_pressure.h`, `src/fesa/loads/shell_surface_pressure.cpp`, `include/fesa/assembly/surface_pressure_assembler.h`, `src/fesa/assembly/surface_pressure_assembler.cpp`, their unit tests
+- `include/fesa/analysis/nonlinear_static_control.h`
+- `src/fesa/analysis/nonlinear_static_control.cpp`
+- `include/fesa/analysis/nonlinear_static_procedure.h`
+- `src/fesa/analysis/nonlinear_static_procedure.cpp`
+- `include/fesa/analysis/nonlinear_analysis_state.h`
+- `src/fesa/analysis/nonlinear_analysis_state.cpp`
+- `include/fesa/elements/nonlinear_mitc4_shell.h`
+- `src/fesa/elements/nonlinear_mitc4_shell.cpp`
+- `include/fesa/solvers/linear/tangent_solver.h`
+- `include/fesa/solvers/linear/mkl_pardiso_tangent_solver.h`
+- `src/fesa/solvers/linear/mkl_pardiso_tangent_solver.cpp`
+- `include/fesa/io/hdf5/nonlinear_hdf5_results_writer.h`
+- `src/fesa/io/hdf5/nonlinear_hdf5_results_writer.cpp`
+- `src/fesa/io/hdf5/hdf5_self_check.h`
+- `src/fesa/io/hdf5/hdf5_self_check.cpp`
+- `include/fesa/analysis/prepared_analysis.h`
+- `src/fesa/analysis/prepared_analysis.cpp`
+- `src/fesa/app/fesa_application.cpp`
+- `tests/integration/analysis/nonlinear_static_procedure_test.cpp`
+- `tests/unit/io/hdf5/nonlinear_hdf5_results_writer_test.cpp`
+- `tests/unit/solvers/linear/tangent_solver_test.cpp`
+- `tests/integration/app/shell_surface_pressure_application_test.cpp`
+- `tests/CMakeLists.txt`
+
+Step 4 must already provide a validated full-space assembler and linear path. Do not change its reference-configuration semantics.
+
+## 소유 파일과 procedure contract
+
+- Create test first: `tests/integration/analysis/shell_surface_pressure_nonlinear_test.cpp`
+- Modify test first: `tests/integration/app/shell_surface_pressure_application_test.cpp`
+- Modify test assertions: `tests/unit/io/hdf5/nonlinear_hdf5_results_writer_test.cpp`
+- Modify: `src/fesa/analysis/nonlinear_static_procedure.cpp`
+- Modify only if checked contribution composition requires a helper: `include/fesa/analysis/nonlinear_static_control.h`, `src/fesa/analysis/nonlinear_static_control.cpp`
+- Modify: `tests/CMakeLists.txt`
+
+Existing PARDISO, HDF5 writer/self-check and application production files are expected no-change verification targets unless RED proves a direct approved-contract defect.
+
+For each Newton trial, use the existing Step 4 interface:
+
+```cpp
+Result<SurfacePressureAssemblyCandidate> AssembleSurfacePressure(
+    const AnalysisModel& model,
+    const DofManager& dofs,
+    const Vector& full_generalized_coordinates,
+    double load_factor,
+    SurfacePressureConfiguration configuration,
+    const ParallelFor& parallel_for);
+```
+
+Evaluate internal and external candidates at the same trial. Compose
+`f_ext=f_fixed+f_pressure`, `K_ext=K_fixed+K_pressure`, `r=f_int-f_ext`, `K=K_int-K_ext`. Use the existing full-CSR unsymmetric `TangentSolver::FactorizeFresh`; never symmetrize pressure tangent.
+
+## RED
+
+Write/register first:
+
+- `NonlinearShellSurfacePressure.AssemblesFollowerForceFromCurrentTrialGeometry`
+- `NonlinearShellSurfacePressure.FormsResidualAndTangentWithApprovedExternalSigns`
+- `NonlinearShellSurfacePressure.AppliesIncrementFactorExactlyOnce`
+- `NonlinearShellSurfacePressure.UsesFullUnsymmetricTangentSolverPath`
+- `NonlinearShellSurfacePressure.ConvergesOpenPatchAndPreservesAntisymmetricEvidence`
+- `NonlinearShellSurfacePressure.SatisfiesAcceptedFreeResidualAndFactorOneGlobalBalance`
+- `NonlinearShellSurfacePressure.IsObjectiveUnderRigidMotionAndTracksCurrentArea`
+- `NonlinearShellSurfacePressure.ReducesSerialAndParallelContributionsDeterministically`
+- `NonlinearShellSurfacePressure.InvalidTrialRollsBackCommittedFrameAndFinalOutput`
+- `NonlinearShellSurfacePressure.WritesSchemaOneExternalInternalResidualReactionAndEquilibrium`
+- `ShellSurfacePressureApplication.InputWithoutPressureRetainsExistingNonlinearBehavior`
+
+Run before production edits:
+
+```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 "^(NonlinearShellSurfacePressure|ShellSurfacePressureApplication)\."
+```
+
+Expected RED: current nonlinear procedure includes fixed CLOAD only, so follower force/tangent, objectivity, sign, convergence or balance tests fail. Record command, exit, duration and tail. Unexpected pass is evidence-gap; unrelated failure is regression.
+
+## Minimal GREEN
+
+- At every Newton trial call `AssembleSurfacePressure` with current full generalized coordinates, exact current increment `load_factor` and `kCurrent`.
+- Checked-finite add fixed and pressure force/tangent in stable order. Apply source pressure magnitude and load factor exactly once.
+- Keep pressure kinematics translation-only; rotation force and tangent blocks stay zero. Retain generally nonsymmetric external tangent and existing `MklPardisoTangentSolver` full CSR `mtype=11` path.
+- Form residual and tangent with approved signs in full space before constrained/free extraction. Internal/external residual and tangent must be from the same trial.
+- Complete and validate candidate kinematics, force/tangent, residual, equilibrium and convergence before `CommitAcceptedFrame`. Invalid geometry/nonfinite/factorization/solve failures must not append frames or replace final HDF5.
+- Preserve existing force/moment convergence channels and thresholds; do not add line search/arc length or alter factor sequence.
+- Preserve schema `1` and existing generalized internal/external/residual/reaction/global equilibrium datasets. Add no pressure dataset/version/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 "^(NonlinearShellSurfacePressure|ShellSurfacePressureApplication)\."
+ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(NonlinearStaticProcedure|NonlinearStaticControl|TangentSolver|NonlinearHdf5ResultsWriter|NonlinearStaticReference)\."
+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: local FD `<=1e-8`; objectivity/current-area normalized error `<=1e-12`; factor-one global force/moment balance `<=1e-8`; existing free force/moment residual nonzero-scale relative `<=1e-2`, zero-scale absolute `<=1e-3`; exact zero-scale rules; schema-1 unique factor-one frame projections exact; serial/parallel order exact; invalid trial rollback exact; all discovered tests pass with no warning/runtime staging failure.
+
+## 불변식, 실패 처리와 증거
+
+- Candidate-before-commit and same-trial internal/external data are mandatory.
+- Failure records deterministic last-completed Newton stage and pressure source identity but publishes no invalid state/output.
+- Record RED/GREEN/VERIFY commands, exits, durations/tails, load factor, force/tangent signs and nonsymmetry, solver spy events, iteration count, residual/balance metrics, HDF5 inventory and rollback snapshots.
+- Failure classification: `configure | compile | link | test | harness | environment | upstream-contract | regression | evidence-gap`.
+
+Trace: `FESA-REQ-SHELL-PRESSURE-008`–`013`, `016`–`019`, `021`; io §§6–7, 9–10; formulation §§9–14; numerical-review follower/tangent/objectivity/open-patch/balance checks.
+
+## 금지사항
+
+- Do not add line search, arc length, new procedure, convergence threshold changes, PARDISO redesign or HDF5 fields.
+- Do not alter Step 3 force/tangent math or Step 4 linear path except a test-proven defect returned to the owning Step through Coordinator.
+- Do not modify upstream docs, tolerance/reference artifacts or run Abaqus.
+- Do not create output JSON, invoke Executor, advance Step 6, commit or push.
+