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

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 and focused VERIFY in this Step, then end so automatic Stop owns exactly one whole-project full verification. 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/solver-core/README.md
• ../../docs/solver-core/README.md
• ../../docs/solver-core/README.md
• ../../docs/solver-core/README.md
• ../../docs/solver-core/README.md
• .codex/hooks.json
• ../../docs/shell-surface-pressure-load/README.md
• ../../docs/shell-surface-pressure-load/formulation.md §§9, 11–14
• ../../docs/shell-surface-pressure-load/README.md §6
• ../../docs/shell-surface-pressure-load/README.md §§6–7, 9–10
• ../../docs/shell-surface-pressure-load/README.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:

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:

과거 도구 실행·출력 지시는 정리했으며, 현재 검증 방법은 기능 요약을 따른다.

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 과거 검증 자료(정리됨) first if present; otherwise:

과거 도구 실행·출력 지시는 정리했으며, 현재 검증 방법은 기능 요약을 따른다.

위 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:

• 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, focused feature/regression pass, no new MSVC warning and runtime staging succeeds;
• automatic Stop의 exactly one whole-project MSVC x64 Debug build/unfiltered CTest pass.

불변식, 실패 처리와 증거

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