From 2d071069b91a87e6b9fa600892a6545a1890e9b2 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Tue, 1 Sep 2026 02:34:04 +0900 Subject: [PATCH] docs: add shell pressure feature workflow --- .../coordination.md | 223 +++++ .../formulation.md | 749 ++++++++++++++++ .../implementation-plan.md | 818 ++++++++++++++++++ docs/shell-surface-pressure-load/io.md | 639 ++++++++++++++ .../numerical-review.md | 254 ++++++ .../reference-model.md | 185 ++++ .../requirements.md | 630 ++++++++++++++ docs/shell-surface-pressure-load/research.md | 231 +++++ phases/index.json | 6 +- phases/shell-surface-pressure-load/index.json | 42 + phases/shell-surface-pressure-load/step1.md | 216 +++++ phases/shell-surface-pressure-load/step2.md | 121 +++ phases/shell-surface-pressure-load/step3.md | 157 ++++ phases/shell-surface-pressure-load/step4.md | 165 ++++ phases/shell-surface-pressure-load/step5.md | 147 ++++ phases/shell-surface-pressure-load/step6.md | 139 +++ phases/shell-surface-pressure-load/step7.md | 114 +++ 17 files changed, 4835 insertions(+), 1 deletion(-) create mode 100644 docs/shell-surface-pressure-load/coordination.md create mode 100644 docs/shell-surface-pressure-load/formulation.md create mode 100644 docs/shell-surface-pressure-load/implementation-plan.md create mode 100644 docs/shell-surface-pressure-load/io.md create mode 100644 docs/shell-surface-pressure-load/numerical-review.md create mode 100644 docs/shell-surface-pressure-load/reference-model.md create mode 100644 docs/shell-surface-pressure-load/requirements.md create mode 100644 docs/shell-surface-pressure-load/research.md create mode 100644 phases/shell-surface-pressure-load/index.json create mode 100644 phases/shell-surface-pressure-load/step1.md create mode 100644 phases/shell-surface-pressure-load/step2.md create mode 100644 phases/shell-surface-pressure-load/step3.md create mode 100644 phases/shell-surface-pressure-load/step4.md create mode 100644 phases/shell-surface-pressure-load/step5.md create mode 100644 phases/shell-surface-pressure-load/step6.md create mode 100644 phases/shell-surface-pressure-load/step7.md diff --git a/docs/shell-surface-pressure-load/coordination.md b/docs/shell-surface-pressure-load/coordination.md new file mode 100644 index 0000000..cc75a4e --- /dev/null +++ b/docs/shell-surface-pressure-load/coordination.md @@ -0,0 +1,223 @@ +# Shell Surface Pressure Load Coordination Record + +## 1. Metadata and Feature Scope + +- feature_id: `shell-surface-pressure-load` +- workflow_state: `needs-implementation` +- owner_agent: `coordinator-agent` +- request_date: `2026-08-30` +- last_updated: `2026-08-31` +- process_classification: `architectural` +- current_goal: 승인·감사된 Harness Step 1–7을 한 Implementation Agent/Executor 흐름으로 순차 실행하고 Gate 6 implementation/build/reference evidence를 확보한다. +- approved_scope: Abaqus subset `*SURFACE, TYPE=ELEMENT`와 `*DSLOAD`의 uniform `P`를 S4/S4R `SPOS|SNEG` surface에 적용한다. Linear static은 reference configuration load를, nonlinear static은 current-configuration follower load와 external tangent를 사용한다. +- scope_boundaries: Unsupported surface/load variants는 fail-closed로 거부하고 stable source identity와 deterministic load/reduction order를 보존한다. 기존 authoritative HDF5 output을 우선 유지하되 Stage 5 I/O gate가 evidence로 최종 확정한다. +- reference_case: `reference/shellNL-meshfine-pressure/`의 existing `.inp`와 CSV를 exact path/name 그대로 read-only 사용한다. +- user_approval: `2026-08-30` approved Abaqus-aligned design; `2026-09-01` approved the 7-Step implementation plan, phase materialization, and Harness implementation/verification execution without push. + +## 2. Eight-Stage Worklist + +| stage | owner | status | output paths | acceptance gate | evidence summary | blockers | attempt count | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 1. Requirements | `requirement-agent` | `passed` | `docs/shell-surface-pressure-load/requirements.md` | 지원/제외 범위, verifiable acceptance criteria, verification quantities, tolerance baseline과 requirement verification matrix가 승인 설계를 손실 없이 고정함 | `FESA-REQ-SHELL-PRESSURE-001`–`024`; normative 24/matrix 24; orphan 0; exact reference input/displacement paths와 blocking/warning/excluded disposition; owner `passed`; Coordinator audit 통과 | 없음 | 1 | +| 2. Research | `research-agent` | `passed` | `docs/shell-surface-pressure-load/research.md` | 이론, benchmark, primary evidence와 applicability limit가 충분함 | Source 15개(Project/Stored 3, Tier 1 official 8, Tier 2 3, Tier 3 navigation 1), key claims 15개, benchmark 8개, normative trace gap 0; owner `passed`; Coordinator audit 통과 | 없음 | 1 | +| 3. Formulation | `formulation-agent` | `passed` | `docs/shell-surface-pressure-load/formulation.md` | Pressure virtual work, equivalent nodal load, follower linearization과 numerical integration 계약이 구현 가능함 | `ready-for-numerical-review`; force/residual/tangent sign, common `2x2` rule, `24x1`/`24x24` dimensions, dimensionless geometry contract, deterministic assembly, requirement trace 24/24; owner `passed`; Coordinator audit 통과 | 없음 | 1 | +| 4. Numerical/reference review | `numerical-review-agent` | `passed` | `docs/shell-surface-pressure-load/numerical-review.md`; `docs/shell-surface-pressure-load/reference-model.md` | Numerical review와 exact reference contract가 함께 `pass-for-io-definition`임 | Aligned `pass-for-io-definition`; `tau_J=1e-12`, analytical/objectivity `1e-12`, FD `h=1e-5`/error `1e-8`, global balance `1e-8`; exact 729-row reference inventory, U/UR 2,187 logical rows each; owner evidence와 Coordinator audit 통과 | 없음 | 1 | +| 5. I/O definition | `io-definition-agent` | `passed` | `docs/shell-surface-pressure-load/io.md` | Abaqus subset, semantic mapping, diagnostics, HDF5 projection과 reference rows가 명확함 | `ready-for-implementation-planning`; exact assembly `SURFACE`/step `DSLOAD P`, Domain/Step/AnalysisModel mapping, ordered fail-closed validation, unchanged schema `0/1`, exact HDF5/reference projection, trace 24/24; owner `passed`; Coordinator audit 통과 | 없음 | 1 | +| 6. Implementation | `implementation-planning-agent`; `implementation-agent` | `in-progress` | `docs/shell-surface-pressure-load/implementation-plan.md`; `docs/shell-surface-pressure-load/implementation-report.md`; `docs/shell-surface-pressure-load/build-test.md`; `docs/shell-surface-pressure-load/reference-comparison.md` | 승인 계획, TDD evidence, MSVC/x64/Debug build/CTest와 blocking reference comparison이 모두 통과함 | Planning/phase subgates `passed`; 7 pending Steps와 exact filenames/slugs/order, RED/GREEN/VERIFY, reference immutability를 Coordinator audit함; `GATE6-IMPL-001` execution dispatch 준비 | Implementation Agent evidence 대기 | 1 | +| 7. Physics evaluation | `physics-evaluation-agent` | `pending` | `docs/shell-surface-pressure-load/physics-evaluation.md` | Direction, symmetry, resultant, reaction과 equilibrium 검토가 `pass-for-release-agent`임 | Gate 6 evidence 대기 | Gate 6 미통과 | 0 | +| 8. Release readiness | `release-agent` | `pending` | `docs/shell-surface-pressure-load/release.md` | Acceptance traceability와 limitation을 포함한 verdict가 `ready-for-release`임 | Gate 7 evidence 대기 | Gate 7 미통과 | 0 | + +## 3. Active Dispatch Package and Latest Sub-Agent Return + +### Completed Dispatch Package + +- dispatch_id: `GATE1-REQ-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `requirement-agent` +- required_inputs: + - `AGENTS.md` + - `docs/PRD.md` + - `docs/ARCHITECTURE.md` + - `docs/ADR.md` + - `docs/TOLERANCE.md` + - `docs/SOLVER_AGENT_DESIGN.md` + - approved design recorded in this file + - `reference/shellNL-meshfine-pressure/` read-only inventory +- expected_outputs: `docs/shell-surface-pressure-load/requirements.md` +- acceptance_gate: Verifiable shall requirements, explicit scope/exclusions, input/output semantics, failure behavior, deterministic identity/order, reference quantities/dispositions, common tolerance baseline and complete requirement verification matrix preserve the approved design without downstream formulation or I/O invention. +- stop_condition: `requirements.md`와 return evidence를 제출한 뒤 중지한다. Peer dispatch, Gate 2 work, source/tests/CMake/reference/tolerance 변경은 금지한다. +- missing_evidence: 없음 + +### Completed Dispatch Package — Gate 2 + +- dispatch_id: `GATE2-RES-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `research-agent` +- required_inputs: + - `AGENTS.md` + - `docs/SOLVER_AGENT_DESIGN.md` + - `docs/shell-surface-pressure-load/requirements.md` binding baseline + - `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/TOLERANCE.md` + - exact read-only inventory under `reference/shellNL-meshfine-pressure/` + - `fesa-research-evidence`; 필요 시 `fem-theory-query` +- expected_outputs: `docs/shell-surface-pressure-load/research.md` +- acceptance_gate: Key claims마다 source/reliability tier 또는 inference label이 있고, Abaqus observable input/load semantics와 FESA-owned theory가 분리된다. Pressure virtual work, current-surface follower force, external tangent, S4/S4R applicability와 verification candidates가 target quantity, 한계, exact artifact와 requirement trace를 갖는다. +- stop_condition: `research.md`와 return evidence 제출 후 중지한다. Formulation 확정, peer dispatch, Gate 3, source/tests/CMake/reference/tolerance 변경은 금지한다. +- missing_evidence: 없음 + +### Completed Dispatch Package — Gate 3 + +- dispatch_id: `GATE3-FORM-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `formulation-agent` +- required_inputs: + - `AGENTS.md` + - `docs/SOLVER_AGENT_DESIGN.md` + - binding `docs/shell-surface-pressure-load/requirements.md` + - approved `docs/shell-surface-pressure-load/research.md` + - applicable project architecture/ADR contracts + - `fesa-formulation-spec`; 필요 시 supporting `fem-theory-query` +- expected_outputs: `docs/shell-surface-pressure-load/formulation.md` +- acceptance_gate: Strong/weak form, S4/S4R interpolation, side/sign map, reference/current geometry, quadrature/Jacobian validity, consistent pressure force, residual sign, exact external tangent, full-space deterministic assembly, units/failures, verification identities와 requirement trace가 implementation-ready이며 Abaqus internal equivalence를 주장하지 않음. +- stop_condition: `formulation.md`와 return evidence 제출 후 중지한다. Parser/API/source/test/reference 변경, peer dispatch, Numerical Review/Gate 4 수행은 금지한다. +- missing_evidence: 없음 + +### Completed Dispatch Package — Gate 4 + +- dispatch_id: `GATE4-NR-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `numerical-review-agent` +- required_inputs: + - `AGENTS.md`, `docs/SOLVER_AGENT_DESIGN.md` + - binding `requirements.md`, approved `research.md`, `formulation.md` + - `docs/TOLERANCE.md`와 applicable architecture/ADR contracts + - exact read-only `reference/shellNL-meshfine-pressure/` artifacts + - `fesa-numerical-review` +- expected_outputs: `docs/shell-surface-pressure-load/numerical-review.md`; `docs/shell-surface-pressure-load/reference-model.md` +- acceptance_gate: 독립 sign/force/tangent/residual/integration/geometry/objectivity/equilibrium/determinism review가 blocking flaw 없이 통과하고, `tau_J`와 internal test thresholds가 scale-aware하게 확정된다. Exact input/required CSV identity, component/blocking classification, row prechecks와 unchanged `docs/TOLERANCE.md` policy가 I/O 정의에 충분해야 한다. +- stop_condition: 두 report와 owner verdict/return evidence 제출 후 중지한다. Upstream flaw는 문서를 조용히 수정하지 않고 precise rework로 반환한다. Source/tests/CMake/reference/tolerance 변경, peer dispatch, Gate 5 수행은 금지한다. +- missing_evidence: 없음 + +### Completed Dispatch Package — Gate 5 + +- dispatch_id: `GATE5-IO-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `io-definition-agent` +- required_inputs: + - `AGENTS.md`, `docs/SOLVER_AGENT_DESIGN.md` + - approved feature `requirements.md`, `research.md`, `formulation.md`, `numerical-review.md`, `reference-model.md` + - applicable PRD/architecture/ADR/CODINGSTYLE/TOLERANCE contracts + - exact read-only `reference/shellNL-meshfine-pressure/` artifacts + - `fesa-io-contract` +- expected_outputs: `docs/shell-surface-pressure-load/io.md` +- acceptance_gate: Approved `*SURFACE TYPE=ELEMENT`/`*DSLOAD P` grammar, model/history mapping, deterministic target resolution/diagnostics, Domain/Step/AnalysisModel semantic ownership, existing authoritative HDF5 field projection, exact reference CSV identity/prechecks/common tolerance와 compatibility boundary가 구현 계획에 충분하고 upstream contract와 일치함. +- stop_condition: `io.md`와 owner return evidence 제출 후 중지한다. Parser/API implementation, source/tests/CMake/phases/reference/tolerance 변경, peer dispatch와 Gate 6 수행은 금지한다. +- missing_evidence: 없음 + +### Completed Dispatch Package — Gate 6 Planning + +- dispatch_id: `GATE6-PLAN-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `implementation-planning-agent` +- required_inputs: + - `AGENTS.md`, `docs/SOLVER_AGENT_DESIGN.md`, `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md` + - approved feature `requirements.md`, `research.md`, `formulation.md`, `numerical-review.md`, `reference-model.md`, `io.md` + - current source/tests/CMake/`.harness/config.json`/hooks/phase inventory read-only + - `fesa-cpp-msvc-tdd`, project-local `harness`, compatible `superpowers:writing-plans` +- expected_outputs: `docs/shell-surface-pressure-load/implementation-plan.md`; concise user-approval Step draft in owner return +- acceptance_gate: Multiple self-contained Steps가 각자 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`를 포함하고 exact files/signatures/tests/commands/dependencies/traceability를 지정한다. Parser/model, force/tangent, linear/nonlinear assembly, deterministic failure, HDF5/reference comparison와 final MSVC x64 Debug CTest evidence를 모두 다루며 reference immutability/atomicity를 보존한다. +- stop_condition: Plan draft와 return evidence 제출 후 사용자 승인을 기다린다. `phases/index.json`, `phases//`, source/tests/CMake/reference 수정, Harness execution, Implementation Agent dispatch는 승인 전 금지한다. +- missing_evidence: 사용자 plan approval + +### Completed Dispatch Package — Gate 6 Phase Materialization + +- dispatch_id: `GATE6-PHASE-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `implementation-planning-agent` (`GATE6-PLAN-001`과 동일 owner instance) +- required_inputs: + - approved `docs/shell-surface-pressure-load/implementation-plan.md` + - `AGENTS.md`, `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`, project-local `harness` + - existing `phases/index.json`과 existing task directories +- expected_outputs: `phases/index.json`; `phases/shell-surface-pressure-load/index.json`; `phases/shell-surface-pressure-load/step1.md`–`step7.md` +- acceptance_gate: Top-level task entry와 task index의 7 pending Steps가 승인 slug/order와 정확히 일치한다. 각 Step은 독립 실행에 필요한 upstream docs, exact files/signatures, RED expected failure, minimal GREEN, focused/full MSVC x64 Debug CMake/CTest commands, dependencies, status ownership, forbidden scope와 reference immutability를 대화 참조 없이 포함한다. +- stop_condition: Planning files만 materialize하고 실행·Step selection·status advancement·timestamp·commit·push를 하지 않는다. Source/tests/CMake/docs/reference/tolerance는 변경하지 않는다. +- missing_evidence: 없음 + +### Active Dispatch — Gate 6 Implementation + +- dispatch_id: `GATE6-IMPL-001` +- feature_id: `shell-surface-pressure-load` +- target_sub_agent: `implementation-agent` +- required_inputs: + - `AGENTS.md`, `.codex/hooks.json`, `.agents/skills/harness/SKILL.md`, `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md` + - approved feature bundle `requirements.md`, `research.md`, `formulation.md`, `numerical-review.md`, `reference-model.md`, `io.md`, `implementation-plan.md` + - materialized `phases/index.json`, `phases/shell-surface-pressure-load/index.json`, `step1.md`–`step7.md` + - `fesa-cpp-msvc-tdd`; user authorization for `python scripts/execute.py shell-surface-pressure-load` without `--push` +- expected_outputs: completed phase Step records; feature production/tests/CMake/comparator changes; `docs/shell-surface-pressure-load/implementation-report.md`; `build-test.md`; `reference-comparison.md`; actual RED/GREEN/VERIFY logs and unchanged reference hashes +- acceptance_gate: Step 1–7 executes in order with expected RED before each production behavior, minimal GREEN, focused and full MSVC x64 Debug build/CTest. Final comparison uses exact stored artifacts, deterministic identity/prechecks/common tolerance and records U blocking/UR warning-only while preserving hashes. All Gate 6 reports must support `pass-for-physics-evaluation` with no unresolved blocking failure. +- stop_condition: Do not push, run Abaqus/reference solvers, change upstream contracts/tolerance/reference artifacts, advance Gate 7, or revert other agents' docs/coordination changes. Repeated/unclear implementation failure returns to Coordinator for bounded correction routing. +- missing_evidence: completed Steps 1–7, three Gate 6 reports, owner return, Coordinator evidence audit + +### Latest Sub-Agent Return + +- target_sub_agent: `implementation-planning-agent` +- output_paths: `phases/index.json`; `phases/shell-surface-pressure-load/index.json`; `phases/shell-surface-pressure-load/step1.md`–`step7.md` +- status: `passed`; phase materialization complete +- evidence_summary: Existing top-level entries/status/timestamps를 보존하고 pending feature entry 하나를 append함. Task index는 승인된 7 slugs를 Step 1–7과 matching files로 등록함. Coordinator audit에서 Executor path resolution, pending statuses, self-contained required/prior files, exact interfaces/tests, expected RED, minimal GREEN, MSVC/x64/Debug focused/full commands, no hidden scope, exact reference hashes/read-only policy와 final literal comparison/report order를 확인함. +- blockers: 없음 +- open_evidence_gaps: Implementation Agent의 actual RED/GREEN/VERIFY, build/CTest, reference comparison과 three reports 대기 +- critical_user_question: 없음 +- forbidden_area_assertion: source, tests, CMake, phases, `docs/TOLERANCE.md`, reference artifact 변경 없음 + +## 4. Gate Decision Log and Workflow State + +| date | dispatch | gate decision | owner evidence | workflow state | +| --- | --- | --- | --- | --- | +| 2026-08-30 | `GATE1-REQ-001` | `passed` | Owner `passed`; `requirements.md` 24 normative IDs/24 matrix rows, complete traceability, approved design/reference boundary, blocker 없음. Coordinator 독립 구조 감사에서 orphan 0, matrix-only 0 및 필수 contract field 누락 0 확인 | `needs-research` | +| 2026-08-30 | `GATE2-RES-001` | `passed` | Owner `passed`; source 15/key claims 15/benchmark 8/trace gap 0. Coordinator audit에서 undeclared cited source 0, Abaqus observable/FESA formulation 분리, limitation과 nonblocking gap 확인 | `needs-formulation` | +| 2026-08-30 | `GATE3-FORM-001` | `passed` | Owner `passed`, document `ready-for-numerical-review`; Coordinator audit에서 required formulation sections 완비, requirement rows 24/24, upstream scope/sign/output 일치와 explicit Numerical Review handoff 확인 | `needs-numerical-review` | +| 2026-08-30 | `GATE4-NR-001` | `passed` | Owner reports aligned `pass-for-io-definition`; Coordinator audit에서 두 verdict/required sections, quantitative gates, exact artifact/row/component classification, precheck/common tolerance/immutability와 no final HDF5 projection 확인 | `needs-io-definition` | +| 2026-08-31 | `GATE5-IO-001` | `passed` | Owner `passed`, document `ready-for-implementation-planning`; Coordinator audit에서 required sections/grammar/ownership/validation/schema/reference projection 완비, trace 24/24, no new dataset/version와 no critical issue 확인 | `needs-implementation-plan` | +| 2026-08-31 | `GATE6-PLAN-001` | `passed` | Owner `passed`, document `draft-awaiting-user-approval`; Coordinator audit에서 7 Steps, TDD/commands/dependencies/24-of-24 trace, no phase/code mutation 확인. Initial `upstream-io-contract-mismatch`는 same-owner follow-up으로 multi-explicit-instance 지원과 committed source identity를 교정함. 이는 planning subgate 판정이며 Stage 6 implementation gate는 미통과 | `needs-user-decision` | +| 2026-09-01 | `GATE6-PLAN-APPROVAL` | `passed` | User explicitly approved the 7-Step draft, phase materialization, and implementation/verification execution; `--push` 금지 | `needs-implementation-plan` | +| 2026-09-01 | `GATE6-PHASE-001` | `pending` | 동일 Implementation Planning Agent의 phase materialization과 Coordinator audit 대기 | `needs-implementation-plan` | +| 2026-09-01 | `GATE6-PHASE-001` | `passed` | Owner `passed`; Coordinator audit에서 existing top index preservation, exact 7 pending slugs/files, Executor-readable paths, self-contained RED/GREEN/VERIFY와 exact reference immutability 확인 | `ready-for-implementation` | +| 2026-09-01 | `GATE6-IMPL-001` | `pending` | Exactly one Implementation Agent execution/evidence 대기 | `needs-implementation` | + +## 5. Risk, Blocker, and User-Decision Register + +- active_blockers: 없음 +- critical_user_questions: 없음 +- USER-DECISION-001: `resolved 2026-09-01`; 7-Step draft, phase materialization, Harness implementation/verification execution 승인. `--push`는 승인되지 않음. +- RISK-001: Element-based `*DLOAD` pressure와 surface-based `*DSLOAD` pressure의 sign/target 의미를 혼합하지 않는다. +- RISK-002: Nonlinear follower pressure의 current-surface force와 external tangent를 fixed-global `*CLOAD`와 혼합하지 않는다. +- RISK-003: Reference artifact 또는 공통 tolerance를 기능 통과를 위해 수정하지 않는다. +- RISK-004: Directly applicable public S4/S4R follower-pressure target 부재는 analytical/tangent/equilibrium suite와 exact stored case를 함께 사용해 보완하며, target을 발명하지 않는다. +- RISK-005: External pressure tangent는 generally nonsymmetric이므로 symmetrize하지 않으며 Numerical Review가 global special-case evidence와 `tau_J`/FD acceptance를 확정한다. +- RISK-006: Stored case의 S4/SPOS/positive `P` coverage 한계는 S4R, side/sign, objectivity와 tangent blocking internal tests로 보완한다. +- RISK-007: Input compatibility는 assembly-level direct/explicit-instance ELSET surface와 parameterless `DSLOAD P` exact subset뿐이며 part-level/implicit qualification/`DLOAD`를 추정 지원하지 않는다. +- adopted_default: 승인 범위 내 secondary detail은 Abaqus surface-pressure behavior와 repository convention을 evidence-backed default로 사용한다. + +## 6. Rework-Loop Control and Stop Condition + +- normalized_failure_attempts: `upstream-io-contract-mismatch` 1회, Gate 6 planning same-owner follow-up에서 교정 완료 +- automatic_rework_limit: 동일 normalized failure classification `2`회 +- current_attempt: `implementation` 1회 dispatch 준비; `implementation-planning` 1회 완료; phase materialization 1회 완료; `io-definition` 1회 완료; `numerical-reference-review` 1회 완료; `formulation-contract` 1회 완료; `research-evidence` 1회 완료; `requirements-baseline` 1회 완료 +- stop_condition: 동일 classification이 2회이면 자동 재작업을 중단하고 `needs-user-decision` 또는 `blocked`로 전환한다. + +## 7. Final Workflow Closure + +- closure_status: `pending` +- required_evidence: Gates 1–8 owner evidence와 `release.md`의 `ready-for-release` recommendation +- current_boundary: Gates 1–5와 Gate 6 planning/phase subgates `passed`; Stage 6 implementation `in-progress`; Gate 6 three-report evidence 전 Gate 7 금지. + +## 8. No-Change Assertion + +- source_code: 변경 없음 +- tests: 변경 없음 +- CMake: 변경 없음 +- reference_artifacts: 변경 없음 +- tolerance_policies: 변경 없음 +- phase_planning: `phases/index.json`에 pending entry append; `phases/shell-surface-pressure-load/index.json`과 `step1.md`–`step7.md` 생성 +- coordinator_change: `docs/shell-surface-pressure-load/coordination.md` 생성 및 Gates 1–5와 Gate 6 planning evidence 기록 +- specialist_change: Requirement Agent가 `requirements.md`, Research Agent가 `research.md`, Formulation Agent가 `formulation.md`, Numerical Review Agent가 `numerical-review.md`와 `reference-model.md`, I/O Definition Agent가 `io.md`, Implementation Planning Agent가 `implementation-plan.md`를 각각 생성함 diff --git a/docs/shell-surface-pressure-load/formulation.md b/docs/shell-surface-pressure-load/formulation.md new file mode 100644 index 0000000..bfac1b8 --- /dev/null +++ b/docs/shell-surface-pressure-load/formulation.md @@ -0,0 +1,749 @@ +# Shell Surface Pressure Load Formulation + +## 1. Metadata + +- feature_id: `shell-surface-pressure-load` +- source_requirement: `docs/shell-surface-pressure-load/requirements.md` +- source_research: `docs/shell-surface-pressure-load/research.md` +- source_requirement_range: `FESA-REQ-SHELL-PRESSURE-001`–`FESA-REQ-SHELL-PRESSURE-024` +- status: `ready-for-numerical-review` +- owner_agent: `formulation-agent` +- date: `2026-08-30` +- formulation_scope: S4/S4R source element의 `SPOS|SNEG` named element surface에 작용하는 uniform surface-based `DSLOAD P` +- evidence_boundary: `research.md`의 `CL-03`–`CL-10`, `CL-12`–`CL-15`와 binding project contracts + +이 문서는 FESA가 소유하는 압력 하중의 수학적·알고리즘 계약이다. Abaqus 문서는 승인된 +입력과 observable sign/follower behavior의 근거일 뿐이다. 이 문서는 Abaqus의 내부 shell +formulation, integration, stabilization, load-vector, pressure-load stiffness 또는 결과 생성 +절차와 FESA가 동등하다고 주장하지 않는다. + +## 2. Scope and Assumptions + +### 2.1 승인 범위 + +| 항목 | 계약 | +| --- | --- | +| analysis type | 단일 linear static 또는 승인된 full-Newton nonlinear static `NLGEOM=YES` | +| source elements | Abaqus source type `S4`, `S4R`; 둘 다 기존 FESA MITC4를 선택하되 source type/label은 보존 | +| load | `*SURFACE, TYPE=ELEMENT`의 single-sided `SPOS|SNEG` member에 uniform finite scalar `*DSLOAD P` | +| linear geometry | reference configuration | +| nonlinear geometry | trial/current configuration `x=X+u`; current-area follower pressure | +| material/section | 기존 MITC4 linear isotropic elastic shell material/section 그대로 | +| coordinates | geometry, pressure force, reaction, equilibrium은 global Cartesian | +| units | model-consistent; `p:[F/L^2]`, `u:[L]`, rotation `[1]`, force `[F]`, physical moment `[F L]` | + +Linear static은 small-displacement/small-rotation 해석이며 pressure geometry를 reference +configuration에 고정한다. Nonlinear static은 finite translation/rotation을 허용하는 +geometrically nonlinear 해석이며 trial/current midsurface geometry를 사용한다. Material +nonlinearity는 추가하지 않는다. + +### 2.2 제외와 기존 계약 보존 + +- `*DLOAD` element-face pressure, `P n`, spatially varying pressure, amplitude, user load, + edge/node/double-sided surface, 다른 element type과 다른 procedure는 이 formulation의 + 대상이 아니다. +- Surface offset, shell thickness face arm, thickness-side pressure correction과 distributed + pressure couple을 사용하지 않는다. 압력은 midsurface에 작용하는 force resultant만 만든다. +- S4/S4R source type은 같은 FESA MITC4 및 같은 pressure quadrature를 사용한다. `S4R`이라는 + source token은 FESA reduced pressure integration이나 별도 hourglass 경로를 선택하지 않는다. +- 기존 MITC4 strain, stress, material tangent, drilling stabilization과 result recovery는 + 변경하지 않는다. 압력은 material-independent external contribution이다. +- 새로운 pressure-only HDF5 dataset, integration-point pressure output 또는 nodal + extrapolation을 만들지 않는다. + +## 3. Primary Variables, Symbols, and DOFs + +### 3.1 Nodal variables and ordering + +Four-node element의 generalized coordinate는 + +\[ +\mathbf q_e= +[\mathbf u_1,\boldsymbol\theta_1, + \mathbf u_2,\boldsymbol\theta_2, + \mathbf u_3,\boldsymbol\theta_3, + \mathbf u_4,\boldsymbol\theta_4]^T\in\mathbb R^{24}, +\] + +이고 각 절점의 global 순서는 + +\[ +[UX,UY,UZ,URX,URY,URZ] +\] + +이다. `\mathbf u_i\in\mathbb R^3`의 단위는 `[L]`, +`\boldsymbol\theta_i\in\mathbb R^3`는 dimensionless finite-rotation coordinate다. +`\mathbf E_i\in\mathbb R^{3\times24}`를 `\mathbf E_i\mathbf q_e=\mathbf u_i`인 +translation extractor로 둔다. + +압력 geometry와 pressure generalized force는 오직 `UX/UY/UZ`에 의존한다. +`URX/URY/URZ`, shell director와 thickness offset은 pressure geometry에 들어가지 않는다. +따라서 pressure force의 rotational entries와 pressure tangent의 rotation row/column은 모두 +정확히 zero다. + +Global generalized coordinates는 stable full-DOF space에서 free set `q_f`와 prescribed +constrained set `q_c`로 분할한다. Pressure contribution은 이 분할 전에 full space에 +조립한다. 기존 essential-constraint policy가 `q_c`를 정하고, constrained residual은 +reaction, free residual은 equilibrium evidence다. + +### 3.2 Symbols and sign convention + +| symbol | meaning | dimension | +| --- | --- | --- | +| `(\xi,\eta)` | natural coordinates on `[-1,1]^2` | `[1]` | +| `N_i` | bilinear shape function | `[1]` | +| `\mathbf X_i`, `\mathbf x_i` | reference, current nodal position; `x_i=X_i+u_i` | `[L]` | +| `\mathbf g_\xi,\mathbf g_\eta` | covariant surface tangents in the chosen configuration | `[L]` | +| `\mathbf a=\mathbf g_\xi\times\mathbf g_\eta` | connectivity-positive oriented area vector per `d\xi d\eta` | `[L^2]` | +| `J_s=\|\mathbf a\|` | unsigned surface Jacobian | `[L^2]` | +| `s` | side multiplier: `+1` for `SPOS`, `-1` for `SNEG` | `[1]` | +| `p` | unscaled signed source `DSLOAD P` magnitude | `[F/L^2]` | +| `\lambda` | current analysis step load factor | `[1]` | +| `[\mathbf v]_\times` | skew matrix satisfying `[v]_\times w=v\times w` | same as `v` | + +Selected-side oriented area vector는 `\mathbf a_s=s\mathbf a`다. Positive `DSLOAD P`는 +selected normal 반대 방향이므로 natural-area force density는 + +\[ +d\mathbf f_p=-\lambda p\,s\,\mathbf a\,d\xi d\eta. \tag{1} +\] + +따라서 exact sign map은 다음과 같다. + +| side | selected normal | `p>0` force | `p<0` force | +| --- | --- | --- | --- | +| `SPOS` | connectivity-positive | `-\mathbf n` | `+\mathbf n` | +| `SNEG` | connectivity-negative | `+\mathbf n` | `-\mathbf n` | + +여기서 `\mathbf n=\mathbf a/\|\mathbf a\|`다. Magnitude에 absolute value를 취하지 않는다. +이 sign은 named surface의 surface-based `DSLOAD P` 계약이다. Element/element-set face label을 +쓰는 `DLOAD` sign rule을 가져오지 않는다. + +## 4. Strong Form and Boundary Conditions + +Reference body `\Omega_0`에 대한 일반적인 equilibrium strong form을 + +\[ +\operatorname{Div}\mathbf P+\mathbf B=\mathbf0 +\quad\text{in }\Omega_0, +\] +\[ +\mathbf u=\bar{\mathbf u}\quad\text{on }\Gamma_u, +\qquad +\mathbf P\mathbf N=\bar{\mathbf t}\quad\text{on }\Gamma_t +\] + +로 둔다. Shell reduction에서 selected shell face pressure는 midsurface external distributed +load로 나타낸다. 승인 pressure patch에서 spatial traction은 + +\[ +\mathbf t_p=-\lambda p\,\mathbf n_s, +\qquad \mathbf n_s=s\mathbf n. \tag{2} +\] + +여기서 `P`는 first Piola stress, `B`는 reference body force density, `N`은 reference outward +normal이고 `Gamma_u`, `Gamma_t`는 Dirichlet/Neumann boundary partition이다. Equation `(2)`는 +current-area spatial traction이다. Reference weak form에서 그 nominal pullback은 +`\bar t_0 dA=t_p da`를 만족해야 하며, 아래 oriented-area integral이 이 변환을 직접 포함한다. + +Linear path에서는 `(2)`의 direction과 area measure를 reference surface에서 평가한다. +Nonlinear path에서는 current surface에서 평가한다. 압력은 edge traction이나 nodal couple을 +추가하지 않으며, 기존 essential displacement/rotation constraints가 `\Gamma_u`를 정의한다. + +## 5. Weak or Variational Form + +Admissible test field `\delta\mathbf q`는 `\Gamma_u`에서 zero다. Equilibrium functional은 + +\[ +G(\mathbf q;\delta\mathbf q) +=\delta W_{int}(\mathbf q;\delta\mathbf q) +-\delta W_{ext}(\mathbf q;\delta\mathbf q)=0. \tag{3} +\] + +Integration by parts 뒤 body/edge natural terms와 selected pressure term이 external virtual +work를 이룬다. 이 feature가 추가하는 element pressure virtual work는 + +\[ +\delta W_{p,e} +=-\lambda p s\int_{-1}^{1}\int_{-1}^{1} +\delta\mathbf x_h(\xi,\eta)\cdot\mathbf a(\xi,\eta) +\,d\xi d\eta, \tag{4} +\] + +\[ +\delta\mathbf x_h=\sum_{i=1}^{4}N_i\,\delta\mathbf u_i. +\] + +Equation `(4)`는 같은 interpolation에 대해 work-equivalent nodal force를 정의한다 +(`research.md` `CL-06`). Rotational virtual coordinates에는 pressure virtual work가 없다. +Internal virtual work와 pressure-independent body/edge load는 기존 MITC4/procedure 계약을 +그대로 사용한다. + +## 6. Discretization + +### 6.1 Nodal layout and shape functions + +Connectivity order와 natural node coordinates는 + +| node `i` | `(\xi_i,\eta_i)` | +| --- | --- | +| 1 | `(-1,-1)` | +| 2 | `(+1,-1)` | +| 3 | `(+1,+1)` | +| 4 | `(-1,+1)` | + +이며 + +\[ +\begin{aligned} +N_1&=\tfrac14(1-\xi)(1-\eta),& +N_2&=\tfrac14(1+\xi)(1-\eta),\\ +N_3&=\tfrac14(1+\xi)(1+\eta),& +N_4&=\tfrac14(1-\xi)(1+\eta). +\end{aligned} \tag{5} +\] + +Natural derivatives are fixed as + +\[ +\begin{aligned} +N_{1,\xi}&=-\tfrac14(1-\eta),&N_{1,\eta}&=-\tfrac14(1-\xi),\\ +N_{2,\xi}&=+\tfrac14(1-\eta),&N_{2,\eta}&=-\tfrac14(1+\xi),\\ +N_{3,\xi}&=+\tfrac14(1+\eta),&N_{3,\eta}&=+\tfrac14(1+\xi),\\ +N_{4,\xi}&=-\tfrac14(1+\eta),&N_{4,\eta}&=+\tfrac14(1-\xi). +\end{aligned} \tag{5a} +\] + +필수 interpolation checks는 + +\[ +\sum_{i=1}^{4}N_i(\xi,\eta)=1, +\qquad N_i(\xi_j,\eta_j)=\delta_{ij} \tag{6} +\] + +이다. `(6)`은 constant translation과 nodal interpolation을 보장한다. + +### 6.2 Isoparametric surface mapping + +Linear/reference mapping은 + +\[ +\mathbf X_h=\sum_iN_i\mathbf X_i, +\quad +\mathbf G_\xi=\sum_iN_{i,\xi}\mathbf X_i, +\quad +\mathbf G_\eta=\sum_iN_{i,\eta}\mathbf X_i, +\quad +\mathbf A=\mathbf G_\xi\times\mathbf G_\eta. \tag{7} +\] + +Nonlinear/current mapping은 + +\[ +\mathbf x_h=\sum_iN_i(\mathbf X_i+\mathbf u_i), +\quad +\mathbf g_\xi=\sum_iN_{i,\xi}\mathbf x_i, +\quad +\mathbf g_\eta=\sum_iN_{i,\eta}\mathbf x_i, +\quad +\mathbf a=\mathbf g_\xi\times\mathbf g_\eta. \tag{8} +\] + +Load integration은 natural derivative와 oriented area vector를 직접 사용하므로 physical +in-plane derivative transform이나 `2x2` inverse Jacobian이 필요하지 않다. Material strain +`B` matrix를 계산하는 기존 MITC4 kernel의 derivative transform은 별도이며 변경하지 않는다. + +## 7. Kinematics + +Pressure load kinematic operator는 `(7)` 또는 `(8)`의 midsurface positional mapping이다. +Linear path는 `\mathbf A`를 고정하며 candidate displacement가 pressure direction이나 area를 +바꾸지 않는다. Nonlinear path는 trial `\mathbf x=\mathbf X+\mathbf u`를 사용한다. + +Current area vector의 directional variation은 임의의 translational direction +`\Delta\mathbf u_j`에 대해 + +\[ +D\mathbf a[\Delta\mathbf u] +=D\mathbf g_\xi[\Delta\mathbf u]\times\mathbf g_\eta ++\mathbf g_\xi\times D\mathbf g_\eta[\Delta\mathbf u], \tag{9} +\] + +\[ +D\mathbf a[\Delta\mathbf u] +=\sum_{j=1}^{4} +\left(-N_{j,\xi}[\mathbf g_\eta]_\times ++N_{j,\eta}[\mathbf g_\xi]_\times\right) +\Delta\mathbf u_j. \tag{10} +\] + +Pressure는 strain, deformation gradient 또는 director strain을 직접 계산하지 않는다. +Geometrically linear/finite-rotation MITC4의 strain-displacement operator, strain measure와 +internal tangent는 기존 formulation 계약을 따른다. 이 문서가 소유하는 새로운 kinematic +derivative는 `(9)`–`(10)`뿐이다. + +Objectivity invariants는 다음과 같다. + +- Uniform translation `x_i'=x_i+c`에서 tangents, area vector, nodal pressure forces는 변하지 않는다. +- Proper rigid rotation `x_i'=Qx_i+c`, `Q^TQ=I`, `det Q=+1`에서 + `a'=Qa`, `f_i'=Qf_i`, `K_{ij}^{uu\prime}=QK_{ij}^{uu}Q^T`다. +- Homogeneous in-plane area change는 current vector area를 바꾸므로, 일정 scalar pressure라도 + nonlinear total resultant magnitude가 current area에 따라 바뀔 수 있다. + +## 8. Constitutive Contract + +Existing MITC4 linear isotropic shell constitutive relation을 추상적으로 + +\[ +\mathbf s=\mathbf D\mathbf e, +\qquad \delta\mathbf e=\mathbf B_{MITC4}\delta\mathbf q_e, +\qquad +\delta W_{int,e}=\int_{\Omega_{0,e}}\delta\mathbf e^T\mathbf s\,d\Omega_0, +\qquad +\mathbf f_e^{int}=\int_{\Omega_{0,e}}\mathbf B_{MITC4}^T\mathbf s\,d\Omega_0 +\] + +로 둔다. `\mathbf e`, `\mathbf s`, `\mathbf D`, MITC shear interpolation, drilling +stabilization, existing material state와 internal consistent tangent는 이 feature가 변경하지 +않는다. Pressure force와 external tangent는 `\mathbf D`, thickness, stress와 material state에 +의존하지 않는다. 새 material state variable, mass 또는 damping contribution은 없다. + +## 9. Element Equations + +### 9.1 Consistent nodal pressure force + +Equation `(4)`와 `(5)`로부터 node `i`의 translational force block은 + +\[ +\mathbf f_{p,i}^{u} +=-\lambda p s\int_{-1}^{1}\int_{-1}^{1} +N_i\mathbf a_c\,d\xi d\eta\in\mathbb R^3, \tag{11} +\] + +여기서 linear path는 `a_c=A`, nonlinear path는 `a_c=a`다. Element generalized vector는 + +\[ +\mathbf f_{p,e}^{ext} +=\sum_{i=1}^{4}\mathbf E_i^T\mathbf f_{p,i}^{u} +\in\mathbb R^{24}. \tag{12} +\] + +각 node block은 `[f_x,f_y,f_z,0,0,0]`이며 translation은 `[F]`, zero rotation entry의 +generalized unit은 `[F L]`이다. `p=0`이면 force와 tangent는 exact zero지만 surface/model +validation을 생략하지 않는다. `\lambda`는 unscaled source `p`에 식 `(11)`에서 정확히 한 번만 +곱한다. + +### 9.2 Linear path + +Linear static에서는 + +\[ +\mathbf f_{p,e}^{lin} +=-\lambda p s\int N_i\mathbf A\,d\xi d\eta, +\qquad +\mathbf K_{p,e}^{ext,lin} +=\frac{\partial\mathbf f_{p,e}^{lin}}{\partial\mathbf q_e} +=\mathbf0_{24\times24}. \tag{13} +\] + +따라서 pressure는 reference-area/reference-normal constant load이고 candidate displacement와 +독립이다. + +### 9.3 Nonlinear external tangent + +`[v]_\times w=v\times w` 정의와 `(10)`을 `(11)`에 대입하면 translation-to-translation +`3x3` block은 + +\[ +\boxed{ +\mathbf K_{p,ij}^{ext,uu} +=\frac{\partial\mathbf f_{p,i}^{u}}{\partial\mathbf u_j} +=\lambda p s\int_{-1}^{1}\int_{-1}^{1} +N_i\left( +N_{j,\xi}[\mathbf g_\eta]_\times +-N_{j,\eta}[\mathbf g_\xi]_\times +\right)d\xi d\eta +}\in\mathbb R^{3\times3}. \tag{14} +\] + +동일 식의 implementable generalized form은 + +\[ +\mathbf K_{p,e}^{ext} +=\sum_{i=1}^{4}\sum_{j=1}^{4} +\mathbf E_i^T\mathbf K_{p,ij}^{ext,uu}\mathbf E_j +\in\mathbb R^{24\times24}. \tag{15} +\] + +모든 rotation row와 column은 exact zero다. Nonzero block unit은 `[F/L]`이다. +`K_{p,e}^{ext}`는 일반적으로 nonsymmetric이며 조용히 symmetrize하지 않는다. 특정 closed +loaded boundary에서 global assembly가 대칭을 보일 수 있으나 element operator나 solver +contract의 가정으로 사용하지 않는다. + +### 9.4 Residual and Newton tangent sign + +FESA nonlinear procedure의 binding convention은 + +\[ +\mathbf r=\mathbf f^{int}-\mathbf f^{ext}, +\qquad +\mathbf K=\frac{\partial\mathbf r}{\partial\mathbf q} +=\mathbf K^{int}-\mathbf K^{ext}, +\qquad +\mathbf K\Delta\mathbf q=-\mathbf r. \tag{16} +\] + +따라서 `(14)`–`(15)`는 `f_ext`의 양의 directional derivative이고 residual tangent에는 +`-K_ext`로 들어간다. Linear static도 같은 equilibrium sign으로 +`r=K_int q-f_ext`다. 이 구분은 pressure force와 tangent에 같은 sign 오류를 넣어 finite +difference만 통과하는 common-mode failure를 방지한다. + +Mass와 damping은 이 static load feature에 없다. + +## 10. Mapping, Numerical Integration, and Geometry Validity + +### 10.1 Pressure quadrature + +S4와 S4R source type 모두 pressure force와 pressure tangent에 동일한 tensor-product +`2x2` Gauss rule을 사용한다. + +\[ +g=1/\sqrt3, +\quad +(\xi_q,\eta_q)\in\{(-g,-g),(+g,-g),(+g,+g),(-g,+g)\}, +\quad w_q=1. \tag{17} +\] + +Force와 tangent는 반드시 같은 point order와 weight를 사용한다. 실제 계산식은 + +\[ +\mathbf f_{p,i}^{u} +=-\lambda p s\sum_{q=1}^{4}w_qN_i(q)\mathbf a_c(q), \tag{18} +\] + +\[ +\mathbf K_{p,ij}^{ext,uu} +=\lambda p s\sum_{q=1}^{4}w_qN_i(q) +\left(N_{j,\xi}(q)[\mathbf g_\eta(q)]_\times +-N_{j,\eta}(q)[\mathbf g_\xi(q)]_\times\right). \tag{19} +\] + +Bilinear mapping에서 `a(\xi,\eta)`는 `\xi,\eta`의 affine vector이고, `(18)`과 `(19)`의 +각 scalar component는 각 natural coordinate에 대해 차수가 최대 2다. 따라서 `2x2` rule은 +이 discrete uniform-pressure force와 그 exact derivative를 적분한다. 이 선택은 +work-equivalence, force/tangent consistency와 단순성을 위한 FESA-owned 결정이며 Abaqus +S4/S4R 내부 integration과의 동등성을 뜻하지 않는다. + +### 10.2 Scale-aware surface validity contract + +Reference validation에는 `y_i=X_i`, current trial validation에는 `y_i=x_i`를 사용한다. +각 configuration에서 + +\[ +\ell_e=\max_{1\le i\tau_J`여야 한다. +4. Check set + `C={(-1,-1),(+1,-1),(+1,+1),(-1,+1)}\cup{four Gauss points}`의 모든 point `z`에서 + + \[ + j_s(z)=\frac{\mathbf a(z)\cdot\bar{\mathbf n}}{\ell_e^2}>\tau_J \tag{21} + \] + + 이어야 한다. +5. Four Gauss points 각각에서 `J_s=\|a\|`, `N_i`, derivatives, force integrand와 nonlinear + tangent blocks가 finite여야 한다. Accumulated element vector/matrix도 finite여야 한다. + +Bilinear surface의 area vector는 natural coordinates에 affine이므로, corner에서 `(21)`의 +signed projection이 양수이면 square 내부 전체에서 같은 orientation을 유지한다. Gauss-point +checks는 실제 적분 위치의 scale과 finite 값을 추가로 보장한다. Mean cancellation 또는 +corner/point sign loss는 fold, local inversion 또는 singular mapping으로 분류해 fail closed한다. + +Connectivity order는 orientation의 유일한 source이며 geometry validation이 node를 reorder, +normal flip 또는 absolute-area repair하지 않는다. `SPOS/SNEG`의 `s`도 step 동안 고정한다. +Current normal을 reference global normal과 dot-product 비교하지 않는다. 그러한 비교는 valid +large rigid rotation을 inversion으로 잘못 거부한다. Coherent proper rigid rotation은 valid이고, +local regularity/orientation loss만 `(20)`–`(21)`로 거부한다. + +Reference configuration은 analysis 시작 전에 검사한다. Nonlinear current configuration은 +매 Newton trial에서 force/tangent 평가 전에 검사한다. 어느 검사든 실패하면 해당 candidate의 +pressure contribution, state와 final output을 commit하지 않는다. + +## 11. Deterministic Assembly and Failure Contract + +### 11.1 Source/facet identity and exact-once semantics + +- Resolved facet identity는 stable source `(instance, element label, source element type, side)`를 + 보존한다. S4/S4R은 같은 numerical kernel을 선택해도 source identity에서 합치지 않는다. +- 한 named surface 안의 동일 facet membership은 unique inventory에 정확히 한 번 존재한다. + 같은 element의 conflicting side/membership은 ambiguity로 fail closed한다. +- 각각의 valid `DSLOAD P` source record는 distinct load identity다. 한 surface를 가리키는 + 여러 valid load record가 있으면 각 record를 source order에서 한 번씩 적용하고 합한다. + 서로 다른 load record를 deduplicate하지 않는다. +- Local contribution identity는 최소한 `(load source order, resolved facet order, instance, + element label, side, local row[, local column])`을 포함한다. + +Element-local vector와 tangent contribution을 먼저 완성·검증하고, 위 stable identity 순서로 +full generalized space에 고정 reduction한다. Parallel producer는 global vector/matrix를 직접 +갱신하지 않는다. Full-space assembly가 끝난 뒤에만 stable free/constrained projection을 +적용한다. 이 계약은 surface declaration order, thread schedule과 internal index가 physical +source identity나 floating reduction order를 바꾸지 않게 한다. + +### 11.2 Fail-closed conditions + +다음은 pressure contribution 없이 deterministic non-success로 끝나야 한다. + +- unsupported surface/load/side/element/procedure, unresolved·empty·ambiguous target 또는 + incompatible duplicate; +- nonfinite `p`, `\lambda`, nodal coordinate, tangent, area vector, integrand, element/global force + 또는 tangent; +- reference 또는 current geometry가 `(20)`–`(21)`을 위반함; +- local/generalized dimension 또는 full-DOF scatter identity 불일치; +- stable reduction 결과가 nonfinite임. + +Input/mapping failure는 file/line/keyword/surface/load/facet source identity를 가능한 범위에서 +보존하고, numerical failure는 configuration, load record와 facet identity를 보존한다. Exact +diagnostic schema/code는 Stage 5 I/O가 소유하지만 failure category, source order와 atomicity는 +여기서 바뀌지 않는다. 실패한 candidate는 accepted state나 정상 final HDF5로 publish하지 않는다. + +## 12. Output Recovery + +압력 효과는 기존 authoritative HDF5 결과에서만 관측한다. + +| quantity | location / identity | pressure contract | +| --- | --- | --- | +| displacement/rotation | nodal, global `[UX,UY,UZ,URX,URY,URZ]` | 기존 accepted frame output; pressure solution effect 포함 | +| full residual/reaction | nodal full DOF, stable source node identity | `r=f_int-f_ext`; constrained entry는 reaction, free entry는 equilibrium residual | +| global equilibrium | accepted nonlinear factor-one frame, global origin | applied pressure force와 current `X+u` arm을 사용한 applied-plus-reaction force/moment balance | +| element force/resultant | 기존 MITC4 element/output locations | internal recovery unchanged; pressure-only row 없음 | +| generalized strain/stress | 기존 MITC4 integration point/section locations | material response를 기존 방식으로 복구; pressure dataset/extrapolation 없음 | + +Pressure generalized vector의 rotational nodal entries는 zero지만 physical global moment는 +current/reference force arm으로 계산한다. Origin `O`에 대한 applied pressure moment는 + +\[ +\mathbf M_O^p +=\sum_i(\mathbf x_i-\mathbf O)\times\mathbf f_{p,i}^{u} +=-\lambda p s\sum_qw_q +(\mathbf x_h(q)-\mathbf O)\times\mathbf a(q) \tag{22} +\] + +이다. Linear check에서는 `x` 대신 `X`, nonlinear accepted equilibrium에서는 current `x`를 +사용한다. 별도 pressure nodal moment를 더하지 않는다. + +External reference disposition은 변경하지 않는다: stored displacement `U1/U2/U3`는 blocking, +`UR1/UR2/UR3`는 warning-only, reaction CSV는 review-only, stress CSV는 excluded다. External +comparison만 `docs/TOLERANCE.md`를 사용하며 analytical/tangent/geometry tolerance를 대신하지 않는다. + +## 13. Algorithm Pseudocode + +```text +INPUT: approved step load factor lambda, ordered DSLOAD records, + ordered unique surface facets, full nodal generalized trial q + +validate procedure, finite lambda, load records, target identity and side + +for load_record in stable source order: + p = unscaled signed uniform magnitude + validate p is finite + + for facet in stable resolved order: + require source type S4 or S4R and side SPOS or SNEG + preserve (instance, element label, source type, side) + s = +1 for SPOS, -1 for SNEG + + if linear static: + y_i = X_i + else if nonlinear static: + y_i = X_i + u_i from the current trial + + evaluate geometry scale and mean oriented area + validate reference/current geometry at four corners and four Gauss points + + initialize f_e[24] = 0 + initialize K_ext_e[24,24] = 0 + + for q in fixed 2x2 Gauss order: + evaluate N_i, N_i,xi, N_i,eta + evaluate g_xi, g_eta, a = g_xi cross g_eta + validate every value and integrand is finite + + for i = 1..4: + f_e.translation(i) += -lambda*p*s*w_q*N_i*a + + if nonlinear static: + for j = 1..4: + block = lambda*p*s*w_q*N_i * + (N_j,xi*skew(g_eta) + - N_j,eta*skew(g_xi)) + K_ext_e.translation(i),translation(j) += block + + require all rotation entries/rows/columns remain exact zero + validate f_e and K_ext_e finite + emit an element-local contribution with stable load/facet identity + +stable-reduce all local pressure contributions into full-space f_ext and K_ext +combine with other approved loads in stable source order + +linear: + solve existing partitioned linear equilibrium using reference f_ext + K_ext_pressure = 0 + +nonlinear trial: + assemble existing MITC4 f_int and K_int + r = f_int - f_ext + K = K_int - K_ext + partition only after full-space assembly + solve K_ff * Delta_q_f = -r_f + evaluate existing convergence gates + +on accepted state only: + recover displacement, full residual/reaction, global equilibrium, + and existing MITC4 results + atomically publish existing HDF5 contract +``` + +## 14. Verification Identities and Oracles + +### 14.1 Analytical and algebraic identities + +1. **Partition/Kronecker:** `(6)` must pass exactly up to the Numerical Review-approved arithmetic + check tolerance. +2. **Resultant:** consistent assembly gives + + \[ + \sum_i\mathbf f_{p,i}^{u} + =-\lambda p s\sum_qw_q\mathbf a_c(q). \tag{23} + \] + + Flat patch에서는 right side가 `-lambda*p*s*A*n`이다. +3. **Moment:** equation `(22)` must hold using the same quadrature and declared origin. +4. **Sign reversal:** `SPOS↔SNEG` 또는 `p↔-p`는 force, tangent와 applied moment의 부호를 + 각각 정확히 반전한다. 두 번 반전하면 원래 부호다. +5. **Load factor:** fixed geometry에서 `lambda={0,0.5,1}` force/tangent는 각각 exact + proportional path를 따른다. Factor는 다른 layer에서 다시 곱하지 않는다. +6. **Rigid motion:** translation/rotation objectivity와 tangent covariance는 §7을 만족한다. +7. **Rotation-only tangent direction:** pressure force가 nodal rotations에 의존하지 않으므로 + rotation-only direction `d_theta`에 대해 `K_ext d_theta=0` exactly다. + +### 14.2 Directional tangent oracle + +Nondegenerate distorted current patch, both source types, both sides와 positive/negative pressure에 +대해 translation direction `d`를 사용하여 + +\[ +\mathbf d_{FD}(\varepsilon) +=\frac{\mathbf f^{ext}(\mathbf u+\varepsilon\mathbf d) +-\mathbf f^{ext}(\mathbf u-\varepsilon\mathbf d)}{2\varepsilon} +\quad\text{and}\quad +\mathbf d_A=\mathbf K^{ext}(\mathbf u)\mathbf d \tag{24} +\] + +를 비교한다. 두 perturbed geometry 모두 §10.2를 만족해야 한다. `epsilon`, direction scaling, +force scale와 norm criterion은 Numerical Review가 dimensionless rule로 확정한다. Residual +tangent check는 `(16)`에 따라 `-K_ext d`와 비교한다. + +### 14.3 Assembly, solution, and reference oracles + +- Flat/distorted S4와 S4R patch에서 resultant, moment, reaction, side/sign reversal을 검증한다. +- 동일 geometry의 single/multi-element mesh와 shuffled declaration/member order에서 force/moment + invariant와 stable reduction/diagnostic order를 검증한다. +- Fully constrained patch에서 constrained reaction은 applied pressure와 equal-and-opposite이며, + mixed constraint에서는 constrained reaction과 free residual을 분리한다. +- Nonlinear accepted factor-one에서 applied-plus-constrained-reaction global force와 moment의 + normalized error는 각각 `<=1e-8`이고 accepted free residual은 기존 convergence gate를 통과한다. +- Exact stored input/CSV는 current path/name 그대로 read-only로 사용한다. External displacement + agreement는 sign, tangent와 equilibrium unit checks를 대체하지 않는다. + +## 15. Numerical Risks + +| risk | formulation consequence / required evidence | +| --- | --- | +| rigid body modes | Pressure는 support를 만들지 않는다. Unconstrained linear patch의 six rigid-body modes를 regularization으로 숨기지 않는다. | +| patch test | Flat/distorted constant-pressure resultant와 moment, mesh subdivision invariant를 검사한다. | +| tangent symmetry | Element `K_ext`는 일반적으로 nonsymmetric이다. Symmetrization 금지; full unsymmetric solver path를 유지한다. | +| positive definiteness | `K_int-K_ext`는 follower loading에서 positive definite일 필요가 없다. Unsupported fallback/regularization으로 failure를 숨기지 않는다. | +| hourglass | Pressure는 S4/S4R 모두 2x2로 적분하므로 pressure under-integration mode를 만들지 않는다. 기존 MITC4 drilling/hourglass 정책은 변경하지 않는다. | +| shear locking | Existing MITC4 internal kinematics의 위험이며 pressure interpolation을 바꾸는 이유가 아니다. Thin-shell verification에서 분리 관찰한다. | +| volumetric locking | Shell pressure load kernel에는 volumetric constitutive mode가 없어 직접 해당하지 않는다. 기존 material contract를 확장하지 않는다. | +| distortion / warpage | Bilinear tangents와 vector area를 pointwise 사용하고 §10.2의 dimensionless check로 fold/collapse를 거부한다. | +| singular Jacobian | `J_s`, signed projected area 또는 mean area scale이 threshold를 통과하지 못하면 force/tangent 계산 전에 실패한다. | +| sign/common-mode error | Analytical sign/reaction oracle를 tangent finite difference와 함께 사용한다. FD만으로 force+tangent 공통 sign 오류를 승인하지 않는다. | +| source duplication/order | Unique facet와 distinct load-record exact-once semantics, stable full-space reduction을 별도로 검사한다. | +| nonfinite propagation | 매 geometry/integration/contribution/reduction boundary에서 finite를 확인하고 accepted state/output을 보존한다. | + +## 16. Requirement Traceability + +| requirement | formulation disposition / verification evidence | +| --- | --- | +| `FESA-REQ-SHELL-PRESSURE-001` | §2, §3 sign/scope; exact syntax mapping은 Stage 5 I/O, formulation은 `DSLOAD`와 `DLOAD`를 분리 | +| `FESA-REQ-SHELL-PRESSURE-002` | §3 `p:[F/L^2]`, signed finite scalar; §9 exact-once scaling | +| `FESA-REQ-SHELL-PRESSURE-003` | §11 stable unique facet identity/order | +| `FESA-REQ-SHELL-PRESSURE-004` | §2 S4/S4R→existing MITC4, source identity retained, only SPOS/SNEG | +| `FESA-REQ-SHELL-PRESSURE-005` | equations `(1)`, `(11)` and §14 sign-reversal oracle | +| `FESA-REQ-SHELL-PRESSURE-006` | connectivity-positive `a`, side multiplier `s`, fixed orientation rule §10.2 | +| `FESA-REQ-SHELL-PRESSURE-007` | equations `(7)`, `(13)`; reference force and zero pressure tangent | +| `FESA-REQ-SHELL-PRESSURE-008` | equations `(8)`, `(11)`; current vector area and §7 objectivity | +| `FESA-REQ-SHELL-PRESSURE-009` | exact derivative `(9)`–`(15)`, residual sign `(16)`, FD oracle `(24)` | +| `FESA-REQ-SHELL-PRESSURE-010` | `lambda` occurs once in `(11)`, `(14)`; proportional oracle §14.1 | +| `FESA-REQ-SHELL-PRESSURE-011` | §11 local contribution then stable full-space assembly before projection | +| `FESA-REQ-SHELL-PRESSURE-012` | residual/reaction sign `(16)`, §12 recovery and equilibrium oracle | +| `FESA-REQ-SHELL-PRESSURE-013` | §11 stable identity, fixed quadrature/reduction/result/diagnostic order | +| `FESA-REQ-SHELL-PRESSURE-014` | §2 exclusions and §11.2 unsupported variant fail-closed handoff | +| `FESA-REQ-SHELL-PRESSURE-015` | §11 unique resolution, ambiguity/empty/conflicting membership failure | +| `FESA-REQ-SHELL-PRESSURE-016` | §10.2 configuration checks and §11.2 procedure/nonfinite/geometry failure | +| `FESA-REQ-SHELL-PRESSURE-017` | §11.2 stable diagnostic identity and no failed state/output commit | +| `FESA-REQ-SHELL-PRESSURE-018` | §2.2, §12 existing HDF5 authority; no new pressure dataset | +| `FESA-REQ-SHELL-PRESSURE-019` | §12 existing nodal/reaction/equilibrium/element result chain | +| `FESA-REQ-SHELL-PRESSURE-020` | §14 flat/distorted S4/S4R sign/resultant/reaction/mesh-order suite | +| `FESA-REQ-SHELL-PRESSURE-021` | §7 objectivity, `(14)`/`(24)` tangent, §14.3 residual/global balance | +| `FESA-REQ-SHELL-PRESSURE-022` | §14.3 exact stored path/name read-only contract retained | +| `FESA-REQ-SHELL-PRESSURE-023` | §12 U blocking/UR warning-only and deterministic source mapping retained | +| `FESA-REQ-SHELL-PRESSURE-024` | §12 reaction CSV review-only, stress CSV excluded; internal equilibrium remains blocking | + +Coverage: normative IDs `24`, covered IDs `24`, formulation trace gaps `0`. + +## 17. Open Issues and Downstream Handoff + +### 17.1 Numerical Review-owned open issues + +| issue_id | exact decision required | constraint | +| --- | --- | --- | +| `FORM-NR-01` | §10.2의 single dimensionless `tau_J` 최종 수치 | chord scale `ell_e`, mean/corner/Gauss rules를 유지; `max(1,...)`, absolute floor, clamp 금지 | +| `FORM-NR-02` | `(24)`의 dimensionless perturbation scaling, vector norm와 acceptance tolerance | centered FD, valid perturbed geometry와 both force/residual sign checks 유지 | +| `FORM-NR-03` | analytical resultant/moment, rigid-motion objectivity와 shape-function arithmetic tolerance | external `docs/TOLERANCE.md`로 대체하지 않고 model scale을 명시 | +| `FORM-NR-04` | element/global pressure tangent symmetry evidence 확인 | `(14)`를 기준으로 검토하며 symmetrization 또는 Abaqus internal assumption 도입 금지 | +| `FORM-NR-05` | 직접 적용 가능한 public S4/S4R follower benchmark 부재의 evidence disposition | analytical suite와 exact stored case를 사용하고 target을 발명하지 않음 | + +이 항목들은 승인 physics, sign, supported scope, HDF5 authority, stored reference disposition 또는 +external tolerance를 바꿀 수 없다. Critical user question은 없다. + +### 17.2 Handoff evidence + +Numerical Review Agent는 Coordinator를 통해 다음을 독립 검토해야 한다. + +- Equation `(11)`의 selected-side/pressure sign과 `(14)`의 skew/cross-product sign; +- `r=f_int-f_ext`, `K=K_int-K_ext` residual convention과 nonsymmetric assembly; +- S4/S4R 공통 `2x2` quadrature가 force/tangent에 동일하게 쓰이고 discrete integrand를 + 정확히 적분한다는 polynomial-degree argument; +- §10.2의 reference/current dimensionless regularity 및 fold/inversion rule; +- resultant, moment, rigid-motion, side/sign, FD tangent, reaction/free residual와 global balance + oracle; +- 24개 requirement trace와 output/reference disposition. + +이 문서는 Numerical Review에 충분한 수학적 계약을 제공하지만 numerical approval을 +의미하지 않는다. Parser/I/O schema, C++ API/file ownership, implementation, reference solver +execution과 Gate 4 decision은 수행하지 않았다. diff --git a/docs/shell-surface-pressure-load/implementation-plan.md b/docs/shell-surface-pressure-load/implementation-plan.md new file mode 100644 index 0000000..f09ac62 --- /dev/null +++ b/docs/shell-surface-pressure-load/implementation-plan.md @@ -0,0 +1,818 @@ +# Shell Surface Pressure Load 구현 계획 + +## 1. Metadata + +- `feature_id`: `shell-surface-pressure-load` +- `status`: `draft-awaiting-user-approval` +- `owner_agent`: `implementation-planning-agent` +- `date`: `2026-08-31` +- `source_requirement`: `docs/shell-surface-pressure-load/requirements.md` +- `source_research`: `docs/shell-surface-pressure-load/research.md` +- `source_formulation`: `docs/shell-surface-pressure-load/formulation.md` +- `source_numerical_review`: `docs/shell-surface-pressure-load/numerical-review.md` +- `source_io_definition`: `docs/shell-surface-pressure-load/io.md` +- `source_reference_models`: `docs/shell-surface-pressure-load/reference-model.md` +- `source_coordination_gate`: `docs/shell-surface-pressure-load/coordination.md` +- `proposed_phase_slug`: `shell-surface-pressure-load` +- `proposed_task_name`: `shell-surface-pressure-load` +- `authoritative_output`: input lexical sibling `_results.h5` +- `approval_hard_stop`: 이 문서는 승인용 Step 초안이다. 사용자 승인 전에는 `phases/index.json`, `phases/shell-surface-pressure-load/index.json`, `phases/shell-surface-pressure-load/stepN.md`를 생성하거나 수정하지 않는다. +- `execution_hard_stop`: Step 초안 또는 향후 phase 파일 승인은 Harness 실행 권한이 아니다. `scripts/execute.py`는 별도의 명시적 사용자 실행 요청이 있을 때만 Harness Executor가 실행한다. +- `executor_policy`: 승인 후에도 Step 선택, branch/commit, 상태·시각 기록, Stop 검증과 실행 report는 Harness Executor 소유다. 이 계획은 수동 `git commit`, 일반 sub-agent 실행 또는 대체 executor를 제안하지 않는다. + +## 2. Goal, Architecture, Tech Stack, Spec + +### Goal + +승인된 Abaqus `.inp` subset의 assembly-level `*SURFACE, TYPE=ELEMENT`와 single-static-step `*DSLOAD P`를 Domain semantic model, MITC4 pressure evaluator, 선형/비선형 full-space assembly, 기존 HDF5 결과 경로와 read-only reference comparison까지 끊김 없이 연결한다. 구현은 각 Step에서 반드시 테스트를 먼저 작성하고 실제 실패를 관찰한 뒤 최소 구현과 집중/전체 검증을 수행한다. + +### Architecture + +- `AbaqusInputReader`는 byte-level lexical contract와 `KeywordBlock`/`DataLine` source location을 소유한다. +- `DomainMappingContext`, `TopologyMapper`, 새 candidate `SurfaceDefinitionMapper`, `StepDefinitionMapper`, `DomainBuilder`가 raw input을 완전한 semantic candidate로 만든 뒤 한 번만 `Domain::Create`에 commit한다. +- `Domain`은 immutable ordered surface/facet inventory를, `StepDefinition`은 additive pressure records를 소유한다. `AnalysisModel`은 이를 복사하지 않는 active-step view만 제공하고 Domain이 더 오래 살아야 한다. +- 새 pressure evaluator는 parser, analysis procedure, HDF5, MKL/TBB에 의존하지 않는 solver-core 함수다. element-local `24 x 1` force와 `24 x 24` external tangent candidate를 반환한다. +- 새 surface-pressure assembler는 immutable Domain identity, `DofManager`, trial generalized coordinates와 `ParallelFor`를 받아 element-local candidate를 stable source order로 reduction한다. worker는 global vector/CSR을 직접 갱신하지 않는다. +- 선형 procedure는 reference-configuration pressure를 기존 CLOAD와 합쳐 full-space external load에 한 번만 반영하고, nonlinear procedure는 current-configuration follower force와 generally nonsymmetric external tangent를 같은 trial에서 평가한다. +- `Hdf5ResultsWriter` schema `0`과 `NonlinearHdf5ResultsWriter` schema `1`은 변경하지 않는다. 새 pressure dataset, schema/version/CLI option을 추가하지 않는다. +- reference utility는 FESA가 생성한 schema-1 factor-one HDF5와 exact stored displacement CSV만 비교한다. Abaqus를 실행하지 않으며 stored input/CSV를 수정하지 않는다. + +### Tech Stack + +- C++17, MSVC x64 Debug, CMake, CTest, GoogleTest +- Intel oneAPI MKL PARDISO: linear SPD path는 기존 `MklPardisoSolver`, nonlinear full-CSR unsymmetric path는 기존 `MklPardisoTangentSolver`와 `mtype=11` +- Intel oneAPI TBB behind `ParallelFor` +- HDF5 behind existing writers/self-check/atomic-finalization boundaries +- Python Harness는 phase orchestration용이며 이 기능이 Harness/Python 코드를 변경하지 않으므로 Python test 추가는 없다. + +### Binding Spec + +- 입력·진단·internal model·HDF5·comparison mapping은 `io.md` §§2–10이 우선한다. +- force/tangent, sign, configuration, integration, geometry validity와 deterministic assembly는 `formulation.md` §§6, 9–11, 13–14가 우선한다. +- analytical, finite-difference, objectivity, equilibrium, reference acceptance threshold는 `numerical-review.md` §6과 `docs/TOLERANCE.md`가 우선한다. +- exact reference paths와 dispositions는 `reference-model.md` §§3–8이 우선한다. +- 다른 solver 내부 알고리즘과의 동등성을 주장하지 않는다. Abaqus 결과는 승인된 외부 수치 reference일 뿐이다. + +## 3. Readiness Check + +| input | upstream status / gate evidence | planning disposition | +| --- | --- | --- | +| `requirements.md` | 문서 자체는 `draft-for-coordinator-gate-review`; Coordinator가 Gate 1을 통과시켰고 normative must IDs `001`–`024`가 완결 | binding | +| `research.md` | 문서 자체는 `draft-for-coordinator-gate-review`; Coordinator gate 통과 | binding evidence | +| `formulation.md` | `ready-for-numerical-review` | binding math handoff | +| `numerical-review.md` | `pass-for-io-definition` | binding numerical/reference readiness | +| `reference-model.md` | `pass-for-io-definition` | binding artifact contract | +| `io.md` | `ready-for-implementation-planning` | binding parser/model/HDF5/comparator contract | +| `coordination.md` | Gate 5 `passed`; document `ready-for-implementation-planning` | planning authorized | + +필수 comparison artifacts는 존재하며 경로·hash·cardinality가 upstream에서 고정되었다. 필수 파일은 `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure.inp`와 `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure displacements.csv` 두 개다. reaction CSV는 존재 여부와 값이 verdict를 바꾸지 않는 review-only inventory이고 stress CSV는 비교 대상에서 제외된다. + +`C:\git\FESADev\.harness\config.json`은 현재 없고 `.harness/config.example.json`만 존재한다. 따라서 Harness Stop의 repository default는 `.harness/build`, CMake/MSVC/CTest다. 현재 `.harness/build/CMakeCache.txt`는 `Visual Studio 18 2026`, `x64`, GoogleTest `C:/git/googletest`, MKL `2026.1`, TBB `2023.1`, HDF5 `2.1.1`로 구성되어 있다. 계획 작성 중 configure/build/test는 실행하지 않았다. + +결론: 구현 계획은 진행 가능하다. blocker는 없으며 유일한 현재 사용자 결정은 아래 7-Step 초안의 승인 또는 수정 요청이다. + +## 4. Implementation Scope + +### Included + +- assembly-level element surface의 direct `instance.element-label` 및 explicit-instance assembly ELSET facet resolution. 하나의 surface가 여러 data line에서 서로 다른 explicit instance의 direct/ELSET member를 함께 포함할 수 있다. +- S4/S4R, SPOS/SNEG, one static step의 additive uniform `DSLOAD P` +- case/ASCII whitespace/numeric/cardinality/keyword continuation/source provenance contract +- exact duplicate normalization warning과 conflicting side를 포함한 deterministic fail-closed diagnostics +- bilinear `2 x 2` pressure force와 exact follower external tangent +- linear reference configuration, nonlinear current configuration, exact-once load-factor scaling +- full-space force/tangent assembly, reaction/free residual/global resultant/moment, deterministic serial/parallel reduction +- 기존 schema 0/1 HDF5 및 CLI/atomic finalization 회귀 +- exact pressure reference input/CSV에 대한 schema-1 factor-one HDF5 comparison과 common tolerance report + +### Excluded + +- `*DLOAD`, `TRVEC`, `PNU`, nonuniform/distribution pressure, nodal surface, part-level surface +- implicit-instance ELSET, 하나의 ELSET 자체가 여러 instance를 섞는 mixed-instance set, part ELSET lookup fallback. 서로 다른 explicit instance에 결속된 여러 member/ELSET를 하나의 surface에 두는 것은 포함 범위다. +- edges, other face labels, solids/beams, shells other than S4/S4R +- multi-step, amplitude, transient, eigen, contact, material/geometric extensions unrelated to pressure +- pressure-specific HDF5 dataset, schema bump, CLI option, result filter, CSV product output +- Abaqus execution, Abaqus CSV creation/repair/rename, reference input/CSV mutation +- reaction or stress external acceptance expansion + +### Non-goals + +- Abaqus internal formulation, integration, stabilization, state or result-generation equivalence +- speculative load hierarchy refactor, generalized distributed-load framework, new vendor abstraction +- unrelated parser cleanup, element refactor, tolerance policy change, documentation portfolio expansion + +## 5. Candidate Interface and Data Contracts + +아래 이름과 파일은 implementation handoff를 위한 candidate다. public compatibility와 upstream 의미를 고정하지만 최종 API/저장 배치는 Implementation Agent가 기존 style과 compile evidence에 맞춰 최소 범위에서 확정한다. + +### Semantic model candidate + +`include/fesa/model/model_types.h`에 다음 의미를 갖는 value types를 추가한다. + +```cpp +enum class ShellSurfaceSide { kSpos, kSneg }; +enum class SurfaceMemberKind { kDirect, kElset }; + +struct ElementSurfaceFacetDefinition { + EntityIndex element_index; + std::size_t facet_ordinal; + std::string part_name_raw; + std::string part_name_canonical; + std::string instance_name_raw; + std::string instance_name_canonical; + std::int64_t source_element_label; + std::string source_element_label_raw; + std::string source_element_type; + ShellSurfaceSide side; + SourceLocation first_member_location; + std::size_t first_member_ordinal; + SurfaceMemberKind member_kind; + std::string elset_name_raw; + std::string elset_name_canonical; +}; + +struct ElementSurfaceDefinition { + std::string surface_name_raw; + std::string surface_name_canonical; + std::vector facets; + SourceLocation declaration_location; + std::size_t declaration_ordinal; +}; + +struct SurfacePressureLoadDefinition { + std::string step_name_raw; + std::string step_name_canonical; + EntityIndex surface_index; + std::string surface_name_raw; + std::string surface_name_canonical; + std::string load_type; + double magnitude; + std::string magnitude_raw; + SourceLocation keyword_location; + SourceLocation data_location; + std::size_t data_ordinal; + std::size_t load_ordinal; +}; +``` + +`ModelDefinition`은 `std::vector element_surfaces`를 소유하고 `StaticStepDefinition`은 `std::vector surface_pressure_loads`를 소유한다. `ElementSurfaceDefinition`의 scope 의미는 exact `assembly`다. Committed facet은 internal lookup/scatter용 `element_index`와 별도로 part/instance raw+canonical identity, source element numeric label+raw token, exact canonical `S4|S4R` source type, side, `facet_ordinal`, 최초 contributing surface member의 file/line/member ordinal, `direct|elset` kind와 ELSET raw+canonical provenance를 계속 소유한다. 따라서 stable source identity가 internal element/equation index로 대체되지 않는다. + +Committed `SurfacePressureLoadDefinition`은 surface lookup용 `surface_index`만 남기는 record가 아니다. sole step과 referenced surface의 raw+canonical identity, exact canonical `load_type="P"`, unscaled signed finite `magnitude`와 `magnitude_raw`, keyword/data `SourceLocation`, DSLOAD block 안의 `data_ordinal`, 전체 step load data에서의 `load_ordinal`을 보존한다. 동일해 보이는 pressure rows도 distinct records이며 `(load_ordinal, facet_ordinal)` Cartesian product가 active contribution identity다. + +`Domain`/`StepDefinition`/`AnalysisModel` candidate query는 다음 의미를 갖는다. + +```cpp +const std::vector& Domain::ElementSurfaces() const noexcept; +const std::vector& +StepDefinition::SurfacePressureLoads() const noexcept; +bool StepDefinition::UsesNonlinearGeometry() const noexcept; +const std::vector& +AnalysisModel::ActiveSurfacePressureLoads() const noexcept; +``` + +모든 반환값은 non-owning immutable reference다. `AnalysisModel`은 surface/facet/load를 복사하지 않고 backing `Domain`이 더 오래 살아야 한다. pressure records는 기존 nodal `Load::ComputeContributions`에 억지로 넣지 않는다. 그 interface는 configuration-independent nodal contributions 전용이고 follower tangent를 표현하지 못하기 때문이다. + +### Local evaluator candidate + +새 `include/fesa/loads/shell_surface_pressure.h`와 `src/fesa/loads/shell_surface_pressure.cpp`는 다음 backend-neutral contract를 제공한다. + +```cpp +enum class SurfacePressureConfiguration { kReference, kCurrent }; + +struct ShellSurfacePressureInput { + std::array reference_coordinates; + std::array translational_displacements; + ShellSurfaceSide side; + double pressure_magnitude; + double load_factor; + SurfacePressureConfiguration configuration; + SourceLocation location; + std::string entity_identity; +}; + +struct ShellSurfacePressureContribution { + std::array force; + std::array external_tangent; +}; + +Result EvaluateShellSurfacePressure( + const ShellSurfacePressureInput& input); +``` + +함수는 fixed node/source order의 row-major tangent를 반환한다. force의 rotational entries와 tangent의 rotational rows/columns는 exact zero다. reference configuration은 `u`를 사용하지 않고 tangent가 exact zero이며, current configuration은 승인된 exact derivative를 반환한다. geometric validation은 pressure 또는 factor가 zero여도 생략하지 않는다. + +### Full-space assembler candidate + +새 `include/fesa/assembly/surface_pressure_assembler.h`와 `src/fesa/assembly/surface_pressure_assembler.cpp`는 다음 contract를 제공한다. + +```cpp +struct SurfacePressureAssemblyCandidate { + Vector full_external_force; + SparseMatrix full_external_tangent; + std::vector diagnostics; +}; + +Result AssembleSurfacePressure( + const AnalysisModel& model, + const DofManager& dofs, + const Vector& full_generalized_coordinates, + double load_factor, + SurfacePressureConfiguration configuration, + const ParallelFor& parallel_for); +``` + +입력 vector는 stable full-DOF `[u1,u2,u3,phi1,phi2,phi3]` order다. assembler는 pressure record source order, 각 surface의 canonical facet order, fixed Gauss order로 local candidates를 만든 뒤 동일 순서로 serial reduction한다. 실패 시 output candidate를 반환하지 않으며 caller-owned `AnalysisState`/`NonlinearTrialState`는 갱신하지 않는다. + +### Procedure composition candidate + +- Linear: `LoadAssembler::AssembleFullNodalLoad(...)` 결과와 `AssembleSurfacePressure(..., 1.0, kReference, ...)`의 full force를 checked finite addition하여 `AnalysisState::ExternalForce()`에 한 번만 assign한다. existing stiffness factorization-before-load order와 `EffectiveFreeRhs(F, Kfc, dc, dofs)`를 보존한다. +- Nonlinear: 같은 trial에서 `AssembleInternal(...)`, existing `AssembleGlobalFixedLoadContribution(...)`, `AssembleSurfacePressure(..., increment.load_factor, kCurrent, ...)`를 평가한다. `f_ext=f_fixed+f_pressure`, `K_ext=K_fixed+K_pressure`, `r=f_int-f_ext`, `K=K_int-K_ext` 순서로 candidate를 완성한 뒤 factorization/solve/validation/commit한다. `MklPardisoTangentSolver`의 existing full-CSR unsymmetric path를 유지하며 tangent를 symmetrize하지 않는다. + +## 6. Candidate Files and Ownership + +### Existing files to modify + +| path | responsibility | +| --- | --- | +| `include/fesa/io/abaqus/input_syntax.h` | continued keyword/source-line representation에 필요한 최소 lexical provenance | +| `src/fesa/io/abaqus/input_reader.cpp` | ASCII, 256-byte logical keyword, keyword-only continuation, comma/whitespace contract | +| `src/fesa/io/abaqus/domain_mapping_context.h` | raw surface/facet/DSLOAD records와 provenance | +| `src/fesa/io/abaqus/domain_mapping_context.cpp` | assembly `SURFACE`, assembly `ELSET INTERNAL`, step `DSLOAD` parsing 및 scope/cardinality diagnostics | +| `src/fesa/io/abaqus/domain_mapper.cpp` | surface resolution stage를 topology finalize와 step definition 사이에 호출 | +| `src/fesa/io/abaqus/step_definition_mapper.cpp` | DSLOAD target를 resolved surface index에 bind하고 procedure rules 검증 | +| `src/fesa/io/abaqus/domain_builder.cpp` | 완전 검증된 surface/load candidate를 ModelDefinition에 commit | +| `include/fesa/model/model_types.h` | immutable surface/facet와 Step pressure value definitions | +| `include/fesa/model/domain.h`, `src/fesa/model/domain.cpp` | Domain/Step ownership과 immutable views | +| `include/fesa/analysis/analysis_model.h`, `src/fesa/analysis/analysis_model.cpp` | active pressure non-owning view | +| `src/fesa/analysis/linear_static_procedure.cpp` | reference pressure full-space external force composition | +| `include/fesa/analysis/nonlinear_static_control.h`, `src/fesa/analysis/nonlinear_static_control.cpp` | pressure-independent fixed-load contract를 유지하면서 checked external contribution composition helper가 필요할 때만 최소 확장 | +| `src/fesa/analysis/nonlinear_static_procedure.cpp` | current follower force/tangent, residual/tangent sign, rollback/commit integration | +| `src/fesa/CMakeLists.txt` | 새 production `.cpp` 두 쌍 등록 | +| `tests/CMakeLists.txt` | 새 unit/integration/reference test sources를 기존 targets에 등록; raw `add_test` 추가 없음 | +| `tests/unit/io/abaqus/input_reader_test.cpp` | ASCII/continuation/length/comma lexical tests | +| `tests/unit/io/abaqus/domain_mapper_test.cpp` | 기존 `DLOAD` rejection 및 no-pressure regression 유지/구체화 | +| `tests/unit/io/abaqus/domain_mapping_components_test.cpp` | mapper stage atomicity와 surface resolution component tests | +| `tests/unit/io/hdf5/hdf5_results_writer_test.cpp` | schema 0 inventory/no-pressure-dataset/atomic final regression | +| `tests/unit/io/hdf5/nonlinear_hdf5_results_writer_test.cpp` | schema 1 force/residual/reaction/equilibrium projection/no-new-dataset regression | +| `tests/reference/nonlinear_static_reference_comparison.h`, `tests/reference/nonlinear_static_reference_comparison.cpp` | pressure case contract, optional review artifacts, factor-one projection/prechecks/report | + +### New files to create during implementation + +| path | responsibility / first owning Step | +| --- | --- | +| `src/fesa/io/abaqus/surface_definition_mapper.h` | raw-to-resolved assembly surface mapper internal interface / Step 1 | +| `src/fesa/io/abaqus/surface_definition_mapper.cpp` | direct/ELSET resolution, canonical sort/duplicate policy / Step 1 | +| `tests/unit/io/abaqus/shell_surface_pressure_domain_test.cpp` | feature-focused valid and fail-closed semantic mapping / Step 1 | +| `include/fesa/loads/shell_surface_pressure.h` | local evaluator input/result contract / Step 3 | +| `src/fesa/loads/shell_surface_pressure.cpp` | bilinear integration, geometry checks, force/external tangent / Step 3 | +| `tests/unit/loads/shell_surface_pressure_test.cpp` | analytical, objectivity, FD, geometry evaluator tests / Step 3 | +| `include/fesa/assembly/surface_pressure_assembler.h` | full-space deterministic assembly candidate / Step 4 | +| `src/fesa/assembly/surface_pressure_assembler.cpp` | local scatter and stable reduction / Step 4 | +| `tests/unit/assembly/surface_pressure_assembler_test.cpp` | source/facet/load order, additive/exact-once, serial/parallel tests / Step 4 | +| `tests/integration/analysis/shell_surface_pressure_linear_test.cpp` | linear procedure/reaction/residual/resultant/HDF5 schema 0 / Step 4 | +| `tests/integration/analysis/shell_surface_pressure_nonlinear_test.cpp` | follower Newton/tangent/rollback/balance/HDF5 schema 1 / Step 5 | +| `tests/integration/app/shell_surface_pressure_application_test.cpp` | CLI exact input syntax, existing output naming/schema/atomic/no-pressure regression / Step 4 then Step 5 additions | +| `tests/reference/shell_surface_pressure_reference_test.cpp` | exact artifact and end-to-end comparison gate / Step 6 | +| `docs/shell-surface-pressure-load/implementation-report.md` | implementation/task/test/change summary, future Step 7 | +| `docs/shell-surface-pressure-load/build-test.md` | command/exit/duration/tail/warning/runtime evidence, future Step 7 | +| `docs/shell-surface-pressure-load/reference-comparison.md` | artifact snapshots, comparison metrics/classification, future Step 7 | + +`src/fesa/app/fesa_application.cpp`, HDF5 production writers, PARDISO adapters와 existing tolerance policy는 read-first verification targets이며 원칙적으로 수정하지 않는다. 새 tests가 승인된 contract 결함을 실제로 증명할 때만 해당 Step의 bounded scope 안에서 최소 수정하고 report에 이유를 남긴다. + +## 7. Work Breakdown and Harness Step Draft + +모든 Step은 이전 Step이 green인 상태에서 시작하고 단일 reviewer-rejectable responsibility를 완결한다. 각 Step은 `RED -> observed expected failure -> minimal GREEN -> focused VERIFY -> full/Stop VERIFY`를 같은 세션 안에서 끝낸다. 아래 phase 파일들은 제안일 뿐 아직 materialize하지 않는다. + +### Step 1 — `map-pressure-input-contract` + +**Bounded responsibility:** valid assembly `SURFACE`와 step `DSLOAD P`를 immutable Domain/Step/AnalysisModel contract로 map한다. + +**Dependencies:** 없음. + +**Prerequisites/read first:** `input_syntax.h`, `input_reader.cpp`, `domain_mapping_context.h/.cpp`, `topology_mapper.h/.cpp`, `step_definition_mapper.h/.cpp`, `domain_builder.h/.cpp`, `domain_mapper.cpp`, `model_types.h`, `domain.h/.cpp`, `analysis_model.h/.cpp`, upstream `requirements.md` §§6–8, `io.md` §§2–6, `formulation.md` §3. + +**Exact files:** 위 Candidate Files의 parser/model existing files, 새 `surface_definition_mapper.h/.cpp`, 새 `shell_surface_pressure_domain_test.cpp`, `tests/CMakeLists.txt`, `src/fesa/CMakeLists.txt`. + +**RED:** 먼저 다음 named tests를 작성한다. + +- `InpSyntax.AcceptsAsciiKeywordContinuationAndPreservesPhysicalSourceLines` +- `ShellSurfacePressureInput.MapsDirectInstanceFacetsForS4AndS4rCaseInsensitively` +- `ShellSurfacePressureInput.MapsExplicitInstanceElsetAndResultNeutralInternalParameter` +- `ShellSurfacePressureInput.MapsMixedDirectAndElsetMembersAcrossTwoExplicitInstancesWithStableDataMemberAndElsetOrder` +- `ShellSurfacePressureInput.PreservesSposSnegMagnitudeTextLocationsAndSourceOrder` +- `ShellSurfacePressureDomain.OwnsCanonicalFacetsAndStepOwnedAdditivePressureRecords` +- `ShellSurfacePressureDomain.AnalysisModelBorrowsActivePressureWithoutCopyingDomain` +- `ShellSurfacePressureInput.AcceptsWhitespaceSignedZeroAndFiniteScientificNotation` + +`MapsMixedDirectAndElsetMembersAcrossTwoExplicitInstancesWithStableDataMemberAndElsetOrder`의 RED fixture는 declaration order가 다른 `Instance-A`와 `Instance-B`, 서로 다른 casing으로 참조한 direct member와 각 instance에 explicit `INSTANCE=`로 결속된 flat assembly ELSET member를 하나의 surface data inventory에 교차 배치한다. Test는 case-insensitive resolution, raw data/member ordinal과 ELSET expansion provenance, canonical facet order, 두 instance에서 numeric label이 같아도 분리되는 part/instance/source label/source type/side identity, 각 unique facet의 first-member provenance를 exact 비교한다. Implicit-instance ELSET을 같은 test의 valid branch로 허용하지 않는다. + +실행: + +```powershell +cmake --build .harness/build --config Debug --target fesa_unit_tests +ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(InpSyntax|ShellSurfacePressureInput|ShellSurfacePressureDomain)\." +``` + +**Observed expected failure:** 새 mapper/header 또는 semantic accessors가 없어 compile이 실패하거나, 현재 `SURFACE`/`DSLOAD`가 unsupported input diagnostic으로 거부되어 assertions가 실패해야 한다. Multi-instance RED fixture는 한 surface의 두 explicit instance와 mixed direct/ELSET를 resolve하지 못하거나 committed identity/provenance fields가 없어 exact assertions가 실패해야 한다. unrelated failure면 Step을 중지하고 `regression`으로 분류한다. + +**Minimal GREEN:** 위 candidate semantic signatures를 최소 구현한다. reader는 keyword-only `**,` comment-aware continuation만 결합하며 logical keyword 256 bytes, ASCII, comma/cardinality와 physical source line을 보존한다. surface mapper는 topology finalize 뒤 direct `.` 또는 assembly ELSET의 explicit `INSTANCE`를 case-insensitive하게 resolve한다. 하나의 surface 안에서 direct와 ELSET member를 섞고 서로 다른 두 개 이상의 explicit instance를 참조할 수 있으며, raw data/member order와 flat ELSET expansion provenance를 보존한 뒤 unique facets를 canonical stable order로 만든다. implicit-instance syntax, 하나의 mixed-instance ELSET, part-scope fallback은 허용하지 않는다. step mapper는 parameterless `DSLOAD`, exactly three fields, `P`, finite C-locale scalar를 surface index에 bind하면서 §5 candidate provenance 전부를 보존한다. DomainBuilder는 모든 validation 이후에만 moved ModelDefinition을 commit한다. legacy `StaticStepDefinition` constructors는 empty pressure vector로 delegating하여 existing callers를 깨지 않는다. + +**Focused VERIFY:** 위 RED 명령이 exit `0`이고 모든 named tests가 pass한다. 이어 parser/domain existing suites를 실행한다. + +```powershell +ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(InpDomainMapping|DomainMappingComponents|InpSyntax)\." +``` + +**Full/Stop VERIFY:** 공통 `V-BUILD`, `V-SHOW`, `V-FULL` 명령을 실행한다. + +**Invariants:** 한 surface 안의 mixed direct/ELSET 및 여러 explicit instance는 지원한다. raw surface data/member ordinal과 각 flat ELSET expansion provenance를 stable하게 보존하되 committed unique facet sort는 `(instance declaration ordinal, numeric element label, SPOS before SNEG)`다. S4/S4R part/instance/source label/type/side와 최초 member provenance를 internal index와 함께 보존한다. DSLOAD rows는 raw+canonical step/surface identity, canonical `P`, signed magnitude/raw token, keyword/data location, data/load ordinal을 가진 distinct/additive records다. lookup은 case-insensitive이고 raw spelling은 보존하며 Domain lifetime > AnalysisModel이다. + +**Failure/atomicity:** parse/map failure는 Domain을 반환하지 않으며 partial surface/load가 visible하지 않다. diagnostics는 backend-independent SourceLocation을 가진다. + +**Forbidden scope:** physics evaluator/assembly, `DLOAD`, general surface framework, HDF5/schema, reference artifacts. + +**Trace:** requirements `001`–`004`, `010`, `013`; `IO §§2–6`; `FORM §3`; numerical-review input readiness. + +**Evidence/report:** exact commands, exit codes, expected RED diagnostic/compile reason, mapped facet/load dumps from tests, modified/new paths, warning count. Handoff은 immutable semantic queries와 stable ordering contract다. + +### Step 2 — `reject-invalid-pressure-input` + +**Bounded responsibility:** pressure input/mapping negative semantics와 deterministic diagnostics를 fail-closed/atomic하게 완결한다. + +**Dependencies:** Step 1 green semantic output. + +**Prerequisites/read first:** Step 1 changed files/tests, `core/ascii.h`, `core/diagnostic.h`, `source_target_resolver.h/.cpp`, `io.md` §§2.5–3.4, 5.2, 9, `requirements.md` `014`–`017` acceptance, `formulation.md` §11. + +**Exact files:** `input_reader.cpp`, `domain_mapping_context.h/.cpp`, `surface_definition_mapper.h/.cpp`, `step_definition_mapper.cpp`, `domain_builder.cpp`, `shell_surface_pressure_domain_test.cpp`, existing `domain_mapper_test.cpp` and `domain_mapping_components_test.cpp`. 새 production type은 만들지 않는다. + +**RED named tests:** + +- `ShellSurfacePressureInput.RejectsNonAsciiOverlengthOrIllegalContinuationAtStableLocation` +- `ShellSurfacePressureInput.RejectsUnsupportedSurfaceParametersTypesSidesAndTargetKinds` +- `ShellSurfacePressureInput.RejectsDsloadParametersLabelsDistributionsAndCardinality` +- `ShellSurfacePressureInput.RejectsEmptyMissingAmbiguousAndCrossScopeSurfaceTargets` +- `ShellSurfacePressureInput.RejectsImplicitInstanceNestedCyclicAndMalformedElsets` +- `ShellSurfacePressureInput.NormalizesExactSameSideDuplicatesWithOneStableWarning` +- `ShellSurfacePressureInput.RejectsConflictingSidesForOneElement` +- `ShellSurfacePressureInput.RejectsNonfiniteDExponentAndLocaleDependentMagnitudes` +- `ShellSurfacePressureInput.PreservesAdditiveRepeatedPressureRowsWithoutDeduplication` +- `ShellSurfacePressureDomain.MappingFailureCommitsNoPartialSemanticCandidate` +- `ShellSurfacePressureInput.EmitsDiagnosticsInStableSourceOrderAcrossRepeatedRuns` + +RED/focused command: + +```powershell +cmake --build .harness/build --config Debug --target fesa_unit_tests +ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(ShellSurfacePressureInput|ShellSurfacePressureDomain)\." +``` + +**Observed expected failure:** Step 1의 happy-path mapper가 unsupported fields를 허용하거나 첫 발견/container order로 진단을 내고, duplicate/conflicting normalization을 구분하지 못해 assertions가 실패해야 한다. + +**Minimal GREEN:** allowed parameter/label/cardinality tables를 exact하게 적용한다. recursive/nested/cyclic ELSET expansion을 금지하고 part/implicit scope fallback을 하지 않는다. exact same-side duplicate는 한 facet으로 normalize하고 한 warning을 stable location/order로 emit하며 conflicting side는 error다. 모든 오류를 candidate validation 단계에서 모으고 `SortDiagnostics` contract로 정렬한 뒤 Domain commit 전에 반환한다. silent skip, guess, average, partial commit은 금지한다. + +**Focused VERIFY:** named negative tests와 모든 `InpDomainMapping` tests exit `0`; golden diagnostic fields `(severity,code,file,line,keyword,entity_identity,message)`와 repeated-run order가 exact하다. + +**Full/Stop VERIFY:** `V-BUILD`, `V-SHOW`, `V-FULL`. + +**Invariants:** exact duplicate warning과 incompatible duplicate error 분리; missing/extra/ambiguous/cyclic/cross-scope/nonfinite 모두 tolerance 이전 차단; legacy input without pressure unchanged. + +**Failure/atomicity:** failed candidate는 Domain/AnalysisState/HDF5로 이동하지 않는다. 실패한 input으로 기존 final output을 건드리지 않는 CLI proof는 Step 4/5에서 추가한다. + +**Forbidden scope:** evaluator, tolerance 완화, artifact rewrite, parser-wide refactor. + +**Trace:** requirements `002`–`004`, `013`–`017`; `IO §§2–6,9`; `FORM §11`; `NR §6` invalid-input rows. + +**Evidence/report:** 각 test의 expected code/location/entity, warning normalization count, repeated diagnostic sequence, RED/GREEN exits. Handoff은 fail-closed semantic model이다. + +### Step 3 — `evaluate-shell-pressure-kernel` + +**Bounded responsibility:** one four-node shell facet의 reference/current pressure force와 exact external tangent를 승인된 geometry policy로 계산한다. + +**Dependencies:** Step 1–2 semantic side/magnitude/source identity. + +**Prerequisites/read first:** `mitc4_shell.h/.cpp`, `nonlinear_mitc4_shell.h/.cpp`, `shell_geometry.h/.cpp`, `vector3.h`, `matrix.h`, existing MITC4 unit/tangent tests, `formulation.md` §§6, 9–10, 13–14, `numerical-review.md` §§3–6. + +**Exact files:** 새 `shell_surface_pressure.h/.cpp`, 새 `shell_surface_pressure_test.cpp`, `src/fesa/CMakeLists.txt`, `tests/CMakeLists.txt`. + +**RED named tests:** + +- `ShellSurfacePressureKernel.PartitionsUnityAndIntegratesPlanarResultantAndMoment` +- `ShellSurfacePressureKernel.ReversesExactlyForSposSnegAndNegativeMagnitude` +- `ShellSurfacePressureKernel.UsesReferenceGeometryWithExactZeroLinearTangent` +- `ShellSurfacePressureKernel.UsesCurrentAreaAndNormalForFollowerForce` +- `ShellSurfacePressureKernel.HasExactZeroRotationalForceRowsAndTangentBlocks` +- `ShellSurfacePressureKernel.IsTranslationAndRigidRotationObjective` +- `ShellSurfacePressureKernel.IsCovariantUnderCyclicNodeRelabeling` +- `ShellSurfacePressureKernel.MatchesCenteredFiniteDifferenceForForceAndResidualSigns` +- `ShellSurfacePressureKernel.PreservesGenerallyNonsymmetricFollowerTangent` +- `ShellSurfacePressureKernel.RejectsNonfiniteCollapsedFoldedAndInvertedGeometryAtEveryRequiredPoint` +- `ShellSurfacePressureKernel.ValidatesGeometryEvenForZeroPressureOrFactor` + +RED/focused command: + +```powershell +cmake --build .harness/build --config Debug --target fesa_unit_tests +ctest --test-dir .harness/build -C Debug --output-on-failure -R "^ShellSurfacePressureKernel\." +``` + +**Observed expected failure:** new evaluator declaration/definition이 없어 compile/link fail해야 한다. 기존 MITC4 internal-force code를 pressure처럼 재사용하여 GREEN으로 만들지 않는다. + +**Minimal GREEN:** fixed Gauss order `(-1/sqrt(3),-1/sqrt(3))`, `(+,−)`, `(+,+)`, `(−,+)`의 common `2 x 2` rule, bilinear `N_i`, `s=+1/-1`, `f_i=-lambda*p*s*sum(w*N_i*a)`와 approved exact derivative를 직접 구현한다. current coordinates는 `X+u` translation만 사용한다. `tau_J=1e-12`와 mean/corner/Gauss chord-scaled checks, finite/fold/inversion rules를 그대로 적용한다. `max(1,...)`, absolute floor, clamp, connectivity reorder, normal flip, tangent symmetrization은 금지한다. + +**Focused VERIFY acceptance:** shape sum error `<=1e-14`; normalized resultant/moment/sign/objectivity/covariance `<=1e-12`; centered FD `h=1e-5`, normalized tangent error `<=1e-8`; zero rotational blocks exact zero; antisymmetric tangent evidence nonzero; invalid cases exact failure. + +**Full/Stop VERIFY:** focused test 뒤 existing `Mitc4Shell`, `NonlinearMitc4Shell`, `NonlinearMitc4ShellTangent` suites와 `V-BUILD`, `V-SHOW`, `V-FULL`. + +**Invariants:** force/tangent same geometry/Gauss evaluation; sign consistency for both `f_ext` and residual derivative; no state mutation; deterministic fixed loops. + +**Failure/atomicity:** function returns no contribution on any nonfinite/geometry failure; caller arrays/state remain unchanged. + +**Forbidden scope:** element internal stiffness/constitutive changes, pressure stress recovery, integration configurability, vendor dependency. + +**Trace:** requirements `005`–`009`, `016`, `020`–`021`; `FORM §§6,9–10,13–14`; `NR §6` kernel/objectivity/tangent/geometry rows. + +**Evidence/report:** normalized metrics, FD numerator/denominator/h, antisymmetric entries, exact-zero checks, diagnostic identity/location and command exits. Handoff은 pure local evaluator contract다. + +### Step 4 — `integrate-linear-shell-pressure` + +**Bounded responsibility:** reference-configuration pressure를 deterministic full-space linear load path, reaction/free residual/global balance와 existing schema-0 CLI output에 연결한다. + +**Dependencies:** Step 1–3 green. + +**Prerequisites/read first:** Step 3 evaluator, `load_assembler.h/.cpp`, `sparse_assembler.h/.cpp`, `parallel_for.h/.cpp`, `dof_manager.h/.cpp`, `linear_static_procedure.cpp`, `analysis_state.h/.cpp`, `result_recovery.h/.cpp`, `global_equilibrium_recovery.h/.cpp`, HDF5 schema-0 writer/self-check/tests, `fesa_application.cpp`, `io.md` §§7.1, 7.3, 10, `formulation.md` §§9,11–13. + +**Exact files:** 새 `surface_pressure_assembler.h/.cpp`, unit assembler test, new linear integration/app tests, `linear_static_procedure.cpp`, `src/fesa/CMakeLists.txt`, `tests/CMakeLists.txt`, schema-0 writer test only for contract assertions. HDF5 production writer는 expected no-change. + +**RED named tests:** + +- `SurfacePressureAssembly.AssemblesFullDofsInPressureFacetAndRecordOrder` +- `SurfacePressureAssembly.AddsRepeatedRecordsAndAppliesUnitFactorExactlyOnce` +- `SurfacePressureAssembly.IsBitwiseStableForSerialAndParallelLocalEvaluation` +- `LinearShellSurfacePressure.UsesReferenceNormalAndAreaAfterPrescribedDisplacement` +- `LinearShellSurfacePressure.AssemblesBeforeProjectionAndIncludesConstrainedReaction` +- `LinearShellSurfacePressure.SatisfiesFreeResidualGlobalResultantAndMoment` +- `LinearShellSurfacePressure.PreservesS4S4rMeshAndCyclicOrderInvariance` +- `LinearShellSurfacePressure.WritesSchemaZeroWithoutPressureDataset` +- `ShellSurfacePressureApplication.LinearFailurePreservesExistingFinalAndNoCandidate` +- `ShellSurfacePressureApplication.InputWithoutPressureRetainsExistingLinearBehavior` + +RED/focused commands: + +```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)\." +``` + +**Observed expected failure:** assembler header/definition이 없거나 linear procedure가 nodal CLOAD만 assembly하여 pressure resultant/reaction가 zero이고 pressure CLI case가 acceptance를 충족하지 못해야 한다. + +**Minimal GREEN:** local pressure candidates를 source/facet/Gauss stable order로 생성하고 worker-local buffers에서 full DOF/scatter COO를 만들며 fixed serial reduction한다. linear procedure는 stiffness partition/factorization 후 existing CLOAD와 reference pressure full force를 checked add하고, projection 전 `state.ExternalForce()`에 한 번만 commit한다. evaluator에는 load factor `1.0`을 정확히 한 번 전달한다. existing `Kff/Kfc`, 0x0 free system, `K*d-F` recovery와 output finalization order는 보존한다. + +**Focused VERIFY acceptance:** analytical normalized force/moment/reaction/mesh/order errors `<=1e-12`; global force/moment balance `<=1e-8`; free residual uses approved existing scale gates; repeated serial/parallel output and diagnostics exact; schema version `0`, existing mandatory datasets만 존재하고 pressure-specific path는 없다; failed candidate가 prior final bytes를 보존한다. + +**Full/Stop VERIFY:** existing `LoadAssembly`, `SparseAssembly`, `LinearStaticCli`, `Mitc4ShellCli`, `Hdf5ResultsWriter` suites와 `V-BUILD`, `V-SHOW`, `V-FULL`. + +**Invariants:** factorization-before-load; full-space before free/constrained projection; linear tangent exact zero; pressure load factor exact once; worker global CSR write 금지; source/internal/equation IDs 분리. + +**Failure/atomicity:** any local/nonfinite/assembly/recovery failure returns before state/result publication; HDF5 existing final preserved by current atomic writer. + +**Forbidden scope:** nonlinear follower path, schema change, linear solver backend change, output dataset addition. + +**Trace:** requirements `005`–`007`, `010`–`013`, `016`–`020`; `IO §§6–7,9–10`; `FORM §§9,11–14`; `NR §6` linear/resultant/balance rows. + +**Evidence/report:** stable contribution order, external vector/reaction/residual/resultants, schema inventory, final-file snapshots, RED/GREEN exits. Handoff은 validated linear pressure path와 reusable full-space assembler다. + +### Step 5 — `integrate-nonlinear-follower-pressure` + +**Bounded responsibility:** current-configuration follower pressure force와 generally nonsymmetric external tangent를 nonlinear full-Newton trial/commit lifecycle 및 schema-1 output에 연결한다. + +**Dependencies:** Step 1–4 green. + +**Prerequisites/read first:** Step 3–4 evaluator/assembler, `nonlinear_static_control.h/.cpp`, `nonlinear_static_procedure.h/.cpp`, `nonlinear_analysis_state.h/.cpp`, `nonlinear_mitc4_shell.h/.cpp`, `tangent_solver.h`, `mkl_pardiso_tangent_solver.h/.cpp`, nonlinear HDF5 writer/self-check/tests, `prepared_analysis.h/.cpp`, `fesa_application.cpp`, `formulation.md` §§9.2–9.4, 11–13, `numerical-review.md` §6 nonlinear suite, `io.md` §§7.2, 7.4. + +**Exact files:** `nonlinear_static_control.h/.cpp` only if checked contribution composition needs a helper, `nonlinear_static_procedure.cpp`, new nonlinear integration/app tests, nonlinear HDF5 writer test. Existing PARDISO/HDF5/app production files are no-change verification targets unless a test exposes a contract gap. + +**RED named tests:** + +- `NonlinearShellSurfacePressure.AssemblesFollowerForceFromCurrentTrialGeometry` +- `NonlinearShellSurfacePressure.FormsResidualAndTangentWithApprovedExternalSigns` +- `NonlinearShellSurfacePressure.AppliesIncrementFactorExactlyOnce` +- `NonlinearShellSurfacePressure.UsesFullUnsymmetricTangentSolverPath` +- `NonlinearShellSurfacePressure.ConvergesOpenPatchAndPreservesAntisymmetricEvidence` +- `NonlinearShellSurfacePressure.SatisfiesAcceptedFreeResidualAndFactorOneGlobalBalance` +- `NonlinearShellSurfacePressure.IsObjectiveUnderRigidMotionAndTracksCurrentArea` +- `NonlinearShellSurfacePressure.ReducesSerialAndParallelContributionsDeterministically` +- `NonlinearShellSurfacePressure.InvalidTrialRollsBackCommittedFrameAndFinalOutput` +- `NonlinearShellSurfacePressure.WritesSchemaOneExternalInternalResidualReactionAndEquilibrium` +- `ShellSurfacePressureApplication.InputWithoutPressureRetainsExistingNonlinearBehavior` + +RED/focused commands: + +```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)\." +``` + +**Observed expected failure:** nonlinear procedure가 existing fixed-global CLOAD만 `f_ext`에 포함하고 pressure force/tangent를 누락하여 follower/objectivity/sign/balance assertions 또는 pressure nonlinear case가 실패해야 한다. + +**Minimal GREEN:** each Newton trial에서 current pressure candidate를 평가하고 fixed/pressure external contributions를 stable checked add한다. internal과 external은 같은 trial이다. `r=f_int-f_ext`, `K=K_int-K_ext`를 full space에서 만든 후 constrained/free extraction한다. existing `FactorizeFresh` full-CSR `mtype=11` path를 사용하고 external tangent를 symmetrize하지 않는다. convergence가 검증된 candidate만 `CommitAcceptedFrame`에 전달하며 invalid geometry/nonfinite/factorization/solve failure는 committed frame/final HDF5를 보존한다. + +**Focused VERIFY acceptance:** local FD `<=1e-8`; objectivity/current-area normalized `<=1e-12`; factor-one global force/moment balance `<=1e-8`; force/moment free residual은 existing nonzero scale relative `<=1e-2`, zero scale absolute `<=1e-3`; exact zero-scale rules 유지; schema version `1`의 unique factor-one accepted frame에 existing generalized external/internal/residual/reaction/equilibrium datasets가 일치한다; serial/parallel report order exact. + +**Full/Stop VERIFY:** existing `NonlinearStaticProcedure`, `NonlinearStaticControl`, `TangentSolver`, `NonlinearHdf5ResultsWriter`, nonlinear reference regression suites와 `V-BUILD`, `V-SHOW`, `V-FULL`. + +**Invariants:** translations only affect pressure kinematics; rotation force/tangent blocks zero; load factor exact once; generally nonsymmetric tangent retained; candidate-before-commit; stable reduction. + +**Failure/atomicity:** failure does not append an accepted frame, does not replace existing final HDF5 and records last completed Newton stage/pressure source identity deterministically. + +**Forbidden scope:** line search/arc length/new procedure, convergence threshold change, PARDISO adapter redesign, new HDF5 fields. + +**Trace:** requirements `008`–`013`, `016`–`019`, `021`; `IO §§6–7,9–10`; `FORM §§9–14`; `NR §6` follower/tangent/objectivity/open-patch/balance rows. + +**Evidence/report:** trial factor, force/tangent signs, nonsymmetry entries, solver spy events, iteration counts, free residual/balance metrics, HDF5 datasets, rollback snapshots, exits/durations/tails. + +### Step 6 — `compare-pressure-reference` + +**Bounded responsibility:** exact stored pressure artifacts와 FESA schema-1 factor-one HDF5의 deterministic displacement comparison을 기존 common tolerance policy에 연결한다. + +**Dependencies:** Step 1–5 green; exact reference files read-only. + +**Prerequisites/read first:** `reference-model.md` 전체, `io.md` §8, `numerical-review.md` §§6.2–6.3, `docs/TOLERANCE.md`, `reference_tolerance_policy.h/.cpp`, nonlinear reference comparison header/source/cases, `tests/CMakeLists.txt`, exact input/CSV. Artifact bytes는 inspection만 하고 수정하지 않는다. + +**Exact files:** `nonlinear_static_reference_comparison.h/.cpp`, new `shell_surface_pressure_reference_test.cpp`, `tests/CMakeLists.txt`. tolerance policy source와 stored reference files는 no-change. + +**RED named tests:** + +- `ShellSurfacePressureReference.AuditsExactRequiredArtifactsAndIgnoresOptionalReviewArtifacts` +- `ShellSurfacePressureReference.SelectsUniqueSchemaOneFactorOneAcceptedFrame` +- `ShellSurfacePressureReference.Projects729WideRowsTo2187LogicalRowsPerFamily` +- `ShellSurfacePressureReference.MatchesByInstanceNodeLabelAndComponentNotRowOrder` +- `ShellSurfacePressureReference.RejectsSchemaIdentityCardinalityMissingExtraDuplicateAndNonfiniteBeforeTolerance` +- `ShellSurfacePressureReference.ClassifiesTranslationBlockingAndRotationWarningOnly` +- `ShellSurfacePressureReference.ExcludesReactionAndStressFamiliesFromVerdict` +- `ShellSurfacePressureReference.UsesUnchangedCommonScaleNearZeroRelativeAndRmsPolicy` +- `ShellSurfacePressureReference.WritesDeterministicComparisonReport` + +RED/focused commands: + +```powershell +cmake --build .harness/build --config Debug --target fesa_reference_tests +ctest --test-dir .harness/build -C Debug --output-on-failure -R "^ShellSurfacePressureReference\." +``` + +**Observed expected failure:** current nonlinear case registry requires coarse/fine legacy artifact portfolios and has no pressure case identity/disposition, so exact two-file pressure contract 또는 729/2187 cardinality가 지원되지 않아 test가 fail해야 한다. + +**Minimal GREEN:** `NonlinearReferenceCase`에 pressure case의 required/optional/excluded artifact disposition을 explicit value fields로 표현한다. exact path/hash snapshot 뒤 input을 build-tree execution directory에 byte-for-byte copy하고 FESA application만 실행한다. HDF5에서 schema `1`, Step-1, unique accepted `load_factor==1`, `/model/nodes`, nodal displacement를 읽어 `(Part-1-1,node label,component)` key로 project한다. wide CSV 729 rows를 translation 2,187 + rotation 2,187 logical rows로 expand한다. all prechecks 후 기존 `EvaluateReferenceTolerance`만 호출한다. U family blocking, UR warning-only이며 reaction은 comparator family를 만들지 않고 review-only inventory, stress는 excluded다. + +**Focused VERIFY acceptance:** input and displacement CSV exact hash/byte size unchanged; 729 unique node keys; each U/UR family 2,187 rows; missing/extra/duplicate/nonfinite/schema/frame/identity failures precede tolerance; common policy `S=max(abs(reference))`, near-zero band `0.01*S`, relative `0.05`, RMS/S `0.01`, zero-scale exact; report rows/warnings/metrics stable. + +**Full/Stop VERIFY:** all `ShellSurfacePressureReference`, `NonlinearStaticReference`, `ReferenceTolerancePolicy`, `Mitc4Reference` suites와 `V-BUILD`, `V-SHOW`, `V-FULL`. + +**Invariants:** stored input/CSV immutable; Abaqus never run; FESA CSV is not product output; reference row order ignored but source keys exact; tolerance unchanged. + +**Failure/atomicity:** any artifact/precheck failure produces failed classification without tolerance result or artifact mutation. copied execution files and generated HDF5/log remain under build tree only. + +**Forbidden scope:** reference CSV generation/edit, new tolerance, reaction/stress promotion, legacy artifact rename/metadata requirement. + +**Trace:** requirements `017`–`019`, `021`–`024`; `IO §8`; reference-model §§3–8; numerical-review external acceptance. + +**Evidence/report:** before/after snapshots, copied input hash, generated HDF5 path, selected frame identity, family cardinality/scale/row/RMS/worst row, warnings, classification, exits/durations/tails. + +### Step 7 — `verify-and-report-pressure-feature` + +**Bounded responsibility:** all implementation artifacts를 inspect하고 full MSVC/CTest 및 exact pressure reference gate를 실행해 implementation-owned reports를 완결한다. 코드 수정은 이 Step의 기본 scope가 아니다. + +**Dependencies:** Step 1–6 green; clean or isolated executor worktree; no stored reference mutation. + +**Prerequisites/read first:** all prior Step outputs, `AGENTS.md`, `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`, `.codex/hooks.json`, `.harness/config.json` if it exists at execution time, current CMake files, all upstream docs, exact reference bundle. + +**Exact files:** future new `implementation-report.md`, `build-test.md`, `reference-comparison.md`. Test/production/CMake files are read-only in this Step unless a verification failure is classified `implementation` and Coordinator authorizes returning to the owning earlier Step; no silent repair here. + +**RED:** report preflight must first prove the three implementation-owned reports are absent/incomplete and that no final passing classification has been recorded. This is the expected evidence-state failure, not permission to fabricate results. If any source/test/CMake change lacks a first-failing test record, classify `evidence-gap` and stop. + +**Minimal GREEN sequence:** literally execute `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` after build/test gates: + +1. **ARTIFACT CHECK:** record exact stored input/displacement CSV path, sha256, size, timestamp before run; reaction review-only and stress excluded disposition; verify source phase never invokes Abaqus. +2. **COMPARE:** run FESA on a copied exact `.inp`, locate generated schema-1 `_results.h5`, execute `ShellSurfacePressureReference` comparison, record 2,187 U and 2,187 UR rows and common tolerance metrics. +3. **CLASSIFY:** fail on U/precheck/internal equilibrium; preserve UR-only difference as warning-only; reaction/stress cannot change verdict. Distinguish `implementation`, `test`, `infrastructure`, `environment`, `artifact`, `regression`, `evidence-gap`. +4. **REPORT:** write commands, exit codes, durations, meaningful output tails, warning inventory, changed files, requirement coverage and artifact post-check to all three reports. + +**Exact commands:** execute `V-CONFIG`, `V-BUILD`, `V-SHOW`, `V-FOCUSED`, `V-FULL`, `V-REFERENCE` from §12. No Harness Python command because no Harness/Python file changes are planned. If an executor later changes `scripts/` or Harness Python behavior under separate authority, it must additionally run `uv run --with pytest python -m pytest -v -rs` and record why. + +**Observed expected failure:** any configure/build/test/reference nonzero exit, zero discovered tests, new `/W4 /WX` warning, runtime DLL staging failure, artifact mutation, cardinality mismatch or U blocking failure keeps reports non-passing and stops closure. + +**Focused/Full/Stop VERIFY:** every command exit `0`, `ctest --show-only=json-v1` reports nonzero tests including all named feature tests, full CTest passes, no new warnings, runtime execution succeeds, artifacts unchanged, reports internally consistent. + +**Invariants:** evidence before success claims; no release approval; no physics Gate 7 claim; no commit/task selection/manual status/timestamp ownership transfer from Harness Executor. + +**Failure/atomicity:** a failed gate leaves status non-passing, retains outputs for diagnosis, does not alter upstream/tolerance/reference artifacts and returns to Coordinator with precise classification. + +**Forbidden scope:** source fixes, reference generation, tolerance adjustment, phase execution expansion, release readiness. + +**Trace:** all requirements `001`–`024`; all upstream contracts; Harness Stop contract. + +**Evidence/report:** complete three-document handoff with task order, tests first, files, commands, comparison, assumptions, acceptance and open constraints. + +## 8. TDD Test Plan + +| order | test id | layer / named suite | RED cause | GREEN evidence | +| --- | --- | --- | --- | --- | +| 1 | `T-INPUT-VALID` | `InpSyntax`, `ShellSurfacePressureInput`, `ShellSurfacePressureDomain` valid tests | unsupported SURFACE/DSLOAD or missing semantic API | exact valid mapping/provenance/ownership | +| 2 | `T-INPUT-NEG` | pressure input negative tests | unsupported forms accepted or unstable/partial failure | fail-closed deterministic diagnostics and no Domain | +| 3 | `T-KERNEL-FORCE` | `ShellSurfacePressureKernel` analytical/sign/resultant/objectivity | evaluator absent | approved force integration and exact zero rotations | +| 4 | `T-KERNEL-TANGENT` | kernel FD/nonsymmetry/geometry | external derivative absent | `h=1e-5`, normalized `<=1e-8`, geometry gate exact | +| 5 | `T-ASSEMBLY` | `SurfacePressureAssembly` | full-space assembler absent | stable additive exact-once serial/parallel reduction | +| 6 | `T-LINEAR` | `LinearShellSurfacePressure` | linear procedure omits pressure | reference force/reaction/residual/resultant and schema 0 | +| 7 | `T-NONLINEAR` | `NonlinearShellSurfacePressure` | nonlinear external force/tangent omit pressure | current follower Newton convergence, rollback and schema 1 | +| 8 | `T-CLI-HDF5` | `ShellSurfacePressureApplication` plus writer tests | pressure route/output regression not covered | existing naming/schema/projection/atomic/no-pressure behavior | +| 9 | `T-REF-PRECHECK` | pressure reference precheck tests | registry/schema/cardinality unsupported | deterministic prechecks before tolerance | +| 10 | `T-REF-COMPARE` | pressure reference end-to-end tests | pressure disposition/comparison unsupported | exact U blocking/UR warning-only report | +| 11 | `E-FINAL` | full build/test/reference evidence | reports incomplete | verified commands and immutable artifact snapshots | + +모든 production change는 같은 Step에서 먼저 생성/수정되는 관련 C++ test와 연결한다. `src/fesa/CMakeLists.txt` production 등록은 corresponding unit test RED와 함께 들어가며, `tests/CMakeLists.txt` 등록은 test source를 생성한 같은 Step에서 한다. + +## 9. CMake/CTest Plan + +- `src/fesa/CMakeLists.txt`: `surface_definition_mapper.cpp`, `shell_surface_pressure.cpp`, `surface_pressure_assembler.cpp`를 existing `fesa_solver` source inventory에 추가한다. public headers는 existing include tree를 통해 노출하고 별도 library/target을 만들지 않는다. +- `tests/CMakeLists.txt`: 새 unit sources는 `fesa_unit_tests`, integration/app sources는 `fesa_integration_tests`, reference source는 `fesa_reference_tests`에 추가한다. +- existing `gtest_discover_tests`가 개별 `Suite.Test` CTest entries를 만든다. 새 raw `add_test`는 필요하지 않다. +- feature-specific selection은 exact suite-name regex로 한다. existing target-wide legacy labels를 전면 재분류하지 않는다. 필요하면 각 `gtest_discover_tests(... PROPERTIES LABELS ...)`의 existing labels에 `shell-surface-pressure-load`를 append하되 기존 labels를 삭제하지 않는다. +- `.harness/config.json`이 execution 전에 생기면 그 설정이 아래 cache-derived command보다 우선한다. 현재는 없으므로 `.harness/build` default와 현재 MSVC x64 Debug cache를 사용한다. +- `ctest --show-only=json-v1`에서 discovered test count가 zero면 success로 인정하지 않는다. +- runtime staging은 existing `fesa_cli`, integration/reference target의 MKL/TBB/HDF5 DLL copy rules를 그대로 사용하며 새 manual PATH hack을 만들지 않는다. + +## 10. Data Flow Contract + +```text +exact/approved Abaqus .inp + -> AbaqusInputReader KeywordBlock/DataLine + physical SourceLocation + -> DomainMappingContext raw SURFACE/DSLOAD candidate + -> topology finalize -> SurfaceDefinitionMapper -> StepDefinitionMapper + -> Domain-owned ordered ElementSurfaceDefinition + + Step-owned ordered SurfacePressureLoadDefinition + -> AnalysisModel non-owning active view (Domain outlives view) + -> ShellSurfacePressureEvaluator local force/tangent candidates + -> SurfacePressureAssembler stable full-space reduction + -> linear: Fext(ref), Kext=0 + nonlinear: Fext(current), Kext(current) + -> residual/reaction/equilibrium recovery + -> existing atomic HDF5 writer + -> authoritative _results.h5 + -> schema-1 factor-one HDF5 projection keyed by + (Step-1, factor=1, Part-1-1, source node label, component) + -> exact read-only displacement CSV projection + -> prechecks -> unchanged common tolerance -> deterministic report +``` + +Exact reference flow: + +- Input: `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure.inp` +- Required CSV: `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure displacements.csv` +- FESA run: input copy under `.harness/build/reference/shell-surface-pressure-load/`; never Abaqus +- HDF5: schema `1`, `Step-1`, unique accepted factor-one frame, `/model/nodes`, existing nodal displacement/generalized force/residual/reaction/equilibrium paths +- CSV: 729 wide node rows; U1/U2/U3 = 2,187 blocking logical rows; UR1/UR2/UR3 = 2,187 warning-only logical rows +- Reaction CSV: optional review-only inventory, no comparison family/verdict effect +- Stress CSV: excluded, no comparison family +- Prechecks: missing/extra/duplicate/nonfinite/schema/frame/source-id/component/cardinality before tolerance +- Tolerance: family-specific Abaqus-only `S=max(abs(reference))`; `abs(ref)<=0.01*S`이면 absolute row error `<=0.01*S`, otherwise relative error `<=0.05`; `RMS(error)/S<=0.01`; zero-scale는 FESA exact zero only. + +## 11. Acceptance Traceability Matrix + +| requirement | Step | task/test evidence | acceptance criterion | +| --- | --- | --- | --- | +| `FESA-REQ-SHELL-PRESSURE-001` | 1, 7 | `T-INPUT-VALID`; valid direct/ELSET S4/S4R tests | approved SURFACE + DSLOAD sequence exact | +| `FESA-REQ-SHELL-PRESSURE-002` | 1, 2 | finite scalar/raw text, nonfinite/D-exponent tests | one uniform finite force/area scalar per row | +| `FESA-REQ-SHELL-PRESSURE-003` | 1, 2, 4 | canonical facet/order tests; assembler order | unique deterministic instance/label/side list | +| `FESA-REQ-SHELL-PRESSURE-004` | 1, 2 | S4/S4R/SPOS/SNEG valid and unsupported inventory | only approved shell types/sides; source type/label preserved | +| `FESA-REQ-SHELL-PRESSURE-005` | 3, 4 | sign reversal and linear analytical tests | positive opposite selected normal; negative reverses | +| `FESA-REQ-SHELL-PRESSURE-006` | 3, 4 | connectivity/SPOS/SNEG reversal | SPOS connectivity normal, SNEG inverse exact | +| `FESA-REQ-SHELL-PRESSURE-007` | 3, 4 | reference geometry and prescribed-displacement invariant | linear pressure fixed to reference geometry | +| `FESA-REQ-SHELL-PRESSURE-008` | 3, 5 | current area/normal/objectivity tests | nonlinear follower uses `X+u` | +| `FESA-REQ-SHELL-PRESSURE-009` | 3, 5 | centered FD and Newton tangent sign tests | exact external derivative included | +| `FESA-REQ-SHELL-PRESSURE-010` | 1, 4, 5 | additive records/unit factor/increment factor tests | pressure magnitude scaled exactly once | +| `FESA-REQ-SHELL-PRESSURE-011` | 4, 5 | full-DOF scatter before projection tests | all pressure assembled full-space first | +| `FESA-REQ-SHELL-PRESSURE-012` | 4, 5, 7 | reaction/free residual/global balance | `K*d-F` or `f_int-f_ext` includes pressure | +| `FESA-REQ-SHELL-PRESSURE-013` | 1, 2, 4, 5, 6 | repeated serial/parallel/order/report tests | deterministic facets, reductions, rows, diagnostics | +| `FESA-REQ-SHELL-PRESSURE-014` | 2 | unsupported params/labels/distribution/type/side tests | fail closed exact | +| `FESA-REQ-SHELL-PRESSURE-015` | 2 | missing/empty/ambiguous/cyclic/scope/duplicate tests | fail closed, no guessing/averaging | +| `FESA-REQ-SHELL-PRESSURE-016` | 2, 3, 4, 5 | invalid procedure/nonfinite/geometry/rollback | no clamp/fallback/partial result | +| `FESA-REQ-SHELL-PRESSURE-017` | 2, 4, 5, 6, 7 | stable diagnostics, no Domain, final snapshots | failed candidate never published | +| `FESA-REQ-SHELL-PRESSURE-018` | 4, 5, 7 | schema 0/1 inventory tests | existing HDF5 sole authority; no pressure dataset/version | +| `FESA-REQ-SHELL-PRESSURE-019` | 4, 5, 6 | displacement/reaction/residual/equilibrium projections | existing units/coordinates/source IDs finite and observable | +| `FESA-REQ-SHELL-PRESSURE-020` | 3, 4 | analytical sign/resultant/reaction/mesh/order suite | normalized analytical checks at approved thresholds | +| `FESA-REQ-SHELL-PRESSURE-021` | 3, 5, 7 | objectivity/current-area/FD/residual/balance/open-patch | FD `<=1e-8`, balance `<=1e-8`, other approved gates | +| `FESA-REQ-SHELL-PRESSURE-022` | 6, 7 | exact artifact audit and immutable snapshots | exact required input/displacement CSV only | +| `FESA-REQ-SHELL-PRESSURE-023` | 6, 7 | 729/2187 key mapping, U/UR disposition, tolerance report | U blocking; UR warning; deterministic factor-one comparison | +| `FESA-REQ-SHELL-PRESSURE-024` | 6, 7 | absent reaction/stress families and classification tests | reaction review-only, stress excluded; internal gates retained | + +Coverage: normative IDs `24`, mapped IDs `24`, orphan IDs `0`. Every must requirement has at least one implementation/verification Step and one named test/evidence item. + +## 12. Validation Commands + +현재 execution context는 `.harness/config.json` 부재, existing `.harness/build` cache 존재다. 실행 시 config가 생겼으면 Harness가 그 값을 먼저 resolve하고 reports에 실제 command를 기록한다. + +### `V-CONFIG` — clean/config-resolved MSVC x64 Debug configure + +```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" +``` + +### `V-BUILD` + +```powershell +cmake --build .harness/build --config Debug +``` + +Acceptance: exit `0`; new MSVC warning `0`; `/W4 /WX` 유지; `fesa_solver`, `fesa_cli`, `fesa_unit_tests`, `fesa_integration_tests`, `fesa_reference_tests` all build; runtime staging errors 없음. + +### `V-SHOW` + +```powershell +ctest --test-dir .harness/build -C Debug --show-only=json-v1 +``` + +Acceptance: exit `0`, discovered count `>0`, 모든 새 named suite가 inventory에 존재. + +### `V-FOCUSED` + +```powershell +ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(InpSyntax|ShellSurfacePressureInput|ShellSurfacePressureDomain|ShellSurfacePressureKernel|SurfacePressureAssembly|LinearShellSurfacePressure|NonlinearShellSurfacePressure|ShellSurfacePressureApplication|ShellSurfacePressureReference)\." +``` + +Acceptance: exit `0`, selected count `>0`, failed `0`. + +### `V-FULL` + +```powershell +ctest --test-dir .harness/build -C Debug --output-on-failure +``` + +Acceptance: exit `0`, failed `0`, existing no-pressure/beam/shell/nonlinear/reference regressions pass. + +### `V-REFERENCE` + +```powershell +ctest --test-dir .harness/build -C Debug --output-on-failure -R "^ShellSurfacePressureReference\." +``` + +Acceptance: exit `0`; exact artifact post-snapshots equal pre-snapshots; U blocking pass; any UR deviations warning-only; internal balance pass; 729 wide/2,187 logical rows per family exact; reaction/stress verdict exclusion exact. + +Harness Python behavior/file은 범위 밖이므로 이 plan에는 Python test 실행을 넣지 않는다. 별도 승인된 Harness/Python 변경이 발생하는 경우에만 다음을 추가한다. + +```powershell +uv run --with pytest python -m pytest -v -rs +``` + +## 13. Risks and Downstream Handoff + +| risk | mitigation / stop condition | +| --- | --- | +| existing `Load` abstraction에 follower tangent를 강제로 넣어 ownership 왜곡 | 별도 evaluator/assembler candidate 유지; public nodal load contract를 변경하지 않음 | +| surface parser와 topology resolution order 혼동 | topology finalize 후 surface, surface 후 step binding 순서 고정 | +| duplicate normalization이 additive DSLOAD와 혼동 | facet exact duplicate만 normalize; DSLOAD records는 항상 distinct/additive | +| nonlinear sign 또는 factor double application | force and residual FD 두 부호 모두 test; factor at assembler boundary once | +| tangent symmetrization 또는 SPD solver 경로 | antisymmetric evidence test; existing `MklPardisoTangentSolver` `mtype=11` spy/adapter tests | +| invalid geometry가 zero load에서 bypass | evaluator zero pressure/factor geometry rejection test | +| parallel nondeterminism | worker-local candidates + fixed source/facet/Gauss serial reduction; repeated byte/metric order tests | +| HDF5 schema creep | no-new-path inventory and version `0`/`1` exact tests | +| reference utility가 legacy four-file portfolio를 강요 | per-case required/optional/excluded disposition을 explicit하게 추가; exact pressure two-file gate | +| reference comparison으로 implementation bug 은폐 | artifact/row prechecks first, tolerance unchanged, U blocking, internal balance retained | +| build environment drift | execution-time `.harness/config.json` precedence; actual commands/cache/toolchain recorded | + +Coordinator를 통한 Implementation Agent 단일 handoff: + +- task order: Step 1 → 7, 각 Step 안의 RED/GREEN/VERIFY 순서 +- first tests: §7 named tests와 §8 test IDs +- candidate files/signatures: §§5–6 +- validation commands: §12 +- HDF5/reference mapping: §10 +- tolerance/identity assumptions: common policy unchanged, factor-one, `(instance,node label,component)`, U blocking/UR warning-only +- acceptance criteria: §11 전 24 requirements + each Step metrics +- open constraints: phase files는 사용자 승인 이후 Planning Agent가 materialize; Executor는 별도 explicit request 이후만 실행; reference artifacts와 tolerance read-only + +## 14. Open Issues + +Implementation readiness를 막는 requirements/formulation/I/O/tolerance/reference/architecture gap은 없다. 다음은 blocker가 아닌 execution-time checks다. + +- Step execution 직전 `.harness/config.json` 생성 여부를 다시 확인해 config precedence를 적용한다. +- current build cache paths가 execution host에서 유효한지 `V-CONFIG`/`V-BUILD` 결과로 증명한다. +- 새 feature suite가 `ctest --show-only=json-v1`에 실제 발견되는지 확인한다. +- exact reference artifact pre/post snapshot을 같은 run에서 기록한다. + +현재 critical user decision은 이 7-Step draft의 `approve` 또는 구체적인 revision 요청이다. 승인만으로 phase 파일을 실행하거나 `scripts/execute.py`를 호출하지 않는다. + +## 15. Plan Self-Review + +- 실제 존재가 확인된 existing paths만 modify/read 대상으로 기재했다. +- 새 paths는 §6의 new-file table에서 first owning Step과 함께 명시했다. +- semantic/evaluator/assembler signatures와 linear/nonlinear caller contract를 Steps 사이에 동일하게 유지했다. +- requirements `001`–`024` 모두 Step과 named test/evidence에 연결했고 orphan이 없다. +- exact reference input/CSV, schema-1 factor-one, 729/2,187 cardinality, dispositions와 tolerance mapping을 포함했다. +- 모든 구현 Step에 test-first RED, expected failure, minimal GREEN, focused/full verification, invariants, atomicity, forbidden scope, trace, handoff evidence를 포함했다. +- final Step은 `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` 순서를 literal하게 보존하고 세 implementation-owned reports를 소유한다. +- manual commit, task selection, executor-owned timestamp/status 기록을 계획하지 않았다. +- `phases/`, source, tests, CMake, config/hooks, upstream docs, tolerance, reference artifacts는 이 planning turn에서 변경하지 않았다. +- `phases/index.json`와 phase task files는 사용자 승인 전 materialize하지 않았으며 Harness Executor 실행도 요청하지 않았다. diff --git a/docs/shell-surface-pressure-load/io.md b/docs/shell-surface-pressure-load/io.md new file mode 100644 index 0000000..c551ecc --- /dev/null +++ b/docs/shell-surface-pressure-load/io.md @@ -0,0 +1,639 @@ +# Shell Surface Pressure Load I/O Definition + +## 1. Metadata + +- feature_id: `shell-surface-pressure-load` +- source_requirement: `docs/shell-surface-pressure-load/requirements.md` +- source_research: `docs/shell-surface-pressure-load/research.md` +- source_formulation: `docs/shell-surface-pressure-load/formulation.md` +- source_numerical_review: `docs/shell-surface-pressure-load/numerical-review.md` +- source_reference_model: `docs/shell-surface-pressure-load/reference-model.md` +- status: `ready-for-implementation-planning` +- owner_agent: `io-definition-agent` +- date: `2026-08-31` +- authoritative_output: input lexical sibling `_results.h5` +- linear_schema_version: `0` +- nonlinear_schema_version: `1` +- external_tolerance_authority: `docs/TOLERANCE.md` + +이 문서는 `S4`/`S4R` shell의 named element surface에 작용하는 uniform +surface-based pressure의 입력, semantic identity, validation, authoritative HDF5와 +reference projection만 정의한다. Abaqus 2025 keyword/modeling documentation은 +`*SURFACE`와 `*DSLOAD`의 외부 입력 의미 근거로만 사용한다. FESA가 Abaqus의 full input +compatibility, element 내부 알고리즘, 적분, stabilization, load linearization 또는 output +생성 절차와 동등하다는 주장은 하지 않는다. + +## 2. Abaqus Input Scope + +### 2.1 Compatibility boundary + +승인된 추가 입력은 assembly-level +`*SURFACE, TYPE=ELEMENT, NAME=`와 step-level `*DSLOAD`의 +`, P, `뿐이다. Surface member는 identity instance의 +`S4` 또는 `S4R` element를 `SPOS` 또는 `SNEG`로 선택한다. Linear static은 reference +configuration, `*STEP, NLGEOM=YES` nonlinear static은 current-configuration follower +pressure와 external tangent를 사용한다. + +이 문서가 명시하지 않은 `*SURFACE`, `*DSLOAD`, element, load, procedure 또는 scope +variant는 지원하지 않는다. Unknown model-affecting keyword도 fail-closed다. 기존 output +request allowlist만 결과를 바꿀 수 없다는 전제에서 warning 후 no-op이다. + +### 2.2 Keyword support table + +`supported`는 이 feature의 valid input에서 parse하고 semantic model에 반영한다. +`unsupported`는 명확한 non-success diagnostic으로 거부한다. +`ignored-with-warning`은 requested result를 바꿀 수 없는 기존 output-control syntax만 +건너뛴다. + +| keyword | policy | purpose / required subset | unsupported behavior | +| --- | --- | --- | --- | +| `*HEADING` | `supported` | 기존 heading block; 해석 의미 없음 | parameter 또는 잘못된 keyword line은 `input-syntax` | +| `*INCLUDE` | `unsupported` | 이 feature는 single physical input source만 허용 | 모든 parameter/data form을 `unsupported-keyword`로 거부; include를 열지 않음 | +| `*PART`, `*END PART` | `supported` | 기존 part topology/material/section wrapper | nested/mismatched wrapper 거부 | +| `*NODE` | `supported` | positive source label와 finite global `X,Y,Z` | duplicate/nonfinite/cardinality error 거부 | +| `*NSET` | `supported` | 기존 node-set subset 및 `GENERATE` | unresolved/duplicate-incompatible/cross-scope target 거부 | +| `*ELEMENT` | `supported` | 이 feature의 pressure target은 `TYPE=S4|S4R`, four-node connectivity | 다른 target type 또는 잘못된 connectivity 거부 | +| `*ELSET` | `supported` | 기존 element-set subset 및 `GENERATE`; assembly form은 explicit `INSTANCE=`; CAE의 result-neutral `INTERNAL` flag 허용 | 그 밖의 parameter와 unresolved/cyclic/ambiguous/cross-scope membership 거부 | +| `*MATERIAL` | `supported` | 기존 named material | duplicate/empty name 거부 | +| `*ELASTIC` | `supported` | 기존 finite linear isotropic `E, nu` | unsupported material form/nonfinite data 거부 | +| `*SHELL SECTION` | `supported` | 기존 finite positive thickness, material와 `ELSET` mapping | missing/incompatible reference 거부 | +| `*ASSEMBLY`, `*END ASSEMBLY` | `supported` | identity-instance topology와 assembly surface scope | nested assembly 또는 malformed scope 거부 | +| `*INSTANCE`, `*END INSTANCE` | `supported` | existing identity instance only | transform data, nested instance 또는 unknown part 거부 | +| `*SURFACE` | `supported` | 아래 §2.3의 assembly-level element surface만 지원 | 다른 scope/type/parameter/member form은 fail-closed | +| `*BOUNDARY` | `supported` | 기존 essential DOF 1–6 constraint subset | unsupported target/DOF/data form 거부 | +| `*CLOAD` | `supported` | 기존 nodal generalized concentrated-load subset | 기존 allowlist 밖 form 거부; pressure alias로 사용하지 않음 | +| `*DLOAD` | `unsupported` | 이 feature의 `*DSLOAD P`와 다른 element-face load | 언제나 `unsupported-keyword`; `P n`을 `P`로 변환하지 않음 | +| `*DSLOAD` | `supported` | 아래 §2.4의 named-surface uniform `P` | parameter, 다른 load label/distribution/cardinality는 fail-closed | +| `*STEP`, `*END STEP` | `supported` | exactly one static step; `NLGEOM`은 §2.5만 | 두 번째 step, propagation/restart 의미 거부 | +| `*STATIC` | `supported` | 기존 linear 또는 approved full-Newton static control data | dynamics/contact/thermal/perturbation procedure 거부 | +| `*OUTPUT` | `ignored-with-warning` | 기존 `FIELD|HISTORY` allowlist; mandatory HDF5를 변경하지 않음 | allowlist 밖 model-affecting parameter는 거부 | +| `*NODE OUTPUT` | `ignored-with-warning` | variable data를 warning 후 no-op | mandatory nodal output을 제거/추가하지 않음 | +| `*ELEMENT OUTPUT` | `ignored-with-warning` | variable data를 warning 후 no-op | mandatory MITC4 recovery를 제거/추가하지 않음 | +| `*PREPRINT`, `*RESTART`, `*TRANSVERSE SHEAR STIFFNESS`, `*CONTACT OUTPUT` | `ignored-with-warning` | 기존, result-neutral allowlist만 | 해석 의미를 바꾸는 variant는 거부 | + +### 2.3 Exact `*SURFACE` grammar + +지원 keyword line의 EBNF는 다음과 같다. Token 비교는 ASCII case-insensitive다. + +```text +surface_keyword := "*SURFACE" "," type_parameter "," name_parameter + | "*SURFACE" "," name_parameter "," type_parameter +type_parameter := "TYPE" "=" "ELEMENT" +name_parameter := "NAME" "=" surface_name +surface_name := name_token_without_dot + +surface_member := direct_member "," side + | elset_member "," side +direct_member := instance_name "." positive_element_label +elset_member := assembly_elset_name +side := "SPOS" | "SNEG" +``` + +Normative restrictions: + +1. `*SURFACE`는 `*ASSEMBLY`와 `*END ASSEMBLY` 사이이며 어떤 `*INSTANCE` block 밖에 + 있어야 한다. Part-level 또는 instance-block-level `*SURFACE`는 이번 subset에서 + `unsupported-surface-scope`다. +2. Keyword parameter는 `TYPE=ELEMENT`와 `NAME=` 각각 하나뿐이다. Parameter order는 + 위 두 순서 모두 허용하지만 duplicate, flag parameter와 `TRIM`, `COMBINE`, + `PROPERTY`, `REGION TYPE` 등 추가 parameter는 거부한다. +3. 각 data line은 정확히 두 개의 nonempty field다. Side는 `SPOS` 또는 `SNEG`뿐이다. +4. Direct member는 정확히 `.`이다. Assembly + scope의 bare element label, `.