FESADev/phases/shell-surface-pressure-load/step5.md

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 and focused VERIFY를 완료한 뒤 종료하며, automatic Stop hook이 exactly one whole-project full verification을 소유한다.

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:

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:

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:

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)\."
ctest --test-dir .harness/build -C Debug --show-only=json-v1

위 targeted build, focused feature/regression tests와 nonzero discovery evidence를 기록한 뒤 Step status/summary를 갱신하고 agent turn을 종료한다. Implementation Agent는 target 없는 whole-project build 또는 unfiltered full CTest를 실행하지 않는다. Automatic Stop hook이 exactly one whole-project MSVC x64 Debug build/full CTest를 수행한다.

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; focused tests pass with nonzero discovery and no warning/runtime staging failure; automatic Stop's exactly one whole-project MSVC x64 Debug build/unfiltered CTest passes.

불변식, 실패 처리와 증거

• 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.