baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: group solver evidence by feature

Browse Source
This commit is contained in:
KOKO\Mimi
2026-08-15 02:18:26 +09:00
parent aa5d271a2e
commit 8b42e7883b
38 changed files with 83 additions and 1903 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/linear-static-mitc4-shell/build-test.md
+193
View File
@@ -0,0 +1,193 @@
# Linear Static MITC4 Shell Build/Test Report
## Metadata
- feature_id: `linear-static-mitc4-shell`
- source_commit: `820ba30c717b3d0e113775608e20dfd5fbc05d53`
- source_implementation_report: `N/A`; Harness completion evidence is recorded in
`phases/linear-static-mitc4-shell/index.json`
- source_implementation_plan:
`docs/implementation-plans/linear-static-mitc4-shell-implementation-plan.md`
- status: `pass-for-reference-verification`
- owner_agent: `build-test-executor-agent`
- date: `2026-08-13`
## Verdict
The formal build/test gate passes. A fresh Visual Studio 18 2026/MSVC x64 Debug
configuration, clean full rebuild, three implementation-plan-focused CTest runs,
nonzero JSON discovery, full CTest regression, and the required Harness Python
self-test all completed successfully.
- clean full rebuild: exit `0`; compiler/linker warning scan `0`; error scan `0`
- focused kernel/model/assembly/recovery regex: `87/87` passed
- focused linear-static lifecycle regex: `10/10` passed
- focused MITC4 reference-test regex: `8/8` passed
- CTest discovery: `144` tests, including `32` names containing `Mitc4`
- full CTest after clean rebuild: `144/144` passed
- Harness Python self-test: `7/7` passed
- failed tests: `0`
- required S4 reference hash mismatches or Git changes: `0`
This verdict authorizes handoff to Reference Verification only. It does not approve
reference tolerance results, physics sanity, or release readiness.
## Execution Environment
- os: `Microsoft Windows 11 Home 10.0.26200 build 26200`
- branch: `feat-linear-static-mitc4-shell`
- source_head: `820ba30c717b3d0e113775608e20dfd5fbc05d53`
- generator: `Visual Studio 18 2026`
- MSBuild: `18.8.2+ce25c0108`
- compiler: `MSVC 19.51.36252.0`
- compiler_architecture: `x64`
- Windows SDK: `10.0.26100.0`
- language/config: `C++17 / Debug`
- CMake: `4.4.0`
- build_dir: `.harness/build`
- harness_config: absent
- project_selection: auto CMake from root `CMakeLists.txt`
- command_discovery_path: default CMake/MSVC x64 Debug with implementation-plan
generator and dependency paths
- resolved dependencies: GoogleTest `C:/git/googletest`; oneMKL `2026.1.0`;
oneTBB package path `2023.1`; HDF5 package path `2.1.1`
The generated compiler metadata at
`.harness/build/CMakeFiles/4.4.0/CMakeCXXCompiler.cmake` independently confirms
`CMAKE_CXX_COMPILER_ID=MSVC` and version `19.51.36252.0`.
## Command Log Summary
All durations below are wall-clock durations measured for the command. The initial
green chain was retained as corroborating evidence; the later clean-rebuild chain is
the canonical acceptance evidence.
| order | command | exit_code | duration | relevant stdout/stderr tail |
| ---: | --- | ---: | ---: | --- |
| 1 | `git status --short --branch; git rev-parse HEAD` | 0 | `0.8 s` | Clean `feat-linear-static-mitc4-shell`; HEAD matched `820ba30...`. |
| 2 | Required dependency `Test-Path` precheck from the implementation plan | 0 | `0.215 s` | All four GoogleTest/MKL/TBB/HDF5 paths returned `True`. |
| 3 | `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"` | 0 | `8.684 s` | MSVC `19.51.36252.0`, MKL `2026.1.0`; `Configuring done`, `Generating done`. The failed pthread probes were normal CMake feature probes; `Found Threads: TRUE`. |
| 4 | `cmake --build .harness/build --config Debug` | 0 | `4.382 s` | Initial incremental build produced `fesa.exe` and all three test executables; warning/error scan `0/0`. |
| 5 | `ctest --test-dir .harness/build -C Debug -R "DomainModel|InpDomainMapping|Mitc4Geometry|Mitc4Shell|DofManager|EssentialConstraints|SparseAssembly|LoadAssembly|ResultRecovery|Hdf5ResultsWriter" --output-on-failure` | 0 | `5.743 s` | `100% tests passed out of 87`; failed `0`. |
| 6 | `ctest --test-dir .harness/build -C Debug -R "LinearStaticCli|Mitc4ShellCli" --output-on-failure` | 0 | `1.442 s` | `100% tests passed out of 10`; failed `0`. |
| 7 | `ctest --test-dir .harness/build -C Debug -R "Mitc4ReferenceComparison|Mitc4S4Reference" --output-on-failure` | 0 | `1.377 s` | `100% tests passed out of 8`; failed `0`. |
| 8 | `ctest --test-dir .harness/build -C Debug --show-only=json-v1` | 0 | `0.208 s` | Discovered `144` tests; `32` test names contained `Mitc4`. |
| 9 | `ctest --test-dir .harness/build -C Debug --output-on-failure` | 0 | `9.789 s` | Initial full regression: `144/144` passed; failed `0`. |
| 10 | First environment/reference audit helper | 1 | `0.9 s` | Non-gating report-generation error: it hardcoded nonexistent CMake internal directory `CMakeFiles/4.3.0`; both S4 hashes had already matched before the helper stopped. No build or test failed. |
| 11 | Corrected dynamic environment/reference audit helper | 0 | `0.583 s` | Located `CMakeFiles/4.4.0/CMakeCXXCompiler.cmake`; confirmed MSVC/version, both S4 hashes, no S4 diff, and clean worktree. |
| 12 | `cmake --build .harness/build --config Debug --target clean` | 0 | `1.251 s` | Generated Visual Studio clean target completed. |
| 13 | `cmake --build .harness/build --config Debug` | 0 | `94.616 s` | Canonical clean rebuild compiled/linked the solver, CLI, and all test executables; `89` output lines, warning scan `0`, error scan `0`. |
| 14 | `cmake --build .harness/build --config Debug --target fesa_unit_tests` | 0 | `1.943 s` | `fesa_solver`, GoogleTest, and `fesa_unit_tests.exe` confirmed. |
| 15 | Focused kernel/model/assembly/recovery regex from order 5 | 0 | `4.863 s` | Canonical focused run: `87/87` passed; failed `0`. |
| 16 | `cmake --build .harness/build --config Debug --target fesa_integration_tests` | 0 | `1.712 s` | `fesa_solver`, GoogleTest, and `fesa_integration_tests.exe` confirmed. |
| 17 | Focused lifecycle regex from order 6 | 0 | `1.531 s` | Canonical focused run: `10/10` passed; failed `0`. |
| 18 | `cmake --build .harness/build --config Debug --target fesa_reference_tests` | 0 | `1.769 s` | `fesa_solver`, GoogleTest, and `fesa_reference_tests.exe` confirmed. |
| 19 | Focused reference regex from order 7 | 0 | `1.511 s` | Canonical focused run: `8/8` passed; failed `0`; S4 end-to-end tests were included. |
| 20 | `ctest --test-dir .harness/build -C Debug --show-only=json-v1` | 0 | `0.080 s` | Canonical discovery: `144` total, `32` MITC4-named; unit/integration/reference labels `121/10/13`. |
| 21 | `ctest --test-dir .harness/build -C Debug --output-on-failure` | 0 | `9.669 s` | Canonical full regression: `100% tests passed out of 144`; failed `0`; CTest real time `9.62 s`. |
| 22 | Full `reference/` Git scope and worktree audit | 0 | `0.362 s` | `reference_diff_count=0`, `reference_status_count=0`; branch and HEAD unchanged. |
| 23 | `git merge-base dev HEAD` plus changed-file scope audit | 0 | `0.321 s` | Merge base `a058ef7...`; detected `scripts/execute.py`, so Harness Python self-test was required. |
| 24 | `uv run --with pytest python -m pytest -v -rs` | 0 | `4.651 s` | Python `3.11.15`, pytest `9.1.1`; `7 passed in 0.11s`; failed `0`. |
## Validation Results
| validation_stage | result | evidence |
| --- | --- | --- |
| clean baseline | pass | Branch and HEAD matched the requested baseline; worktree was clean before report creation. |
| dependency precheck | pass | All four implementation-plan dependency paths existed. |
| fresh configure | pass | VS18/x64 configure exit `0`; compiler metadata is MSVC x64. |
| clean full build | pass | Exit `0`; solver, CLI, unit, integration, and reference targets compiled/linked. |
| compiler warning policy | pass | Clean rebuild emitted zero warning lines and zero compiler/linker error lines; product CMake uses warnings-as-errors. |
| feature-specific tests | pass | Approved focused regexes passed `87/87`, `10/10`, and `8/8`. |
| CTest discovery | pass | Nonzero inventory: `144` tests, including `32` MITC4-named tests. |
| full CTest | pass | `144/144` passed after the clean rebuild. |
| Harness self-test | pass | Required because `scripts/execute.py` differs from the `dev` merge base; `7/7` passed. |
| reference immutability | pass | Required S4 SHA-256 values match; entire `reference/` tree has no Git diff or status entry. |
## CTest Inventory
| inventory | count |
| --- | ---: |
| all discovered tests | 144 |
| unit label | 121 |
| integration label | 10 |
| reference label | 13 |
| test names containing `Mitc4` | 32 |
| failed tests | 0 |
The `32` MITC4-named tests comprise `30` tests in `Mitc4*` suites plus
`DomainModel.Mitc4ShellRecordsPreserveSourceAndInternalIdentity` and
`InpDomainMapping.MapsS4AndS4rThroughOneMitc4Identity`. The broader focused regex
also exercises shared Domain, DOF, constraints, assembly, recovery, and HDF5 seams.
CTest currently applies the target-wide legacy label
`linear-static-3d-euler-beam` to all `144` tests and has no separate MITC4 label.
The approved implementation plan explicitly permits exact suite regex filtering,
which was used here, so this labeling limitation is nonblocking.
## Warning and Failure Audit
- Clean rebuild warning lines: `0`.
- Clean rebuild compiler/linker error lines: `0`.
- Focused CTest failures: `0`.
- Full CTest failures: `0`.
- Harness Python failures: `0`.
- Configure probes for POSIX pthread symbols reported expected negative probe
results on MSVC before CMake resolved `Threads: TRUE`; this is not a configure
warning or failure.
- One report-generation helper failed because it assumed a CMake internal versioned
directory. The corrected dynamic lookup passed. This incident did not affect
configure, compile, link, test, reference artifacts, or the gate verdict.
## Reference Read-Only Audit
| exact approved path | observed SHA-256 | expected match |
| --- | --- | --- |
| `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` | yes |
| `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` | yes |
The post-test audit found zero changed paths anywhere under `reference/`. No Abaqus
or other reference solver was run.
## Failure Classification
- classification: `N/A`
- primary_failure: `N/A`
- first_failed_build_or_test_command: `N/A`
- failed_target_or_test: `N/A`
- correction_handoff: `N/A`
- non_gating_incident: report-only environment metadata lookup used the wrong CMake
internal directory and was rerun successfully; no product correction is required
## Failed Test Inventory
None. All focused, full CTest, and Harness Python tests passed.
## Handoff Recommendation
| target_agent | reason | required_input |
| --- | --- | --- |
| Reference Verification Agent | Build/test status is `pass-for-reference-verification`. | This report, source HEAD `820ba30...`, `.harness/build/tests/Debug/fesa_reference_tests.exe`, and the unchanged declared S4 input/CSV pair. |
The focused reference CTest generated/used build-local comparison evidence, but the
Build/Test Executor does not interpret that evidence as the formal reference
tolerance verdict. Reference Verification must independently inspect and report it.
## No-Change Assertion
- source_files_modified: `false`
- test_files_modified: `false`
- cmake_files_modified: `false`
- requirements_formulation_io_numerical_reference_documents_modified: `false`
- phase_files_modified: `false`
- tolerance_policies_modified: `false`
- reference_artifacts_modified: `false`
- owned_report_modified: `true`
- notes: The worktree was clean at the requested source HEAD before this report was
created. Build products remained under the ignored `.harness/build/` directory.
## Open Issues
- None blocking Reference Verification.
- The target-wide legacy CTest label prevents a precise MITC4 label count; exact
implementation-plan suite regexes provide the approved focused test entry point.
docs/linear-static-mitc4-shell/coordination.md
+42
View File
@@ -0,0 +1,42 @@
# Linear Static MITC4 Shell Coordination Report
## Metadata
- feature_id: linear-static-mitc4-shell
- status: completed
- owner_agent: coordinator-agent
- date: 2026-08-15
- migration_note: Existing evidence was relocated without rerunning workflow gates.
## Worklist
| stage | owner | status | evidence |
| --- | --- | --- | --- |
| 1. requirements | requirement-agent | passed | `requirements.md` |
| 2. research | research-agent | passed | `research.md` |
| 3. formulation | formulation-agent | passed | `formulation.md` |
| 4. numerical and reference | numerical-review-agent | passed | `numerical-review.md`; `reference-model.md` |
| 5. I/O | io-definition-agent | passed | `io.md` |
| 6. implementation and verification | implementation-planning-agent; implementation-agent | passed | `implementation-plan.md`; `build-test.md`; `reference-comparison.md` |
| 7. physics | physics-evaluation-agent | passed | `physics-evaluation.md` |
| 8. release | release-agent | passed | `release.md` |
## Current Progress
- active_sub_agent: none
- next_handoff: none
- closure_evidence: `release.md` status `ready-for-release`
- workflow_disposition: completed
- historical_gap: No standalone `implementation-report.md` existed before migration; no replacement was fabricated.
## Decision Log
| date | decision | evidence | rationale |
| --- | --- | --- | --- |
| 2026-08-15 | Record migrated workflow as completed | `release.md` | Preserve the existing release verdict without retroactive gate execution. |
## Blockers and Rework
- active_blockers: none
- correction_attempt_count: 0
- needs_user_decision: false
docs/linear-static-mitc4-shell/formulation.md
+1711
View File
File diff suppressed because it is too large Load Diff
docs/linear-static-mitc4-shell/implementation-plan.md
+921
View File
@@ -0,0 +1,921 @@
# Linear Static MITC4 Shell Implementation Plan
> **For agentic implementation workers:** 이 문서는 사용자 승인 전 `draft`다. 승인 후
> Implementation Planning Agent가 같은 내용으로 Harness phase planning files만
> materialize한다. Implementation Agent는 승인된 phase의 pending Step을
> `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`에 따라 하나씩 실행해야 하며,
> Harness hook/runner lifecycle을 우회해서는 안 된다.
## 1. Metadata
- feature_id: `linear-static-mitc4-shell`
- document_type: `implementation-plan`
- status: `ready-for-implementation`
- approval_state: `harness-step-draft-approved-2026-08-12`
- owner_agent: `implementation-planning-agent`
- date: `2026-08-13`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- source_research: `docs/research/linear-static-mitc4-shell-research.md`
- source_formulation: `docs/formulations/mitc4-shell-formulation.md`
- source_numerical_review:
`docs/numerical-reviews/linear-static-mitc4-shell-review.md`
- source_io_definition:
`docs/io-definitions/linear-static-mitc4-shell-io.md`
- source_reference_models:
`docs/reference-models/linear-static-mitc4-shell-reference-models.md`
- target_platform: `Windows x64 / MSVC / C++17`
- build_system: `CMake + CTest`
- execution_infrastructure: `Python Harness`
- current_numerical_verdict: `pass-for-implementation-planning`
- harness_task_name_candidate: `linear-static-mitc4-shell`
- implementation_authorized: `true-user-requested-2026-08-12`
- harness_execution_authorized: `true-user-requested-2026-08-12`
- phase_files_authorized: `true-user-approved-2026-08-12`
### Goal
승인된 Abaqus `.inp` subset의 `S4` 및 `S4R` source element를 하나의 FESA
`FESA-MITC4` 선형 정적 shell formulation으로 해석하고, 물리적으로 분리된 fixed
drilling stabilization, deterministic sparse assembly, mandatory HDF5 shell results,
sole declared S4 displacement reference case를 end-to-end로 연결한다.
### Architecture
기존 B33 경로를 파괴하거나 speculative common element hierarchy를 만들지 않는다.
Domain에 shell semantic records를 추가하고, 별도 concrete `Mitc4Shell` kernel과
shell-specific recovery를 만든다. 기존 `Analysis` lifecycle, six-DOF nodal
load/constraint, sparse COO reduction, `LinearSolver`, generic `ResultsWriter` 경계,
HDF5 temporary/self-check/atomic replacement는 재사용한다.
### Tech Stack
- C++17, MSVC `/W4 /WX`
- CMake 3.25+, Visual Studio 18 2026 generator, x64 Debug
- GoogleTest/CTest
- Intel oneAPI MKL and TBB
- HDF5 schema version 0
- Python 3 Harness runner and repository hooks
### Global Constraints
1. 모든 production behavior는 같은 Step 안에서 `RED -> observed failure ->
minimal GREEN -> focused VERIFY -> full VERIFY`를 닫는다.
2. production C++ 파일 변경은 관련 C++ test와 함께 수행한다.
3. public solver headers에 MKL, TBB, HDF5, Win32/vendor type을 노출하지 않는다.
4. Node/Element에 equation ID를 저장하지 않고 `DofManager`만 numbering, scatter,
constrained/free mapping 및 sparse pattern을 소유한다.
5. `S4`와 `S4R`은 같은 FESA numerical path를 사용하며 source metadata만 다르다.
6. physical 20-DOF kernel과 four numerical drilling coordinates를 recovery/output에서
분리한다.
7. reference files를 생성, 수정, rename, repair, normalize하지 않으며 Abaqus를
실행하지 않는다.
8. future geometrically nonlinear residual/tangent, distributed loads, mixed beam-shell
models, reduced integration/hourglass, drilling calibration/energy output,
`NR-O03`/`NR-O04`는 구현 범위 밖이다.
9. 이 `draft`의 승인은 phase planning files 작성만 허용한다. Harness 실행은 별도의
명시적 사용자 요청이 있어야 한다.
## 2. Readiness Check
| gate | evidence | status | planning consequence |
| --- | --- | --- | --- |
| Requirements | `docs/requirements/linear-static-mitc4-shell.md`, 001-072 approved | pass | 모든 must를 task/test에 추적 |
| Research | `docs/research/linear-static-mitc4-shell-research.md` | pass | source-backed MITC4 tying/director/drilling 경계 유지 |
| Formulation | `docs/formulations/mitc4-shell-formulation.md`, `approved-for-implementation-planning` | pass | linear sections만 구현; Section 15 future nonlinear 제외 |
| Numerical Review | `docs/numerical-reviews/linear-static-mitc4-shell-review.md` | pass | critical blocker 없음; planning authorized |
| I/O | `docs/io-definitions/linear-static-mitc4-shell-io.md`, `approved-for-implementation-planning` | pass | keyword, diagnostic, HDF5 schema를 그대로 구현 |
| Reference Model | `docs/reference-models/linear-static-mitc4-shell-reference-models.md` | pass | sole S4 input/CSV pair만 read-only acceptance input으로 사용 |
| Repository seams | parser/model, element/analysis, result/reference 영역 read-only 조사 | pass | candidate files와 current signatures 확인 |
| Toolchain paths | GoogleTest/MKL/TBB/HDF5 config directories 존재 | pass | Section 10의 exact configure command 사용 가능 |
Toolchain path evidence was resolved in this workspace on `2026-08-12`with
`Test-Path -LiteralPath`returning `True`for all four literal directories used in
Sections 10 and 12. They are environment-resolved paths, not placeholders. Each Step
copies the fail-fast path precheck before CMake so a changed machine configuration
stops before RED/GREEN evidence is recorded.
Declared read-only reference inventory:
| case | source | displacement CSV | SHA-256 |
| --- | --- | --- | --- |
| S4 | `reference/shell/shell.inp` | `reference/shell/shell displacements.csv` | input `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF`; CSV `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` |
README, `metadata.json`, Abaqus provenance/version, canonical naming 및 추가 portfolio는
readiness gate가 아니다. 현재 열린 product/numerical 결정은 없다. 남은 승인 항목은
Section 12의 multi-Step Harness draft뿐이다.
## 3. Implementation Scope
### Included behavior
- exactly one `*STEP, *STATIC`, small displacement/small rotation
- four-node `S4`/`S4R` parsing and one internal `FESA-MITC4` identity
- stable source instance/label/type and four-node source ordering
- homogeneous isotropic `E,nu` and centered single-layer constant `t`
- deterministic positive-thickness nodal directors and right-handed frames
- six global nodal DOFs; 24-entry shell scatter
- physical membrane, bending, transverse shear with MITC edge-midpoint tying
- common `2x2x2` Gauss integration for S4 and S4R
- fixed `k_d=10^-3 min(R+)` drilling stabilization from the eight physical
tangent-rotation diagonals only
- nodal BC and global CLOAD; aggregate director-parallel moment rejection
- deterministic global stiffness, constrained partition, factorize-before-load,
effective RHS, solve, full residual/reaction
- physical-only shell recovery, energy/equilibrium/verification metrics
- exact mandatory HDF5 model/result schema and failure-atomic finalization
- direct HDF5-to-Abaqus-displacement comparison: U blocking, UR warning-only
### Non-goals
- Abaqus `S4`/`S4R` algorithm equivalence
- B31 mapping, mixed B33/MITC4 model execution or common public element hierarchy
- `*DLOAD`, pressure, gravity, body/edge/follower load
- composite, offsets, variable thickness, explicit normal/orientation
- reduced integration, hourglass control, MITC4+
- nonlinear state, finite director update, nonlinear residual/tangent execution
- drilling physical strain/load/result/stress/energy, coefficient sweep or calibration
- `NR-O03` smooth-angle and `NR-O04` warp/distortion threshold sweeps
- extra shell benchmarks as a completion gate
- Abaqus execution or reference artifact mutation
## 4. Work Breakdown
Tasks are ordered by implementation dependency. Harness executes Steps 0-13 in strict
order even when the minimal dependency set below is smaller.
| task | depends on |
| --- | --- |
| TASK-00 | none |
| TASK-01 | TASK-00 |
| TASK-02 | TASK-01 |
| TASK-03 | TASK-02 |
| TASK-04 | TASK-03 |
| TASK-05 | TASK-04 |
| TASK-06 | TASK-00; executed after TASK-05 |
| TASK-07 | TASK-04, TASK-06 |
| TASK-08 | TASK-02, TASK-07 |
| TASK-09 | TASK-05, TASK-08 |
| TASK-10 | TASK-05, TASK-09 |
| TASK-11 | TASK-09, TASK-10 |
| TASK-12 | TASK-01, TASK-07, TASK-08, TASK-10, TASK-11 |
| TASK-13 | TASK-11, TASK-12 |
| TASK-14 | TASK-13 |
| TASK-15 | TASK-01, TASK-07, TASK-11 |
| TASK-16 | TASK-00 through TASK-15 |
### TASK-00: `shell-semantic-model`
- Own only model semantic records and immutable Domain access.
- Candidate additions: `Mitc4ShellDefinition`, `ShellSection`, source type enum/value,
internal formulation identity, four-node indices, material/section indices, node
director/frame storage.
- Preserve current B33 records and stable source/internal identity; reject mixed models
at mapping rather than designing a heterogeneous solver hierarchy.
- Tests: `MITC4-MODEL-001`, `MITC4-MODEL-002`.
### TASK-01: `shell-domain-mapping`
- Extend `AbaqusDomainMapper::map(const ParsedInput&)`; keep `AbaqusInputReader`
syntax-only.
- Accept exact S4/S4R and single-layer SHELL SECTION grammar, resolve ELSET/material,
identity wrappers and six-DOF BC/CLOAD.
- Fail closed with exact I/O diagnostic classes for connectivity, assignment,
unsupported option/procedure/mixed model/distributed load.
- Tests: `MITC4-MAP-001` through `MITC4-MAP-004`.
### TASK-02: `shell-director-geometry`
- Add deterministic geometry preprocessing after instance expansion: element normal
candidates, area-weighted nodal director, pairwise orientation validation and nodal
frame tie-break.
- Validate center, eight stiffness points, four tying points and committed recovery
points for finite bases, nonzero surface measure and positive finite Jacobian.
- Do not introduce calibrated angle, warp or distortion thresholds.
- Tests: `MITC4-GEO-001` through `MITC4-GEO-004`.
### TASK-03: `mitc4-kinematics-constitutive`
- Create concrete candidate `Mitc4Shell` without a public base hierarchy.
- Implement shape identities, local frames, `T_p`/`T_d` channel maps, direct
membrane/bending terms, all four covariant MITC tying samples/interpolation,
engineering-shear factors, `C_ps/C_5/A/D/A_s` and fixed point order.
- Keep all intermediate physical coordinates at 20 DOFs.
- Tests: `MITC4-KIN-001` through `MITC4-KIN-005`.
### TASK-04: `mitc4-stiffness-drilling`
- Form physical `K20` with common `2x2x2` integration and embed by congruence.
- Build `R+` only from the eight physical tangent-rotation diagonals, use exact
`k_d=10^-3 min(R+)` and `T_d^T(k_d I4)T_d`; fail empty/nonfinite `R+`.
- Tests: `MITC4-KERNEL-001` through `MITC4-KERNEL-006`.
### TASK-05: `mitc4-physical-recovery`
- Add only the element-kernel physical recovery seam for generalized strain/resultant,
bottom/middle/top stress and physical element energy.
- Prove pure numerical drill action contributes zero to every physical recovery value.
- Tests: `MITC4-KERNEL-007`, `MITC4-PHYSREC-001`.
### TASK-06: `shell-dof-scatter`
- Retain six per-node full DOFs and add typed 24-entry shell scatter/pattern access;
preserve existing 12-entry B33 behavior.
- Preserve stable full/free/constrained numbering and all-constrained `0x0 Kff`.
- Tests: `MITC4-DOF-001` through `MITC4-DOF-003`.
### TASK-07: `shell-sparse-assembly`
- Dispatch shell topology to `Mitc4Shell::globalStiffness()`.
- Emit 576 element-local COO entries with stable `elementOrder`/`localOrder` into
worker-owned buffers; preserve canonical fixed reduction and diagonal slots.
- Tests: `MITC4-ASM-001` through `MITC4-ASM-003`.
### TASK-08: `shell-load-validation`
- Reuse global six-DOF `LoadAssembler` and existing constraint partition.
- Aggregate CLOAD deterministically before testing exact-zero or
`rho_M=abs(dot(d,M))/norm(M)<=1e-12`; rejected moments never reach stabilization.
- Preserve force/moment units and factorization-before-load lifecycle.
- Tests: `MITC4-LOAD-001` through `MITC4-LOAD-004`.
### TASK-09: `shell-analysis-state`
- Add shell result rows to `AnalysisState` and `result_records.hpp`: four fixed
midsurface locations, local frames, eight generalized strains/resultants,
bottom/middle/top stress, physical energy, equilibrium and verification metrics.
- Preserve stable row order and expose candidate-owned containers only; perform no
element calculation in this task.
- Tests: `MITC4-STATE-001` through `MITC4-STATE-003`.
### TASK-10: `shell-result-recovery`
- Recover full residual `K*d-F` for nodal reaction/equilibrium evidence but call the
kernel physical-only recovery for shell quantities.
- Validate candidates fully before committing state; keep stable row order.
- Tests: `MITC4-REC-001` through `MITC4-REC-005`.
### TASK-11: `shell-hdf5-output`
- Extend `Hdf5ResultsWriter` behind the unchanged generic `ResultsWriter::write`
boundary.
- Add exact schema paths/shapes/component attributes from the I/O contract without
changing B33 dataset meaning.
- Reuse temporary write, finite/schema self-check, close/reopen and atomic replace.
- Tests: `MITC4-H5-001` through `MITC4-H5-004`.
### TASK-12: `shell-linear-static-flow`
- Route a shell Domain through the existing eight-hook `Analysis::run()` lifecycle.
- Preserve assemble/partition, factorize, load/effective RHS, substitute,
reconstruct, full residual/recover, atomic write order and single factorization.
- Validate nonzero prescribed values, singular support and valid all-constrained solve.
- Tests: `MITC4-FLOW-001` through `MITC4-FLOW-004`.
### TASK-13: `shell-reference-comparison`
- Add a test-only MITC4 comparator rather than widening beam-specific assumptions.
- Consume exactly one declared input and displacement CSV per case; map instance,
source node and six displacement components directly to HDF5.
- Precheck header/row set/duplicates/nonfinite/schema/identity before numeric work.
- Apply fixed absolute `1.0e-5` to every U/UR row without a scale-dependent decision
term; U blocks, UR only emits deterministic warning; record all required metrics
and worst row.
- Tests: `MITC4-REF-001` through `MITC4-REF-006`.
### TASK-14: `shell-s4-end-to-end`
- This is declared-case sub-work owned by TASK-13/Step 13's test-only reference module,
not an independent production-module Step.
- Run the declared S4 deck through CLI, authoritative HDF5, schema checks and
read-only comparator.
- Assert source type `S4`, internal `FESA-MITC4` and U pass/UR report behavior.
- Tests: `MITC4-E2E-S4-001`, `MITC4-E2E-S4-002`.
### TASK-15: `shell-s4r-common-path-verification`
- This is non-reference coverage distributed across the existing domain-mapping,
sparse-assembly and HDF5 tests; Step 13 does not consume an S4R Abaqus artifact.
- Assert S4R selects the same FESA-MITC4 integration/kernel/assembly path as an
otherwise identical S4 semantic fixture while preserving only source metadata.
- Tests: `InpDomainMapping.MapsS4AndS4rThroughOneMitc4Identity`,
`SparseAssembly.S4AndS4rSemanticFixturesAssembleIdenticalStiffness`, and the
existing shell HDF5 source-type metadata coverage.
### TASK-16: `mitc4-full-verification`
- Run MSVC x64 Debug full build, CTest discovery, focused feature suites and full CTest.
- Audit warnings, deterministic repeat evidence, required HDF5 inventory, reference
immutability and git diff scope.
- Produce only downstream implementation evidence; do not claim reference verification,
physics sanity or release readiness.
- Tests/audits: `MITC4-VERIFY-001` through `MITC4-VERIFY-004`.
## 5. TDD Test Plan
| test id | initial RED assertion | minimal GREEN behavior | focused verification |
| --- | --- | --- | --- |
| MITC4-MODEL-001 | four-node S4/S4R records/director/source identity do not exist | immutable shell records preserve source and internal identity | `DomainModel.*` |
| MITC4-MODEL-002 | shell section/material/thickness ownership unavailable | one resolved centered homogeneous assignment per element | `DomainModel.*` |
| MITC4-MAP-001 | valid S4/S4R and SHELL SECTION reject | both source types map to FESA-MITC4 | `InpDomainMapping.*` |
| MITC4-MAP-002 | duplicate/unresolved/conflicting section cases lack exact errors | exact assignment/material validation | `InpDomainMapping.*` |
| MITC4-MAP-003 | excluded shell options/mixed models may be ignored | exact fail-closed diagnostics | `InpDomainMapping.*` |
| MITC4-MAP-004 | second/nonstatic/NLGEOM/DLOAD cases lack shell boundary tests | exact procedure/load rejection; no-op output unchanged | `InpDomainMapping.*` |
| MITC4-GEO-001 | planar/rotated/warped directors unavailable | deterministic unit director and right-handed frame | `Mitc4Geometry.*` |
| MITC4-GEO-002 | incident orientation/tie-break is untested | stable area-weighted result across repeated order | `Mitc4Geometry.*` |
| MITC4-GEO-003 | duplicate/bow-tie/zero/reversed/nonfinite geometry may pass | exact geometry failures | `Mitc4Geometry.*` |
| MITC4-GEO-004 | required-point Jacobian inventory absent | every required point finite and positive | `Mitc4Geometry.*` |
| MITC4-KIN-001 | shape/derivative identities unavailable | partition/unity/derivative identities | `Mitc4ShellKinematics.*` |
| MITC4-KIN-002 | frame/T transforms unavailable | orthonormal/right-handed frames and channel selection | `Mitc4ShellKinematics.*` |
| MITC4-KIN-003 | tying values/weights unavailable | four hand-computed covariant tying values | `Mitc4ShellKinematics.*` |
| MITC4-KIN-004 | constitutive/section matrices unavailable | exact coefficients, symmetry, positivity, unit rescaling | `Mitc4ShellConstitutive.*` |
| MITC4-KIN-005 | quadrature order not fixed | exact common 2x2x2 points/weights | `Mitc4ShellKinematics.*` |
| MITC4-KERNEL-001 | no 24x24 shell stiffness | finite symmetric 24x24 stiffness | `Mitc4ShellKernel.*` |
| MITC4-KERNEL-002 | energy congruence unavailable | 20/24 virtual work and energy equal within 1e-12 | `Mitc4ShellKernel.*` |
| MITC4-KERNEL-003 | rigid/rank checks fail | six physical rigid modes, physical rank 14, stabilized rank 18 | `Mitc4ShellKernel.*` |
| MITC4-KERNEL-004 | deformation energy/patch fields unavailable | positive membrane/bending/shear/twist modes | `Mitc4ShellPatch.*` |
| MITC4-KERNEL-005 | R+ membership/coefficient not implemented | exact rotational-only min and 1e-3 factor | `Mitc4ShellDrilling.*` |
| MITC4-KERNEL-006 | empty R+ and pure drill behavior unspecified | deterministic failure; pure drill stabilized | `Mitc4ShellDrilling.*` |
| MITC4-KERNEL-007 | drilling contaminates recovery/energy | physical recovery/energy exact zero for pure drill | `Mitc4ShellDrilling.*` |
| MITC4-PHYSREC-001 | kernel recovery contract is not independently callable | exact physical strain/resultant/stress/energy for hand field | `Mitc4ShellPhysicalRecovery.*` |
| MITC4-DOF-001 | shell scatter fixed at 12 | stable 24-entry scatter in node/component order | `DofManager.*` |
| MITC4-DOF-002 | shell pattern unavailable | sorted unique pattern with all diagonals | `DofManager.*` |
| MITC4-DOF-003 | constraint roundtrip lacks shell-sized system | no/mixed/all constraints and nonzero values roundtrip | `DofManager.*; EssentialConstraints.*` |
| MITC4-ASM-001 | assembler rejects four-node element | 576 stable local contributions assemble | `SparseAssembly.*` |
| MITC4-ASM-002 | thread/repetition may reorder | serial/TBB/repeated CSR bytes and values match | `SparseAssembly.*` |
| MITC4-ASM-003 | S4/S4R could branch numerically | identical semantic fixtures produce identical K | `SparseAssembly.*` |
| MITC4-LOAD-001 | shell force/moment fixture unavailable | six global components aggregate stably | `LoadAssembly.*` |
| MITC4-LOAD-002 | director-parallel exact-zero branch untested | zero aggregate moment accepted | `LoadAssembly.*` |
| MITC4-LOAD-003 | rho boundary/rejection untested | <=1e-12 accepted; >1e-12 exact diagnostic | `LoadAssembly.*` |
| MITC4-LOAD-004 | rejected moment might enter drill channel | failure occurs before RHS/substitution | `LoadAssembly.*` |
| MITC4-STATE-001 | AnalysisState has no shell row containers | exact shell row/component/location types are owned | `AnalysisState.*` |
| MITC4-STATE-002 | physical energy/equilibrium/metrics are absent | finite candidate global evidence is stored | `AnalysisState.*` |
| MITC4-STATE-003 | shell candidate rollback is unavailable | invalid candidate leaves prior state unchanged | `AnalysisState.*` |
| MITC4-REC-001 | shell row types absent | four ordered location/frame/strain/resultant rows | `ResultRecovery.*` |
| MITC4-REC-002 | bottom/middle/top stress absent | direct S11/S22/S12 recovery in fixed order | `ResultRecovery.*` |
| MITC4-REC-003 | energy may include drilling | physical strain energy excludes stabilization | `ResultRecovery.*` |
| MITC4-REC-004 | reaction/equilibrium semantics may diverge | full residual, force/moment balance, normalized metrics | `ResultRecovery.*` |
| MITC4-REC-005 | invalid partial rows may commit | nonfinite/inventory failure preserves old state | `ResultRecovery.*` |
| MITC4-H5-001 | shell metadata/model schema missing | exact metadata, elements, director/frame, material/section | `Hdf5ResultsWriter.*` |
| MITC4-H5-002 | mandatory shell result paths missing | exact displacement/reaction/frame/strain/resultant/stress/global rows | `Hdf5ResultsWriter.*` |
| MITC4-H5-003 | output request could filter or drilling paths appear | inventory unconditional; forbidden paths absent | `Hdf5ResultsWriter.*` |
| MITC4-H5-004 | invalid shell candidate may replace final file | self-check failure preserves prior final | `Hdf5ResultsWriter.*` |
| MITC4-FLOW-001 | shell cannot traverse Analysis lifecycle | exact hook order and one factorization | `LinearStaticCli.*` |
| MITC4-FLOW-002 | prescribed shell RHS/reconstruction absent | Ff-Kfc*dc and full displacement correct | `LinearStaticCli.*` |
| MITC4-FLOW-003 | singular/all-constrained behavior unproven | singular fails; 0x0 Kff succeeds | `LinearStaticCli.*` |
| MITC4-FLOW-004 | failed output may commit state | candidate state/output commits only after validation | `LinearStaticCli.*` |
| MITC4-REF-001 | six-column CSV header unsupported | exact MITC4 header maps instance/node/U/UR | `Mitc4ReferenceComparison.*` |
| MITC4-REF-002 | invalid row inventory may be ignored | missing/extra/duplicate/nonfinite/schema mismatch fails first | `Mitc4ReferenceComparison.*` |
| MITC4-REF-003 | tolerance could remain scale-dependent or clamp/row-normalize | exact fixed absolute `1.0e-5` for every U/UR row | `Mitc4ReferenceComparison.*` |
| MITC4-REF-004 | UR may block verdict | U blocks; UR only warns | `Mitc4ReferenceComparison.*` |
| MITC4-REF-005 | report metrics/order incomplete | row decisions, max, normalized, RMS, vector, worst row deterministic | `Mitc4ReferenceComparison.*` |
| MITC4-REF-006 | comparator may require administrative files | only declared input/CSV/HDF5 required | `Mitc4ReferenceComparison.*` |
| MITC4-E2E-S4-001 | S4 deck cannot produce valid shell HDF5 | CLI succeeds with exact S4 metadata/schema | `Mitc4S4Reference.*` |
| MITC4-E2E-S4-002 | S4 U comparison unavailable | all U rows pass; UR fully reported | `Mitc4S4Reference.*` |
| MITC4-VERIFY-001 | feature tests not discoverable | all planned suites discovered/labeled | CTest JSON inventory |
| MITC4-VERIFY-002 | warnings/regressions unknown | MSVC Debug full build passes /W4 /WX | full build |
| MITC4-VERIFY-003 | nondeterminism unknown | repeated focused/full tests pass | full CTest |
| MITC4-VERIFY-004 | artifact governance unknown | reference hashes/path and git diff unchanged | read-only audit |
Numerical thresholds are fixed: frame/symmetry/transformation-energy `<=1e-12`;
rigid action, linear residual and global equilibrium `<=1e-10`. Patch tests compare
against independently hand-computed analytical fields and signs, not the production
routine itself.
## 6. CMake/CTest Plan
### Existing topology to preserve
- production library: `fesa_solver`
- CLI: `fesa_cli`
- unit: `fesa_unit_tests`
- integration: `fesa_integration_tests`
- reference: `fesa_reference_tests`
- aggregate: `fesa_tests`
No new executable target is required. New kernel/test/comparator source files are
explicitly registered in existing source lists. Add `linear-static-mitc4-shell` as an
additive CTest label without removing the B33 label. Because
`gtest_discover_tests()` currently applies target-wide labels, focused Step
verification uses exact suite regexes; label-based MITC4 filtering is enabled only
if per-test labeling can be added without relabeling unrelated B33 tests.
Candidate registrations:
- `src/fesa/CMakeLists.txt`: candidate `model/shell_geometry.cpp`,
`elements/mitc4_shell.cpp` and any separate shell recovery implementation.
- `tests/CMakeLists.txt`: candidate `shell_geometry_test.cpp`,
`mitc4_shell_test.cpp`, optional focused shell recovery/HDF5 tests, and MITC4
reference comparator/test sources.
- Preserve existing runtime staging for MKL/TBB/HDF5 on all three test executables.
CTest discovery must show every suite named in Section 5 before implementation is
considered verified.
## 7. Candidate Files and Ownership
All signatures in this section are candidates for the Implementation Agent to confirm
against the approved contracts during the owning Step; they are not new approved APIs.
| owner/module | candidate files | candidate interface/direction |
| --- | --- | --- |
| model | `include/fesa/model/model_types.hpp`, `include/fesa/model/domain.hpp`, `src/fesa/model/domain.cpp` | separate shell records/accessors; no equation IDs |
| shell semantic geometry | candidate new `include/fesa/model/shell_geometry.hpp`, `src/fesa/model/shell_geometry.cpp` | director/frame and required-point geometry validation without parser/kernel dependency |
| Abaqus semantic map | `include/fesa/io/abaqus/domain_mapper.hpp`, `src/fesa/io/abaqus/domain_mapper.cpp` | keep `map(const ParsedInput&) -> Result<Domain>` |
| analysis view | `include/fesa/analysis/analysis_model.hpp`, `src/fesa/analysis/analysis_model.cpp` | non-owning active shell view only if record representation requires |
| shell kernel | new `include/fesa/elements/mitc4_shell.hpp`, `src/fesa/elements/mitc4_shell.cpp` | concrete create/stiffness/physical-recover API |
| DOF | `include/fesa/fem/dof_manager.hpp`, `src/fesa/fem/dof_manager.cpp` | typed `array<size_t,24>` shell scatter beside B33 scatter |
| sparse assembly | `src/fesa/assembly/sparse_assembler.cpp` | topology dispatch; unchanged public assemble signature |
| load | `src/fesa/assembly/load_assembler.cpp` only if aggregate director projection cannot live in semantic validation | reuse full six-DOF assembly |
| state/results | `include/fesa/analysis/analysis_state.hpp`, `src/fesa/analysis/analysis_state.cpp`, `include/fesa/results/result_records.hpp` | additive shell rows/global metrics |
| recovery | `include/fesa/results/result_recovery.hpp`, `src/fesa/results/result_recovery.cpp` or new shell-specific cpp | candidate-then-commit; physical/drill split |
| HDF5 | `src/fesa/io/hdf5/hdf5_results_writer.cpp` | generic public writer unchanged |
| lifecycle | `src/fesa/analysis/linear_static_analysis.cpp` | preserve existing hook order |
| app | `tests/integration/app/fesa_application_test.cpp`; production app only if feature dispatch needs it | CLI syntax unchanged |
| reference tests | new `tests/reference/mitc4_reference_comparison.hpp/.cpp` and tests | test-only direct HDF5/CSV comparator |
| build graph | `src/fesa/CMakeLists.txt`, `tests/CMakeLists.txt` | explicit additive source/test registration |
Candidate kernel seam:
```cpp
class Mitc4Shell {
public:
static Result<Mitc4Shell> create(
std::array<const Node*, 4> nodes,
std::array<Vector3, 4> initialDirectors,
const ShellSection& section,
const LinearElasticMaterial& material);
[[nodiscard]] Matrix physicalLocalStiffness20() const;
[[nodiscard]] Matrix globalStiffness24() const;
[[nodiscard]] Result<ShellRecovery> recoverPhysical(
const Vector& globalElementDisplacement24) const;
};
```
This candidate explicitly avoids returning drill energy/results and avoids a common
public `Element` hierarchy. Exact value/reference ownership and math types are decided
inside TASK-03 after compiling the first RED test.
## 8. Data Flow Contract
```text
.inp bytes
-> AbaqusInputReader (syntax/source locations only)
-> AbaqusDomainMapper (approved semantics, S4/S4R provenance, section/material)
-> geometry/director preprocessing
-> immutable Domain
-> non-owning AnalysisModel
-> DofManager (6 DOF/node, 24-entry shell scatter, free/constrained maps)
-> Mitc4Shell physical K20 + fixed drill embedding -> global K24
-> worker-local COO -> stable SparseMatrix reduction
-> Kff/Kfc/Kcf/Kcc partition -> Kff factorize
-> aggregate CLOAD/director check -> Ff-Kfc*dc
-> substitute -> full displacement
-> full residual K*d-F
-> physical-only shell recovery + global evidence
-> validated candidate AnalysisState
-> temporary results.h5 -> schema self-check -> atomic finalization
authoritative results.h5
-> test-only MITC4 HDF5 projection
-> exact source instance/node/component row-set precheck
-> read-only declared Abaqus displacement CSV
-> U blocking / UR warning-only deterministic report
```
Invariants:
- Domain outlives AnalysisModel; no Domain copying.
- Source labels/instances/types never become equation indices.
- `S4`/`S4R` source type is metadata; both call the same kernel/quadrature.
- full residual uses stabilized global K; shell strain/resultant/stress/physical energy
use physical recovery only.
- HDF5 `nodal/reaction` is full residual; constraint mask decides reaction versus free
residual evidence.
- result rows use fixed GP1..GP4 and BOTTOM/MIDDLE/TOP identity; no averaging or Abaqus
integration-point relabeling.
- state/output mutation occurs only after complete validation.
## 9. Acceptance Traceability Matrix
The inclusive ranges below cover every must requirement `001` through `072` exactly
once without gap or overlapping requirement range.
| requirement range | owning tasks | test/evidence id | reference model id | acceptance |
| --- | --- | --- | --- | --- |
| 001 | TASK-01, TASK-12 | MAP-004, FLOW-001 | N/A | one static step only; deterministic rejection otherwise |
| 002-004 | TASK-00, TASK-01, TASK-11, TASK-14, TASK-15 | MODEL-001, MAP-001, H5-001, S4 E2E plus S4R common-path tests | `shell-s4` for reference; S4R N/A | S4/S4R one kernel; distinct stable source identity |
| 005 | TASK-00, TASK-06, TASK-11 | MODEL-001, DOF-001/003, H5-001/002 | N/A | exact six-component order; no distributed equation ownership |
| 006-010 | TASK-00, TASK-01 | MODEL-002, MAP-002/003 | N/A | finite E,nu,t; one assignment; unsupported meanings fail |
| 011-016 | TASK-02, TASK-03 | GEO-001..004, KIN-002 | N/A | deterministic unit directors; exact geometry predicates |
| 017-020 | TASK-01, TASK-08 | MAP-004, LOAD-001..004 | N/A | six-DOF BC/CLOAD; drilling/distributed load fails |
| 021-023 | TASK-01 | MAP-001..004 and existing no-op regression | N/A | approved parser subset/identity wrappers/no-op policy |
| 024-030 | TASK-00, TASK-06, TASK-07, TASK-09, TASK-10, TASK-12, TASK-16 | MODEL, DOF, ASM, STATE, REC, FLOW, VERIFY suites | N/A | ownership, deterministic assembly, lifecycle, residual reaction |
| 031-038 | TASK-03, TASK-04, TASK-05, TASK-07, TASK-10 | KIN, KERNEL, PHYSREC, ASM-003, REC-003 | N/A | physical 5-DOF embedding, exact drilling, same quadrature, invariants |
| 039-048 | TASK-09, TASK-10, TASK-11, TASK-12 | STATE-001..003, REC-001..005, H5-001..004, FLOW-004 | N/A | mandatory finite schema/results and atomic commit |
| 049 | TASK-00 through TASK-16 | every production Task records RED/failure/GREEN/focused/full VERIFY; VERIFY-001..003 | `shell-s4` where reference-dependent | TDD evidence, related C++ tests, MSVC Debug no-warning build and full CTest |
| 050 | TASK-02 through TASK-05, TASK-07 | GEO-001/002, KIN-001/002, KERNEL-001..004, ASM-002 | N/A | frames, Jacobian, symmetry, transformation, six modes, positivity and repeatability |
| 051 | TASK-02 through TASK-05, TASK-10, TASK-12 | GEO-001, KERNEL-001..003, REC-004, FLOW-002 | N/A | exact normalized 1e-12 and 1e-10 algebraic thresholds |
| 052 | TASK-03 through TASK-05, TASK-10 | KIN-003/004, KERNEL-004, PHYSREC-001, REC-001/002 | N/A | independent membrane, bending, shear, twist fields and recovery signs/order |
| 053 | TASK-04, TASK-05, TASK-14 | KERNEL-001..007, PHYSREC-001, declared S4 E2E suite | `shell-s4` | formulation invariants/patches and the S4 reference case pass |
| 054 | TASK-02 | GEO-001..004 | N/A | exact valid/rejected geometry inventory; no NR-O03/O04 |
| 055 | TASK-16 | VERIFY scope audit | N/A | extra benchmark portfolio is explicitly nonblocking and absent from completion gate |
| 056 | TASK-04, TASK-05, TASK-07, TASK-10 | KERNEL-005..007, PHYSREC-001, ASM-001/002, REC-003 | N/A | exact fixed drilling, deterministic rank/action and physical-output exclusion |
| 057 | TASK-10, TASK-12, downstream Physics Evaluation | REC-002..004, FLOW-002, later physics report | `shell-s4` | implementation exposes equilibrium/sign/energy evidence; physical plausibility verdict is downstream |
| 058-060 | TASK-13, TASK-14 | REF-003 and S4 E2E comparison | `shell-s4` | exact fixed absolute U tolerance `1.0e-5` without scale/clamp |
| 061-062 | TASK-13, TASK-14 | REF-004/005 and S4 E2E test | `shell-s4` | UR fixed absolute `1.0e-5`, deterministic warning only |
| 063-064 | TASK-13 | REF-001/002/005 | `shell-s4` | schema/row failure before numeric comparison; full metrics |
| 065-068 | TASK-13, TASK-14, TASK-15 | REF-001/002/006, S4 case precheck and S4R non-consumption/common-path evidence | `shell-s4` | exact two S4 paths; unique finite mapped rows; no S4R artifact consumption |
| 069-071 | TASK-14, TASK-15 | S4 E2E suite and S4R common-path tests | `shell-s4` | S4 U blocks/UR warns; S4R mapping has no Abaqus equality gate |
| 072 | TASK-13 through TASK-16 | REF-006, VERIFY-004 and git/hash audit | `shell-s4` | no reference solver run or artifact mutation |
## 10. Validation Commands
These commands are the environment-resolved Windows x64 Debug baseline. Planning does
not execute build/tests. Each approved Harness Step first runs this literal path
precheck and then repeats the relevant build/test subset after its RED and GREEN
changes.
```powershell
$requiredBuildPaths = @(
"C:/git/googletest",
"C:/Program Files (x86)/Intel/oneAPI/mkl/2026.1/lib/cmake/mkl",
"C:/Program Files (x86)/Intel/oneAPI/tbb/2023.1/lib/cmake/tbb",
"C:/Program Files/HDF_Group/HDF5/2.1.1/cmake"
)
foreach ($requiredBuildPath in $requiredBuildPaths) {
if (-not (Test-Path -LiteralPath $requiredBuildPath)) {
throw "Required configured build path is absent: $requiredBuildPath"
}
}
cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
"-DFESA_GTEST_SOURCE_DIR=C:/git/googletest" `
"-DMKL_DIR=C:/Program Files (x86)/Intel/oneAPI/mkl/2026.1/lib/cmake/mkl" `
"-DTBB_DIR=C:/Program Files (x86)/Intel/oneAPI/tbb/2023.1/lib/cmake/tbb" `
"-DHDF5_DIR=C:/Program Files/HDF_Group/HDF5/2.1.1/cmake"
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```
Focused commands:
```powershell
cmake --build .harness/build --config Debug --target fesa_unit_tests
ctest --test-dir .harness/build -C Debug -R "DomainModel|InpDomainMapping|Mitc4Geometry|Mitc4Shell|DofManager|EssentialConstraints|SparseAssembly|LoadAssembly|ResultRecovery|Hdf5ResultsWriter" --output-on-failure
cmake --build .harness/build --config Debug --target fesa_integration_tests
ctest --test-dir .harness/build -C Debug -R "LinearStaticCli|Mitc4ShellCli" --output-on-failure
cmake --build .harness/build --config Debug --target fesa_reference_tests
ctest --test-dir .harness/build -C Debug -R "Mitc4ReferenceComparison|Mitc4S4Reference" --output-on-failure
```
Planning-document verification:
```powershell
git diff --check -- docs/implementation-plans/linear-static-mitc4-shell-implementation-plan.md
git status --short
git diff --name-only
```
Reference immutability audit is read-only and fails on any mismatch:
```powershell
$expectedReferenceHashes = [ordered]@{
"reference/shell/shell.inp" = "4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF"
"reference/shell/shell displacements.csv" = "C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B"
}
foreach ($referencePath in $expectedReferenceHashes.Keys) {
$actualHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $referencePath).Hash
if ($actualHash -ne $expectedReferenceHashes[$referencePath]) {
throw "Reference artifact changed: $referencePath"
}
}
```
Do not invoke `scripts/hooks/*.py` manually. Harness runner installs/uses the configured
PreToolUse and Stop hooks automatically. Do not invoke `scripts/execute.py` until the
user separately authorizes execution.
## 11. Risks and Downstream Handoff
| risk | controlling plan decision | stop condition |
| --- | --- | --- |
| beam-only ModelDefinition leaks through every layer | add shell semantic records first; preserve B33 access | stop if a Step requires unapproved mixed-model hierarchy |
| fixed 12-DOF scatter breaks B33 | typed beam/shell scatter paths and B33 regressions | stop on any B33 focused/full regression |
| drilling contaminates physical output | separate physical recovery from stabilized full K | stop if pure-drill recovery/energy is nonzero |
| director/frame sign nondeterminism | source-order, area-weight and tie-break tests | stop on repeat/order/thread difference |
| S4R accidentally selects reduced integration | one internal formulation and ASM/E2E equality tests | stop if source type reaches quadrature dispatch |
| full residual confused with element resultants | keep reaction from Kd-F, physical recovery separately | stop if reaction is reconstructed from shell resultants |
| writer expansion changes B33 schema | additive shell branches plus full B33 CTest | stop on B33 schema regression |
| comparator inherits B33 four-file/Frame assumptions | dedicated test-only MITC4 comparator | stop if administrative files become required |
| reference artifacts staged by Harness | clean isolated worktree, hash/diff audit | stop immediately on any reference path change |
| future nonlinear equations enter production | scope and code review prohibition | stop if nonlinear state/tangent is allocated or called |
### Implementation Agent
- Read the approved implementation plan, `docs/HARNESS.md` and
`docs/HARNESS_WORKFLOW.md` before every Step.
- Execute only the Harness-selected pending Step and use the repository hooks/scripts
through the documented runner lifecycle.
- Never choose the next Step, edit executor-owned timestamps/statuses, batch multiple
Steps, or implement outside the Step's file ownership.
- Record the RED command and observed failure before GREEN.
### Build/Test Executor Agent
- Use Section 10 exact CMake/MSVC/CTest baseline after implementation Steps finish.
- Report new warnings, discovery gaps and exact failing test names without changing
upstream contracts.
### Correction Agent
- Apply only minimal failure-driven corrections inside approved file ownership.
- Do not reinterpret MITC4 mathematics, I/O schema or tolerance.
### Reference Verification Agent
- Consume authoritative HDF5 and declared read-only CSV directly.
- Create the separate reference-verification report; only U affects pass/fail and every
UR warning remains visible.
### Physics Evaluation and Release Agents
- Physics evaluates equilibrium, directions, symmetry, energy and result signs after
reference verification.
- Release readiness remains blocked until implementation, build/test, reference and
physics gates all provide evidence.
## 12. Harness Step Draft
This approved draft is materialized under `phases/linear-static-mitc4-shell/`.
Every Step is zero-based, kebab-case and closes RED/GREEN/VERIFY before the
Executor advances it. TASK-14 is declared-case sub-work inside Step 13's single
test-only reference module; TASK-15 is non-reference coverage already owned by
Steps 1/7/11; TASK-16 is downstream Build/Test Executor evidence,
not an Implementation Agent phase Step. During materialization, the exact required-reading
paths, configure block, focused command and full VERIFY block shown here are copied
verbatim into every `stepN.md`; a materialized Step never refers back to this draft or
to an external conversation.
Every materialized Step copies this mandatory reading inventory before its
Step-specific paths:
- `AGENTS.md`
- `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`
- `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`
- this approved implementation plan and all source contracts listed in Metadata
- `.codex/hooks.json`
- `phases/index.json`, `phases/linear-static-mitc4-shell/index.json` and its own
`phases/linear-static-mitc4-shell/stepN.md`
- every path created/modified by prerequisite Steps and their step output/status
If any mandatory or Step-specific path is missing or contradicts the approved plan,
the Implementation Agent records `blocked` for the Executor-selected current Step and
stops; it does not invent the missing contract.
Step-specific path ledger copied into the corresponding materialized Step:
| Step | exact source/prerequisite paths |
| ---: | --- |
| 0 | `include/fesa/model/model_types.hpp`; `include/fesa/model/domain.hpp`; `src/fesa/model/domain.cpp`; `tests/unit/model/model_types_test.cpp`; `tests/unit/model/domain_test.cpp` |
| 1 | Step 0 paths; `include/fesa/io/abaqus/domain_mapper.hpp`; `src/fesa/io/abaqus/domain_mapper.cpp`; `tests/unit/io/abaqus/domain_mapper_test.cpp` |
| 2 | Step 0-1 paths; candidate new `include/fesa/model/shell_geometry.hpp`; `src/fesa/model/shell_geometry.cpp`; `tests/unit/model/shell_geometry_test.cpp`; `src/fesa/CMakeLists.txt`; `tests/CMakeLists.txt` |
| 3 | Step 2 paths; candidate new `include/fesa/elements/mitc4_shell.hpp`; `src/fesa/elements/mitc4_shell.cpp`; `tests/unit/elements/mitc4_shell_test.cpp`; `src/fesa/CMakeLists.txt`; `tests/CMakeLists.txt` |
| 4 | Step 3 MITC4 kernel/header/test paths |
| 5 | Step 3-4 MITC4 kernel/header/test paths |
| 6 | Step 0 paths; `include/fesa/fem/dof_manager.hpp`; `src/fesa/fem/dof_manager.cpp`; `tests/unit/fem/dof_manager_test.cpp`; `tests/unit/constraints/essential_constraints_test.cpp` |
| 7 | Steps 4/6 paths; `include/fesa/assembly/sparse_assembler.hpp`; `src/fesa/assembly/sparse_assembler.cpp`; `tests/unit/assembly/sparse_assembler_test.cpp` |
| 8 | Steps 2/7 paths; `include/fesa/assembly/load_assembler.hpp`; `src/fesa/assembly/load_assembler.cpp`; `tests/unit/assembly/load_assembler_test.cpp` |
| 9 | Step 5 paths; `include/fesa/results/result_records.hpp`; `include/fesa/analysis/analysis_state.hpp`; `src/fesa/analysis/analysis_state.cpp`; `tests/unit/results/result_records_test.cpp` |
| 10 | Steps 5/9 paths; `include/fesa/results/result_recovery.hpp`; `src/fesa/results/result_recovery.cpp`; `tests/unit/results/result_recovery_test.cpp` |
| 11 | Steps 9/10 paths; `include/fesa/io/hdf5/hdf5_results_writer.hpp`; `src/fesa/io/hdf5/hdf5_results_writer.cpp`; `tests/unit/io/hdf5/hdf5_results_writer_test.cpp` |
| 12 | Steps 7-11 paths; `include/fesa/analysis/linear_static_analysis.hpp`; `src/fesa/analysis/linear_static_analysis.cpp`; `tests/integration/analysis/linear_static_analysis_test.cpp`; `tests/integration/app/fesa_application_test.cpp` |
| 13 | Steps 11/12 paths; candidate new `tests/reference/mitc4_reference_comparison.hpp`, `tests/reference/mitc4_reference_comparison.cpp`, `tests/reference/mitc4_reference_comparison_test.cpp`, `tests/reference/mitc4_reference_cases_test.cpp`; `tests/CMakeLists.txt`; the two exact read-only S4 reference paths in Section 2 |
The configure command copied before each Step's RED build is:
```powershell
$requiredBuildPaths = @(
"C:/git/googletest",
"C:/Program Files (x86)/Intel/oneAPI/mkl/2026.1/lib/cmake/mkl",
"C:/Program Files (x86)/Intel/oneAPI/tbb/2023.1/lib/cmake/tbb",
"C:/Program Files/HDF_Group/HDF5/2.1.1/cmake"
)
foreach ($requiredBuildPath in $requiredBuildPaths) {
if (-not (Test-Path -LiteralPath $requiredBuildPath)) {
throw "Required configured build path is absent: $requiredBuildPath"
}
}
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"
```
The full VERIFY block copied at the end of every Step is:
```powershell
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```
### Step 0 — `shell-semantic-model`
- Required reading: requirements 002-016/024, I/O Sections 3/5, architecture model
ownership, current `model_types.hpp`/`domain.*` and their tests.
- Prerequisite: approved plan only; no production dependency on a prior Step.
- RED: add MODEL-001/002 tests and CMake registration if needed; run:
`cmake --build .harness/build --config Debug --target fesa_unit_tests` then
`ctest --test-dir .harness/build -C Debug -R "DomainModel" --output-on-failure`.
Record the missing shell type/accessor failure. Unexpected pass is a stop.
- GREEN: minimally add shell semantic records/Domain const access; no parser/kernel.
- VERIFY: rerun the focused commands and common full VERIFY.
- Prohibitions: no equation IDs, element hierarchy, mixed-model execution, parser edits.
### Step 1 — `shell-domain-mapping`
- Required reading: Step 0 outputs, requirements 001-010/017-023, I/O Sections 1-3/8-9,
current `domain_mapper.*` and parser/model tests.
- Prerequisite: Step 0 `completed`.
- RED: add MAP-001..004; build `fesa_unit_tests` and run
`ctest --test-dir .harness/build -C Debug -R "InpDomainMapping" --output-on-failure`.
Record valid S4/S4R rejection and exact negative diagnostic failures.
- GREEN: minimally extend semantic mapping; keep `input_reader` syntax-only.
- VERIFY: focused parser/model tests, then common full VERIFY.
- Prohibitions: no element math, no silent unsupported keyword, no reference edits.
### Step 2 — `shell-director-geometry`
- Required reading: requirements 011-016, formulation Sections 4/9/17, Numerical Review
5.2/5.5/6.1, I/O 3.3/9, completed semantic model/mapping.
- Prerequisite: Step 1 `completed`.
- RED: add GEO-001..004; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "Mitc4Geometry" --output-on-failure`.
- GREEN: implement deterministic director/frame and exact geometry inventory validation.
- VERIFY: focused geometry/mapping tests, then common full VERIFY.
- Prohibitions: no calibrated angle/warp/distortion threshold; no NR-O03/O04.
### Step 3 — `mitc4-kinematics-constitutive`
- Required reading: formulation Sections 3-11/17, Numerical Review 5.1-5.6/6.1,
current math adapters and Euler kernel style.
- Prerequisite: Step 2 `completed`.
- RED: add KIN-001..005 in new `mitc4_shell_test.cpp`, register it, build unit target,
run `ctest --test-dir .harness/build -C Debug -R "Mitc4ShellKinematics|Mitc4ShellConstitutive" --output-on-failure`.
- GREEN: minimally add concrete shell kernel kinematics/constitutive seams; no global
assembly or drilling.
- VERIFY: focused kernel tests, then common full VERIFY.
- Prohibitions: no public base hierarchy, no S4R branch, no nonlinear tangent code.
### Step 4 — `mitc4-stiffness-drilling`
- Required reading: formulation Sections 10-14/17, requirements 031-038/050-056,
Numerical Review 5.7/6.1-6.2, completed Step 3 kernel.
- Prerequisite: Step 3 `completed`.
- RED: add KERNEL-001..006; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "Mitc4ShellKernel|Mitc4ShellPatch|Mitc4ShellDrilling" --output-on-failure`.
- GREEN: implement K20, 20-to-24 congruence and exact fixed drilling only.
- VERIFY: focused kernel suite, then common full VERIFY.
- Prohibitions: translations in R+, coefficient sweep, recovery/result output, future nonlinear.
### Step 5 — `mitc4-physical-recovery`
- Required reading: formulation Sections 14/16, requirements 035/042-046/052/056,
I/O result component/location order, completed Step 4 kernel.
- Prerequisite: Step 4 `completed`.
- RED: add KERNEL-007 and PHYSREC-001; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "Mitc4ShellDrilling|Mitc4ShellPhysicalRecovery" --output-on-failure`.
- GREEN: minimally add kernel-local physical recovery and physical energy API only.
- VERIFY: focused physical recovery/drilling tests, then common full VERIFY.
- Prohibitions: no AnalysisState/global result rows, no drilling contribution or HDF5.
### Step 6 — `shell-dof-scatter`
- Required reading: requirements 005/025, architecture DofManager ownership, current
`dof_manager.*` and constraint tests, completed shell model.
- Prerequisite: Step 5 `completed`.
- RED: add DOF-001..003; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "DofManager|EssentialConstraints" --output-on-failure`.
- GREEN: minimally add typed 24-entry scatter/pattern while preserving 12-entry B33.
- VERIFY: focused DOF/constraint tests, then common full VERIFY.
- Prohibitions: no equation IDs in model, no constraint/load ownership move.
### Step 7 — `shell-sparse-assembly`
- Required reading: requirements 027/030/037, architecture deterministic COO rule,
current `sparse_assembler.cpp`/`sparse_matrix.cpp` tests, completed kernel/scatter.
- Prerequisite: Step 6 `completed`.
- RED: add ASM-001..003; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "SparseAssembly" --output-on-failure`.
- GREEN: minimally dispatch shell and emit stable 576-entry local buffers.
- VERIFY: focused assembly tests, then common full VERIFY.
- Prohibitions: no worker global CSR mutation, unordered reduction or S4R integration branch.
### Step 8 — `shell-load-validation`
- Required reading: requirements 017-020/028, formulation 8/13, I/O 4.2-4.3,
current `load_assembler.*` and constraint lifecycle.
- Prerequisite: Step 7 `completed`.
- RED: add LOAD-001..004; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "LoadAssembly|EssentialConstraints" --output-on-failure`.
- GREEN: minimally add aggregate nodal moment/director validation and reuse full DOF load.
- VERIFY: focused load/constraint tests, then common full VERIFY.
- Prohibitions: no distributed/equivalent/follower load; no drill load channel.
### Step 9 — `shell-analysis-state`
- Required reading: requirements 026/041-046/048, I/O 6.3-6.5,
current `analysis_state.*`/`result_records.hpp` and completed physical recovery types.
- Prerequisite: Step 8 `completed`.
- RED: add STATE-001..003; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "AnalysisState" --output-on-failure`.
- GREEN: minimally add candidate-owned shell row/global evidence containers and
validation/commit mechanics.
- VERIFY: focused AnalysisState tests, then common full VERIFY.
- Prohibitions: no element calculation, ResultRecovery orchestration or HDF5 writing.
### Step 10 — `shell-result-recovery`
- Required reading: requirements 029/035/041-046/048, formulation 14/16, I/O 6.3-6.5,
current `result_recovery.*` and completed Steps 5/9.
- Prerequisite: Step 9 `completed`.
- RED: add REC-001..005; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "ResultRecovery" --output-on-failure`.
- GREEN: minimally orchestrate full-residual evidence and physical shell recovery into
a fully validated candidate, then commit it.
- VERIFY: focused recovery tests, then common full VERIFY.
- Prohibitions: no new result record type, location averaging, drill recovery or writer edit.
### Step 11 — `shell-hdf5-output`
- Required reading: requirements 039-048, I/O Section 6 exact schema, ADR atomic output,
current HDF5 writer/self-check tests, completed recovery records.
- Prerequisite: Step 10 `completed`.
- RED: add H5-001..004; build unit target and run
`ctest --test-dir .harness/build -C Debug -R "Hdf5ResultsWriter" --output-on-failure`.
- GREEN: add exact additive shell schema behind unchanged ResultsWriter boundary.
- VERIFY: focused HDF5 tests, then common full VERIFY.
- Prohibitions: no B33 schema reinterpretation, CSV solver output, partial final file.
### Step 12 — `shell-linear-static-flow`
- Required reading: requirements 024-030, architecture eight-hook lifecycle, I/O CLI
contract, current `linear_static_analysis.*`/application integration tests.
- Prerequisite: Step 11 `completed`.
- RED: add FLOW-001..004; build integration target and run
`ctest --test-dir .harness/build -C Debug -R "LinearStaticCli|Mitc4ShellCli" --output-on-failure`.
- GREEN: minimally route shell through existing lifecycle; preserve one factorization.
- VERIFY: focused integration tests, then common full VERIFY.
- Prohibitions: no analysis lifecycle reorder, no 0x0 singular conversion, no early state commit.
### Step 13 — `shell-reference-comparison`
- Required reading: requirements 058-072, I/O Section 7, Reference Model contract,
the sole declared S4 paths and hashes, and current B33 comparator only as reusable
identity/report precedent.
- Scope ownership: this one test-only reference module owns TASK-13 comparator behavior
plus TASK-14 declared-case tests; it owns no solver production module.
- Prerequisite: Step 12 `completed` and valid MITC4 HDF5 fixture.
- RED: update REF-003 first so the existing scale-dependent comparator fails against
literal fixed-boundary cases around `1.0e-5`; build the reference target and run
`ctest --test-dir .harness/build -C Debug -R "Mitc4ReferenceComparison|Mitc4S4Reference" --output-on-failure`.
Record the expected old-tolerance assertion failure.
- GREEN: minimally replace only the MITC4 comparator decision value with fixed absolute
`1.0e-5`; keep reference scale as diagnostic report data only.
- If a declared case exposes a production defect outside this reference-test module,
stop the Step and route a focused correction to the owning prior module; do not patch
unrelated production layers inside this Step.
- VERIFY: focused comparator and the declared S4 tests, then common full VERIFY.
- Prohibitions: no reference artifact writes/Abaqus run, no metadata/README gate, no UR
blocking, no B33 comparator change, and no scale/clamp substitution for fixed `1.0e-5`.
After explicit approval, planning may create only:
- `phases/index.json` with task status `pending` and no creation timestamp;
- `phases/linear-static-mitc4-shell/index.json` with Steps 0-13 initially `pending` and
no executor-owned timestamps;
- `phases/linear-static-mitc4-shell/stepN.md` containing the approved self-contained
directions.
Approval does not authorize `python scripts/execute.py linear-static-mitc4-shell` or
`--push`.
## 13. Open Issues
| id | item | blocking now | resolution owner |
| --- | --- | --- | --- |
| OI-001 | Section 12 multi-Step Harness draft was explicitly approved on 2026-08-12 and materialized. | resolved | user |
| OI-002 | Candidate shell semantic representation and exact C++ value/reference types are not public API decisions. | no | owning RED test in Steps 0/3 |
| OI-003 | Per-test MITC4 CTest label can be added without relabeling B33 tests인지 확인한다. Exact suite regex remains sufficient. | no | Step 0 and downstream TASK-14 CMake verification |
No mathematical, I/O, reference-inventory or tolerance decision remains open for
implementation planning. The user separately authorized implementation and Harness
execution on 2026-08-12; the Executor still owns branch, Step selection, timestamps,
commits and advancement.
docs/linear-static-mitc4-shell/io.md
+663
View File
@@ -0,0 +1,663 @@
# Linear Static MITC4 Shell I/O Definition
## Metadata
- feature_id: `linear-static-mitc4-shell`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- source_research: `docs/research/linear-static-mitc4-shell-research.md`
- source_formulation: `docs/formulations/mitc4-shell-formulation.md`
- source_numerical_review: `docs/numerical-reviews/linear-static-mitc4-shell-review.md`
- source_commits: requirements/research/formulation policy revision `73df844`
- status: `approved-for-implementation-planning`
- owner_agent: `io-definition-agent`
- date: `2026-08-13`
- authoritative_output: `results.h5`
- hdf5_schema_version: `0`
- reference_cases: sole acceptance case is read-only full-integration S4 at `reference/shell/`; S4R is covered by non-reference source-mapping/kernel/metadata tests
- implementation_planning_authorized: `true`
This document defines the approved semantic input and output contract for the
linear-static MITC4 shell feature. It does not define parser, model, HDF5-writer, or
comparison-tool C++ APIs and does not claim full Abaqus compatibility or Abaqus
`S4`/`S4R` formulation equivalence.
The user approved the following I/O-specific decisions on `2026-08-12`:
1. `S4` and `S4R` source types map to one internal full-integration `FESA-MITC4`
formulation, while only S4 is an Abaqus acceptance reference.
2. The optional positive integer on a `*SHELL SECTION` thickness row is accepted
without a warning and has no semantic effect on FESA quadrature. FESA always uses
the formulation's `2 x 2 x 2` rule.
3. The existing `reference/shell/` S4 input/displacement files are the sole declared
acceptance pair and remain under their current names without mutation. Existing
`reference/shellR/` files are untouched optional evidence and are not consumed by
acceptance comparison. No canonical or legacy-alias classification is required.
4. HDF5 schema version `0` is extended additively with MITC4-specific datasets while
retaining the existing common metadata, nodal-result, diagnostic, CLI, and
failure-atomicity conventions.
The approved requirements fix the drilling rule and the MITC4 fixed absolute
displacement tolerance `1.0e-5`.
Drilling calibration/output, `NR-O03`, `NR-O04`, bundle-administration metadata, and
an expanded reference portfolio are outside this contract.
## 1. Abaqus Input Scope
- input_format: Abaqus input file (`.inp`)
- supported_analysis: exactly one small-displacement, small-rotation linear-static
step containing four-node `S4` and/or `S4R` shell elements
- ordinary_unit_system: user-consistent; FESA does not infer SI or another unit
system from an `.inp` file
- internal_element_formulation: `FESA-MITC4`
- compatibility_disclaimer: only the keyword locations, parameters, and data grammar
in this document are supported
`supported` means only the documented subset is semantically interpreted. `warning
no-op` means the syntax is consumed and a structured warning is recorded, but no
Domain, AnalysisModel, numerical, or mandatory-output meaning changes. The optional
`*SHELL SECTION` integration-point field is a separately approved silent provenance
field, not a warning no-op keyword.
| keyword | status and allowed location | required parameters and data grammar | semantic mapping | unsupported behavior |
| --- | --- | --- | --- | --- |
| `*HEADING` | supported; optional top-level first keyword | no parameters; zero or more text rows until next keyword | original heading retained as source metadata | nested location or parameters are input errors |
| `*PART` / `*END PART` | supported; top-level model block | `NAME=<part-name>` required; no `*END PART` data | scope for part-local nodes, elements, sets, and shell sections | unclosed/nested part or duplicate name is an input error |
| `*NODE` | supported; part scope | no parameters; each row `node_label,x,y,z` | positive source node label and finite global Cartesian coordinates | wrong arity, duplicate label, or nonfinite value is an input error |
| `*ELEMENT` | supported; part scope | `TYPE=S4` or `TYPE=S4R`; each row `element_label,node_1,node_2,node_3,node_4` | ordered four-node shell connectivity; source type retained separately; internal type is `FESA-MITC4` | another type is `unsupported-element-formulation`; wrong arity, repeated connected node, or dangling node is an error |
| `*NSET` | supported; part or assembly scope | `NSET=<name>`; optional `GENERATE`; assembly scope requires `INSTANCE=<name>`; explicit labels or `first,last,increment` | deterministic node-set membership | mixed-instance set, invalid generate range, duplicate name, or dangling member is an error |
| `*ELSET` | supported; part or assembly scope | `ELSET=<name>`; optional `GENERATE`; assembly scope requires `INSTANCE=<name>`; same row rules as `*NSET` | deterministic element-set membership | mixed-instance set, invalid range, duplicate name, or dangling member is an error |
| `*MATERIAL` | supported; top-level model data | `NAME=<material-name>` required; no data | owns exactly one approved isotropic `*ELASTIC` definition | duplicate name, missing/duplicate elasticity, or another material model is an error |
| `*ELASTIC` | supported; current material scope | no parameters; exactly one row `E,nu` | homogeneous isotropic elasticity; `G=E/(2(1+nu))` | extra row/field, dependency/temperature data, nonfinite value, `E<=0`, or `nu<=-1`/`nu>=0.5` is an error |
| `*SHELL SECTION` | supported; part scope | `ELSET=<name>` and `MATERIAL=<name>` required; exactly one row `thickness[,integration_points]` | one centered homogeneous layer with constant thickness | composite/layer data, offset, orientation, distributed/nodal thickness, missing reference, or conflicting assignment is an error |
| `*ASSEMBLY` / `*END ASSEMBLY` | supported; exactly one top-level assembly | `NAME=<assembly-name>` required; no end data | scope for identity instances and assembly sets | nested/duplicate assembly is `unsupported-nested-assembly` |
| `*INSTANCE` / `*END INSTANCE` | supported; assembly scope | `NAME=<instance-name>`, `PART=<part-name>` required; no intervening data | named identity copy; multiple instances of a part are allowed | translation/rotation data is `unsupported-instance-transform`; duplicate or dangling instance is an error |
| `*BOUNDARY` | supported; top-level model data or sole step | no parameters; each row `target,first_dof,last_dof[,value]`; omitted value is exact zero | prescribed global shell DOFs 1 through 6 | invalid arity/range, unresolved target, or conflicting expanded value is an error |
| `*CLOAD` | supported; sole step | no parameters; each row `target,dof,magnitude` | concentrated global nodal force/moment on DOFs 1 through 6 | invalid arity/DOF, nonfinite magnitude, unresolved target, or drilling-direction aggregate moment is an error |
| `*STEP` / `*END STEP` | supported; exactly one top-level history block | optional `NAME`; optional `NLGEOM=NO`; no end data | one canonical result identity `(Step-1,frame 0)` | second step is `unsupported-multiple-step`; `NLGEOM=YES` is `unsupported-nonlinear-geometry` |
| `*STATIC` | supported; exactly once in sole step | no parameters; exactly one row `initial_increment,time_period,minimum_increment,maximum_increment` | source values retained; exactly one linear solve and frame 0 | another procedure or missing/extra/nonfinite/nonpositive field is an error |
| `*PREPRINT` | warning no-op; top-level | all parameters retained then ignored; no data | accepts generator control | no semantic object is created |
| `*RESTART` | warning no-op; sole step | all parameters retained then ignored; no data | accepts a legacy restart request | no restart state is created |
| `*OUTPUT, FIELD` | warning no-op; sole step | parameters and subordinate variable data retained then ignored | accepts field-output request root | cannot select, suppress, or expand mandatory FESA output |
| `*OUTPUT, HISTORY` | warning no-op; sole step | parameters and subordinate variable data retained then ignored | accepts history-output request root | no history dataset is created |
| `*NODE OUTPUT` | warning no-op; active output request | all parameters and following variable rows ignored | accepts legacy nodal request | cannot change the HDF5 schema |
| `*ELEMENT OUTPUT` | warning no-op; active output request | all parameters and following variable rows ignored | accepts legacy element request | cannot change the HDF5 schema |
| `*CONTACT OUTPUT` | warning no-op; active output request | all parameters and following variable rows ignored | accepts legacy contact-output syntax only | no contact model or output is created |
`*DLOAD`, pressure, gravity, body force, edge traction, follower load, explicit
normal/director input, `*ORIENTATION`, composite/layer controls, `*INCLUDE`, and
model-affecting keywords not listed above are `unsupported-keyword` errors. A mixed
B33/shell model and a shell-beam joint are `unsupported-mixed-element-model`; the
presence of an existing B33 implementation does not expand this feature contract.
Multiple `*ELEMENT` blocks containing `S4`, `S4R`, or both are allowed. Every element
retains its own source element type, and source type never changes FESA quadrature,
tying, drilling, recovery, or numerical path.
### 1.1 Shell-section data rule
The exact accepted data row is
```text
thickness[,integration_points]
```
- `thickness` is a finite `double` strictly greater than zero.
- If present, `integration_points` is a positive base-10 integer.
- The optional field is syntactically accepted without a warning and has no Domain,
quadrature, recovery, or output effect.
- The raw input remains recoverable through the source file/content identity, but
no `source_integration_points` physical property is created.
- FESA stiffness remains four midsurface Gauss locations times two thickness Gauss
locations, including when the source value is `5` in the declared S4 case.
Silently accepting this field is an explicit feature contract, not a general rule
that Abaqus section parameters may be ignored.
### 1.2 Nesting grammar
```text
input-file
:= heading? part+ assembly material+ model-boundary* step EOF
part
:= *PART
node-block+ element-block+ (nset | elset)* shell-section+
*END PART
assembly
:= *ASSEMBLY
instance+ assembly-set*
*END ASSEMBLY
instance
:= *INSTANCE *END INSTANCE
step
:= *STEP *STATIC step-boundary* cload* allowed-no-op* *END STEP
```
All parts close before assembly. Assembly contains only identity instances and
assembly-level sets. Instance-local node/element redefinition, nested assembly,
instance transforms, and dependent/independent mesh semantics are excluded.
## 2. Syntax Policy
- The first non-whitespace character of a keyword line is `*`; `**` begins a comment.
- Comments have no semantic effect but retain normalized file and 1-based line
provenance for neighboring parsed records.
- Keyword names, parameter names, enumerated values, and named-reference lookup are
ASCII case-insensitive. Raw source spelling remains available for identity and
diagnostics.
- Keyword and data fields are comma-separated with surrounding whitespace removed.
A required empty field, an unexpected trailing field, or a malformed numeric token
is an input error.
- Keyword continuation, physical-line continuation, quoted/multiline names, and
include files are unsupported. Each logical keyword or data row is complete on one
physical line.
- Node/element labels and explicit set members are positive base-10 integers.
Internal numeric IDs do not replace preserved source label text.
- All real-valued input is finite. `NaN` and positive/negative infinity are rejected.
- Every parsed keyword, parameter, data row, and semantic entity remains traceable to
normalized file path, 1-based line, raw keyword, and source identity.
- Output-request variable data is a warning no-op only while subordinate to an
allowlisted output keyword. An unexpected standalone data line is an input error.
### 2.1 Duplicate and dangling-reference policy
- Part, assembly, instance, material, set, and section identities are unique in
their documented case-insensitive scope.
- Node and element source labels are unique within a part.
- Multiple identity instances of the same part are distinct through instance name.
- Connectivity, set membership, instance `PART`, section `ELSET`/`MATERIAL`, assembly
set `INSTANCE`, boundary target, and load target all resolve before Domain commit.
- Duplicate definitions use `duplicate-entity`; unresolved references use
`unresolved-reference`. A partial Domain is never passed to analysis.
## 3. Model Data Mapping
### 3.1 Stable source identity and ordering
After identity-instance expansion, each node and element has
```text
SourceEntityId { instance_name, source_label }
```
Raw spelling and the case-insensitive lookup key are separate. Stable internal IDs
follow input part declaration order, instance declaration order, and part-local
entity declaration order. Hash iteration and thread scheduling cannot affect IDs,
director accumulation, result rows, or diagnostics.
Assembly sets name one identity instance and resolve their numeric members to that
instance's part-local source identities. A set cannot mix members from multiple
instances in the approved grammar.
### 3.2 Nodes, elements, sets, material, and section
- A node has global Cartesian coordinates, stable internal ID, source identity,
geometry-derived initial director, and deterministic tangent frame.
- A shell element has ordered connectivity `[node_1,node_2,node_3,node_4]`, stable
internal ID, source identity, preserved source type `S4` or `S4R`, internal type
`FESA-MITC4`, and exactly one resolved section/material.
- Connectivity order fixes natural corners `1=(-1,-1)`, `2=(+1,-1)`,
`3=(+1,+1)`, `4=(-1,+1)` and positive thickness through
`A_xi x A_eta`. Connectivity is not silently reversed.
- Explicit set order follows data rows. Generated sets use inclusive
`first,last,increment` order. Set members remain round-trippable to source identity.
- Material preserves `E` and `nu`; `G=E/(2(1+nu))` is derived.
- Section preserves positive constant thickness and resolved material. It represents
one centered homogeneous isotropic layer.
- Multiple materials, sections, element sets, `S4` blocks, and `S4R` blocks are
allowed when each element resolves to exactly one valid assignment.
### 3.3 Director and geometry preprocessing
Initial directors are semantic model data derived after instance expansion, not
parser-provided rotations.
1. Process accepted shell elements in stable source-element order.
2. Compute each source-order-positive center normal candidate and its `2 x 2`
surface-area weight.
3. At each node, sort incident elements by stable source identity and reject any
nonpositive pairwise normal dot product before averaging.
4. Form and normalize the deterministic area-weighted director.
5. Select the least-aligned global basis axis with fixed `x,y,z` tie order and form
right-handed nodal frame `[a,b,d]`.
The complete center, volume-Gauss, tying, and committed-recovery inventory requires
finite nonzero surface area, finite covariant/reciprocal bases, and finite positive
`J`. This document supplies no point omission, normal flip, or default axis.
Geometry and director failures are model-validation errors. Duplicate connectivity,
self-intersection, degenerate/reversed geometry, invalid Jacobians, opposed incident
normals, and invalid basic mappings fail closed. No calibrated smooth-angle,
distortion, aspect, or warpage threshold is applied.
## 4. History Data Mapping
### 4.1 Step and procedure
Exactly one history object is created. The source step name remains provenance, but
the result identity is literal `Step-1`, frame index `0`. The four `*STATIC` values
are finite positive source data and `minimum_increment <= maximum_increment`; they do
not create increments, iteration history, or additional frames.
`NLGEOM=NO` or omission is accepted. `NLGEOM=YES`, another procedure, or another step
is unsupported. The future nonlinear formulation does not expand this history
contract.
### 4.2 Boundary conditions
Boundary target is a direct source node label or node set and expands to stable
source node identities. `first_dof <= last_dof`, with both in `1..6`. Omitted value
is exact zero; a finite nonzero value is supported. Model-level and step-level
boundaries activate in the sole step. Different prescribed values on one expanded
node/DOF are an error.
| DOF | kinematic component | unit dimension |
| ---: | --- | --- |
| 1 | `U1` | length |
| 2 | `U2` | length |
| 3 | `U3` | length |
| 4 | `UR1` | radian/dimensionless angle |
| 5 | `UR2` | radian/dimensionless angle |
| 6 | `UR3` | radian/dimensionless angle |
### 4.3 Concentrated loads and drilling projection
`*CLOAD` target expansion matches boundary expansion. Rows resolving to the same
node/DOF are accumulated in stable source order before physical admissibility is
tested.
| DOF | load component | unit dimension |
| ---: | --- | --- |
| 1 | `F1` | force |
| 2 | `F2` | force |
| 3 | `F3` | force |
| 4 | `M1` | force*length |
| 5 | `M2` | force*length |
| 6 | `M3` | force*length |
For aggregate nodal moment `M_I` and approved unit director `d_I`, exact-zero moment
is accepted as a separate case. Otherwise compute, without denominator clamping,
```text
rho_M = abs(dot(d_I,M_I)) / norm(M_I)
```
and require `rho_M <= 1e-12`. Failure is `unsupported-drilling-load`. No part of a
rejected physical moment is transferred to numerical drilling stabilization.
### 4.4 Output requests
Allowlisted Abaqus output requests do not activate history output and cannot change
the mandatory HDF5 inventory. FESA writes all datasets in Section 6 on a successful
run even when the input contains no output request. Requested Abaqus variables that
have no FESA dataset do not create empty synthetic physical results.
## 5. Internal Model Contract
- Domain owns the complete immutable-after-mapping definition of nodes, shell
elements, sets, materials, sections, boundary/load data, sole static step, stable
source identities, initial directors, and source formulation labels.
- `S4`/`S4R` remains source metadata. Numerical selection uses one explicit internal
identity, `FESA-MITC4`.
- AnalysisModel is a non-owning view of active Domain objects and does not copy them.
- Nodes/elements do not own equation IDs. Six-DOF numbering, constrained/free maps,
scatter maps, and sparse pattern are DofManager responsibilities.
- Boundary and load records retain both the source target and their deterministic
expanded source-node identities.
- Section/material assignment is resolved before element processing. An element with
zero or multiple assignments is invalid.
- AnalysisState contains only the current linear-static displacement, external and
internal force, full residual/reaction, shell recovery, equilibrium, and energy
rows. No nonlinear director history, iteration state, velocity, or acceleration is
allocated.
- Midsurface generalized rows, section-position stress rows, nodal rows, and global
equilibrium rows have distinct quantity/location identity. Values from different
locations are never averaged to satisfy a schema. Drilling-specific result rows do
not exist.
## 6. Output HDF5 Schema
The sole authoritative output is `results.h5`, schema version `0`. MITC4 extends
that schema additively; it does not migrate or reinterpret B33 datasets. Every
string is UTF-8, every physical real is IEEE-754 float64, stable internal IDs are
uint64, and constraint masks are uint8.
The literal result path identity is `(Step-1,frame 0)`. No history or nonlinear
frame group is created.
### 6.1 Metadata
`/metadata` is a group with these required scalar attributes:
| attribute | required value or meaning |
| --- | --- |
| `schema_version` | integer `0` |
| `feature_id` | `linear-static-mitc4-shell` |
| `solver_version` | executing solver version |
| `source_input_identity` | normalized input path plus auditable content identity |
| `unit_system_label` | `user-consistent-unspecified`; FESA does not infer a named unit system from `.inp` or reference artifacts |
| `coordinate_convention` | `global-cartesian; shell-local=(e1,e2,e3); positive-thickness=+zeta` |
| `internal_formulation` | `FESA-MITC4` |
| `integration_rule` | `2x2x2-gauss; mitc4-edge-midpoint-shear` |
| `step_name` | `Step-1` |
| `frame_index` | integer `0` |
No drilling coefficient/ratio/energy, `theta_smooth`, or distortion/warp calibration
attribute is required. The fixed drilling formula is part of the formulation identity,
not a per-run result policy.
### 6.2 Model identity datasets
| exact dataset path | shape/dtype | row identity and fields | attributes/order |
| --- | --- | --- | --- |
| `/model/nodes` | `[node_count]` compound | `internal_node_id:uint64`, `instance_name:utf8`, `source_label:utf8`, `coordinates:float64[3]` | internal node ID ascending; global Cartesian; coordinate unit `length` |
| `/model/elements` | `[element_count]` compound | `internal_element_id:uint64`, `instance_name:utf8`, `source_label:utf8`, `source_element_type:utf8`, `internal_formulation:utf8`, `node_internal_ids:uint64[4]`, `shell_section_internal_id:uint64`, `material_internal_id:uint64` | internal element ID ascending; connectivity in exact source order; source type `S4|S4R`; formulation `FESA-MITC4` |
| `/model/shell/nodal_director` | `[node_count,3]` float64 | `/model/nodes` row | dimensionless global components; unit norm within `1e-12` frame check |
| `/model/shell/nodal_frame` | `[node_count,3,3]` float64 | `/model/nodes` row, axis row `[a,b,d]`, global component column | dimensionless; right-handed and orthonormal |
| `/model/shell/materials` | `[material_count]` compound | `internal_material_id`, raw `name`, `E`, `nu` | stable declaration order; units `[force/length^2,1]` |
| `/model/shell/sections` | `[section_count]` compound | `internal_section_id`, source keyword file/line identity, source ELSET, `material_internal_id`, `thickness` | stable declaration order; centered single layer; thickness unit `length` |
| `/model/nodal_constraint_mask` | `[node_count,6]` uint8 | node row and global DOF order | `0=free`, `1=constrained`; existing HDF5 component names `[UX,UY,UZ,URX,URY,URZ]` |
| `/model/prescribed_displacement` | `[node_count,6]` float64 | same row/component order | constrained entry is prescribed value; free entry is exact zero with mask as authority |
| `/model/shell/midsurface_locations` | `[4,2]` float64 | `location_index` implicit row 1..4; columns `[xi,eta]` | exact order in Section 6.3; dimensionless |
| `/model/shell/section_positions` | `[3]` float64 | rows `BOTTOM,MIDDLE,TOP`; value is `zeta` | exact values `[-1,0,+1]`; physical `z=t*zeta/2` |
The optional source shell-section integration-point field is not written as a
physical model property. Exact source bytes remain auditable through
`source_input_identity`.
### 6.3 Fixed shell location ordering
Let `g=1/sqrt(3)`. Every shell result with a four-location axis uses:
| location index | name | `(xi,eta)` |
| ---: | --- | --- |
| 1 | `GP1` | `(-g,-g)` |
| 2 | `GP2` | `(+g,-g)` |
| 3 | `GP3` | `(+g,+g)` |
| 4 | `GP4` | `(-g,+g)` |
Every three-section-position axis uses `BOTTOM(zeta=-1)`, `MIDDLE(zeta=0)`, then
`TOP(zeta=+1)`. Location indices are not Abaqus integration-point numbers and must
not be relabeled as such in a reference comparison.
### 6.4 Step/frame result datasets
All datasets are mandatory after a successful run, independent of Abaqus output
requests.
| quantity | exact dataset path | shape | row identity and component order | units/coordinates/location |
| --- | --- | --- | --- | --- |
| displacement | `/steps/Step-1/frames/0/nodal/displacement` | `[node_count,6]` float64 | `/model/nodes` row; existing HDF5 component names `[UX,UY,UZ,URX,URY,URZ]` | `[length x3,radian x3]`; global; nodal |
| reaction/full residual | `/steps/Step-1/frames/0/nodal/reaction` | `[node_count,6]` float64 | `/model/nodes` row; `[RF1,RF2,RF3,RM1,RM2,RM3]` | `[force x3,force*length x3]`; global; nodal; constrained entry is physical reaction, free entry is residual evidence |
| local frame | `/steps/Step-1/frames/0/element/shell/local_frame` | `[element_count,4,3,3]` float64 | element row, location row, axis row `[e1,e2,e3]`, global component column | dimensionless; location-specific shell local frame |
| generalized strain | `/steps/Step-1/frames/0/element/shell/generalized_strain` | `[element_count,4,8]` float64 | element row, location row; `[E11,E22,G12,K11,K22,K12,G13,G23]` | `[1,1,1,1/length,1/length,1/length,1,1]`; shell local; midsurface location |
| section resultant | `/steps/Step-1/frames/0/element/shell/section_resultant` | `[element_count,4,8]` float64 | element row, location row; `[N11,N22,N12,M11,M22,M12,Q13,Q23]` | `[force/length x3,force x3,force/length x2]`; shell local; midsurface location |
| in-plane stress | `/steps/Step-1/frames/0/element/shell/stress` | `[element_count,4,3,3]` float64 | element row, location row, section-position row, component `[S11,S22,S12]` | `force/length^2`; shell local; direct bottom/middle/top evaluation |
| energy | `/steps/Step-1/frames/0/global/energy` | `[1]` float64 | `[PHYSICAL_STRAIN_ENERGY]` | `force*length`; deterministic element reduction; excludes numerical drilling stabilization |
| force/moment balance | `/steps/Step-1/frames/0/global/equilibrium` | `[6]` float64 | `[FORCE_1,FORCE_2,FORCE_3,MOMENT_1,MOMENT_2,MOMENT_3]` | `[force x3,force*length x3]`; global; moment reference point is global origin `[0,0,0]` |
| verification metrics | `/steps/Step-1/frames/0/global/verification_metrics` | `[3]` float64 | `[FREE_RESIDUAL_NORMALIZED,FORCE_BALANCE_NORMALIZED,MOMENT_BALANCE_NORMALIZED]` | dimensionless; metric-definition IDs and thresholds required as attributes |
| diagnostics | `/diagnostics` | `[diagnostic_count]` compound | `severity`, `code`, `file`, `line`, `keyword`, `entity_identity`, `message` | deterministic order; required empty dataset when count is zero |
`S33=0` is a plane-stress assumption and is not emitted. `S13`, `S23`, physical
drilling stress/resultant, and nodally extrapolated/averaged shell stress are not
created. Transverse shear is externally represented through `Q13/Q23`.
Each numeric result dataset has required attributes `component_names`,
`component_unit_dimensions`, `coordinate_system`, `location`, `step_name=Step-1`,
and `frame_index=0`. Shell element results additionally identify their source
element type, internal formulation, midsurface-location dataset, section-position
dataset when applicable, and local-frame dataset.
Verification-metric definitions and thresholds follow the approved formulation and
requirements; they are not reference-bundle metadata.
### 6.5 Reaction, residual, equilibrium, and energy meaning
`nodal/reaction` stores the assembled full residual `K*d-F`; a duplicate nodal
residual dataset is not written. `/model/nodal_constraint_mask` controls meaning:
- constrained entry: physical reaction;
- free entry: equation-equilibrium residual evidence.
Global force/moment balance uses applied `CLOAD` plus constrained reaction about
the global origin. Free residual entries remain separate evidence and are not added
as physical reactions. The energy dataset contains only physical shell strain energy;
no drilling energy or drilling-to-physical ratio is written.
### 6.6 Atomic finalization
The writer creates a temporary candidate in the final output directory, writes every
mandatory group/dataset/attribute, validates finite values, shape, identity, and
ordering, flushes, closes, reopens read-only, and self-checks the schema. Only then
may it atomically replace/create the requested final path. A failure preserves any
previous valid final output when possible, removes or quarantines the non-authority
candidate, emits an output diagnostic, and returns exit code `6`.
## 7. FESA HDF5 to Reference CSV Comparison Schema
Authoritative comparison reads `results.h5` and read-only Abaqus CSV artifacts.
A deterministic FESA CSV projection is a debugging/review view only; it is neither
solver output nor a reference artifact.
### 7.1 Full-integration reference boundary
- FESA maps S4 and S4R source types to the same full `2 x 2 x 2` FESA-MITC4 path.
- Reference comparison consumes only the declared S4 input/displacement pair.
- Equality of FESA internal numerical rows after changing only source type is a
separate implementation test; it does not consume or compare Abaqus S4R rows.
### 7.2 Declared S4 case
The blocking S4 case uses:
| role | exact path | SHA-256 | observed inventory |
| --- | --- | --- | --- |
| input | `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` | `TYPE=S4`; declared comparison input |
| displacement | `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` | 49 finite data rows; U and UR columns |
The files must not be renamed, rewritten, zero-clamped, normalized, or repaired.
The reaction and stress CSV files in the same directory are optional review evidence
and are not comparison inputs.
### 7.3 S4R non-reference coverage
No file under `reference/shellR/` is required or consumed by this acceptance
comparison. S4R source support is verified by parser mapping, S4/S4R common-kernel
and deterministic-assembly equivalence, plus preserved HDF5 source-type metadata.
Any existing S4R artifacts remain immutable optional inspection evidence. No README,
`metadata.json`, canonical name, legacy alias, provenance record, or duplicated model
description is required.
### 7.4 Displacement header mapping
After trimming header whitespace, the declared S4 displacement CSV uses:
| CSV column | comparison field/component | FESA HDF5 source |
| --- | --- | --- |
| `Part Instance Name` | `instance_name` | `/model/nodes.instance_name` |
| `Node Label` | `source_node_label` | `/model/nodes.source_label` |
| `U-U1` | displacement `U1` | `nodal/displacement` column 0, HDF5 component `UX` |
| `U-U2` | displacement `U2` | `nodal/displacement` column 1, HDF5 component `UY` |
| `U-U3` | displacement `U3` | `nodal/displacement` column 2, HDF5 component `UZ` |
| `UR-UR1` | displacement `UR1` | `nodal/displacement` column 3, HDF5 component `URX` |
| `UR-UR2` | displacement `UR2` | `nodal/displacement` column 4, HDF5 component `URY` |
| `UR-UR3` | displacement `UR3` | `nodal/displacement` column 5, HDF5 component `URZ` |
Reaction and stress CSVs do not enter MITC4 pass/fail. No row is synthesized from
those optional files.
### 7.5 Normalized comparison row
CSV and HDF5 displacement rows normalize in memory to:
```text
case_id, instance_name, source_node_label, component, value, hdf5_dataset_path
```
The unique key is `(case_id,instance_name,source_node_label,component)`. Stable
ordering is case, instance declaration order, stable source node order, then component order
`[U1,U2,U3,UR1,UR2,UR3]`.
### 7.6 Row-set precheck and comparison policy
Before tolerance evaluation:
1. Verify the declared input and displacement CSV path exists without mutating it.
2. Verify the trimmed displacement headers in Section 7.4.
3. Verify finite values, unique row keys, and exact source node/instance identities.
4. Project HDF5 and reference to the same six-component displacement inventory.
5. Fail on any missing, extra, duplicate, nonfinite, header-mismatched, or
identity-mismatched projected row.
Only `U1/U2/U3` affect pass/fail. `UR1/UR2/UR3` are always compared and reported but
can emit only an approved deterministic nonblocking warning.
For every matched displacement row:
```text
row_tolerance = 1.0e-5
row_pass = abs(fesa_value-reference_value) <= row_tolerance
```
The `1.0e-5` value is in the user-consistent length unit for U and dimensionless for
UR. No reference or result value is zero-clamped and neither component scale nor a
row-specific denominator changes the fixed value. A reference scale may remain in the
report as diagnostic information only. U exceedance fails; UR exceedance emits a
deterministic warning only. The separate B33 mixed tolerance is unchanged.
The report records every U/UR row, blocking/nonblocking decision, absolute error,
fixed-tolerance-normalized error, RMS error, displacement/rotation vector-norm
error, worst source row/component, and every UR warning.
## 8. CLI and Diagnostics Contract
```powershell
fesa.exe <model.inp> --output <results.h5>
```
Omitting `--output` uses `results.h5` in the current directory. Unknown option,
missing input, missing output argument, or repeated `--output` is usage failure.
| exit code | meaning |
| ---: | --- |
| `0` | successful analysis and authoritative HDF5 finalization |
| `2` | CLI usage error |
| `3` | input syntax or semantic mapping error, including unsupported keyword, formulation, wrapper, step, or distributed load |
| `4` | model validation error, including section/material property, geometry, director, Jacobian, or drilling-direction aggregate moment |
| `5` | factorization or substitution error |
| `6` | HDF5 write, schema validation, or atomic finalization error |
Each stderr and HDF5 diagnostic has exact field order `severity`, `code`, `file`,
`line`, `keyword`, `entity_identity`, `message`. Source-backed records carry
normalized file and 1-based line; source-less solver/output records use explicit
empty source fields. Order is source declaration order, file line, stable entity ID,
diagnostic code, then discovery order for an otherwise equal key.
The approved shell-specific diagnostic inventory includes:
| code | class/exit | meaning |
| --- | --- | --- |
| `unsupported-element-formulation` | input/3 | element type is not S4/S4R in this feature |
| `unsupported-mixed-element-model` | input/3 | shell and non-shell element/joint semantics are mixed |
| `invalid-shell-connectivity` | input/3 | connectivity arity is not four, a node repeats, or a connected source node is unresolved |
| `unresolved-shell-section` | input/3 | section/material/ELSET reference is unresolved |
| `invalid-shell-section-assignment` | input/3 | an element resolves to zero or multiple shell sections |
| `unsupported-shell-section-option` | input/3 | composite, offset, orientation, variable thickness, or other excluded meaning appears |
| `invalid-shell-thickness` | model/4 | thickness is nonfinite or nonpositive |
| `invalid-shell-material` | model/4 | isotropic material violates finite `E,nu` bounds |
| `invalid-shell-geometry` | model/4 | duplicate, self-intersecting, zero-area, reversed, or nonfinite surface geometry |
| `opposed-incident-normal` | model/4 | an incident normal pair has nonpositive dot product before averaging |
| `invalid-shell-director` | model/4 | candidate, average, interpolation, or tangent-frame construction is invalid |
| `invalid-shell-jacobian` | model/4 | a required point has nonfinite/nonpositive `J` or nonfinite basis data |
| `unsupported-drilling-load` | model/4 | nonzero aggregate moment violates `rho_M<=1e-12` |
| `unsupported-distributed-load` | input/3 | DLOAD, pressure, gravity, body/edge/follower load is requested |
The accepted optional `*SHELL SECTION` integration-point field emits no diagnostic.
Allowlisted `*PREPRINT`, `*RESTART`, and output-request no-ops retain their existing
warning behavior.
## 9. Validation Rules
| validation area | required pass condition | failure class |
| --- | --- | --- |
| keyword inventory | supported or exact allowlisted no-op | input, exit 3 |
| nesting/cardinality | closed part/assembly/instance/step; one assembly and one static step | input, exit 3 |
| source identity | duplicates absent; all references resolved; multi-instance identity unique | input, exit 3 |
| element syntax/semantics | only four-node S4/S4R, distinct resolved connectivity, internal FESA-MITC4, no mixed element model | input, exit 3 |
| resolved element geometry | source order, finite nonzero area, topology and positive-Jacobian predicates pass | model, exit 4 |
| material/section syntax | exact row grammar, resolvable references, exactly one centered homogeneous assignment per element | input, exit 3 |
| material/section values | finite approved `E,nu,t` bounds | model, exit 4 |
| director/geometry | deterministic pairwise orientation, average and frame construction pass | model, exit 4 |
| boundary/load syntax | global DOF 1..6, resolved finite values, no conflicting prescribed values | input, exit 3 |
| aggregate nodal moment | exact-zero case or nonzero `rho_M<=1e-12` | model, exit 4 |
| history | sole static Step-1/frame 0, NLGEOM disabled | input, exit 3 |
| HDF5 model | exact paths, dtypes, shapes, IDs, source types, directors, sections, and finite values | output, exit 6 |
| HDF5 results | every mandatory row/location/component exists in stable order and is finite | output, exit 6 |
| S4 case | exact declared input/displacement paths and unique finite U/UR rows | reference precheck |
| S4R source support | parser/common-kernel/deterministic-assembly/HDF5 metadata tests; no Abaqus artifact consumption | implementation verification |
| comparison | exact normalized row-set; U blocking; UR warning-only; approved tolerance | reference verification |
No successful parser/HDF5 implementation, numerical solution, reference comparison,
physics review, or release status follows from approval of this document alone.
## 10. Requirement Traceability
| requirement group | I/O contract coverage | remaining owner |
| --- | --- | --- |
| `001-004`, `021-023`, `030`, `037` | exact step, S4/S4R mapping, source/internal identity, wrapper and no-op policies | Implementation Planning tests |
| `005-010` | six global DOFs, isotropic ELASTIC, single-row SHELL SECTION, exact assignment | Implementation Planning tests |
| `011-016` | auto-director semantic mapping, basic geometry predicates and fail-closed diagnostics | Implementation Planning tests |
| `017-020` | BOUNDARY/CLOAD grammar, deterministic aggregation, `rho_M<=1e-12`, distributed-load rejection | Implementation Planning tests |
| `024-029` | Domain/AnalysisModel/DofManager/AnalysisState semantic ownership and residual meaning | Implementation Planning |
| `031-038` | source-independent MITC4 identity, fixed drilling stabilization and full-integration policy; no drilling output | Implementation Planning tests |
| `039-048` | additive HDF5 v0 paths, mandatory quantities, location identity, atomic output | Reference Model and Implementation Planning |
| `049-057` | diagnostic/schema hooks and required verification-metric/physical-energy evidence | Numerical Review and planning |
| `058-064` | normalized U/UR rows, fixed absolute `1.0e-5`, blocking/warning behavior, report inventory | Reference Verification |
| `065-072` | exact current S4 paths, S4R reference non-consumption, immutability and displacement-only gate | Reference Model |
## 11. Open Issues and Downstream Handoff
### 11.1 Numerical Review boundary
No I/O-owned calibration value remains open. Numerical Review shall verify the exact
fixed drilling rule, basic geometry predicates, required HDF5 inventory, and fixed
absolute MITC4 tolerance mapping. Drilling calibration/energy output, `NR-O03`, `NR-O04`, bundle
administration and reference-portfolio expansion are removed scope.
### 11.2 Reference Model Agent
- Write `docs/reference-models/linear-static-mitc4-shell-reference-models.md` using
this exact keyword/HDF5/reference-row contract.
- Record only the two exact existing input/displacement pairs, comparison components,
HDF5 projection, source-row identity, fixed absolute MITC4 tolerance and immutability rule.
- Treat reaction/stress artifacts as nonblocking review evidence and do not create
location-equivalence claims absent from this contract.
### 11.3 Numerical Review Agent
- Confirm cross-document numerical consistency and rerun the gate before authorizing
Implementation Planning.
### 11.4 Implementation Planning Agent
- Planning is authorized by the numerical review; implementation and Harness execution
remain separately unauthorized until explicitly requested.
- After approval, convert every supported/unsupported keyword row, source identity,
geometry/director error, drilling-load projection, exact HDF5 path/shape/order,
atomic failure, source-row normalization, and U-versus-UR decision into
`RED -> GREEN -> VERIFY` tests.
- Use the project Harness skill to draft multiple self-contained Steps and obtain user
approval before creating phase-planning files. Do not run the executor without a
separate explicit request.
- Keep distributed loads, mixed beam-shell models, Abaqus reduced integration,
nonlinear state/tangent, and reference artifact mutation outside the plan.
### 11.5 Reference Verification Agent
- Enforce artifact/schema precheck before numeric tolerance.
- Match HDF5 and Abaqus rows only by the normalized identity in Section 7.5.
- Never ignore missing/extra/nonfinite rows, synthesize S33/S13/S23, average location
mismatches, or let UR warnings change U pass/fail.
docs/linear-static-mitc4-shell/numerical-review.md
+366
View File
@@ -0,0 +1,366 @@
# Linear Static MITC4 Shell Numerical Review
## 1. Metadata
- feature_id: `linear-static-mitc4-shell`
- source_formulation: `docs/formulations/mitc4-shell-formulation.md`
- source_requirements: `docs/requirements/linear-static-mitc4-shell.md`
- source_research: `docs/research/linear-static-mitc4-shell-research.md`
- source_io_definition: `docs/io-definitions/linear-static-mitc4-shell-io.md`
- source_reference_inventory: `docs/reference-models/linear-static-mitc4-shell-reference-models.md`
- repository_policy: `AGENTS.md`, `docs/SOLVER_AGENT_DESIGN.md`,
`docs/numerical-reviews/README.md`
- reviewed_head: `cf769aa` (`mathematical implementation baseline`)
- prior_pass_commit: `60b42f4` (`context-only; verdict not inherited`)
- status: `pass-for-implementation-planning`
- owner_agent: `numerical-review-agent`
- date: `2026-08-13`
- implementation_planning_authorized: `true`
- implementation_complete: `false`
- build_test_complete: `false`
- reference_comparison_complete: `false`
- physics_evaluation_complete: `false`
- release_ready: `false`
이번 재검토는 현재 HEAD의 요구조건, 연구, 정식화, I/O 및 reference-case 계약을
처음부터 상호 대조했다. 기존 review의 판정과 artifact 관찰 결과는 결론의 전제로
사용하지 않았고, 이전 finding은 현 문서의 수식으로 다시 검산한 뒤 disposition만
기록했다. 원 MITC4 local paper는 tying 위치와 covariant shear 보간을 확인하는 데
read-only로 사용했다.
이 단계에서는 Abaqus, Harness, C++ build/test, FESA 실행 및 reference comparison을
수행하지 않았다. Reference artifact를 생성, 수정, 복원 또는 정규화하지 않았다.
## 2. Review Verdict
- verdict: `pass-for-implementation-planning`
- critical_blockers: `none`
- confirmed_defects: `none in the approved current linear-static scope`
- open_blocking_questions: `none`
- reason: 현재 정식화는 24 global DOF와 20 physical DOF의 관계, MITC4 shear
tying, plane-stress section law, 공통 `2 x 2 x 2` quadrature, residual/stiffness,
고정 drilling 안정화, 물리 recovery 및 검증 불변식을 구현계획으로 옮길 수 있을
만큼 명시한다. 요구조건, I/O 및 reference 계약과 모순되는 차원, 부호, 위치 또는
pass/fail 의미도 발견되지 않았다.
- downstream_boundary: 이 판정은 Implementation Planning 진입만 허용한다. 구현,
MSVC build/CTest, reference comparison, physics sanity 또는 release를 승인하지 않는다.
정식화 Section 15의 geometrically nonlinear residual/tangent는 future-only다. 완전한
`Phi: R24 -> R20`, map Hessian, objective drilling potential 및 finite-rotation load work가
미정인 사실은 미래 nonlinear 구현을 막지만 현재 linear-static 판정은 막지 않는다.
## 3. Critical Findings
### 3.1 Confirmed defects
현재 승인된 선형 정적 범위에서 구현계획 전에 Formulation 또는 Research로 돌려보낼
confirmed mathematical defect는 없다.
`K20`의 exact-arithmetic 대칭/positive-semidefinite 구조와 20-to-24 congruence는
일관된다. 다만 실제 구현의 rank, rigid action, patch field와 reference error는 문서
검토만으로 통과했다고 볼 수 없으며 Section 6의 downstream test evidence가 필요하다.
### 3.2 Previous finding disposition
| previous item | rerun disposition | current independent basis |
| --- | --- | --- |
| `NR-C01` Jacobian/geometry inventory | `resolved` | Formulation 9.2-9.3은 center, eight stiffness points, four tying points 및 committed recovery points를 공통 fail-closed inventory로 두고 finite bases, nonzero surface measure와 `J>0`를 요구한다. 승인 범위는 calibrated distortion/warp cutoff를 요구하지 않는다. |
| `NR-C02` drilling normalization | `resolved` | Formulation 12.2는 `R+`를 오직 8 physical tangent-rotation diagonals의 finite positive 값으로 제한하므로 모든 후보의 단위가 `force*length`로 같다. |
| `NR-C03` mixed-DOF spectrum scaling | `resolved` | Formulation 12.5의 `(L_e I3,I2)` 및 `(L_e I3,I3)` congruence는 rank/condition evidence에서 translation/rotation 단위 혼합을 제거한다. Raw mixed-unit spectrum은 금지된다. |
| `NR-C04` 20/24 weak-form mismatch | `resolved` | Formulation 5.2-5.3과 7.1-7.2는 physical, drilling, external work를 모두 `V24`에서 `T_p^T`와 `T_d^T`로 결합한다. |
| `NR-C05` nonlinear 20-to-24 closure | `resolved for current scope` | Section 15는 physical chart tangent와 conditional global pullback을 분리하고 map-curvature 항을 보존하며, 미정인 global map/objective drill을 future-only blocker로 명시한다. |
| `NR-D01` drilling-direction moment | `retained and consistent` | Exact-zero moment는 별도 처리하고 nonzero moment에 `rho_M=abs(d dot M)/norm(M)<=1e-12`를 적용한다. Numerical drilling은 거부된 moment를 운반하지 않는다. |
| `NR-D02` normalized algebraic checks | `retained and consistent` | `1e-12` symmetry/frame/energy와 `1e-10` rigid/residual/equilibrium 기준은 scaled matrices와 unclamped denominators에 적용된다. |
| `NR-O01` coefficient sweep/plateau | `closed by product decision` | `k_d=1e-3 min(R+)`가 고정 계약이다. Sweep, plateau 및 coefficient optimality는 구현 gate가 아니다. |
| `NR-O02` drilling-energy ratio | `removed from scope` | Drilling energy는 내부 quadratic identity일 뿐 physical energy나 mandatory output이 아니며 ratio/warning threshold도 요구하지 않는다. |
| `NR-O03` smooth-director calibration | `removed from scope` | Pairwise positive incident-normal orientation, finite/nonzero averaging 및 duplicate-node fold modeling이 승인된 exact predicate다. 별도 angle calibration은 gate가 아니다. |
| `NR-O04` distortion/warp calibration | `removed from scope` | Basic topology, finite/nonzero surface measure 및 required-point `J>0`가 승인된 predicate다. Quality sweep이나 cutoff는 gate가 아니다. |
| `NR-O05` U/UR tolerance | `resolved` | 모든 관련 문서가 sole S4 reference에 고정 절대오차 `1.0e-5`, U blocking, UR warning-only를 동일하게 정의한다. Reference scale은 판정에 사용하지 않으며 S4R은 reference gate가 아닌 common-path evidence다. |
이전의 `needs-reference-model` 판정에 포함됐던 canonical naming, README,
`metadata.json`, provenance, expanded portfolio 및 아직 없는 comparison result는 현재
프로젝트 정책상 formulation verdict의 blocker가 아니다. 현 Reference Model 문서는
정확한 기존 input/displacement path와 row/tolerance 계약을 제공한다.
### 3.3 Open questions
- current_linear_scope: `none blocking`
- future_geometric_nonlinearity: finite global rotation coordinate, `Phi`와 그 1/2차
미분, chart recentering, objective drilling, nodal-moment work 및 nonlinear output/state
계약이 미정이다. 이는 별도 future formulation/review가 소유한다.
- optional_characterization: near-singular positive-J geometry의 conditioning과 original
MITC4의 distorted-curved membrane locking을 더 넓게 정량화할 수 있으나 현재 승인된
planning/completion gate는 아니다.
- downstream_results: implementation rank/patch evidence, S4 reference comparison과
S4R common-path test 결과는 해당 후속 Agent가 판정한다. 부재 자체는
pre-implementation review의 결함이 아니다.
## 4. Numerical Risk Assessment
| risk label | assessment | required in-scope control |
| --- | --- | --- |
| `rigid_body_modes` | Physical `K20`은 six rigid modes와 expected rank 14를 가져야 한다. 24-DOF embedding은 네 drill null coordinates를 더하고 fixed drill block 뒤 expected rank 18/nullity 6이다. | 세 translation과 세 rotation을 명시적으로 구성한다. Rotation mode는 `u_I=omega x X_I`, `theta_I=omega-(omega dot d_I)d_I`, `gamma_I=0`를 사용한다. |
| `patch_test` | Bilinear membrane/bending field와 MITC tied shear는 required patch states를 표현할 계약을 갖는다. | `E11/E22/G12`, `K11/K22/K12`, `G13/G23`를 독립 시험하고 signs/component order/resultants/stress를 함께 확인한다. |
| `symmetry` | `B^T C B`, `T_p^T K20 T_p`, `T_d^T(k_d I)T_d`는 exact arithmetic에서 symmetric이다. | Scaled Frobenius check `<=1e-12`; deterministic assembly가 대칭을 깨지 않는지 확인한다. |
| `positive_definiteness` | Free element는 six-mode semidefinite이고, 충분히 구속된 nonsingular `Kff`는 positive definite가 기대된다. Geometry 또는 supports가 부적절하면 singularity가 정당하다. | Scaled spectrum/rank, non-rigid positive physical energy, constrained solve 및 singular negative cases를 분리한다. |
| `hourglass` | `1 x 1` reduced integration을 쓰지 않으므로 Abaqus-style hourglass path는 `N/A`다. | Full `2 x 2` midsurface rank test는 유지한다. S4R source label로 reduced rule을 선택하지 않는다. |
| `shear_locking` | Edge-midpoint MITC projection이 transverse-shear locking을 다루지만 모든 mesh/thickness에서 완전 제거를 주장할 수 없다. | Required shear/bending patch와 declared S4 reference를 통과한다. Broader thin/thick convergence는 nonblocking characterization이다. |
| `membrane_locking` | Original MITC4는 membrane strain을 수정하지 않아 distorted curved meshes에서 알려진 locking 위험이 남는다. | Known limitation을 유지하고 MITC4+ 성능을 주장하지 않는다. Expanded curved/distorted portfolio는 optional이다. |
| `volumetric_locking` | 승인된 homogeneous plane-stress shell에는 `N/A`다. | `C5`를 3D nearly-incompressible law로 확장하지 않는다. |
| `distortion` | 양의 `J`를 유지하는 심한 distortion/warpage는 정확도와 rank/conditioning을 악화할 수 있다. | 모든 required location의 exact predicates와 rank/finite-result checks를 시행한다. 승인되지 않은 quality cutoff를 추가하지 않는다. |
| `singular_jacobian` | Nonfinite/nonpositive `J`, zero surface measure, invalid reciprocal basis는 mapping을 무효화한다. | Center, stiffness, tying 및 recovery inventory 전체를 omission/clamp 없이 fail closed한다. |
| `conditioning` | Thin shells, near-degenerate positive-J geometry 및 작은 fixed drill scale에서 `Kff` conditioning이 나빠질 수 있다. | Spectrum/condition evidence는 오직 length-scaled matrix를 사용한다. Threshold calibration은 gate가 아니지만 factorization failure는 결정적으로 진단한다. |
| `convergence` | Current solve는 direct linear solve라 Newton convergence는 `N/A`; spatial convergence와 locking trend는 모델 의존이다. | Free residual/global equilibrium `<=1e-10`과 declared S4 reference case를 확인한다. Broader mesh sequences는 optional이다. |
| `drilling_contamination` | Numerical drill이 physical strain/recovery에 들어가면 비물리 결과가 생긴다. | `T_p`/`T_d`를 분리하고 pure drill에서 physical strain/resultant/stress/energy가 zero임을 시험한다. Full residual은 의도대로 stabilized system 전체를 포함한다. |
| `future_nonlinear_misuse` | Section 15만으로 global nonlinear element를 만들면 nonobjective drill 또는 inconsistent tangent가 된다. | Current plan에서 완전히 제외하고 별도 승인 전 실행하지 않는다. |
## 5. Consistency Checks
### 5.1 Units, dimensions, DOF order, and constrained/free system — `pass`
- Per-node global order is exactly `[UX,UY,UZ,URX,URY,URZ]`; element order is 24
global coordinates and 20 physical coordinates
`[uX,uY,uZ,alpha,beta]` per node plus four separately selected `gamma` coordinates.
- `T_p` is `20 x 24`, `T_d` is `4 x 24`, `K20` is `20 x 20`, and both global
stiffness contributions are `24 x 24`.
- Translation-translation, translation-rotation, and rotation-rotation stiffness
blocks have units `force/length`, `force`, and `force*length`; `R+` therefore
excludes every translational diagonal.
- The constrained/free equation is `Kff*df=Ff-Kfc*dc`. Stiffness partition and
factorization precede load assembly, and an all-constrained valid `0 x 0 Kff` is
not reclassified as singular.
- `r=K*d-F` fixes the internal-minus-external sign. Constrained entries are the
required reaction rows and free entries remain residual evidence.
### 5.2 Local/global transforms, congruence, and energy — `pass`
- `(a_I,b_I,d_I)` and `(e1,e2,e3)` are deterministic right-handed orthonormal frames.
The least-aligned-axis nodal rule avoids a fixed-axis parallel singularity.
- `[alpha,beta,gamma]^T=R_I^T theta_I^g` gives
`delta d=beta*a-alpha*b=theta x d` with the required sign.
- `q20=T_p qg` and `gamma=T_d qg` preserve virtual work. Congruence gives
`Kphys24=T_p^T K20 T_p` and `Kdrill24=T_d^T(k_d I4)T_d`; the corresponding local and
global quadratic energies are identical.
- A physical rigid rotation uses only the tangent projection of `omega`, so `gamma=0`
and drilling does not destroy the six physical rigid modes.
### 5.3 Kinematic operators and MITC tying — `pass`
- Bilinear `N_I` satisfies partition, Kronecker and derivative-sum identities.
- Membrane and bending content comes from the direct covariant small-strain operator.
Only `epsilon_xi-zeta` and `epsilon_eta-zeta` are replaced.
- `epsilon_xi-zeta` is tied at `(0,-1,0)` and `(0,+1,0)` and interpolated in `eta`;
`epsilon_eta-zeta` is tied at `(-1,0,0)` and `(+1,0,0)` and interpolated in `xi`.
Each interpolation reproduces its own edge value and is constant along the edge
direction, matching the original MITC4 construction.
- The assumed covariant tensor is reconstructed through reciprocal bases, projected
into the stored local Cartesian frame, and converted once to engineering shear
`gamma_ij=2 epsilon_ij`. The same projected `B_bar` drives strain, internal force,
stiffness and recovery.
### 5.4 Constitutive and section matrices — `pass`
- `Cps=E/(1-nu^2)[[1,nu,0],[nu,1,0],[0,0,(1-nu)/2]]` uses engineering `G12`; its
shear coefficient is exactly `G=E/[2(1+nu)]`.
- `C5=diag(Cps,(5/6)G I2)` is symmetric positive definite for `E>0` and
`-1<nu<0.5`. `sigma33=0` and absent thickness stretch remain assumptions.
- `A=t Cps`, `B=0`, `D=t^3 Cps/12`, and `As=(5/6)Gt I2` have consistent dimensions.
Membrane/shear strains are dimensionless, curvature is `1/length`, `N/Q` is
`force/length`, `M` is `force`, stress is `force/length^2`, and energy is
`force*length`.
### 5.5 Jacobian, derivative transform, and integration — `pass`
- The three-dimensional degenerated mapping uses
`X=sum(N X_I)+(t*zeta/2)sum(N d_I)` with a unit nodal director and separate
thickness, preventing nodal thickness double counting.
- `J=det[G_xi,G_eta,G_zeta]` and finite covariant/reciprocal bases are checked at all
eight stiffness points, all four midsurface tying points, center, and every
committed bottom/middle/top recovery evaluation. Failed points are not skipped,
averaged, clamped or repaired.
- Direct natural derivatives are converted covariantly and then to the local
Cartesian tensor through contravariant bases; no flat-element derivative shortcut
is substituted for curved/warped accepted geometry.
- Both S4 and S4R use the common in-plane `2 x 2` points
`+-1/sqrt(3)` with unit weights and two identical thickness points, for eight
volume evaluations. Tied shear is evaluated at `zeta=0` and reused at both
thickness points while the remaining mapping and direct components use the actual
thickness point.
### 5.6 Internal force, residual, stiffness, and future tangent — `pass`
- Current `K20=integral(B_bar^T C5 B_bar dV)` and `f_int20=K20 q20` are mutually
consistent and symmetric positive semidefinite in exact arithmetic.
- The complete current weak form is in `V24` and adds the numerical drilling
gradient before subtracting the global nodal `CLOAD` vector.
- No geometric stiffness or nonlinear state enters the current product path.
Future Section 15 correctly separates `Kmat` and the stress-dependent `Kgeo` and,
conditionally on a future `Phi`, includes both `A^T K20 A` and the
residual-weighted map-Hessian term.
### 5.7 Fixed drilling contract — `pass`
- `R+` contains only finite strictly positive diagonals of the eight physical
tangent-rotation coordinates. `k_ref=min(R+)`, `k_d=1e-3 k_ref`, and
`Kd_local=k_d I4` are dimensionally consistent and deterministic; empty `R+`
fails validation.
- `T_d^T(k_d I4)T_d` is symmetric and positive on the four pure drilling
coordinates. It must remove those four nonphysical null modes without changing
the physical rank/null modes.
- Drilling is excluded from generalized strain/resultant/stress and reported
physical strain energy. A director-parallel applied nodal moment is rejected as
`unsupported-drilling-load`; no numerical drill load channel exists.
### 5.8 Recovery, signs, locations, units, and external comparison — `pass`
- Nodal `[U1,U2,U3,UR1,UR2,UR3]` and full-residual
`[RF1,RF2,RF3,RM1,RM2,RM3]` are global and source-node ordered.
- Four midsurface Gauss rows recover
`[E11,E22,G12,K11,K22,K12,G13,G23]` and
`[N11,N22,N12,M11,M22,M12,Q13,Q23]` in the stored local frame. The definition
`e_m(z)=epsilon0+z*kappa` fixes curvature, moment, and bottom/top stress signs.
- `[S11,S22,S12]` is evaluated directly at `zeta=-1,0,+1`; `S33=0` is documented but
not emitted, and `S13/S23` point stress is not synthesized. Different natural or
section locations are never averaged.
- Reference comparison first rejects missing, extra, duplicate, nonfinite or
identity-mismatched rows. Every U/UR row then uses fixed absolute tolerance
`1.0e-5`; no reference-scale decision term, zero clamp or row denominator is
introduced. U1/U2/U3 is blocking and UR1/UR2/UR3 is warning-only.
- Source S4 and S4R select the same FESA MITC4 kernel/quadrature/recovery path while
preserving source type. This is an input mapping, not an Abaqus formulation,
integration, stabilization or recovery equivalence claim.
## 6. Verification Readiness
### 6.1 Downstream unit and invariant tests
Implementation Planning shall convert the following to `RED -> GREEN -> VERIFY`:
1. Shape identities; nodal/integration frame orthonormality, handedness and axis
tie-break determinism.
2. `T_p`/`T_d` dimensions, orthogonal channel selection, virtual-work equality and
nonzero transformation-energy equality.
3. Hand-calculated direct membrane/bending columns, all four covariant tying values,
interpolation weights and engineering-shear factors.
4. `Cps/C5/A/D/As` coefficients, symmetry, positive definiteness, dimensions and
force/length unit-rescaling invariance.
5. Common `2 x 2 x 2` point/weight order and an independent analytical or
higher-order flat-element stiffness/recovery cross-check.
6. Required-location geometry validation: valid planar/rotated/warped cases and
duplicate, bow-tie/self-intersecting, zero-area, reversed, nonfinite,
nonpositive-J and opposed-normal negative cases.
7. Scaled symmetry `<=1e-12`, physical rigid action `<=1e-10`, expected physical
rank 14, stabilized rank 18/nullity six, and positive non-rigid physical energy.
8. Exact `R+` membership, exclusion of translations, fixed coefficient, empty-`R+`
failure, pure drill action and zero physical recovery/energy.
9. Stable COO/reduction, source/result/diagnostic order and thread-count
repeatability.
10. `Kff/Kfc` effective RHS, nonzero prescribed values, full-residual reaction,
singular-support negative case, and valid all-constrained `0 x 0 Kff` case.
11. Exact-zero and accepted/rejected `rho_M` moment projections, including proof
that rejected drilling moments never reach stabilization.
12. Mandatory HDF5 locations/components/units, physical-only energy, nonfinite
recovery failure and atomic finalization.
### 6.2 Required patch and sign tests
- independent constant `E11`, `E22`, and `G12` membrane fields with `N` and
middle-stress signs;
- pure `K11` and `K22` bending with `M` order and bottom/top stress reversal;
- pure `K12` twist with `M12` sign;
- constant `G13` and `G23` transverse shear with `Q13/Q23` order;
- six physical rigid states and four pure drilling states;
- source-type-only S4/S4R variants producing identical FESA numeric rows and
different preserved source metadata.
### 6.3 Reference and physics handoff readiness
The sole declared read-only acceptance pair is:
- `reference/shell/shell.inp` with
`reference/shell/shell displacements.csv` for full-integration S4.
S4R remains required input coverage through source mapping, common-kernel,
deterministic-assembly and HDF5 metadata tests, but no S4R Abaqus artifact is
consumed by reference acceptance.
The Reference Model and I/O documents define deterministic HDF5-to-CSV identity,
precheck and tolerance sufficiently for later comparison. This review did not assert
that `results.h5` exists or that any row passes. Reference Verification owns numeric
U/UR outcome; Physics Evaluation owns force/moment balance, displacement direction,
symmetry, result signs, recovered-resultant consistency and physical plausibility.
### 6.4 Missing evidence classification
- blocking_for_current_formulation: `none`
- required_after_implementation: invariant, patch, MSVC build/CTest, declared
reference comparison and physics evidence above
- nonblocking_optional: drilling coefficient sweep/energy ratio, `NR-O03`, `NR-O04`,
canonical naming, README/metadata/provenance, expanded benchmark portfolio and
broader mesh convergence studies
- future_only: nonlinear directional-derivative/objectivity/Newton evidence after
its missing formulation decisions are separately approved
## 7. Required Revisions
### Formulation Agent
- None for the approved current linear-static implementation scope.
- Do not promote Section 15 to executable status until a separate formulation closes
the nonlinear global coordinate map, objective drilling and load-work contracts.
### Research Agent
- None before current Implementation Planning.
- Optional locking/convergence characterization must remain clearly outside the
approved implementation gate and must not imply MITC4+ or Abaqus equivalence.
### I/O Definition Agent
- None for the current numerical verdict. Preserve exact physical/full-residual
distinction, source identity, locations, units and U-versus-UR decision rule.
### Reference Model Agent
- None for the current numerical verdict. Preserve the two declared S4 files and every
optional existing reference artifact read-only, exclude S4R artifacts from acceptance
comparison, and do not add administrative or portfolio gates.
## 8. Downstream Handoff
### Implementation Planning Agent
Implementation Planning is authorized and shall:
- trace the required tests in Section 6 to the approved requirement IDs before
production work;
- keep `24 global -> 20 physical + 4 drilling` transforms, covariant MITC tying,
common `2 x 2 x 2` integration, fixed drilling and physical recovery as explicit
independent test seams;
- preserve stiffness assembly/partition/factorization-before-load, stable reduction,
full-residual reaction and failure-atomic HDF5 lifecycle;
- keep future nonlinear execution, coefficient calibration, drilling output,
`NR-O03/NR-O04`, reference-artifact mutation and Abaqus-equivalence claims outside
the plan.
This handoff authorizes planning only. It does not authorize Harness execution,
production implementation, reference artifact changes, or completion claims.
### Reference Verification Agent
- Compare authoritative FESA HDF5 rows directly with the matching declared Abaqus
displacement CSV after exact row-set precheck.
- Let only U1/U2/U3 affect pass/fail; report every UR1/UR2/UR3 warning without
changing the verdict.
### Physics Evaluation Agent
- After reference verification, independently evaluate force and global moment
balance, free residual, reaction sign, displacement direction, symmetry, positive
physical energy and consistency of local resultants/stresses.
### Coordinator and Release Agents
- Record the Numerical Review gate as passed for planning at HEAD `a058ef7`.
- Do not infer implementation or release completion. Build/test, reference,
physics-sanity and release-readiness gates remain pending.
docs/linear-static-mitc4-shell/physics-evaluation.md
+331
View File
@@ -0,0 +1,331 @@
# Linear Static MITC4 Shell Physics Evaluation Report
## Metadata
- feature_id: `linear-static-mitc4-shell`
- model_id: `shell-s4`
- evaluated_head: `820ba30c717b3d0e113775608e20dfd5fbc05d53`
- source_build_test_report:
`docs/build-test-reports/linear-static-mitc4-shell-build-test.md`
- source_reference_verification_report:
`docs/reference-verifications/linear-static-mitc4-shell-reference-verification.md`
- source_reference_model:
`docs/reference-models/linear-static-mitc4-shell-reference-models.md`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- source_formulation: `docs/formulations/mitc4-shell-formulation.md`
- source_numerical_review:
`docs/numerical-reviews/linear-static-mitc4-shell-review.md`
- source_io_definition: `docs/io-definitions/linear-static-mitc4-shell-io.md`
- status: `pass-for-release-agent`
- owner_agent: `physics-evaluation-agent`
- date: `2026-08-13`
This verdict means that the documented physical checks pass and the Release Agent
may audit release readiness. It does not approve release readiness, re-approve the
reference comparison, or change its tolerance decision.
## Input Evidence
The prerequisite reference-verification report has status
`pass-for-physics-evaluation`. The existing S4 reference-test route was rebuilt and
executed to regenerate fresh FESA evidence. Abaqus and other reference solvers were
not executed.
| evidence | exact path or identity | status | notes |
| --- | --- | --- | --- |
| build/test report | `docs/build-test-reports/linear-static-mitc4-shell-build-test.md` | `pass-for-reference-verification` | Clean MSVC x64 Debug build, focused `87/87`, lifecycle `10/10`, reference `8/8`, and full `144/144` CTest passed. |
| reference verification | `docs/reference-verifications/linear-static-mitc4-shell-reference-verification.md` | `pass-for-physics-evaluation` | Required prerequisite satisfied; 147/147 blocking U rows passed and no UR warning was emitted. |
| solver HDF5 | `.harness/build/reference/mitc4-shell-s4-comparison/results.h5` | present and readable | Freshly generated, 95,024 bytes; observed raw SHA-256 `E102D80E82BA133EBDF1C5532F3A0A4FE9984AB6CC36D00264399F7308D9230F` (inventory only). |
| comparison ledger | `.harness/build/reference/mitc4-shell-s4-comparison/comparison.json` | present and passing | 94,349 bytes; SHA-256 `8E8DEA51B6F7C663BACC41FDA6103A4596DB26E02F1EAD6069D458F51E0102E6`; `passed=true`. |
| declared S4 input | `reference/shell/shell.inp` | present, unchanged, read-only | SHA-256 `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF`. |
| declared displacement CSV | `reference/shell/shell displacements.csv` | present, unchanged, read-only | SHA-256 `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B`. |
| optional Abaqus reaction/stress CSVs | `reference/shell/shell reactions.csv`, `reference/shell/shell stresses.csv` | not used as equality gates | Their presence did not expand the approved U-only blocking boundary. |
| solver CSV views | N/A | not generated | HDF5 was inspected directly. |
| fresh S4 route | `.harness/build`, MSVC x64 Debug | pass | `Mitc4S4Reference.*` passed `2/2`. |
The HDF5 contains 49 nodes, 36 source-`S4` elements, internal formulation
`FESA-MITC4`, and the required full `2 x 2 x 2` result inventory. All inspected
numeric model and result values were finite. The diagnostics dataset contains four
approved warning rows for ignored `PREPRINT`, `RESTART`, and `OUTPUT` keywords and
no error diagnostic.
Raw HDF5 bytes are not a physics decision identity and may change across valid
regenerations. The projected values and deterministic comparison ledger are the
relevant evidence.
### Documented model expectation
The reference input is a flat `10 x 10`, thickness `0.5`, homogeneous isotropic
square plate with `E=2.1e11` and `nu=0.3`. Its 24 perimeter nodes are fully clamped
in all six global DOFs, and center node 2 at the global origin carries one
`F3=-100000` concentrated force. The geometry, boundary, material, and load are
symmetric about both global `x=0` and `y=0` planes.
The documented physical expectations are therefore:
- total constrained reaction force opposes the applied `-Z` force;
- total force and moment about the global origin balance within the approved
normalized `1e-10` limit;
- perimeter displacements are zero and the interior deflects in `-Z`, with the
largest magnitude at the center;
- the displacement and rotation field obeys the polar/axial-vector reflection
parity about both symmetry planes;
- a linear, flat transverse plate response has no membrane strain/resultant or
middle-surface in-plane stress, while bottom and top in-plane stresses reverse;
- stored physical strain energy is finite, strictly positive, and consistent with
the recovered generalized fields and `0.5 F^T d`;
- free residual, finite results, rank/rigid-mode evidence, and the approved
one-case coverage show no rigid-body or unsupported-mode symptom.
## Physics Checks
| check | documented expectation | observed evidence | verdict | classification |
| --- | --- | --- | --- | --- |
| global equilibrium | Applied plus constrained reaction force/moment about origin; normalized metrics `<=1e-10` | force residual `[0,0,-1.12049747258425e-9]`; moment residual `[6.45741238258779e-10,-2.63753463514149e-10,0]`; normalized force/moment `1.12049747258425e-14` / `2.35981341581908e-15` | pass | N/A |
| reaction consistency | Perimeter-only reactions from full residual oppose `F3=-100000`; constrained motion is zero | summed constrained force `[0,0,99999.9999999989]`; constrained displacement exactly zero | pass | N/A |
| displacement direction | Interior bends in `-Z`; center is maximum; no in-plane or drilling leakage | center `U3=-2.35504417650849e-5`; all 25 free-node U3 values nonpositive; `U1/U2/UR3` exactly zero | pass | N/A |
| symmetry | Correct polar/axial reflection parity about `x=0` and `y=0` | max absolute reflection mismatch `4.27126230127111e-20` / `2.29087480670778e-20` | pass | N/A |
| element force balance | No documented direct element-end-action output exists for shell GP resultants | Global assembled residual/equilibrium passed; direct element-end-action balance is skipped rather than inferred from mismatched locations | skipped | N/A |
| recovered resultant consistency | `N=A*epsilon0`, `M=D*kappa`, `Q=As*gamma0` at each of 144 GP rows | absolute L2 residual `9.9301874551584e-12`; normalized L2 `5.56240926027087e-17` | pass | N/A |
| stress/location/sign sanity | Local `[S11,S22,S12]` at bottom/middle/top; middle zero and faces reverse for this linear flat bending field | absolute L2 constitutive residual `1.29488994752188e-9`; normalized `3.05323934859307e-16`; middle stress exactly zero; face reversal exact | pass | N/A |
| rigid body/nonfinite | Complete constraints, finite solution, acceptable residual, no abnormal uncontrolled mode | zero nonfinite values; `FREE_RESIDUAL_NORMALIZED=1.07747756058988e-14`; rank/rigid-mode tests passed upstream | pass | N/A |
| physical energy | Positive and consistent physical-only energy; no drilling-energy gate | `1.17752208825422`; independently recovered value identical to relative `1.88569375589575e-16`; `0.5F^Td=1.17752208825424` | pass | N/A |
| model coverage | Approved sole S4 case plus declared invariant/patch/common-path portfolio | S4 case covers end-to-end symmetric plate response; focused build/test portfolio passed; expanded models are explicitly nonblocking | pass | N/A |
### 1. Global force and moment equilibrium
The reaction dataset is the assembled full residual `K*d-F`. Applying the
constraint mask gives
```text
sum constrained RF = [0, 0, 99999.9999999989]
sum applied F = [0, 0, -100000]
force residual = [0, 0, -1.12049747258425e-9]
```
The load acts at the global origin and therefore contributes no origin moment.
The constrained force and moment rows give
```text
moment residual = [ 6.45741238258779e-10,
-2.63753463514149e-10,
0 ]
```
These independently reconstructed values match the stored HDF5 equilibrium vector
exactly. The serialized normalized metrics are:
| metric | value | threshold | result |
| --- | ---: | ---: | --- |
| `FREE_RESIDUAL_NORMALIZED` | `1.07747756058988e-14` | `1.0e-10` | pass |
| `FORCE_BALANCE_NORMALIZED` | `1.12049747258425e-14` | `1.0e-10` | pass |
| `MOMENT_BALANCE_NORMALIZED` | `2.35981341581908e-15` | `1.0e-10` | pass |
### 2. Reaction consistency and constrained/free meaning
The 24 perimeter nodes provide 144 constrained DOFs; the remaining 150 DOFs are
free. The HDF5 constraint mask agrees with the input set exactly, all prescribed
values are zero, and the maximum constrained displacement is exactly zero.
The total positive `RF3=99999.9999999989` opposes the center `F3=-100000`. The
nearly zero total `RF1/RF2` and origin `RM1/RM2/RM3` are required by the centered
load and double symmetry. The largest raw free residual component is
`7.62156560085714e-10`; because translational and rotational entries have different
dimensions, the decision uses the documented normalized metric rather than this
raw maximum. The normalized free residual passes by more than three orders of
magnitude.
### 3. Displacement direction and deformation mode
Center node 2 has
```text
[U1,U2,U3,UR1,UR2,UR3]
= [0, 0, -2.35504417650849e-5, 0, 0, 0]
```
Every free-node `U3` is nonpositive, the center is the maximum-magnitude
translation, and every clamped boundary displacement is zero. Across the complete
model, maximum absolute `U1`, `U2`, and `UR3` are exactly zero. Maximum absolute
`UR1` and `UR2` are `7.55060026636931e-6` and
`7.55060026636933e-6`, respectively. This is the expected symmetric plate-bending
mode under a negative transverse center load, with no in-plane or drilling
deformation leakage.
### 4. Reflection symmetry and expected zeros
For reflection through `x=0`, polar displacement components transform as
`[-U1,+U2,+U3]`, while the axial rotation vector transforms as
`[+UR1,-UR2,-UR3]`. Reflection through `y=0` similarly uses
`[+U1,-U2,+U3,-UR1,+UR2,-UR3]`.
All 294 scalar nodal component comparisons per reflection were paired by source
coordinates. The maximum absolute mismatch was `4.27126230127111e-20` for the
`x` reflection and `2.29087480670778e-20` for the `y` reflection. The equality
evidence is numerical roundoff, not a new acceptance tolerance.
### 5. Shell generalized resultants and physical work signs
At every one of 36 elements times four midsurface Gauss locations, an independent
constitutive reconstruction applied the documented centered-section identities:
```text
N = A * epsilon0
M = D * kappa
Q = As * gamma0
```
The complete 1,152-component resultant comparison has absolute L2 residual
`9.9301874551584e-12` and normalized L2 residual
`5.56240926027087e-17`. All membrane strains and `N` resultants are exactly zero,
as required for this linear flat plate bending response.
The generalized work density `generalized_strain dot section_resultant` is strictly
positive at all 144 locations: minimum `4.46321446508071e-4`, maximum
`1.27059464107458e-1`, negative count `0`. This supports the physical sign and
component-order interpretation.
The shell contract does not expose element-end nodal actions and explicitly forbids
averaging mismatched result locations. Consequently a separate GP-to-element-end
force-balance assertion is not documented and is marked `skipped`; the assembled
global residual and equilibrium checks provide the required force-balance evidence.
### 6. Stress component, location, and sign sanity
HDF5 stores local in-plane `[S11,S22,S12]` directly at each GP and ordered section
positions `BOTTOM(-1), MIDDLE(0), TOP(+1)`. Independent reconstruction used
`Cps*(epsilon0+z*kappa)` at all 432 section locations. The absolute L2 residual is
`1.29488994752188e-9`, or normalized `3.05323934859307e-16`, against a maximum
absolute stored stress of `313250.779137971`.
All middle-surface in-plane stresses are exactly zero. For every component and GP,
bottom and top stresses are equal in magnitude and opposite in sign. This is the
documented curvature/stress-location convention for a centered homogeneous section.
No `S33`, `S13`, `S23`, nodal stress, or Abaqus stress equality was inferred.
### 7. Physical energy, residual, and rigid-body symptoms
The stored `PHYSICAL_STRAIN_ENERGY` is finite and positive:
```text
HDF5 physical energy = 1.17752208825422
independent GP generalized energy = 1.17752208825422
0.5 * F^T * d = 1.17752208825424
```
The HDF5-versus-recovered normalized difference is
`1.88569375589575e-16`; the final fresh HDF5-versus-external-work normalized
difference is `9.14561471609432e-15`. The HDF5 value excludes numerical drilling stabilization,
as required. No drilling-energy ratio, calibration, or warning criterion was
introduced.
The solution is finite, the full perimeter support is enforced, the expected
deformation mode is smooth and symmetric, all three normalized verification
metrics pass `1e-10`, and the build/test evidence passes six-rigid-mode,
stabilized-rank, non-rigid positive-energy, and pure-drill separation tests. No
rigid-body, singular, nonfinite, or abnormal-mode symptom is present.
### 8. Approved model coverage
The sole approved reference model provides end-to-end evidence for the
full-integration `S4 -> FESA-MITC4` path, a nonzero transverse bending response,
fully constrained reaction recovery, global force/moment balance, two-axis
symmetry, physical energy, and shell result recovery.
The prerequisite focused `87/87` build/test portfolio supplies the documented
complementary element evidence: membrane, bending, transverse-shear and twist patch
fields; six physical rigid modes; expected physical/stabilized rank; frame and
energy invariance; fixed numerical drilling and physical-recovery separation; and
S4/S4R common-kernel/source-metadata behavior. The reference verification supplies
the approved external displacement comparison.
This is the complete approved coverage for the feature. Pinched-cylinder,
hemisphere, Scordelis-Lo, locking/convergence sequences, drilling calibration,
expanded distorted/curved portfolios, and `NR-O01` through `NR-O04` are explicitly
nonblocking or out of scope and were not invented as new physics gates.
## Execution Evidence
| order | exact command or read-only operation | exit code | result |
| ---: | --- | ---: | --- |
| 1 | `cmake --build .harness/build --config Debug --target fesa_reference_tests` | `0` | Existing S4 reference route rebuilt. |
| 2 | `ctest --test-dir .harness/build -C Debug -R '^Mitc4S4Reference\.' --output-on-failure` | `0` | Fresh S4 tests `2/2` passed; FESA HDF5 and ledger regenerated. |
| 3 | `h5dump.exe -n .harness/build/reference/mitc4-shell-s4-comparison/results.h5` with HDF5/oneAPI runtime on `PATH` | `0` | Required HDF5 inventory inspected read-only. |
| 4 | `h5dump.exe -y -w 0 -m '%.17g' -d <dataset> .harness/build/reference/mitc4-shell-s4-comparison/results.h5` for model nodes/elements/mask/prescribed values, nodal U/R, shell frames/strain/resultant/stress, energy/equilibrium/metrics/diagnostics | `0` | High-precision read-only numerical audit supplied all reported values. |
| 5 | PowerShell independent input/mask, reaction/equilibrium, reflection, constitutive recovery, stress-location, energy, finite, and diagnostics audit over the `h5dump` values | `0` | All documented physics assertions passed. |
| 6 | `cmake --build .harness/build --config Debug --target fesa_unit_tests fesa_reference_tests`, then `ctest --test-dir .harness/build -C Debug -R 'Mitc4Shell(Kernel|Patch|Drilling|PhysicalRecovery)|ResultRecovery\..*Shell|Mitc4S4Reference' --output-on-failure` | `0` | Final focused verification passed `17/17`; the regenerated ledger retained `passed=true`, 294 rows, and zero warnings. |
Three intermediate audit-helper incidents were diagnostic-only and did not alter
the product or verdict: a compound-record regular expression initially omitted the
last node, a PowerShell array-expression initially bound subtraction to an array,
and a final optional `h5ls` operand-order probe exited `1`. The root causes were
confirmed as audit-command/parser usage, while successful high-precision HDF5
inspection established 49/49 nodes and the complete evidence above. They are not
solver, HDF5-schema, reference, or physics failures.
## Failure Classification
- classification: `N/A`
- primary_failure: `N/A`
- evidence: all documented force/moment equilibrium, reaction, displacement,
symmetry, recovery, stress-location, physical-energy, residual, finite-result,
rigid-mode and approved coverage checks passed
- correction_handoff: `N/A`
- non_gating_incident: resolved read-only audit helper parsing/usage errors only
## Evaluation Verdict
- verdict: `pass-for-release-agent`
- reason: the prerequisite reference status is valid and fresh FESA S4 evidence
satisfies every documented physical expectation under its approved threshold;
no implementation, formulation, I/O, model-coverage, nonfinite, rigid-body, or
environment failure remains
- release_approval: `not granted by this report`
- reference_reapproval: `not performed by this report`
## Handoff Recommendation
| target_agent | reason | required_input |
| --- | --- | --- |
| Release Agent | All documented MITC4 physics checks passed. | This report, the build/test and reference-verification reports, the fresh build-local HDF5/comparison evidence, and the nonblocking limitations below. |
## No-Change Assertion
- source_files_modified: `false`
- test_files_modified: `false`
- cmake_files_modified: `false`
- requirements_modified: `false`
- formulation_modified: `false`
- numerical_review_modified: `false`
- io_contract_modified: `false`
- reference_model_contract_modified: `false`
- build_test_report_modified: `false`
- reference_verification_report_modified: `false`
- phase_files_modified: `false`
- tolerance_policies_modified: `false`
- reference_artifacts_modified: `false`
- Abaqus_or_other_reference_solver_executed: `false`
- owned_report_created: `true`
- generated_build_local_evidence: `true`, ignored under `.harness/build/`
- pre_existing_untracked_build_test_report_preserved: `true`
- pre_existing_untracked_reference_verification_report_preserved: `true`
## Open Issues
- Nonblocking coverage limitation: the approved external reference inventory is one
flat, symmetric, fully clamped S4 plate. The approved analytical/unit portfolio
supplies membrane, shear, twist, rigid-mode, rank, drilling-separation and S4R
common-path evidence. No broader Abaqus or benchmark portfolio is claimed.
- Known original-MITC4 limitations remain: transverse-shear locking is mitigated by
the tying field, but distorted-curved membrane locking and broader thin/thick mesh
convergence are not characterized by this release gate.
- Source `S4R` maps to the same full-integration FESA kernel and is not compared to
the optional Abaqus S4R artifacts. This is an approved boundary, not missing
physics evidence.
- The fixed numerical drilling stiffness is not a physical stress/resultant/energy
channel. No drilling calibration, coefficient sweep, energy-ratio gate, or
director-parallel moment support is claimed.
- Geometrically nonlinear execution remains outside the current feature even though
future-only residual/tangent equations are documented. No nonlinear release claim
is made.
- No open issue blocks Release Agent review.
docs/linear-static-mitc4-shell/reference-comparison.md
+242
View File
@@ -0,0 +1,242 @@
# Linear Static MITC4 Shell Reference Verification Report
## Metadata
- feature_id: `linear-static-mitc4-shell`
- model_id: `shell-s4`
- source_head: `820ba30c717b3d0e113775608e20dfd5fbc05d53`
- source_build_test_report:
`docs/build-test-reports/linear-static-mitc4-shell-build-test.md`
- source_reference_models:
`docs/reference-models/linear-static-mitc4-shell-reference-models.md`
- source_io_definition: `docs/io-definitions/linear-static-mitc4-shell-io.md`
- source_requirements: `docs/requirements/linear-static-mitc4-shell.md`
- status: `pass-for-physics-evaluation`
- owner_agent: `reference-verification-agent`
- date: `2026-08-13`
The prerequisite build/test report has status `pass-for-reference-verification`.
This report verifies only the approved full-integration S4 displacement case. It
does not compare S4R artifacts, claim Abaqus formulation equivalence, approve
physics sanity, or approve release readiness.
## Verdict
The reference-comparison gate passes. The fresh FESA result has an exact
294-row identity match to the read-only Abaqus displacement CSV. All 147 blocking
`U1/U2/U3` rows satisfy the fixed absolute tolerance `1.0e-5`. All 147
warning-only `UR1/UR2/UR3` rows also satisfy `1.0e-5`, so no rotational warning
was emitted.
- declared cases compared: `1/1`
- blocking rows passed: `147/147`
- blocking failures: `0`
- warning-only rows compared: `147/147`
- warning-only exceedances and warnings: `0/0`
- missing / extra / duplicate / nonfinite rows: `0 / 0 / 0 / 0`
- largest blocking normalized error: `0.0190378534915144`
- comparison verdict: `passed=true`
## Artifact Inventory
| item | exact path | status | direct evidence |
| --- | --- | --- | --- |
| declared S4 input | `reference/shell/shell.inp` | present, unchanged | 4,770 bytes; SHA-256 `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` |
| required displacement CSV | `reference/shell/shell displacements.csv` | present, unchanged | 5,592 bytes; SHA-256 `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B`; 49 wide rows and six finite components per row |
| authoritative solver output | `.harness/build/reference/mitc4-shell-s4-comparison/results.h5` | present, valid | 95,024 bytes after a fresh verification run; observed raw SHA-256 `E88E5E5E1F83AB95CAE545AD1F28F896D3FCB82F3EA2B8006A3A703FED07A5CB` (non-decision inventory only) |
| deterministic comparison ledger | `.harness/build/reference/mitc4-shell-s4-comparison/comparison.json` | present, valid | 94,349 bytes; SHA-256 `8E8DEA51B6F7C663BACC41FDA6103A4596DB26E02F1EAD6069D458F51E0102E6`; `passed=true` |
| S4R reference artifacts | `reference/shellR/` | not consumed | Excluded from the approved acceptance comparison. |
| reaction and stress CSVs | other files under `reference/shell/` | not consumed | Optional inspection evidence only; not an equality gate. |
| FESA-derived CSV | N/A | not generated | HDF5 was compared directly to the Abaqus CSV. |
The input and required CSV had identical SHA-256 values and identical UTC
modification times (`2026-08-11T11:44:40.9520527Z`) before and after the fresh
comparison runs. `git diff --name-only -- reference` and
`git status --short -- reference` each returned zero paths.
The HDF5 hash above inventories one fresh generation, not a stable content
identity. Raw HDF5 bytes changed across regenerations while the projected values
and deterministic JSON ledger remained identical; concurrent executions of the
same ignored build-local route may replace the file again. This report does not
claim byte-identical HDF5 container output.
### Authoritative HDF5 projection audit
The comparator and a read-only HDF5 2.1.1 inspection established:
- `/metadata`: schema version `0`, feature `linear-static-mitc4-shell`, solver
version `0.1.0`, `Step-1`, frame `0`, internal formulation `FESA-MITC4`, and
integration rule `2x2x2-gauss; mitc4-edge-midpoint-shear`;
- source input identity:
`path=C:/Users/baram/orca/workspaces/FESADev/MITC4/reference/shell/shell.inp;content_identity=fnv1a64:cf0795df753d377e`;
- `/model/nodes`: 49 compound rows with ordered fields
`internal_node_id`, `instance_name`, `source_label`, and `coordinates`;
- `/model/elements`: 36 compound rows, source element type `S4`, and internal
formulation `FESA-MITC4`;
- `/steps/Step-1/frames/0/nodal/displacement`: float64 shape `[49,6]`, global
nodal components `[UX,UY,UZ,URX,URY,URZ]`, mapped to
`[U1,U2,U3,UR1,UR2,UR3]`;
- all projected source identities and displacement values are unique and finite.
## Comparison Contract
- case identity: `shell-s4`
- authoritative FESA dataset:
`/steps/Step-1/frames/0/nodal/displacement`
- HDF5 node identity source: `/model/nodes.instance_name` and
`/model/nodes.source_label`
- normalized key:
`(case_id, instance_name, source_node_label, component)`
- observed instance: `Part-1-1`
- observed source nodes: 49 unique labels
- CSV projection: trimmed `Part Instance Name`, `Node Label`, `U-U1`, `U-U2`,
`U-U3`, `UR-UR1`, `UR-UR2`, and `UR-UR3`
- stable component order: `[U1,U2,U3,UR1,UR2,UR3]`
- blocking inventory: `U1/U2/U3`
- warning-only inventory: `UR1/UR2/UR3`
- row precheck: exact key set, unique rows, finite HDF5/reference values, and
exact required HDF5 schema before tolerance evaluation
- tolerance source: requirements `FESA-REQ-LSMITC4-058` through `064`, the I/O
definition Section 7, and the approved reference-model contract Section 5
- row tolerance: `abs(fesa-reference) <= 1.0e-5`
- tolerance-normalized error: `absolute_error / 1.0e-5`
- `reference_scale`: diagnostic only; it does not alter the tolerance or verdict
- zero policy: no clamp, substitution, omission, averaging, or row-order matching
Independent ledger reconstruction found 294 projected CSV keys, 294 comparison
keys, zero duplicate keys, and exact set equality. All 294 serialized row
tolerances equal `1.0e-5`. The complete per-row decisions remain in the
identified deterministic `comparison.json`.
## Execution Evidence
The existing FESA S4 reference route was used; Abaqus and other reference solvers
were not executed. The first run regenerated the evidence after its test-owned
output directory cleanup. Further exact reruns confirmed the ledger bytes and the
final verification assertions.
| order | exact command | exit code | result |
| ---: | --- | ---: | --- |
| 1 | `cmake --build .harness/build --config Debug --target fesa_reference_tests` | `0` | Reference test executable built; duration `1.830 s`. |
| 2 | `ctest --test-dir .harness/build -C Debug -R '^Mitc4S4Reference\.' --output-on-failure` | `0` | Fresh S4 E2E tests `2/2` passed; duration `0.760 s`. |
| 3 | PowerShell CSV/JSON identity and metric audit | `0` | 294 exact keys; missing/extra/duplicate/nonfinite/nonfixed-tolerance counts all zero. |
| 4 | `ctest --test-dir .harness/build -C Debug -R '^Mitc4S4Reference\.' --output-on-failure` | `0` | Repeat S4 E2E tests `2/2` passed; duration `0.911 s`; JSON hash unchanged. |
| 5 | `h5dump.exe -A -g '/metadata' <results.h5>` with HDF5 and Intel oneAPI 2026.1 runtime directories prepended to `PATH` | `0` | Required metadata values inspected read-only. |
| 6 | `h5dump.exe -H -d '/model/nodes' <results.h5>` | `0` | Compound schema and shape `[49]` inspected. |
| 7 | `h5dump.exe -H -d '/model/elements' <results.h5>` | `0` | Compound schema and shape `[36]` inspected. |
| 8 | `h5dump.exe -H -d '/steps/Step-1/frames/0/nodal/displacement' <results.h5>` | `0` | Float64 displacement schema and shape `[49,6]` inspected. |
| 9 | Final `ctest --test-dir .harness/build -C Debug -R '^Mitc4S4Reference\.' --output-on-failure` plus report/metric assertion script | `0` | S4 E2E tests `2/2`; `verification=PASS`; final generated artifacts retained. |
| 10 | `git diff --check` | `0` | Report patch has no whitespace errors. |
| 11 | target-only Git scope and reference no-change audit | `0` | Only this owned report and the pre-existing untracked build/test report are visible; reference scope remains clean. |
An initial optional `h5dump` probe without the Intel runtime directory exited
`-1073741515` because `libmmd.dll` was not on that process's `PATH`. The same
read-only inspection passed after adding the installed oneAPI runtime path. This
was an inspection-environment incident, not a solver, schema, comparison, or
reference-artifact failure.
The repeated JSON ledger was byte-identical:
- size: `94,349` bytes
- SHA-256 before and after repeat: `8E8DEA51B6F7C663BACC41FDA6103A4596DB26E02F1EAD6069D458F51E0102E6`
- row decisions: `294`
- component metrics: `6`
- node vector metrics: `49`
- warnings: `0`
- verdict: `passed=true`
## Quantity Results
`max_rel` is calculated only for nonzero Abaqus values and is diagnostic. Tiny
reference residues make it ill-conditioned; the acceptance decision uses only
the fixed absolute tolerance and its fixed-tolerance-normalized error.
| quantity | components | behavior | compared | missing | extra | duplicate | nonfinite | max abs | max rel | max normalized | RMS | L2 norm | worst ID/component by abs error | result |
| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- | --- |
| displacement | `U1/U2/U3` | blocking | 147 | 0 | 0 | 0 | 0 | `1.90378534915144e-7` | `1.0` | `0.0190378534915144` | `2.45308118840709e-8` | `2.97420287738877e-7` | `Part-1-1`, node 2, `U3` | pass |
| rotation | `UR1/UR2/UR3` | warning-only | 147 | 0 | 0 | 0 | 0 | `6.88285496274043e-8` | `35.7165926082675` | `0.00688285496274043` | `2.26478498250615e-8` | `2.74590586054375e-7` | `Part-1-1`, node 44, `UR1` | pass, no warning |
The translational maximum relative error `1.0` occurs on near-zero reference
residue, including node 1 `U3=-1.17769804e-32`. The rotational maximum relative
error `35.7165926082675` occurs at node 2 `UR2`, where the reference is
`1.3860685e-22` and the absolute error is only `4.95056439416524e-21`.
Neither value was clamped or omitted, and neither relative diagnostic controls
the verdict.
### Component metrics
Each component contains 49 matched rows. `reference_scale` is retained only as
diagnostic information. `L2 norm` is the comparator's component
`vector_norm_error`, and `worst_row` is the zero-based index in the JSON ledger.
| component | behavior | reference scale | tolerance | max abs | max rel | max normalized | RMS | L2 norm | worst row | worst identity | result |
| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- | --- |
| `U1` | blocking | `3.11730945e-23` | `1.0e-5` | `3.11730945e-23` | `1.0` | `3.11730945e-18` | `1.13587076092006e-23` | `7.95109532644045e-23` | 66 | node 12 / `U1` | pass |
| `U2` | blocking | `3.11730945e-23` | `1.0e-5` | `3.11730945e-23` | `1.0` | `3.11730945e-18` | `1.13587076092006e-23` | `7.95109532644045e-23` | 61 | node 11 / `U2` | pass |
| `U3` | blocking | `2.37408203e-5` | `1.0e-5` | `1.90378534915144e-7` | `1.0` | `0.0190378534915144` | `4.24886125341252e-8` | `2.97420287738877e-7` | 8 | node 2 / `U3` | pass |
| `UR1` | warning-only | `7.60725743e-6` | `1.0e-5` | `6.88285496274043e-8` | `11.9344619221920` | `0.00688285496274043` | `2.77378379212910e-8` | `1.94164865449037e-7` | 261 | node 44 / `UR1` | pass, no warning |
| `UR2` | warning-only | `7.60725743e-6` | `1.0e-5` | `6.88285496273990e-8` | `35.7165926082675` | `0.00688285496273990` | `2.77378379212909e-8` | `1.94164865449036e-7` | 202 | node 34 / `UR2` | pass, no warning |
| `UR3` | warning-only | `5.27113701e-25` | `1.0e-5` | `5.27113701e-25` | `1.0` | `5.27113701e-20` | `2.12986098533393e-25` | `1.49090268973375e-24` | 203 | node 34 / `UR3` | pass, no warning |
### Worst rows and node-vector metrics
- global worst and worst blocking row: `shell-s4`, `Part-1-1`, node 2,
`U3`; FESA `-2.35504417650849e-5`, Abaqus `-2.37408203e-5`, absolute
error `1.90378534915144e-7`, tolerance `1.0e-5`, normalized error
`0.0190378534915144`, within tolerance;
- worst warning-only row: `shell-s4`, `Part-1-1`, node 44, `UR1`; FESA
`1.39850632037260e-6`, Abaqus `1.46733487e-6`, absolute error
`6.88285496274043e-8`, normalized error `0.00688285496274043`, within
tolerance;
- maximum per-node displacement-vector error: `1.90378534915144e-7` at
`Part-1-1`, node 2;
- maximum per-node rotation-vector error: `7.21144690026432e-8` at
`Part-1-1`, node 39.
## Failure Classification
- classification: `N/A`
- primary_failure: `N/A`
- evidence: declared artifacts exist; the authoritative HDF5 projection passed
schema and identity checks; 294/294 exact row keys are unique and finite;
147/147 blocking rows pass; zero rotational exceedances or warnings occurred
- correction_handoff: `N/A`
The optional first `h5dump` runtime-path incident is classified as a resolved
inspection-environment incident and does not affect this gate.
## Handoff Recommendation
| target_agent | reason | required input |
| --- | --- | --- |
| Physics Evaluation Agent | All declared blocking reference rows passed the exact approved tolerance, and the warning-only inventory has no exceedance. | This report, `.harness/build/reference/mitc4-shell-s4-comparison/results.h5`, and its deterministic `comparison.json`. |
The handoff status is `pass-for-physics-evaluation` only. Physics Evaluation
remains responsible for equilibrium, reaction sign, displacement direction,
symmetry, physical energy, result signs, and model-coverage adequacy.
## No-Change Assertion
- source_files_modified: `false`
- test_files_modified: `false`
- cmake_files_modified: `false`
- requirements_modified: `false`
- formulation_modified: `false`
- numerical_review_modified: `false`
- io_contract_modified: `false`
- reference_model_contract_modified: `false`
- phase_files_modified: `false`
- tolerance_policies_modified: `false`
- reference_artifacts_modified: `false`
- Abaqus_or_other_reference_solver_executed: `false`
- owned_report_created: `true`
- generated_build_local_evidence: `true`, ignored under `.harness/build/`
- pre_existing_untracked_build_test_report_preserved: `true`
## Open Issues
- None blocking Physics Evaluation.
- Nonblocking audit note: raw HDF5 container hashes differed across fresh
regenerations, while the authoritative projected rows and serialized comparison
ledger were stable and the JSON was byte-identical. No HDF5 byte-determinism
claim is made by this report.
docs/linear-static-mitc4-shell/reference-model.md
+122
View File
@@ -0,0 +1,122 @@
# Linear Static MITC4 Shell Reference Cases
## Metadata
- feature_id: `linear-static-mitc4-shell`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- source_io_definition: `docs/io-definitions/linear-static-mitc4-shell-io.md`
- status: `approved-for-implementation-planning`
- owner_agent: `reference-model-agent`
- date: `2026-08-13`
- artifact_policy: `read-only-existing-files`
- authoritative_fesa_output: `results.h5`
## 1. Purpose and boundary
This document is the lightweight inventory and comparison contract for the sole
approved full-integration S4 reference case. Abaqus supplies an external displacement reference;
it does not define FESA element equations, integration, stabilization, recovery, or
implementation structure. FESA and Abaqus are not required to operate identically.
Reference readiness requires only:
- the declared Abaqus `.inp` file and displacement CSV for each case;
- the FESA `results.h5` generated from that case's `.inp`;
- deterministic source-instance/node/component matching;
- the approved tolerance and decision rule in Section 5.
README, `metadata.json`, canonical naming, legacy-alias approval, Abaqus version or
generation provenance, duplicated unit/coordinate/model/step/frame/material/section
descriptions, and a CSV schema-version record are not required. If `metadata.json`
later exists, it is optional read-only context and does not override the declared
input, CSV, row mapping, or tolerance.
## 2. Read-only case inventory
| case_id | source label | role | exact path | SHA-256 | observed content |
| --- | --- | --- | --- | --- | --- |
| `shell-s4` | `S4` | input | `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` | `TYPE=S4`; one linear-static case |
| `shell-s4` | `S4` | required reference | `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` | 49 data rows; U and UR components |
The existing reaction and stress CSVs in `reference/shell/` are optional inspection
evidence only. Existing files under `reference/shellR/` are also optional inspection
evidence and are not consumed by acceptance comparison. They are not pass/fail inputs.
No agent may rename, rewrite, normalize, repair, regenerate, or restore any reference
artifact unless a later phase explicitly authorizes that operation.
## 3. Required CSV mapping
Trim surrounding whitespace from header names, then apply this exact projection:
| Abaqus CSV column | normalized identity/value | FESA HDF5 source |
| --- | --- | --- |
| `Part Instance Name` | `instance_name` | `/model/nodes.instance_name` |
| `Node Label` | `source_node_label` | `/model/nodes.source_label` |
| `U-U1` | `U1` | `/steps/Step-1/frames/0/nodal/displacement[:,0]` (`UX`) |
| `U-U2` | `U2` | `/steps/Step-1/frames/0/nodal/displacement[:,1]` (`UY`) |
| `U-U3` | `U3` | `/steps/Step-1/frames/0/nodal/displacement[:,2]` (`UZ`) |
| `UR-UR1` | `UR1` | `/steps/Step-1/frames/0/nodal/displacement[:,3]` (`URX`) |
| `UR-UR2` | `UR2` | `/steps/Step-1/frames/0/nodal/displacement[:,4]` (`URY`) |
| `UR-UR3` | `UR3` | `/steps/Step-1/frames/0/nodal/displacement[:,5]` (`URZ`) |
The normalized row key is
`(case_id,instance_name,source_node_label,component)`. Stable comparison order is
case `shell-s4`; then FESA instance declaration order; stable source-node order; and
component order `[U1,U2,U3,UR1,UR2,UR3]`.
## 4. Precheck
Before numerical comparison, each case shall satisfy all of the following:
1. The declared input, displacement CSV, and FESA `results.h5` exist.
2. The six required displacement headers map exactly as Section 3 specifies.
3. Each required CSV and HDF5 value is finite.
4. Each normalized row key is unique.
5. CSV and HDF5 normalized row-key sets are exactly equal.
Missing, extra, duplicate, nonfinite, header-mismatched, or source-identity-mismatched
required rows fail reference verification before tolerance evaluation. Values are not
zero-clamped and mismatched rows are not omitted, averaged, or synthesized.
## 5. Tolerance and decision rule
For every matched row:
```text
tolerance = 1.0e-5
absolute_error_i = abs(fesa_value_i - abaqus_value_i)
```
The fixed `1.0e-5` value is expressed in the model's user-consistent length unit for
`U1/U2/U3` and is dimensionless for `UR1/UR2/UR3`. Neither a component reference scale
nor a row-specific denominator changes the value. Reference scale may be reported as
non-decision diagnostic information. The separate B33 mixed tolerance is unchanged.
- Every matched `U1/U2/U3` row must satisfy `absolute_error_i <= tolerance`.
Any U exceedance fails that case and the feature reference comparison.
- `UR1/UR2/UR3` uses the same fixed value. Every exceedance produces a deterministic
warning containing the case, source row, component, error, and tolerance, but does
not change pass/fail.
The comparison report records every U/UR row decision, maximum absolute error,
fixed-tolerance-normalized error, RMS error, vector-norm error, worst source
row/component, and every UR warning.
## 6. Coverage and handoff
The S4 case is the complete required reference inventory for this feature:
- `shell-s4` checks the approved full-integration `S4 -> FESA-MITC4` input path against Abaqus U.
- `S4R -> FESA-MITC4` support is verified by parser, common-kernel,
deterministic-assembly and HDF5 source-metadata tests without consuming an Abaqus
S4R reference artifact.
They do not prove Abaqus formulation equivalence or general MITC4 accuracy outside
the modeled cases. Additional flat/thin/thick/distorted/curved models, mesh studies,
drilling sweeps, drilling-energy criteria, `NR-O03`, and `NR-O04` are not required
before Implementation Planning or feature completion.
Numerical Review may use this inventory as downstream comparison input, but missing
bundle-administration data shall not change a mathematically consistent formulation
verdict. The revised Numerical Review passes the formulation and authorizes
Implementation Planning; this does not authorize implementation or Harness execution.
docs/linear-static-mitc4-shell/release.md
+294
View File
@@ -0,0 +1,294 @@
# Linear Static MITC4 Shell Release Report
## Metadata
- feature_id: `linear-static-mitc4-shell`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- source_research: `docs/research/linear-static-mitc4-shell-research.md`
- source_formulation: `docs/formulations/mitc4-shell-formulation.md`
- source_numerical_review: `docs/numerical-reviews/linear-static-mitc4-shell-review.md`
- source_io_definition: `docs/io-definitions/linear-static-mitc4-shell-io.md`
- source_reference_model: `docs/reference-models/linear-static-mitc4-shell-reference-models.md`
- source_implementation_plan: `docs/implementation-plans/linear-static-mitc4-shell-implementation-plan.md`
- source_implementation_evidence: `phases/linear-static-mitc4-shell/index.json`
- source_implementation_report: `N/A`; the project Harness phase index is the implementation completion ledger for this execution
- source_correction_report: `N/A`; no final Build/Test, Reference Verification, or Physics Evaluation failure was handed to Correction Agent
- source_build_test_report: `docs/build-test-reports/linear-static-mitc4-shell-build-test.md`
- source_reference_verification_report: `docs/reference-verifications/linear-static-mitc4-shell-reference-verification.md`
- source_physics_evaluation_report: `docs/physics-evaluations/linear-static-mitc4-shell-physics-evaluation.md`
- audited_source_head: `820ba30c717b3d0e113775608e20dfd5fbc05d53`
- audited_branch: `feat-linear-static-mitc4-shell`
- status: `ready-for-release`
- owner_agent: `release-agent`
- date: `2026-08-13`
- release_boundary: internal FESA feature release readiness only; no publish, deploy, package, tag, commit, or external release was performed
## Release Scope
| item | included | excluded | notes |
| --- | --- | --- | --- |
| analysis type | One small-displacement, small-rotation `*STEP, *STATIC` | Multiple steps, geometric/material nonlinearity, buckling, modal, dynamic, contact, thermal | Existing factorize-before-load linear-static lifecycle is retained. |
| element type | Four-node source `S4` and `S4R` mapped to one full-integration `FESA-MITC4` path | `S3`, `S8`, `S8R`, continuum/solid/axisymmetric shells, MITC4+, MITC4/D, reduced integration/hourglass behavior | Source type is preserved as metadata; no Abaqus formulation-equivalence claim is made. |
| nodal degrees of freedom | Global `[UX,UY,UZ,URX,URY,URZ]`; 20 physical element coordinates plus four numerical drilling coordinates | Physical drilling strain/load/result channel | Director-parallel nodal moment is rejected. |
| material and section | Centered, single-layer, homogeneous isotropic linear elasticity with finite valid `E`, `nu`, and constant positive thickness | Composite/laminated or orthotropic sections, offsets, variable/nodal thickness, user orientation | Multiple valid materials/sections/element sets are allowed with exactly one assignment per element. |
| geometry | Valid four-node quadrilaterals and smooth shell patches with deterministic geometry-derived directors | Explicit normals/directors, shared-node sharp folds, hinges, shell-beam joints, calibrated distortion/warp thresholds | A physical fold requires duplicated source nodes. |
| loads and constraints | Nodal `*BOUNDARY` and global nodal `*CLOAD` on DOFs 1-6, subject to the drilling-moment projection rule | `*DLOAD`, pressure, gravity, body/edge/follower load | Output-request keywords in the allowlist remain warning no-ops. |
| authoritative output | HDF5 `results.h5`: nodal displacement/full residual, shell frames, generalized strain/resultant, bottom/middle/top in-plane stress, physical energy, equilibrium, verification metrics, diagnostics | Official CSV solver output, drilling output/energy, `S33`, pointwise `S13/S23`, nodal shell-stress averaging | HDF5 schema version remains `0` and is extended additively. |
| external acceptance | Read-only `reference/shell/shell.inp` and `reference/shell/shell displacements.csv`; `U1/U2/U3` blocking at fixed absolute `1.0e-5`; `UR1/UR2/UR3` warning-only at the same value | S4R artifact consumption; Abaqus reaction/stress/strain/resultant equality | Direct HDF5-to-CSV source identity mapping is authoritative. |
## Gate Evidence Inventory
| gate | source | expected status/evidence | observed status/evidence | verdict |
| --- | --- | --- | --- | --- |
| requirements | `docs/requirements/linear-static-mitc4-shell.md` | approved scope, acceptance criteria, tolerance and reference boundary | `approved`; requirements `001-072` are all `must` and covered without gaps | pass |
| research | `docs/research/linear-static-mitc4-shell-research.md` | approved evidence with applicability limits | `approved`; no research-owned blocking decision remains | pass |
| formulation | `docs/formulations/mitc4-shell-formulation.md` | implementation-ready current linear formulation | `approved-for-implementation-planning`; future nonlinear Section 15 remains explicitly non-executable | pass |
| numerical review | `docs/numerical-reviews/linear-static-mitc4-shell-review.md` | `pass-for-implementation-planning` | `pass-for-implementation-planning`; no current-scope blocker | pass |
| I/O definition | `docs/io-definitions/linear-static-mitc4-shell-io.md` | approved input/HDF5/comparison contract | `approved-for-implementation-planning`; exact S4-only acceptance boundary and fixed tolerance are present | pass |
| reference model | `docs/reference-models/linear-static-mitc4-shell-reference-models.md` | approved exact artifact inventory and row mapping | `approved-for-implementation-planning`; both declared files exist and match hashes | pass |
| implementation plan | `docs/implementation-plans/linear-static-mitc4-shell-implementation-plan.md` | approved TDD plan tracing every `must` requirement | `ready-for-implementation`; ranges cover `001-072` exactly once | pass |
| implementation | `phases/linear-static-mitc4-shell/index.json` at source HEAD | completed RED/GREEN/VERIFY execution | Steps `0-13` are `completed`; all 14 `stepN-output.json` records have `exitCode=0`; top-level phase is `completed` | pass |
| correction | final downstream reports and commit/Harness history | no unresolved implementation-owned failure | `N/A`; final Build/Test and Reference Verification classify correction handoff as `N/A`; historical pre-gate Step 13 retries are closed | pass |
| build/test | `docs/build-test-reports/linear-static-mitc4-shell-build-test.md` | `pass-for-reference-verification` | `pass-for-reference-verification`; clean MSVC x64 Debug build, focused `87/87`, `10/10`, `8/8`, full `144/144`, Harness Python `7/7`, zero warnings | pass |
| reference verification | `docs/reference-verifications/linear-static-mitc4-shell-reference-verification.md` | `pass-for-physics-evaluation` | `pass-for-physics-evaluation`; exact `294/294` row identity, blocking U `147/147`, UR warnings `0`, invalid rows `0` | pass |
| physics evaluation | `docs/physics-evaluations/linear-static-mitc4-shell-physics-evaluation.md` | `pass-for-release-agent` | `pass-for-release-agent`; equilibrium, reaction, direction, symmetry, recovery, stress signs, residual and physical energy pass | pass |
### Gate Consistency and Staleness Audit
- Every gate uses `feature_id=linear-static-mitc4-shell`. Build/Test, Reference Verification, and Physics Evaluation all identify source HEAD `820ba30c717b3d0e113775608e20dfd5fbc05d53`, which is the audited current HEAD.
- The requirements metadata value `current_product_state=requirements-approved-not-implemented` records the product state when the requirements gate was authored. It is not the requirements gate status and does not alter the later implementation evidence.
- Numerical Review values `implementation_complete=false`, `build_test_complete=false`, `reference_comparison_complete=false`, `physics_evaluation_complete=false`, and `release_ready=false` are explicit pre-implementation review boundaries. Later same-feature reports at the audited HEAD supply those downstream decisions. They are phase-time markers, not contradictory live statuses.
- No contract meaning, reference inventory, tolerance, or source identity in those earlier documents conflicts with the final reports. The phase-time markers are therefore nonblocking and are not silently treated as current completion claims.
- A separate implementation report is nonblocking under the current workflow because the Build/Test report explicitly declares `source_implementation_report=N/A` and points to the Harness index. The index records each RED failure, GREEN behavior, focused/full verification summary and completion timestamp, while all 14 generated step-output records have `exitCode=0`.
- A correction report is nonblocking `N/A`: Correction Agent reporting is required after a formal downstream failure handoff. The final formal Build/Test, Reference Verification, and Physics Evaluation gates report no such failure or unresolved defect. Historical implementation-phase retries and correction commits precede the clean independent gates and are closed by the final phase ledger and source HEAD.
- The Numerical Review metadata contains two historical commit references (`reviewed_head=cf769aa` and a downstream note naming `a058ef7`). This is a document-history inconsistency, but its mathematical verdict was re-audited against the current tracked requirements/formulation/I/O/reference contracts and independently exercised at `820ba30...`; it does not create a scope, tolerance, or acceptance contradiction.
## Evidence Hash Inventory
SHA-256 values are lowercase. The build-local HDF5 container is intentionally not a decision identity because valid regenerations can change raw container bytes; the deterministic projected ledger is the stable comparison evidence.
| evidence | bytes | SHA-256 | audit role |
| --- | ---: | --- | --- |
| requirements | 35,124 | `c8966f667ee42c3d35d0bf2f1bc1662a93784a2037d5b191b59793fb5ad66c64` | approved must-requirement baseline |
| research | 37,197 | `45f02291c8b2fdc7066cdb938cf6662a97dd3dceb9023fa743fe1c356a7970b4` | theory/benchmark/applicability evidence |
| formulation | 57,593 | `117932a112b2ad7f1cb6a8084304733fcd529a675a93cca6364c2f6a16c57cd0` | mathematical implementation contract |
| numerical review | 24,406 | `c82bd7b4f14f7664fb082d9a860dc443bf76571affa24caa8a7a9acfba04af1e` | independent formulation gate |
| I/O definition | 41,327 | `6f362b16625e61c85949648e6bc1f215c92ff31e99654f6efd9787b428dd54c4` | input/HDF5/comparison contract |
| reference model | 6,112 | `978e18485a627b6abf83373f74929cfe564952d29f68574e0cab75ef5e689c44` | exact S4 inventory and row mapping |
| implementation plan | 56,316 | `8d269455d0d5fe9bb9dc32f140d1ea6f105bab60ebfe73d368ad8c5225af6482` | TDD task/test traceability |
| Harness implementation index | 7,392 | `8c0a7369bc81fc7a12f9f3a49158a9534d4727b9a924c95b1ece7e915d16880d` | 14-step completion ledger |
| Build/Test report | 11,970 | `d261e13eb1c6dc20cf24f85ee97a3fcb6b667420486ad12725030e3eebf8dcd1` | independent MSVC/CMake/CTest evidence |
| Reference Verification report | 14,362 | `2c69814eeb265bd47672c46e17e2c63d55a0f8d834325c2b0d78e0500a83bade` | fixed-tolerance comparison evidence |
| Physics Evaluation report | 19,596 | `d753521c73ac8509fe2d3e2896e2f6dd23a362c0f17f153fadbeb6227b8ed4c6` | physical plausibility evidence |
| declared S4 input | 4,770 | `4005851e1ab22fd3a16ac17a8d5da3e051233f69f37419079f3553ad134ecfcf` | immutable reference input |
| declared S4 displacement CSV | 5,592 | `c81d94e0b4a849f87aa0f79c83a79b94d5661ac79e44ed826919ab432c87746b` | immutable required reference quantity |
| deterministic comparison ledger | 94,349 | `8e8dea51b6f7c663bacc41fda6103a4596db26e02f1ead6069d458f51e0102e6` | `294` row decisions, `passed=true`, zero warnings |
## Acceptance Traceability
Evidence abbreviations: `PH` = Harness phase index; `BT` = Build/Test report; `RV` = Reference Verification report; `PE` = Physics Evaluation report. `shell-s4` means the sole declared read-only S4 comparison model. Every row below has priority `must` in the approved requirements baseline.
| requirement_id | acceptance criterion | test/phase evidence | reference/physics evidence | release disposition |
| --- | --- | --- | --- | --- |
| `001` | Exactly one supported static step; unsupported procedure or second step fails deterministically. | `InpDomainMapping.*Procedure*`; `Mitc4ShellCli.*`; PH Steps 1/12; BT | N/A | released |
| `002` | S4 and S4R map to one FESA MITC4 path without equivalence claim. | `InpDomainMapping.MapsS4AndS4rThroughOneMitc4Identity`; PH Steps 0/1/7; BT | S4R is intentionally non-reference | released |
| `003` | Source element type and internal formulation remain separate metadata. | `DomainModel.Mitc4ShellRecordsPreserveSourceAndInternalIdentity`; `Hdf5ResultsWriter.WritesExactShellMetadataAndModelIdentity`; BT | RV HDF5 projection audit | released |
| `004` | Four distinct ordered nodes and stable source element identity are enforced. | `InpDomainMapping.RejectsInvalidShellConnectivityOptionsAndMixedModels`; Domain/HDF5 tests; BT | RV observed 36 uniquely identified S4 elements | released |
| `005` | Six global DOFs use the exact order and equation ownership remains in DofManager. | `DofManager.BuildsShellScatterInSourceNodeAndComponentOrder`; HDF5 schema tests; PH Steps 0/6/11; BT | RV `[UX,UY,UZ,URX,URY,URZ]` projection | released |
| `006` | Valid homogeneous isotropic `E,nu` is accepted and invalid/unsupported material data fails. | `InpDomainMapping.RejectsInvalidShellAssignmentsAndProperties`; `Mitc4ShellConstitutive.*`; BT | PE material audit | released |
| `007` | One finite positive constant thickness is accepted for a centered single-layer shell section. | Domain/model/mapping tests; `Mitc4ShellConstitutive.*`; BT | PE thickness/model audit | released |
| `008` | Each element resolves to exactly one section and material; missing/conflicting/duplicate assignments fail. | `DomainModel.ShellOwnershipPreservesResolvedAssignmentsAndOptionalFrames`; `InpDomainMapping.RejectsInvalidShellAssignmentsAndProperties`; BT | N/A | released |
| `009` | Multiple valid sets/sections/materials are allowed while each element remains homogeneous and single-layer. | Domain/model/mapping suites; PH Steps 0/1; BT | N/A | released |
| `010` | Composite, offset, variable thickness, explicit normal and orientation meanings fail closed. | `InpDomainMapping.RejectsInvalidShellConnectivityOptionsAndMixedModels`; BT | N/A | released |
| `011` | Nodal director is a unit vector separate from scalar thickness. | `Mitc4Geometry.BuildsDeterministicFramesForPlanarRotatedAndWarpedElements`; HDF5 director tests; BT | PE finite/model audit | released |
| `012` | Element normal candidate follows deterministic source order and tangent cross product. | `Mitc4Geometry.*`; PH Step 2; BT | N/A | released |
| `013` | Smooth shared-node directors use deterministic area-weighted averaging. | `Mitc4Geometry.AreaWeightsSharedDirectorsInStableSourceIdentityOrder`; BT | N/A | released |
| `014` | Nonfinite/zero/opposed normals fail without an invented smooth-angle threshold. | `Mitc4Geometry.RejectsInvalidSurfaceJacobianAndIncidentOrientationCases`; BT | N/A | released |
| `015` | Discontinuous shared-node director fields are not silently averaged; folds require duplicate nodes. | Geometry negative tests and mapper unsupported-scope tests; BT | Documented limitation | released |
| `016` | Duplicate, bow-tie, nonfinite, zero-area and nonpositive-J geometry fails at every required point. | `Mitc4Geometry.RejectsInvalidSurfaceJacobianAndIncidentOrientationCases`; `.ExposesTheCompleteRequiredValidationPointInventory`; BT | PE finite-result audit | released |
| `017` | Nodal label/set boundary targets support global DOFs 1-6 and zero/nonzero prescribed values. | `EssentialConstraints.PreservesShellSizedNoMixedAndAllConstraintRoundTrips`; `Mitc4ShellCli.AppliesKfcForNonzeroPrescribedDisplacement`; BT | PE constraint-mask audit | released |
| `018` | Global nodal force/moment CLOAD components aggregate deterministically. | `LoadAssembly.AggregatesAllSixGlobalShellLoadComponentsInSourceOrder`; BT | PE load/reaction audit | released |
| `019` | Aggregate director-parallel moment fails as `unsupported-drilling-load`. | `LoadAssembly.AcceptsExactlyZeroAggregateShellMoment`; `.EnforcesAggregateShellMomentDirectorProjectionThreshold`; PH Step 8; BT | N/A | released |
| `020` | Distributed/follower/body/edge load inputs remain unsupported. | `InpDomainMapping.PreservesProcedureLoadAndOutputRequestBoundariesForShells`; BT | Documented limitation | released |
| `021` | Only the approved identity-preserving keyword subset plus S4/S4R and shell section is accepted. | `InpDomainMapping.*`; full CTest regression; BT | `shell-s4` parsed end-to-end | released |
| `022` | Identity wrappers/multiple instances preserve source identity; transforms/nesting remain unsupported. | `InpDomainMapping.*`; Domain identity tests; BT | RV exact instance/node identity | released |
| `023` | Allowlisted output requests do not affect mandatory results; other model-affecting meanings fail. | `InpDomainMapping.PreservesProcedureLoadAndOutputRequestBoundariesForShells`; `Hdf5ResultsWriter.WritesShellInventoryDespiteRequestsAndOmitsForbiddenPaths`; BT | PE observed warning-only diagnostics | released |
| `024` | Domain owns shell semantics and AnalysisModel remains a non-owning active view. | `DomainModel.*`; PH Step 0 and full lifecycle Step 12; BT | N/A | released |
| `025` | DofManager solely owns six-DOF numbering, maps, scatter and sparse pattern. | `DofManager.*`; `EssentialConstraints.*`; PH Step 6; BT | N/A | released |
| `026` | AnalysisState owns only required linear-static shell solution/recovery/evidence rows. | `AnalysisState.OwnsExactShellRowsInStableElementAndLocationOrder`; `.CommitsFiniteShellGlobalEvidence`; BT | PE required-result audit | released |
| `027` | Element buffers and stable COO/fixed reduction are deterministic across thread paths. | `SparseAssembly.ShellSerialTbbReverseAndRepeatedRunsAreByteIdentical`; PH Step 7; BT | N/A | released |
| `028` | Stiffness/partition/factorization precedes load/effective RHS/substitution/recovery/commit. | `Mitc4ShellCli.UsesExistingLifecycleAndExactlyOneFactorization`; `.AppliesKfcForNonzeroPrescribedDisplacement`; `.DoesNotWriteAnInvalidRecoveryCandidate`; BT | PE final-state evidence | released |
| `029` | Reaction/free equilibrium derives from full residual `K*d-F`. | `ResultRecovery.KeepsFullResidualAndComputesGlobalShellEquilibrium`; BT | PE reaction and equilibrium reconstruction | released |
| `030` | S4/S4R use the same numerical path and may differ only in source metadata. | Mapper identity test; `SparseAssembly.S4AndS4rSemanticFixturesAssembleIdenticalStiffness`; HDF5 metadata tests; BT | S4R reference intentionally N/A | released |
| `031` | Physical kernel uses three translations plus two tangent rotations; drilling is not physical strain. | `Mitc4ShellKinematics.BuildsRightHandedFramesAndSeparatePhysicalDrillingMaps`; drill/recovery tests; BT | PE no drilling leakage | released |
| `032` | Deterministic right-handed frames transform global rotations to tangent/drilling coordinates. | `Mitc4ShellKinematics.BuildsRightHandedFramesAndSeparatePhysicalDrillingMaps`; `Mitc4Geometry.*`; BT | PE symmetry/direction evidence | released |
| `033` | Drilling is a symmetric positive numerical stabilization only. | `Mitc4ShellDrilling.*`; `Mitc4ShellKernel.*`; BT | PE physical-energy audit | released |
| `034` | `R+`, `k_ref`, `k_d=1e-3*k_ref`, and `I4` use only eight positive physical rotational diagonals. | `Mitc4ShellDrilling.UsesOnlyEightPositivePhysicalRotationDiagonalsAndFixedFactor`; BT | N/A | released |
| `035` | Drilling contributes to no physical generalized strain/resultant/stress/output. | `Mitc4ShellDrilling.ExcludesPureDrillFromPhysicalRecoveryAndEnergy`; HDF5 forbidden-path test; BT | PE physical-only recovery/energy | released |
| `036` | Empty/nonfinite valid `R+` fails; no coefficient/energy calibration gate or output exists. | `Mitc4ShellDrilling.FailsNonfiniteReferenceAndStabilizesEachPureDrillCoordinate`; BT | Documented limitation/boundary | released |
| `037` | S4 and S4R share the approved full `2x2x2` rule; no reduced integration/hourglass selection. | `Mitc4ShellKinematics.UsesOneFixedTwoByTwoByTwoQuadratureOrder`; S4/S4R assembly parity; BT | RV S4-only boundary | released |
| `038` | Stabilized element keeps six physical rigid modes, symmetry, energy invariance and positive non-rigid modes. | `Mitc4ShellKernel.*`; `Mitc4ShellPatch.*`; BT | PE rigid/rank/energy evidence | released |
| `039` | HDF5 is authoritative and invalid candidates cannot replace a valid final result. | `Hdf5ResultsWriter.InvalidShellInventoryPreservesExistingFinal`; CLI invalid-candidate test; BT | RV/PE read authoritative HDF5 | released |
| `040` | Required metadata/model identities, frames, directors, section/material and source/internal types are written. | `Hdf5ResultsWriter.WritesExactShellMetadataAndModelIdentity`; BT | RV HDF5 schema audit | released |
| `041` | Every node has global six-component displacement and full-residual reaction rows in stable order. | HDF5 mandatory inventory; `ResultRecovery.*`; BT | RV 49x6 displacement; PE reaction audit | released |
| `042` | Four shell locations contain ordered eight-component generalized strain with correct dimensions. | `Mitc4ShellPhysicalRecovery.*`; `ResultRecovery.RecoversShellRowsInStableElementAndGpOrder`; HDF5 tests; BT | PE 144-GP reconstruction | released |
| `043` | The same locations contain ordered `N/M/Q` section resultants with correct dimensions. | Physical recovery/result recovery/HDF5 suites; BT | PE 1,152-component resultant reconstruction | released |
| `044` | Bottom/middle/top local `[S11,S22,S12]` is emitted; S33/S13/S23 is not. | `ResultRecovery.RecoversDirectBottomMiddleTopShellStress`; HDF5 inventory/forbidden paths; BT | PE stress/location/sign reconstruction | released |
| `045` | Rows preserve source element, exact natural/section location, frame and component order without averaging. | AnalysisState, ResultRecovery stable-order and HDF5 schema tests; BT | PE location-specific audit | released |
| `046` | Free residual, force/moment balance and deterministic physical shell energy are output without drilling datasets. | `ResultRecovery.*ShellEquilibrium`; `.SumsOnlyPhysicalShellEnergyInSourceOrder`; HDF5 global rows; BT | PE equilibrium and energy checks | released |
| `047` | Abaqus output requests neither suppress nor expand mandatory HDF5; CSV remains auxiliary. | Mapper output-request test; `Hdf5ResultsWriter.WritesShellInventoryDespiteRequestsAndOmitsForbiddenPaths`; BT | RV compared HDF5 directly; no FESA CSV | released |
| `048` | Nonfinite/incomplete recovery or HDF5 inventory fails without partial success. | `AnalysisState.InvalidShellCandidatesLeavePriorStateUnchanged`; `ResultRecovery.InvalidLaterShellLeavesEntirePriorStateUnchanged`; HDF5 invalid-inventory test; BT | N/A | released |
| `049` | Each production behavior has RED/GREEN/VERIFY evidence, related C++ tests, clean MSVC Debug build and no new warning. | PH Steps 0-13 and outputs; BT clean build, zero warnings, `144/144` | N/A | released |
| `050` | Frames, Jacobians, symmetry, transform energy, six modes, positivity and repeatability are tested. | Geometry, Kinematics, Kernel, Patch and SparseAssembly suites; BT | PE rigid/rank summary | released |
| `051` | Approved normalized `1e-12` and `1e-10` algebraic/equilibrium criteria are applied. | Kernel/frame tests; `ResultRecovery.UsesScaleAwareShellMetricsAndRejectsExcess`; BT | PE verification metrics all below `1e-10` | released |
| `052` | Independent membrane, bending, shear and twist patch/sign/component checks pass. | `Mitc4ShellPatch.ReproducesIndependentMembraneBendingShearAndTwistFields`; PhysicalRecovery tests; BT | PE recovery sign checks | released |
| `053` | Formulation invariants/patches and declared S4 displacement reference case pass; expanded portfolio is not required. | Kernel/Patch/PhysicalRecovery suites; `Mitc4S4Reference.*`; BT | RV blocking U `147/147`; PE coverage audit | released |
| `054` | Exact geometry acceptance/rejection tests pass without NR-O03/NR-O04 calibration. | `Mitc4Geometry.*`; BT | N/A | released |
| `055` | Additional curved/locking/convergence benchmarks remain optional and nonblocking. | Implementation-plan scope audit; BT/PE coverage inventory | PE records limitation and approved coverage | released |
| `056` | Exact drilling formula, symmetry/positivity/rank/determinism and recovery exclusion are verified. | `Mitc4ShellDrilling.*`; Kernel/Sparse/Recovery suites; BT | PE drilling separation evidence | released |
| `057` | Physics verifies equilibrium, direction, symmetry, energy, signs and resultant consistency. | ResultRecovery/CLI suites; BT | PE all documented checks pass | released |
| `058` | Every matched U row uses fixed absolute `1.0e-5` and blocks on exceedance. | `Mitc4ReferenceComparison.AppliesFixedAbsoluteToleranceWithoutScaleClampOrRowDenominator`; `Mitc4S4Reference.*`; BT | RV U `147/147` pass | released |
| `059` | Reference scale, row denominator, component magnitude and zero clamp never alter MITC4 tolerance. | Fixed-tolerance comparator test; BT | RV all 294 tolerances exactly `1.0e-5` | released |
| `060` | U tolerance is in user-consistent length units and independent of B33 policy. | Comparator contract test and scope audit; BT | RV reports independent fixed policy | released |
| `061` | UR uses fixed absolute `1.0e-5`; exceedance warns deterministically and never blocks. | `Mitc4ReferenceComparison.RotationExceedanceWarnsWithoutBlockingTranslationVerdict`; BT | RV UR `147/147`, zero warnings | released |
| `062` | UR tolerance is dimensionless and no extra UR/drilling threshold is required. | Comparator/report tests; BT | RV fixed-tolerance metrics | released |
| `063` | Missing/extra/duplicate/nonfinite/schema/identity mismatch fails before tolerance. | `Mitc4ReferenceComparison.RejectsInvalidInventoryBeforeNumericComparison`; BT | RV all invalid counts zero | released |
| `064` | Report contains every U/UR decision, maximum, normalized, RMS, vector and worst-row evidence. | `Mitc4ReferenceComparison.ReportsMetricsVectorsWorstRowAndJsonDeterministically`; BT | RV complete quantity/component/worst-row tables | released |
| `065` | Exact S4 input and displacement CSV paths are used without mutation. | `Mitc4S4Reference.*`; comparator required-file test; BT hash audit | `shell-s4`; immutable hashes match | released |
| `066` | S4R artifacts are not required/consumed; parser/common-kernel/assembly/HDF5 tests cover S4R. | Mapper identity, S4/S4R assembly parity, HDF5 source-type tests; BT | RV confirms `reference/shellR/` not consumed | released |
| `067` | Only declared input/CSV, FESA HDF5, mapping and tolerance/precheck rules gate readiness. | `Mitc4ReferenceComparison.RequiresOnlyDeclaredInputCsvAndHdf5`; BT | RV no administrative artifact gate | released |
| `068` | Reference rows are unique, finite and deterministically source-mapped without internal-equivalence inference. | Comparator mapping and invalid-inventory tests; BT | RV exact `294/294` key set | released |
| `069` | Sole Abaqus case is full-integration S4; S4R coverage remains non-reference. | Common quadrature/S4R mapping tests and `Mitc4S4Reference.*`; BT | RV one declared case, S4R excluded | released |
| `070` | Authoritative FESA HDF5 rows are compared directly by model/step/frame/source/component. | Comparator mapping/E2E tests; BT | RV direct HDF5 projection, no FESA CSV | released |
| `071` | Reaction/stress/strain/resultants do not become undeclared equality gates. | Comparator only projects U/UR; BT | RV and PE keep optional CSVs out of pass/fail | released |
| `072` | No Abaqus/reference-solver execution or reference artifact mutation occurs. | PH/BT Git and hash audits | RV and PE no-change assertions; immutable hashes match | released |
No requirement is deferred or blocked. Out-of-scope behavior is documented as a limitation rather than silently accepted.
## Validation Evidence
| command or report | expected | observed | verdict |
| --- | --- | --- | --- |
| config-resolved VS18/MSVC x64 Debug fresh configure and clean build | exit `0`, no new warning | exit `0`; warning/error scan `0/0` | pass |
| focused model/kernel/assembly/recovery CTest | pass | `87/87` | pass |
| focused linear-static lifecycle CTest | pass | `10/10` | pass |
| focused MITC4 reference CTest | pass | `8/8` | pass |
| CTest discovery and full regression | nonzero inventory and all pass | `144` discovered; `144/144` pass; current read-only discovery includes 57 test names containing `Mitc4` or `Shell` | pass |
| Harness Python verification | pass because Harness runner changed on the feature branch | `7/7` pass | pass |
| final release-stage confirmation | current HEAD build, full CTest and Harness self-test pass | fresh `cmake --build` exit `0`; CTest `144/144`; Harness pytest `7/7` | pass |
| Harness implementation ledger | every Step completed successfully | Steps `0-13` completed; `14/14` output `exitCode=0` | pass |
| reference verification | `pass-for-physics-evaluation` | exact 294 rows; U `147/147`; invalid rows/warnings `0` | pass |
| physics evaluation | `pass-for-release-agent` | all equilibrium/direction/symmetry/recovery/energy checks pass | pass |
| immutable reference audit | exact expected hashes, no Git reference diff/status | both hashes match; zero changed reference paths | pass |
The Release Agent did not run Abaqus. It independently read the complete upstream evidence chain, enumerated current CTest discovery read-only, checked all Harness output exit codes, verified source HEAD/branch/status, and recomputed the declared artifact/report hashes. The primary audit then performed a fresh current-HEAD incremental full build, full CTest run and Harness self-test as the final completion check; all passed as recorded above.
## Release Checklist
- [x] One `feature_id` across all required gate documents.
- [x] Requirements, research, formulation, numerical review, I/O, reference-model and implementation-plan gates are approved/passing for their intended downstream phase.
- [x] Harness implementation is complete at the audited source HEAD with 14 successful Step outputs.
- [x] Independent Build/Test status is `pass-for-reference-verification`.
- [x] Reference Verification status is `pass-for-physics-evaluation`.
- [x] Physics Evaluation status is `pass-for-release-agent`.
- [x] All `must` requirements `001-072` trace to acceptance criteria, test/phase evidence, reference/physics evidence where applicable, and a released disposition.
- [x] Sole required comparison files exist, match approved hashes, and were not modified.
- [x] Fixed MITC4 tolerance and U-blocking/UR-warning-only policy are unchanged.
- [x] No unresolved build, test, reference, physics, schema, identity, nonfinite or environment failure remains.
- [x] Known limitations, unsupported Abaqus meanings and accepted risks are documented below and in the Release Notes Draft.
- [x] Release Agent changed only this report and performed no external release action.
## Known Limitations
| limitation | category | user impact | disposition |
| --- | --- | --- | --- |
| One small-displacement/small-rotation linear-static step only | analysis | Nonlinear, buckling, modal, dynamic, contact and thermal models are rejected/not executed. | documented |
| S4 and S4R are source labels for one full-integration FESA-MITC4 formulation | input/numerical | No Abaqus S4/S4R internal algorithm, reduced-integration or hourglass equivalence is claimed. | documented |
| External acceptance uses one flat symmetric fully clamped S4 plate | verification | General curved/distorted/thin-thick convergence is not established by the source-solver comparison. | accepted risk; optional future evidence |
| Original MITC4 membrane field is unmodified | numerical | Distorted curved meshes may exhibit membrane locking; MITC4+ performance is not claimed. | documented |
| S4R has no blocking Abaqus reference comparison | verification | S4R support is proven by parser/common-kernel/deterministic-assembly/HDF5 metadata tests only. | approved boundary |
| Homogeneous isotropic centered single layer with constant thickness | material/section | Composite, orthotropic, offset and variable-thickness models are unsupported. | documented |
| Smooth geometry-derived director field only | geometry | Explicit normals and shared-node folds/hinges/intersections are unsupported; folds require duplicated nodes. | documented |
| Nodal loads/constraints only | load | Pressure, gravity, DLOAD, body/edge/follower load are unsupported. Director-parallel moments fail as `unsupported-drilling-load`. | documented |
| Fixed numerical drilling stabilization | numerical | It is not a physical strain/load/result channel; no calibration sweep or drilling-energy ratio is supplied. | accepted fixed policy |
| In-plane stress only at bottom/middle/top | output | `S33` is a plane-stress assumption; `S13/S23` point stress and nodal averaging are not emitted. | documented |
| Raw HDF5 container bytes are not a declared deterministic identity | output/evidence | Regeneration may change the raw file hash; ordered projected rows and the JSON comparison ledger are deterministic evidence. | documented, nonblocking |
| Target-wide CTest label remains the legacy beam label | test infrastructure | MITC4 selection uses the approved exact suite regexes instead of a dedicated label. | documented, nonblocking |
## Release Notes Draft
### Feature Summary
- Adds end-to-end single-step linear-static analysis for four-node shell inputs labeled `S4` or `S4R`, both mapped to the independent full-integration `FESA-MITC4` formulation.
- Adds deterministic geometry-derived nodal directors, six global nodal DOFs, MITC4 transverse-shear tying, fixed nonphysical drilling stabilization, deterministic sparse assembly, full-residual reactions, physical shell recovery and failure-atomic HDF5 output.
- Adds mandatory HDF5 nodal displacement/reaction, shell local frames, generalized strain/resultant, bottom/middle/top in-plane stress, physical energy, equilibrium and verification metrics.
### Verification Scope
- Clean Visual Studio 18 2026/MSVC x64 Debug build and full `144/144` CTest regression passed with zero compiler/linker warnings.
- All 14 Harness implementation Steps completed with recorded RED/GREEN/VERIFY evidence and successful output exit codes.
- The sole declared S4 case matched all `147` blocking translational rows within fixed absolute `1.0e-5`; all `147` rotation rows were within the warning threshold and produced no warnings.
- Physics checks passed for global force/moment equilibrium, full-residual reactions, displacement direction, double symmetry, generalized resultant/stress consistency, free residual, finite results and positive physical energy.
### Main Limitations
- The released scope is linear static, small deformation, homogeneous isotropic single-layer MITC4 with nodal loads and constraints only.
- Abaqus compatibility and Abaqus S4/S4R formulation equivalence are not claimed. S4R uses the same FESA full-integration kernel and is not an Abaqus reference gate.
- Broader curved/distorted/thin-thick convergence, original-MITC4 membrane-locking characterization, nonlinear execution, distributed loads, composites, physical drilling behavior and expanded stress output remain outside this release.
### Artifacts
- Release report: `docs/releases/linear-static-mitc4-shell-release.md`
- Build/Test report: `docs/build-test-reports/linear-static-mitc4-shell-build-test.md`
- Reference Verification report: `docs/reference-verifications/linear-static-mitc4-shell-reference-verification.md`
- Physics Evaluation report: `docs/physics-evaluations/linear-static-mitc4-shell-physics-evaluation.md`
- Declared reference pair: `reference/shell/shell.inp`, `reference/shell/shell displacements.csv`
- Build-local deterministic ledger: `.harness/build/reference/mitc4-shell-s4-comparison/comparison.json`
## Release Verdict
- verdict: `ready-for-release`
- reason: all required upstream gates are present and passing; the final three mandatory handoff statuses are exactly `pass-for-reference-verification`, `pass-for-physics-evaluation`, and `pass-for-release-agent`; every `must` requirement `001-072` has a released disposition; required S4 artifacts and row mappings are present and valid; no unresolved defect, missing comparison file, tolerance conflict, nonfinite result, identity gap, or physics blocker remains.
- approval_scope: internal feature release closure only
- external_release_action: `none`
## Handoff Recommendation
| target_agent | reason | required_input |
| --- | --- | --- |
| Coordinator Agent | Close the feature workflow with `ready-for-release`. | This report, source HEAD `820ba30c717b3d0e113775608e20dfd5fbc05d53`, and the three passing downstream gate reports. |
| Correction Agent | N/A; no implementation-owned release blocker remains. | N/A |
| Reference Verification Agent | N/A; the required S4 comparison is complete and passing. | N/A |
| Physics Evaluation Agent | N/A; physics evaluation is complete and passing. | N/A |
## No-Change Assertion
- source_files_modified: `false`
- test_files_modified: `false`
- cmake_files_modified: `false`
- requirements_modified: `false`
- research_modified: `false`
- formulation_modified: `false`
- numerical_review_modified: `false`
- io_contract_modified: `false`
- reference_model_contract_modified: `false`
- implementation_plan_or_phase_files_modified: `false`
- build_test_report_modified: `false`
- reference_verification_report_modified: `false`
- physics_evaluation_report_modified: `false`
- reference_artifacts_modified: `false`
- tolerance_policies_modified: `false`
- Abaqus_or_other_reference_solver_executed: `false`
- publish_deploy_package_tag_commit_performed: `false`
- owned_report_created: `true`
- pre_existing_untracked_reports_preserved: `true`
- notes: before this report was created, the worktree had no tracked/staged diff and contained only the three upstream gate reports as untracked files. This audit adds only `docs/releases/linear-static-mitc4-shell-release.md`; generated build-local evidence remains ignored under `.harness/build/`.
## Open Issues
- blocking: `none`
- deferred requirements: `none`
- unresolved defects: `none`
- missing required comparison files or mappings: `none`
- nonblocking administrative note: the Build/Test, Reference Verification, Physics Evaluation and this Release report are untracked workspace reports pending whatever repository-integration action the user or Coordinator Agent separately authorizes. Their untracked state does not invalidate their content or the current internal readiness verdict.
- nonblocking evidence note: raw `results.h5` hashes can differ across valid regenerations; no byte-identical HDF5 container claim is made.
docs/linear-static-mitc4-shell/requirements.md
+280
View File
@@ -0,0 +1,280 @@
# Linear Static MITC4 Shell Requirements
## Metadata
- feature_id: `linear-static-mitc4-shell`
- title: `Linear Static MITC4 Shell`
- status: `approved`
- owner_agent: `requirement-agent`
- date: `2026-08-13`
- approval_basis: 사용자와 확정한 선형 정적 범위, `S4`/`S4R` 매핑, 6자유도 외부 계약, drilling 안정화, 자동 director 생성, 결과 및 검증 계약
- current_product_state: `requirements-approved-not-implemented`
- formulation_alignment: `docs/formulations/mitc4-shell-formulation.md`는 이 baseline의 6자유도 및 고정 drilling 안정화 계약과 정렬함
- reference_inventory_state: full-integration FESA-MITC4의 Abaqus acceptance comparison은 `reference/shell/`의 S4 input/displacement CSV만 기존 경로와 이름 그대로 사용함; S4R source support는 reference artifact 없이 mapping/kernel/HDF5 tests로 검증함
## Purpose
이 baseline은 승인된 Abaqus `.inp` subset의 4절점 `S4` 또는 `S4R` 요소를
FESA의 단일 MITC4 formulation으로 매핑하고, 소변형·소회전 선형 정적 해석을 수행해
검증 가능한 절점 및 쉘 요소 결과를 authoritative `results.h5`에 기록하는 다음
end-to-end 기능을 정의한다.
FESA는 Abaqus `S4` 또는 `S4R` formulation을 재현한다고 주장하지 않는다. 두 source
element type은 같은 FESA MITC4 formulation으로 매핑하며 source type과 internal
formulation identity를 분리해 보존한다. Abaqus reference comparison은 병진변위
`U1/U2/U3`만 pass/fail에 사용하고 회전 `UR1/UR2/UR3`은 비차단 warning evidence로
사용한다.
이 문서의 승인은 MITC4가 현재 제품에 구현되었다는 뜻이 아니다. Research,
Formulation, Numerical Review, I/O, Reference Model, Implementation Planning 및 이후
검증 gate가 순서대로 완료되어야 제품 기능이 된다.
## Source Basis
- 사용자 승인 결정: 선형 정적 실행 범위, `S4`/`S4R` 공통 MITC4 매핑, 전역 6자유도,
비물리 drilling 안정화, 자동 두께방향 director, 단일층 등방성 재료, 필수 결과와
displacement 중심 reference 판정
- `docs/reference-papers/MITC4/`: MITC4 director kinematics, assumed transverse shear,
5-DOF physical kernel, 6-DOF transformation/stabilization 사례 및 shell benchmark 근거
- `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`: end-to-end feature boundary,
ownership, linear-static lifecycle, deterministic assembly, HDF5, reference immutability 및
failure atomicity
- `docs/formulations/mitc4-shell-formulation.md`: 후속 정렬이 필요한 선행 draft이며 이
approved requirements baseline을 변경하는 근거로 사용하지 않음
## In Scope
- 입력 파일당 하나의 `*STEP, *STATIC` 선형 정적 해석
- small displacement와 small rotation
- 4절점 bilinear quadrilateral MITC4 shell
- Abaqus source element type `S4`와 `S4R`의 동일한 FESA MITC4 매핑
- 절점당 전역 자유도 `[UX, UY, UZ, URX, URY, URZ]`
- 3개 병진과 director 접평면 회전 2개로 구성된 물리 MITC4 kernel
- 비물리 local drilling 회전 1개에 대한 고정 수치 안정화
- 막, 굽힘, 횡전단 및 이들의 coupling
- 단일층, 균질 등방성 선형 탄성
- element set별 일정한 양의 두께와 하나의 material을 갖는 `*SHELL SECTION`
- 평면 및 매끄러운 곡면을 근사하는 유효한 사각형 mesh
- midsurface geometry와 element connectivity로부터 초기 두께방향 unit director 자동 생성
- DOF 1~6의 nodal `*BOUNDARY`와 nodal `*CLOAD`
- deterministic assembly와 기존 linear-static partition/factorization/substitution lifecycle
- HDF5 nodal displacement/reaction, shell generalized strain/resultant, in-plane stress, residual 및 energy output
- element invariant, patch, 현재 S4 displacement reference 및 physics verification
## Out Of Scope
- Abaqus full compatibility 또는 Abaqus `S4`/`S4R` formulation equivalence 주장
- Abaqus reduced-integration, hourglass-control 또는 finite-membrane-strain 의미의 재현
- `S3`, `S8`, `S8R`, continuum shell, solid-shell 및 axisymmetric shell
- 다중 step과 step 간 load, boundary 또는 state propagation
- 기하비선형, 재료비선형, 좌굴, modal, dynamic, contact 및 thermal analysis 실행
- composite/laminated shell, orthotropic material, layer orientation 및 층별 integration output
- variable/nodal/distributed thickness, section offset 및 thickness stretch DOF
- explicit nodal normal/director input과 user-defined shell orientation
- shared source node에서 불연속 director를 요구하는 sharp fold, hinge 또는 shell-beam joint
- `*DLOAD`, pressure, gravity, body force, edge traction, follower load 및 current-normal load
- drilling 방향의 nodal moment를 물리 하중으로 취급하는 동작
- `S13/S23` section-point stress와 `S33` stress recovery
- Abaqus reaction, stress, strain 또는 section resultant equality를 release pass/fail로 사용하는 비교
- Abaqus, Nastran 또는 다른 reference solver 실행과 reference artifact 생성·수정·복원
## Analysis Definition
- analysis_type: single-step linear static
- kinematics: small displacement, small rotation, fixed initial geometry/director
- element: four-node bilinear quadrilateral MITC4 shell
- source_element_types: Abaqus `S4`, `S4R`
- internal_formulation: one FESA MITC4 formulation independent of source type
- nodal_dofs: global `[UX, UY, UZ, URX, URY, URZ]`
- physical_local_dofs: three translations and two director-tangent rotations per node
- numerical_local_dof: one nonphysical drilling rotation per node
- deformation_modes: membrane, bending, transverse shear, and coupling
- material_model: single-layer homogeneous isotropic linear elasticity from `E` and `nu`
- section_model: one constant positive thickness and one material per assigned element
- boundary_conditions: nodal essential constraints on global DOFs 1 through 6
- loads: nodal concentrated force/moment; drilling-direction moment excluded
- initial_director: deterministic geometry-derived positive-thickness unit vector
- units: user-consistent unit system; no unit system inferred from `.inp`
- authoritative_output: HDF5 `results.h5`
- reference_pass_fail: global translational displacement `U1/U2/U3`
- reference_warning_only: global nodal rotation `UR1/UR2/UR3`
## Input Requirements
- **FESA-REQ-LSMITC4-001** — The solver shall accept exactly one `*STEP` containing `*STATIC` and shall reject a second analysis step or a non-linear/non-static procedure with a structured unsupported diagnostic.
- **FESA-REQ-LSMITC4-002** — The semantic mapper shall map both `*ELEMENT, TYPE=S4` and `*ELEMENT, TYPE=S4R` to the same FESA MITC4 formulation without claiming Abaqus formulation equivalence.
- **FESA-REQ-LSMITC4-003** — The model and result metadata shall preserve the source element type separately from the internal `FESA-MITC4` formulation identity.
- **FESA-REQ-LSMITC4-004** — Each accepted shell element shall contain exactly four distinct source nodes in the documented bilinear quadrilateral order, and the original source element identity shall remain stable through diagnostics and results.
- **FESA-REQ-LSMITC4-005** — Each shell node shall expose global DOFs `[UX, UY, UZ, URX, URY, URZ]` in that exact order; equation IDs shall not be stored in Node or Element records.
- **FESA-REQ-LSMITC4-006** — The material subset shall accept homogeneous isotropic `*ELASTIC` data containing `E` and `nu`, require finite `E > 0` and `-1 < nu < 0.5`, and reject temperature/field dependence and unsupported material behavior.
- **FESA-REQ-LSMITC4-007** — The section subset shall accept a single-layer `*SHELL SECTION, MATERIAL=<name>` with one finite constant thickness `t > 0` per section assignment.
- **FESA-REQ-LSMITC4-008** — Every active shell element shall resolve to exactly one shell section and exactly one material; missing, conflicting, duplicate or unresolved assignments shall be model errors.
- **FESA-REQ-LSMITC4-009** — A model may contain multiple element sets, constant-thickness shell sections and isotropic materials, but every individual element shall remain single-layer and homogeneous.
- **FESA-REQ-LSMITC4-010** — Composite data, section offset, distributed/nodal thickness, explicit director/normal input and user-defined material orientation shall be rejected as unsupported rather than ignored.
- **FESA-REQ-LSMITC4-011** — The initial nodal director shall be a dimensionless unit vector in the positive thickness direction; scalar thickness shall remain a separate property and shall not be encoded in the director magnitude.
- **FESA-REQ-LSMITC4-012** — The positive element normal candidate shall be derived deterministically from the source node order and midsurface covariant tangent cross product.
- **FESA-REQ-LSMITC4-013** — At a smooth shared node, consistently oriented incident element normal candidates shall be combined by deterministic area-weighted averaging and normalized to form the common nodal director.
- **FESA-REQ-LSMITC4-014** — Nonfinite or zero normal candidates, a nonfinite or zero averaged director, and opposing incident orientations shall fail model validation; this feature does not introduce a calibrated smooth-patch angle.
- **FESA-REQ-LSMITC4-015** — A physical fold or hinge shall be represented with duplicated source nodes so each smooth shell patch owns a separate director; the solver shall not silently average a discontinuous director field.
- **FESA-REQ-LSMITC4-016** — Element geometry validation shall reject duplicate nodes, self-intersection, nonfinite coordinates, zero area, and nonpositive or nonfinite Jacobians at every formulation-required Gauss and tying location; this feature does not introduce calibrated distortion or warp thresholds.
- **FESA-REQ-LSMITC4-017** — The solver shall support nodal `*BOUNDARY` targets resolved by source node label or node set for global DOFs 1 through 6, including existing zero and nonzero prescribed-displacement semantics.
- **FESA-REQ-LSMITC4-018** — The solver shall support nodal `*CLOAD` forces on DOFs 1 through 3 and nodal moments on DOFs 4 through 6 after deterministic aggregation in global coordinates.
- **FESA-REQ-LSMITC4-019** — The aggregated nodal moment component parallel to the approved nodal director shall be rejected as `unsupported-drilling-load`; a drilling-direction moment shall not be carried only by numerical stabilization.
- **FESA-REQ-LSMITC4-020** — `*DLOAD`, pressure, gravity, body force, edge traction and follower load shall remain unsupported at parser/CLI level even if a formulation-only equivalent-load kernel is later tested.
- **FESA-REQ-LSMITC4-021** — The accepted parser subset shall include the existing identity-preserving node, set, material, assembly, boundary, load and single-static-step keywords plus `*ELEMENT, TYPE=S4|S4R` and the approved single-layer `*SHELL SECTION` subset.
- **FESA-REQ-LSMITC4-022** — Identity `*PART/*ASSEMBLY/*INSTANCE` wrappers and multiple identity instances shall preserve `SourceEntityId`; instance transforms, nested assembly and dependent/independent mesh semantics shall remain unsupported unless separately approved.
- **FESA-REQ-LSMITC4-023** — Output-request keywords in the existing no-op allowlist shall not alter mandatory FESA results, and unsupported model-affecting keywords outside the allowlist shall be errors.
## Architecture and Execution Requirements
- **FESA-REQ-LSMITC4-024** — `Domain` shall own parsed shell elements, material/section assignments, source identity and initial directors; `AnalysisModel` shall expose the active single-step view without copying Domain objects.
- **FESA-REQ-LSMITC4-025** — `DofManager` alone shall own six-DOF node definitions, full/free equation numbering, constraint mappings, shell scatter maps and sparse-pattern ownership.
- **FESA-REQ-LSMITC4-026** — Linear-static `AnalysisState` shall own only the solution, force/residual/reaction, shell recovery and energy rows needed by this procedure and shall not preallocate nonlinear director history, iteration state, velocity or acceleration.
- **FESA-REQ-LSMITC4-027** — Element-local shell calculations shall use independent buffers and global sparse assembly shall preserve stable source-element ordering, deterministic COO ordering and fixed reduction independent of thread count.
- **FESA-REQ-LSMITC4-028** — The linear-static lifecycle shall assemble and partition stiffness, factorize `Kff`, then assemble loads, form `Ff-Kfc*dc`, substitute, reconstruct the full displacement, recover the full residual and only then commit results.
- **FESA-REQ-LSMITC4-029** — Constrained reactions and free-equilibrium evidence shall be recovered from the assembled full residual `K*d-F`; the shell feature shall not define reaction by separately summing recovered element resultants.
- **FESA-REQ-LSMITC4-030** — `S4` and `S4R` source elements with identical geometry, properties, constraints and loads shall execute the same FESA MITC4 numerical path; only preserved source metadata may differ.
## Numerical Formulation Boundary Requirements
- **FESA-REQ-LSMITC4-031** — The physical MITC4 kernel shall use three translations and two director-tangent rotations per node and shall not treat the drilling rotation as a physical strain variable.
- **FESA-REQ-LSMITC4-032** — The six-DOF element embedding shall transform global nodal rotations into two director-tangent components and one director-parallel drilling component using deterministic right-handed orthonormal frames.
- **FESA-REQ-LSMITC4-033** — The drilling contribution shall be a symmetric positive numerical stabilization of the four director-parallel coordinates and shall not define a physical drilling strain or load channel.
- **FESA-REQ-LSMITC4-034** — Let `R+` be the finite strictly positive diagonal entries of the physical local stiffness belonging only to the eight director-tangent rotational DOFs. The element shall use `k_ref=min(R+)`, `k_d=10^-3*k_ref`, `K_drill_local=k_d I4`, and the documented drilling transformation `T_d`; translational diagonals shall never enter `R+`.
- **FESA-REQ-LSMITC4-035** — Drilling stabilization shall not contribute to physical membrane, bending or transverse-shear generalized strain/resultant, section-point stress, or separately reported result quantities.
- **FESA-REQ-LSMITC4-036** — An otherwise accepted element with no finite strictly positive entry in `R+` shall fail numerical validation deterministically; coefficient sweeps, plateau selection, conditioning calibration, artificial-energy ratios, and drilling-specific result datasets are outside this feature.
- **FESA-REQ-LSMITC4-037** — Source `S4R` shall not select reduced integration or Abaqus hourglass control; all accepted `S4` and `S4R` inputs shall use the single quadrature and MITC tying contract approved by the FESA formulation.
- **FESA-REQ-LSMITC4-038** — The stabilized element shall retain exactly six physical rigid-body modes within the approved normalized tolerance, preserve stiffness symmetry and coordinate-transformation energy, and have positive energy for every accepted non-rigid physical deformation mode.
## Output Requirements
- **FESA-REQ-LSMITC4-039** — The sole authoritative solver output shall be HDF5 `results.h5`; the writer shall validate and close a temporary candidate before replacing the final path and shall not leave an incomplete final file after failure.
- **FESA-REQ-LSMITC4-040** — Metadata/model output shall include schema and solver versions, source input identity, user-consistent unit label, global/local coordinate conventions, source element type, internal formulation, stable node/element identities, shell section/material identity and initial nodal director.
- **FESA-REQ-LSMITC4-041** — Every node shall have global displacement `[U1,U2,U3,UR1,UR2,UR3]` and full-residual reaction `[RF1,RF2,RF3,RM1,RM2,RM3]` rows in stable source identity order.
- **FESA-REQ-LSMITC4-042** — Every required shell integration location shall output local generalized strain components `[E11,E22,G12,K11,K22,K12,G13,G23]` with membrane/shear strain dimensionless and curvature dimension `1/length`.
- **FESA-REQ-LSMITC4-043** — The same shell locations shall output local section resultant components `[N11,N22,N12,M11,M22,M12,Q13,Q23]`, where `N` and `Q` have dimension `force/length` and `M` has dimension `force` as moment resultant per unit edge length.
- **FESA-REQ-LSMITC4-044** — Each required shell location shall output local in-plane stress `[S11,S22,S12]` at bottom, middle and top section positions with dimension `force/length^2`; `S33` shall be documented as the plane-stress assumption and `S13/S23` point stress shall not be emitted.
- **FESA-REQ-LSMITC4-045** — Result rows shall identify source element, integration/tying or recovery location, natural coordinates, section position, local frame/director and component order without averaging mismatched locations.
- **FESA-REQ-LSMITC4-046** — The output shall include free-DOF residual evidence, total force/moment equilibrium metrics and physical shell strain energy with dimension `force*length` and deterministic aggregation order; no drilling-specific stiffness, ratio or energy dataset is required.
- **FESA-REQ-LSMITC4-047** — Abaqus output requests shall neither suppress nor expand the mandatory HDF5 quantity inventory; any deterministic FESA CSV projection shall remain a debugging/review view rather than official solver output.
- **FESA-REQ-LSMITC4-048** — Nonfinite recovery values, inconsistent component/location inventory or failure to finalize required HDF5 rows shall fail the analysis without committing a partial successful state.
## Verification Requirements
- **FESA-REQ-LSMITC4-049** — Every production behavior shall follow project TDD `RED -> GREEN -> VERIFY`, have a related C++ test, and later pass MSVC x64 Debug CMake/CTest with no new warning; this requirements phase shall not run Harness or implementation validation.
- **FESA-REQ-LSMITC4-050** — Element invariant tests shall cover frame orthonormality/handedness, Jacobian sign, stiffness symmetry, coordinate-transformation energy invariance, six physical rigid modes, deformation-mode positivity and deterministic repeatability.
- **FESA-REQ-LSMITC4-051** — Normalized algebraic acceptance shall use `1e-12` for symmetry, frame orthonormality and transformation-energy invariance and `1e-10` for rigid-mode action, linear-system residual and global equilibrium unless Numerical Review approves and documents an evidence-backed scale-aware replacement before Implementation Planning.
- **FESA-REQ-LSMITC4-052** — Patch verification shall independently cover constant membrane strain/stress, pure bending, transverse shear and twist, including sign and component-order checks for generalized strain, resultant and recovered in-plane stress.
- **FESA-REQ-LSMITC4-053** — The implementation shall pass the formulation-defined element invariants and patch/manufactured tests plus the declared S4 displacement reference case; an expanded locking, distortion or curved-shell benchmark portfolio is not an implementation-completion gate for this feature.
- **FESA-REQ-LSMITC4-054** — Geometry validation tests shall cover the exact accepted/rejected conditions defined by the formulation and I/O contract; `NR-O03` smooth-director calibration and `NR-O04` distortion/warp threshold sweeps are not required tests.
- **FESA-REQ-LSMITC4-055** — Additional pinched-cylinder, hemispherical-shell, Scordelis-Lo or mesh-convergence studies may be added later as nonblocking research or release evidence, but are not required for Implementation Planning or feature completion.
- **FESA-REQ-LSMITC4-056** — Drilling verification shall check the fixed formula in Requirement 034, symmetry, positivity, deterministic assembly, removal of the four nonphysical local drilling null modes, and exclusion from physical recovery; coefficient sweeps and drilling-energy checks are not required.
- **FESA-REQ-LSMITC4-057** — Physics verification shall check load/reaction balance, global moment balance, displacement direction, symmetry, energy positivity, result sign and consistency between assembled residual and recovered shell resultants.
## Verification Quantities
- nodal_displacement: required, global six components; `U1/U2/U3` reference pass/fail and `UR1/UR2/UR3` warning-only
- reaction: required, global six components from full residual; internal physics verification
- shell_generalized_strain: required, local eight components at documented locations
- shell_section_resultant: required, local `N/M/Q` eight components at documented locations
- stress: required, local bottom/middle/top `[S11,S22,S12]`; Abaqus equality comparison N/A
- residual: required, free-DOF and normalized global equilibrium evidence
- energy: required for the physical shell strain energy; drilling-specific energy output is not required
- modes_and_invariants: required, six physical rigid modes, symmetry, transformation invariance and positive deformation energy
## Tolerance Policy
- **FESA-REQ-LSMITC4-058** — Abaqus reference pass/fail shall apply only to matched global `U1/U2/U3` rows using the fixed absolute tolerance `abs(fesa-reference) <= 1.0e-5` for every row.
- **FESA-REQ-LSMITC4-059** — MITC4 row tolerance and tolerance-normalized error shall not depend on `reference_scale`, a row-specific denominator, zero clamp or component magnitude; a reference scale may be reported only as non-decision diagnostic information.
- **FESA-REQ-LSMITC4-060** — The fixed `1.0e-5` U tolerance is expressed in the model's user-consistent length unit and is independent of the approved B33 component-scale mixed tolerance.
- **FESA-REQ-LSMITC4-061** — Global `UR1/UR2/UR3` rows shall use the same fixed absolute value `1.0e-5` and shall be fully reported; an exceedance emits a deterministic nonblocking warning and never changes pass/fail.
- **FESA-REQ-LSMITC4-062** — The fixed `1.0e-5` UR tolerance is dimensionless. No separate UR large-error or drilling-energy threshold is required.
- **FESA-REQ-LSMITC4-063** — Missing, extra, duplicate, nonfinite, schema-mismatched or source-identity-mismatched rows shall fail artifact/schema validation before numeric tolerance evaluation for both U and UR inventories.
- **FESA-REQ-LSMITC4-064** — The comparison report shall record each U/UR row decision, maximum absolute error, fixed-tolerance-normalized error, RMS error, vector-norm error and worst source row/component; nonblocking UR warnings shall not be omitted from an otherwise passing report.
## Reference Artifact Requirements
The approved lightweight acceptance inventory uses only the existing S4 paths below.
Every file under `reference/` remains read-only; its name is an identity, not a
canonical/legacy-policy decision.
- **FESA-REQ-LSMITC4-065** — The S4 case shall use `reference/shell/shell.inp` and `reference/shell/shell displacements.csv` without creating, renaming, rewriting or repairing either file.
- **FESA-REQ-LSMITC4-066** — No S4R Abaqus artifact shall be required or consumed by this feature's reference acceptance comparison. S4R source support shall instead be verified by parser, common-kernel, deterministic assembly and HDF5 source-metadata tests; any existing `reference/shellR/` files remain untouched optional evidence.
- **FESA-REQ-LSMITC4-067** — Reference readiness requires only the declared input and required displacement CSV, FESA `results.h5`, deterministic source-node/component mapping, and Requirements 058-063 tolerance/precheck rules. README, `metadata.json`, canonical naming, provenance, Abaqus version, duplicated model semantics, and a schema version are not required gates; a present `metadata.json` is optional read-only context.
- **FESA-REQ-LSMITC4-068** — Artifact validation shall require unique finite displacement rows and deterministic source-node/component identity before comparison; it shall not attempt to establish Abaqus internal formulation equivalence.
- **FESA-REQ-LSMITC4-069** — The sole declared Abaqus comparison case is `reference/shell/` S4 because FESA-MITC4 uses full `2 x 2 x 2` integration. S4R source-label coverage is satisfied by the non-reference tests in Requirement 066; no expanded reference portfolio is required for this feature.
- **FESA-REQ-LSMITC4-070** — Reference verification shall compare FESA HDF5 global nodal displacement rows directly against Abaqus displacement CSV rows by model, step/frame, source node and component identity; a FESA-generated CSV view shall not become the authoritative comparison source.
- **FESA-REQ-LSMITC4-071** — Abaqus reaction, stress, strain and shell force/moment output may be retained as review evidence if present but shall not change the approved `U1/U2/U3` pass/fail boundary or become an undeclared equality gate.
- **FESA-REQ-LSMITC4-072** — FESA agents shall not execute Abaqus or another reference solver and shall not generate, modify, restore or normalize reference artifacts during requirements, research, formulation, implementation or verification unless a later phase explicitly authorizes that operation.
## Requirement Verification Matrix
Each range row below applies its verification method and acceptance criteria to every
individual requirement ID in that inclusive range; the ranges cover `001` through `072`
without gaps or overlap.
| id range | requirement theme | category | source | priority | verification method | acceptance criteria | tolerance/decision owner | downstream agents | status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `001` | Single linear-static step | analysis | User approval; PRD/ADR linear-static lifecycle | must | Parser/semantic negative and CLI integration tests | One supported static step runs; other procedures or a second step fail deterministically | Exact procedure inventory | I/O Definition; Implementation Planning | approved |
| `002-004` | `S4`/`S4R` mapping and identity | input/model | User approval | must | Parser/semantic/HDF5 metadata tests | Both source types map to one MITC4 path and preserve distinct source metadata and four-node identity | Exact element/type identity | I/O Definition; Implementation Planning | approved |
| `005` | Six global nodal DOFs | model | User approval; project DOF convention | must | DofManager and HDF5 schema tests | Exact component order and no distributed equation ownership | Exact ordering | Formulation; I/O Definition; Implementation Planning | approved |
| `006-010` | Isotropic material and single-layer section | input/model | User approval | must | Parser, mapping and validation tests | Valid `E,nu,t` resolve once per element; excluded section/material meanings fail | Exact inequalities; finite values | Research; I/O Definition; Implementation Planning | approved |
| `011-016` | Initial director and geometry validity | geometry | User approval; MITC director kinematics | must | Geometry/unit/property-based tests | Deterministic unit directors for supported valid meshes; explicitly invalid mappings fail | Exact formulation/I/O predicates; no `NR-O03`/`NR-O04` calibration gate | Formulation; I/O Definition; Implementation Planning | approved |
| `017-020` | Boundary and nodal-load subset | input/load | User approval | must | Parser/semantic/load tests | Global BC/CLOAD works; director-parallel moment and distributed loads fail | Exact-zero/projection rule from Formulation and I/O | Formulation; I/O Definition; Implementation Planning | approved |
| `021-023` | Parser subset, wrappers and no-op policy | input | User approval; ADR-003/013/018 | must | Parser diagnostic and semantic identity tests | Only approved meanings affect Domain; excluded meanings fail closed | Exact keyword/diagnostic inventory | I/O Definition; Implementation Planning | approved |
| `024-030` | Ownership, deterministic assembly and linear-static execution | architecture/execution | PRD; ADR-004/007/008/009/016/017 | must | Unit, orchestration and repeated-thread-count tests | Ownership boundaries, event order, residual reaction and deterministic bytes/rows match | `1e-12` deterministic numeric target where applicable | Numerical Review; Implementation Planning | approved |
| `031-038` | 5-DOF physics embedded in 6-DOF with fixed drilling stabilization | numerical boundary | User approval; MITC literature and thesis 6-DOF discussion | must | Formulation review, invariant and rank tests | Exact `10^-3` positive rotational-diagonal rule; physical outputs exclude drilling | Fixed by Requirements 033-036 | Formulation; Numerical Review; Implementation Planning | approved |
| `039-048` | Mandatory HDF5 output and failure atomicity | output | User approval; ADR-005/016/018 | must | Recovery, schema, identity, nonfinite and atomicity tests | Every quantity/location/unit/identity exists; failure commits no partial success | Exact component/location inventory; I/O Definition owns schema | Formulation; I/O Definition; Implementation Planning | approved |
| `049-057` | TDD, invariants, patch, declared reference and physics | verification | User approval; shell formulation evidence; project process | must | CTest evidence, analytical/patch tests, the S4 reference case and physics review | Required tests pass; removed calibration/portfolio checks are not reintroduced | `1e-12` symmetry/frame; `1e-10` rigid/residual | Numerical Review; Implementation Planning | approved |
| `058-060` | Translational displacement pass/fail tolerance | tolerance | User approval; ADR-020 | must | Comparator unit/integration tests and report review | Every matched U row uses fixed absolute `1.0e-5` without scale, clamp or omission | Fixed by Requirements 058-060 | Reference Verification | approved |
| `061-062` | Rotational warning-only comparison | tolerance/warning | User approval; ADR-020 | must | Comparator/diagnostic tests and report review | UR never changes pass/fail; fixed absolute `1.0e-5` exceedance emits a deterministic warning | Fixed by Requirements 061-062 | Reference Verification | approved |
| `063-064` | Row/schema failure and report completeness | reference verification | User approval; ADR-005/014/018 | must | Negative comparator and report-schema tests | Invalid inventory fails before numeric comparison; all U/UR metrics remain visible | No ignored invalid rows | I/O Definition; Reference Verification | approved |
| `065-068` | Exact S4 reference-case inventory, S4R exclusion and row validity | reference | User declaration; ADR-019 | must | Read-only S4 inventory, source-row/component precheck and S4R non-consumption test | Two declared S4 paths exist; required rows are unique, finite and deterministically mapped; S4R artifacts are not required or consumed | Requirements `058-063` | Reference Model; Reference Verification | approved |
| `069-071` | S4 reference coverage and displacement-only comparison | reference | User approval | must | HDF5-to-CSV comparison | Declared S4 case only; U blocks and UR only warns; S4R mapping remains independently tested | Requirements `058-064` | Reference Verification; Physics Evaluation | approved |
| `072` | Reference solver/artifact immutability | governance | User/project policy; ADR-010 | must | Process audit and Git diff | No unapproved execution or artifact mutation | Exact zero mutations | All downstream agents | approved |
## Open Questions and Required Downstream Decisions
No user or numerical calibration decision remains before Implementation Planning. Formulation
shall retain exact quadrature, tying interpolation, local-axis, sign and recovery definitions.
Future geometric-nonlinear execution remains separately unauthorized even though its residual
and tangent derivation may remain in the formulation document.
## Downstream Handoff
### Research Agent
- Establish source-backed MITC4 linear kinematics, tying, quadrature, shear correction and benchmark applicability.
- Record the thesis drilling rule and the approved dimensional restriction to positive physical rotational diagonals; do not reopen coefficient calibration.
- Preserve nodal-director and geometry evidence as implementation guidance without creating `NR-O03`/`NR-O04` calibration gates.
### Formulation Agent
- Revise `docs/formulations/mitc4-shell-formulation.md` to align with global 6-DOF input/output and a physical 5-DOF MITC4 kernel plus numerical drilling embedding.
- Keep current-product equations strictly linear static; retain geometric-nonlinear residual/tangent only as clearly separated future formulation.
- Define local frames, transformations, generalized component order, quadrature/tying, stress/resultant recovery and consistent units/signs.
- Do not introduce distributed-load product support or make `S4R` select reduced integration.
### Numerical Review Agent
- Independently review the revised formulation for dimensions, rigid modes, rank, symmetry, invariance, Jacobian/director handling and separation of fixed drilling stabilization from physical recovery.
- Treat drilling calibration/energy-ratio checks and `NR-O03`/`NR-O04` as removed scope, not missing evidence.
### I/O Definition Agent
- Define the exact Abaqus keyword/data subset for `S4`, `S4R`, single-layer `*SHELL SECTION`, material, BC and CLOAD semantics.
- Define source identity, auto-director data, unsupported-drilling-load projection, diagnostics and exact HDF5 dataset/row schemas without drilling-specific result datasets.
- Preserve source element type separately from FESA formulation and define bottom/middle/top stress location identity.
### Reference Model Agent
- Record only the exact existing S4 input/displacement CSV paths from Requirement 065 as acceptance artifacts and keep every existing reference artifact read-only.
- Do not consume the S4R bundle in reference verification; route S4R source support to parser/common-kernel/HDF5 tests from Requirement 066.
- Define only the HDF5-to-CSV source-node/component projection and the approved fixed absolute MITC4 tolerance `1.0e-5`; do not add bundle administration or portfolio gates.
### Implementation Planning Agent
- Do not start until Research, revised Formulation, Numerical Review, I/O and lightweight Reference Model inventory are mutually consistent.
- Trace every `must` requirement to RED/GREEN/VERIFY tests and preserve current solver ownership, deterministic assembly and failure-atomic HDF5 boundaries.
- Use the project Harness skill to propose self-contained implementation Steps for user approval, then write only the approved phase-planning files; do not execute Harness without a separate explicit request.
- Include tests for source-type mapping, auto directors, fixed drilling rank/separation, required recovery quantities, row failures and S4-only U-versus-UR comparison behavior; retain non-reference S4R source mapping coverage and exclude coefficient sweeps, drilling energy and `NR-O03`/`NR-O04`.
docs/linear-static-mitc4-shell/research.md
+236
View File
@@ -0,0 +1,236 @@
# Linear Static MITC4 Shell Research Brief
## Metadata
- feature_id: `linear-static-mitc4-shell`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- status: `approved`
- owner_agent: `research-agent`
- date: `2026-08-13`
- product_scope: small-displacement, small-rotation, single-step linear static analysis
- evidence_route: local papers in `docs/reference-papers/MITC4/`, the configured FEM wiki, original peer-reviewed papers, and official Abaqus documentation
- reference_inventory_state: the sole acceptance comparison is the existing read-only full-integration S4 case at `reference/shell/`; S4R source support is verified without consuming an Abaqus reference artifact
- source_policy: each external claim below is assigned a reliability tier; FESA decisions are labeled `Project contract`, and derived recommendations are labeled `Inference` or `Research recommendation`
This brief supplies evidence to the Formulation, Numerical Review, I/O Definition, and
Reference Model gates. It does not approve the existing formulation draft, finalize a C++
design, run a reference solver, create reference results, or claim that FESA MITC4 is
formulation-equivalent to Abaqus S4 or S4R.
## Research Questions
1. What kinematics and degrees of freedom define the original four-node continuum-mechanics-based MITC4 element in the linear regime?
2. How are the transverse shear components tied, and what evidence supports the quadrature and homogeneous-isotropic section behavior?
3. How can the physical five-DOF kernel be exposed through six global rotational components without treating drilling rotation as a physical MITC4 strain?
4. What evidence and dimensional restriction support the approved fixed drilling stabilization without turning it into a physical strain or load channel?
5. What evidence supports connectivity-derived thickness directions, nodal-normal smoothing, local tangent frames, and geometry rejection?
6. What may and may not be inferred when Abaqus S4 and S4R input types are both mapped to one FESA MITC4 formulation?
7. Which element-level checks and the declared full-integration S4 source-solver case fit the approved implementation scope while retaining non-reference S4R mapping coverage?
## Source Reliability Tiers
- **Tier 1:** original peer-reviewed formulation or evaluation paper, authoritative standards benchmark, or official solver theory/user documentation.
- **Tier 2:** peer-reviewed implementation summary, graduate thesis, or technical review whose formulas and numerical results are useful but require confirmation against Tier 1 evidence before becoming a FESA numerical constant.
- **Tier 3:** derived wiki synthesis or informal study notes. These are navigation and terminology aids, not sole authority for a numerical decision.
- **Project contract:** approved FESA requirement or architecture decision. It defines product meaning but is not external validation evidence.
## Source Inventory
| id | source | reliability | applicable evidence | limits |
| --- | --- | --- | --- | --- |
| S1 | E. N. Dvorkin and K.-J. Bathe, “A Continuum Mechanics Based Four-Node Shell Element for General Non-linear Analysis,” *Engineering Computations* 1 (1984) 77–88, DOI `10.1108/eb023562`; local transcription `docs/reference-papers/MITC4/AContinuumMechanicsBasedFourNodeShell/`; [author-hosted paper](https://web.mit.edu/kjb/www/Publications_Prior_to_1998/A_Continuum_Mechanics_Based_Four-Node_Shell_Element_for_General_Nonlinear_Analysis.pdf) | Tier 1 | original director kinematics, five physical DOFs, assumed transverse shear field, plane-stress degeneration, quadrature used by the authors, patch and shell benchmark results | nonlinear capability in the paper does not expand the approved FESA linear-static product scope |
| S2 | E. Dvořáková and B. Patzák, “Four-Node Quadrilateral Shell Element MITC4,” *Applied Mechanics and Materials* 825 (2016) 99–106, DOI `10.4028/www.scientific.net/AMM.825.99`; local transcription `docs/reference-papers/MITC4/FourNodeQuadrilateralShellElementMITC4/` | Tier 2 | compact 20-DOF ordering, tying equations and OOFEM implementation summary, patch-test classes, Scordelis–Lo convergence | secondary implementation paper; one OCR component label in the local transcription appears inconsistent and must not override the tensor equations |
| S3 | 이희준, *유한요소해석법을 이용한 쉘 구조물의 동적 좌굴 해석*, 인하대학교 석사학위논문 (2012); local transcription `docs/reference-papers/MITC4/유한요소해석법을이용한쉘구조물의동적좌굴해석/` | Tier 2 | five-to-six DOF transformation example, printed drilling diagonal rule, `5/6` shear factor, `2x2x2` integration, patch, pinched-cylinder, and hemispherical examples | thesis-specific implementation; the drilling rule mixes stiffness diagonal families unless a dimensional restriction is added; nonlinear/dynamic sections are out of current product scope |
| S4 | P.-S. Lee and H.-C. Noh, “On the Finite Element Analysis of Shell Structures”; local transcription `docs/reference-papers/MITC4/쉘구조물의유한요소해석에대하여/` | Tier 2 | locking classes, shell asymptotic behavior, need for a benchmark portfolio and field/error evidence | review evidence; it does not define FESA constants or I/O semantics |
| S5 | K.-J. Bathe, A. Iosilevich, and D. Chapelle, “An Evaluation of the MITC Shell Elements,” *Computers & Structures* 75 (2000) 1–30; [author-hosted paper](https://web.mit.edu/kjb/www/Principal_Publications/An_Evaluation_of_the_MITC_Shell_Elements.pdf) | Tier 1 | discriminating shell tests across different asymptotic behaviors; warning against judging a general shell element from one response value | evaluates a family and problem portfolio, not the exact future FESA implementation |
| S6 | Y. Ko, P.-S. Lee, and K.-J. Bathe, “The MITC4+ Shell Element and Its Performance,” *Computers & Structures* 169 (2016) 57–68, DOI `10.1016/j.compstruc.2016.03.002`; [publisher record](https://www.sciencedirect.com/science/article/pii/S0045794916300487) | Tier 1 | original MITC4 leaves membrane strain unmodified; distorted curved meshes can exhibit membrane locking | MITC4+ is a different formulation and is not approved for FESA in this feature |
| S7 | Y. Ko, K.-J. Bathe, and X. Zhang, “Continuum Mechanics-Based Shell Elements with Six Degrees of Freedom at Each Node—the MITC4/D and MITC4+/D Elements,” *Computers & Structures* 308 (2025) 107622, DOI `10.1016/j.compstruc.2024.107622`; [publisher record](https://www.sciencedirect.com/science/article/pii/S0045794924003511) | Tier 1 | a physical drilling-rotation extension can improve membrane behavior and shell/beam or intersecting-shell coupling without an artificial factor | MITC4/D is not the approved “five physical DOFs plus numerical drilling stabilization” FESA element |
| S8 | T. J. R. Hughes and F. Brezzi, “On Drilling Degrees of Freedom,” *CMAME* 72 (1989) 105–121, DOI `10.1016/0045-7825(89)90124-2`; [publisher record](https://www.sciencedirect.com/science/article/pii/0045782589901242) | Tier 1 | independent-rotation variational formulations exist for physical membrane drilling DOFs | not evidence that a diagonal numerical penalty is a physical strain or may carry drilling load |
| S9 | Abaqus, [Shell Section Behavior](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEELMRefMap/simaelm-c-shellsectionbehavior.htm) and [Shear Flexible Small-Strain Shell Elements](https://docs.software.vt.edu/abaqusv2025/English/SIMACAETHERefMap/simathe-c-shearflexshells.htm) | Tier 1 | homogeneous-shell transverse shear stiffness, small drill penalty proportional to transverse shear stiffness, and a dimensionally consistent area/thickness scaling precedent | Abaqus does not publish a FESA coefficient and its element formulation must not be copied by implication |
| S10 | Abaqus, [Defining the Initial Geometry of Conventional Shell Elements](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEELMRefMap/simaelm-c-shellgeometry.htm) | Tier 1 | connectivity/midsurface normals, order-independent grouping, 20-degree normal-averaging precedent, and coarse-mesh/fold cautions | 20 degrees is an Abaqus modeling heuristic, not a universal mathematical smoothness threshold; Abaqus permits multiple/user normals that FESA excludes |
| S11 | Abaqus, [Finite-Strain Shell Element Formulation](https://docs.software.vt.edu/abaqusv2025/English/SIMACAETHERefMap/simathe-c-finitestrainshells.htm) and [Choosing a Shell Element](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-c-shellelem.htm) | Tier 1 | S4 is fully integrated, S4R is reduced-integrated, their membrane treatments differ, and both use drill control | Abaqus finite-strain and hourglass algorithms are outside the FESA MITC4 identity and current small-deformation scope |
| S12 | Abaqus, [LE3 Hemispherical Shell with Point Loads](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEBMKRefMap/simabmk-c-le3.htm) and [The Pinched Cylinder Problem](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEBMKRefMap/simabmk-c-pinchcyl.htm) | Tier 1 | authoritative point-load-compatible curved-shell benchmark definitions, target displacements, S4/S4R convergence, and distorted-mesh evidence | official input decks contain semantics such as explicit normals or symmetry shorthand that require an approved FESA-subset adaptation |
| S13 | Abaqus, [Shell Thickness and Section Points](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEGSARefMap/simagsa-c-shlthick.htm) and [Whole and Partial Model Variables](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEOUTRefMap/simaout-c-std-wholeandpartialmodelvariables.htm) | Tier 1 | bottom/middle/top linear-elastic stress recovery precedent and separate reporting of artificial energy that includes drill constraints | no drill-specific acceptable artificial-energy percentage is stated |
| S14 | configured FEM wiki pages `[[MITC4 Shell Element]]`, `[[MITC Shell Kinematics]]`, `[[Assumed Transverse Shear Strain Interpolation]]`, `[[Shell Locking Phenomenon]]`, `[[Shell Element Benchmark Testing]]`, and `[[Scordelis-Lo Shell Benchmark]]` | Tier 3 synthesis | navigation between local raw sources; locking, tying, and benchmark terminology | key claims are cited to S1–S13 rather than relying on the wiki alone |
| P1 | `docs/requirements/linear-static-mitc4-shell.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, and `docs/ADR.md` | Project contract | exact FESA scope, six-global-DOF interface, source identity, output, verification, lifecycle, and reference immutability | does not prove numerical correctness by itself |
The informal `docs/reference-papers/MITC4/MITC공부/` notes were used only as a
navigation aid. No key numerical decision relies on them.
## Theory Summary
### Continuum-degenerated kinematics and physical DOFs
- **F-01 — Verified, Tier 1 (S1):** MITC4 represents a point through the shell thickness with bilinear midsurface interpolation plus a thickness coordinate multiplying nodal thickness and nodal director vectors. In compact form,
`X(xi,eta,zeta) = sum(N_i X_i) + zeta/2 sum(t_i N_i n_i)`.
- **F-02 — Verified, Tier 1 (S1), plus Project contract (P1):** The original director need not be exactly normal to an individual element midsurface. FESA deliberately narrows this freedom: its initial unit thickness director is generated from consistently oriented connectivity normals and thickness remains a separate positive scalar.
- **F-03 — Verified, Tier 1/2 (S1/S2):** The physical nodal variables are three midsurface translations and two rotations in the director tangent plane, giving 20 physical element DOFs. For a right-handed nodal frame `(t1,t2,n)`, the linear director increment has the form `delta_n = -alpha t2 + beta t1`.
- **F-04 — Project-contract consequence:** Global `[URX,URY,URZ]` is an interface vector. Only its projections onto `t1` and `t2` enter the physical MITC4 strains. The projection along `n` is a numerical drilling coordinate and must not appear in membrane, bending, transverse-shear, resultant, or section-point stress output.
### Assumed transverse shear interpolation
- **F-05 — Verified, Tier 1/2 (S1/S2):** Direct bilinear displacement/director interpolation cannot make transverse shear vanish throughout a thin element under constant bending, producing parasitic shear energy and shear locking.
- **F-06 — Verified, Tier 1/2 (S1/S2):** MITC4 evaluates the covariant shear components at the four edge-midpoint tying locations and interpolates them as
`e13_hat(xi,eta) = 0.5(1+eta)e13_A + 0.5(1-eta)e13_C` and
`e23_hat(xi,eta) = 0.5(1+xi)e23_D + 0.5(1-xi)e23_B`, with the tied covariant components transformed consistently to the local Cartesian shell basis.
- **F-07 — Verified, Tier 1 (S1):** The original elastic examples used `2x2` Gauss integration on the midsurface and two Gauss points through the thickness. The authors reported the expected six rigid-body modes and no spurious zero-energy modes in the undistorted and distorted element checks they performed.
- **F-08 — Research recommendation from F-06/F-07:** Formulation should evaluate standard membrane/bending terms and MITC tied shear terms on one common, documented `2x2` midsurface quadrature path for both source S4 and S4R. This is evidence-backed as a candidate, but the Formulation and Numerical Review gates must still re-derive the exact `B` rows, Jacobian use, and rank.
### Homogeneous isotropic section behavior and recovery
- **F-09 — Verified, Tier 1/2 (S1/S3/S9):** The shell constitutive law is formed in a local orthonormal frame under a through-thickness normal-stress condition (`sigma33=0`). For the approved homogeneous isotropic layer, `G=E/[2(1+nu)]`; a `5/6` transverse-shear correction is a documented homogeneous rectangular-section precedent.
- **F-10 — Inference from linear section kinematics:** With midsurface membrane strain `epsilon0`, curvature `kappa`, and thickness coordinate `z`, in-plane strain and stress are linear through thickness. Under one candidate curvature convention this is `epsilon(z)=epsilon0+z kappa`, `sigma(z)=Cps epsilon(z)`; Formulation must fix the final sign against its director and positive-face convention. Bottom, middle, and top in-plane stresses are then direct evaluations at `z=-t/2,0,+t/2`, while section resultants follow the familiar `A=Cps t` and `D=Cps t^3/12` integrals for a centered homogeneous layer.
- **F-11 — Verified precedent, Tier 1 (S13):** Official Abaqus guidance likewise treats bottom/middle/top as the default linear-elastic shell stress locations and states that three section points are exact for a linear through-thickness problem. This supports location choice, not Abaqus formulation equivalence.
### Six-global-DOF embedding and drilling stabilization
- **F-12 — Verified transformation, Tier 2 (S3):** The nodal rotation projection can be written `[alpha,beta,gamma]^T = [t1^T;t2^T;n^T] theta_global`, followed by `K_global=T^T K_local T`. An orthonormal right-handed frame preserves virtual work and strain energy.
- **F-12A — Kinematic inference requiring explicit review:** A physical rigid rotation of a five-DOF director shell is represented by rigid midsurface translations plus the tangent-plane change of each director; the director-parallel drilling coordinate is a gauge and can be zero. A rigid-mode test must construct those director changes explicitly. Blindly assigning the full spatial rotation vector, including its normal projection, to every six-DOF shell rotation would excite the numerical penalty and test a different quantity.
- **F-13 — Verified thesis implementation, Tier 2 (S3):** The thesis fills each otherwise zero local drilling diagonal with `d=10^-3 min(Kii)`. It does not provide a dimensional restriction on which diagonals enter the minimum.
- **F-14 — Dimensional inference and approved restriction:** Translational stiffness diagonals have units `force/length`, while rotational stiffness diagonals have units `force*length`. Taking a minimum across all of them is not unit invariant. P1 therefore applies the thesis coefficient only to finite strictly positive physical director-tangent rotational diagonals, all of which have `force*length` units.
- **F-15 — Verified precedent, Tier 1 (S9):** Abaqus states that a small drill penalty is proportional to transverse shear stiffness. Its small-strain shell theory presents a rotational constraint scale of the family `G h A_node / (1 + q A_node/h^2)`, multiplied by a small dimensionless factor, with `q=2.5e-5`. The base quantity has units `force*length` and transitions toward a thickness-cubed scale for thin shells. Abaqus says the small factor was selected numerically but does not disclose a general FESA-ready value.
- **F-16 — Historical alternatives, not current gates:** A transverse-shear/area transition scale and `D_iso=E t^3/[12(1-nu^2)]` are dimensionally compatible alternatives. The project has instead approved the implementation-local statistic `k_ref=min(R+)`, where `R+` contains only positive physical rotational diagonals; no comparison among these alternatives is required in this feature.
- **F-17 — Approved project decision with evidence limit:** P1 fixes `k_d=10^-3 k_ref` and `K_drill_local=k_d I4`. The `10^-3` value is a project choice informed by S3, not a claim of universal optimality or Abaqus equivalence. Coefficient sweeps, plateau/conditioning calibration, and response-sensitivity studies are outside the approved implementation gate.
- **F-18 — Scope consequence:** S13 supplies no drill-specific acceptable artificial-energy percentage. P1 therefore defines no `E_drill/E_physical` threshold and requires no drilling stiffness, ratio, or energy result dataset. This absence is an explicit scope decision, not missing numerical evidence.
- **F-19 — Verified boundary, Tier 1 (S7/S8):** MITC4/D and independent-rotation membrane formulations give drilling rotation physical/variational content. FESA's approved diagonal regularization is not MITC4/D, must not carry a director-parallel applied moment, and does not justify intersecting-shell, sharp-fold, hinge, or shell–beam drilling transfer.
### Initial director, tangent frame, and geometry evidence
- **F-20 — Verified precedent, Tier 1 (S10):** Abaqus computes normals from adjacent shell midsurfaces and uses order-independent grouping; its default averaging heuristic requires all normals in a smooth group to remain within 20 degrees. The manual warns that a coarse mesh can create a false fold or smooth a real fold.
- **F-21 — Project contract, informed by F-20:** FESA uses one deterministic area-weighted unit director at a smooth shared node and fails discontinuous/opposed incident directions, requiring duplicated source nodes at a physical fold. It does not adopt Abaqus's ability to retain multiple normals at one source node.
- **F-22 — Evidence limit and project decision:** The 20-degree value is an Abaqus modeling heuristic, not a universal MITC4 constant. P1 does not adopt or calibrate a smooth-patch angle in this feature; `NR-O03` is removed. Supported inputs still require finite nonzero, consistently oriented incident normals.
- **F-23 — Research recommendation:** Build each tangent frame by selecting the global basis least aligned with the unit director, projecting or crossing it into the tangent plane, normalizing, and forming the second tangent by a cross product. This avoids the near-parallel fixed-axis singularity seen in simpler source examples and is deterministic, but the exact sign/axis rule belongs in Formulation.
- **F-24 — Evidence limit and project decision:** No reviewed source establishes a universal distortion/warp cutoff. P1 therefore requires only the formulation/I/O finite, nonzero-area, topology, and positive-Jacobian predicates and removes `NR-O04`; a distortion/warp threshold sweep is not an implementation-readiness gate.
### Abaqus S4/S4R mapping and comparison meaning
- **F-25 — Verified, Tier 1 (S11):** Abaqus S4 is fully integrated, while S4R uses reduced integration and associated control; the membrane treatment differs. S4 and S4R therefore do not identify the original Dvorkin–Bathe MITC4 formulation.
- **F-26 — Project-contract conclusion:** Both source labels may select the single FESA MITC4 path only because P1 explicitly defines that input mapping. Source type remains metadata. The mapping is not evidence that the Abaqus elements or their recovered rotations, forces, stresses, integration points, or stabilization energies are equal to FESA's.
- **F-27 — Verification consequence:** Abaqus displacement rows are useful source-solver evidence for the same physical model, especially across mesh refinement. Only global `U1/U2/U3` is blocking under P1; large `UR1/UR2/UR3` differences are warning-only because the drilling and rotation representations are not equivalent.
### Known accuracy limits of original MITC4
- **F-28 — Verified, Tier 1 (S6):** Original MITC4 specifically treats transverse shear locking but leaves membrane strains unmodified. Distorted elements on curved geometries can therefore suffer membrane locking; MITC4+ was introduced to address that limitation.
- **F-29 — Verified, Tier 1/2 (S1/S4/S5):** Shell behavior depends on geometry, boundary conditions, thickness, asymptotic class, and mesh. A patch test or one point displacement cannot establish general robustness. Convergence sequences, distortion, curvature, field/resultant behavior, equilibrium, and energy must be examined together.
## Candidate Benchmarks
This catalog records useful future evidence, not the minimum implementation-completion
portfolio. The approved blocking source-solver cases are only the existing S4 and S4R
input/displacement pairs named in P1. Published values below do not create additional gates.
| benchmark_id | source/evidence | configuration and target quantities | verifies | does not verify / adaptation limit |
| --- | --- | --- | --- | --- |
| `MITC4-RIGID-RANK` | S1 plus P1 | free valid planar, rotated, and smoothly curved elements; six physical rigid motions, `K r`, symmetry, rank, and positive non-rigid energy | physical null modes, transform, drilling regularization rank, energy invariance | global supports, curved-shell accuracy, Abaqus agreement |
| `MITC4-MEMBRANE-PATCH` | S1/S2/S5 | independent constant `E11`, `E22`, and `G12` states on regular and distorted multi-element patches; generalized strain, `N`, stress, residual | membrane completeness, signs, component order, stress/resultant recovery | bending, shear locking, curved membrane locking |
| `MITC4-BENDING-PATCH` | S1/S2/S3 | constant curvature in both principal directions for thick and very thin thicknesses; rotations, `K11/K22`, `M`, bottom/top stress | bending consistency, thickness-cubed scaling, stress sign | complex curved membrane response |
| `MITC4-SHEAR-PATCH` | S1/S2/S3 | zero-rotation constant transverse shear states in each local direction; `G13/G23` and `Q13/Q23` | MITC shear tying, `5/6` section factor, component signs | thin bending convergence by itself |
| `MITC4-TWIST-PATCH` | S1/S2/S3 | constant twist on thin and thick patches; `K12`, `M12`, displacement/rotation symmetry | mixed bending terms and tying consistency | S3 reports thick-case sensitivity; it cannot set a universal accuracy tolerance |
| `MITC4-THIN-THICK-CANTILEVER` | S1 | nodal tip force or moment on regular and intentionally distorted meshes over documented `t/L` sequence; tip displacement/rotation, reaction, resultants, energy | shear-locking trend, thick response, distortion, equilibrium | curved membrane locking and general shell behavior |
| `MITC4-QUADRATURE-CROSSCHECK` | S1 plus inference | one constant-property planar element; `2x2` stiffness versus independently integrated high-order/analytical section result; tying-point shear values | quadrature, Jacobian, `B` rows, stiffness symmetry | benchmark validation or curved geometry |
| `MITC4-PINCHED-CYLINDER` | S1/S3/S12 | thin cylinder with end diaphragms and concentrated pinching load; radial displacement and mesh convergence. S12 cites `1.825e-5`; S3 uses `L=600`, `R=300`, `t=3`, `E=3e6`, `nu=0.3`, `P=1` and reports `1.8248e-5` | nodal-load-compatible inextensional bending, complex membrane response, curvature, convergence, regular/irregular mesh sensitivity | one response point cannot certify stresses or drilling; diaphragm semantics must fit approved BCs without rigid elements |
| `MITC4-NAFEMS-LE3` | S12 | radius-10 hemispherical shell, `t=0.04`, `E=68.25 GPa`, `nu=0.3`, opposite radial `2 kN` point loads; target `Ux(A)=185 mm`; S4 and S4R official cases exist | positive Gaussian curvature, point load, symmetry, automatic directors, S4/S4R source-label coverage candidate | official decks use explicit nodal normals and shorthand symmetry/perturbation semantics; FESA adaptation and mesh refinement are required, and the target is not a tolerance |
| `MITC4-SCORDELIS-LO` | S1/S2/S4/S5 | quarter cylindrical roof, mesh convergence of free-edge displacement and preferably field/resultant evidence | mixed-dominated shell behavior and classical convergence comparison | original dead-weight loading is outside P1; only a documented deterministic equivalent nodal CLOAD version may enter FESA product tests |
| `MITC4-DIRECTOR-GEOMETRY` | S10 plus P1 | connectivity reversal, opposed normals, bow-tie, inversion, degeneracy, and Gauss/tying Jacobian checks | deterministic director generation and fail-closed basic geometry policy | `NR-O03`/`NR-O04` calibration and physical shell accuracy |
| `MITC4-DRILL-FIXED` | S3 plus P1 | exact positive physical-rotational-diagonal selection, fixed `10^-3` factor, free-element rank, symmetry, and physical-recovery exclusion | implementation of the approved numerical regularization | coefficient optimality, sensitivity plateau, or energy ratio |
| `MITC4-S4-S4R-SAME-PATH` | S11 plus P1 | identical supported model written once as S4 and once as S4R; FESA HDF5 numeric rows equal while source metadata differs | approved semantic mapping and deterministic internal path | Abaqus S4/S4R equivalence; their reference displacements are expected to differ on finite meshes |
The local S3 hemispherical example with target displacement `0.0924` and its reported
mesh convergence is useful corroborating evidence, but NAFEMS LE3 has stronger benchmark
provenance and a directly accessible official S4/S4R definition. The two hemispherical
problems must not be mixed.
## Verification Relevance
- **Element code verification:** rigid modes, stiffness symmetry, tangent-frame orthonormality, transformation-energy invariance, quadrature cross-checks, individual tying values, and patch fields isolate algebraic mistakes before a source-solver comparison.
- **Locking and convergence:** thin/thick cantilevers, pinched cylinder, LE3, and Scordelis–Lo remain useful future studies. They are not additional completion gates for the approved two-case implementation scope.
- **Geometry verification:** tests must evaluate every formulation-required Gauss and tying location, not only the element center. Director smoothing and Jacobian quality are separate checks; a smooth director cannot rescue a self-intersecting or inverted mapping.
- **Drilling verification:** verify the fixed formula, dimensional family, symmetry, positivity, four-mode regularization, and absence from physical `E/N/M/Q/stress` recovery. Sensitivity and artificial-energy evidence are excluded.
- **Reference comparison:** the declared S4 case tests full-integration source mapping and global displacement. It cannot prove formulation identity. Missing, extra, duplicate, nonfinite, or source-node/component-mismatched required rows fail before P1's mixed displacement tolerance is evaluated. S4R source support is established separately by FESA mapping/kernel/metadata tests.
- **Physics sanity:** force and global moment balance, symmetry, displacement direction, reaction sign, positive physical energy, free residual, and consistency of recovered resultants remain mandatory even when all reference displacement rows pass.
- **Validation boundary:** the identified sources provide analytical, benchmark, and source-solver verification. No experimental dataset was established for the approved homogeneous linear-static feature; physical validation remains N/A unless separately added.
## Applicability Limits
- **analysis:** one small-displacement, small-rotation linear-static step. Nonlinear tangent, buckling, dynamics, finite rotation, and follower-load results present in S1/S3 are research background only.
- **element:** original four-node MITC4 transverse-shear treatment with unmodified membrane strain, not MITC4+, MITC4/D, Abaqus S4, or Abaqus S4R.
- **degrees of freedom:** five physical director-shell DOFs embedded in six global DOFs. Drilling is numerical regularization, not a physical load/result channel.
- **geometry:** smooth shell patches with one auto-generated director per source node. Explicit normals, discontinuous shared-node normals, physical folds without duplicate nodes, hinges, intersections, and shell–beam joints are excluded.
- **material/section:** one centered homogeneous isotropic linear-elastic layer with constant positive thickness. No composites, offsets, orthotropy, plasticity, field dependence, or thickness stretch.
- **loads:** nodal global forces and non-drilling moments only. Pressure, gravity, body force, edge traction, distributed load, and follower load are outside the product path.
- **locking:** assumed transverse shear addresses shear locking; original MITC4 does not guarantee immunity to membrane locking for distorted curved meshes.
- **quadrature:** `2x2` midsurface integration is a source-backed candidate for this feature, not permission to reinterpret S4R as a reduced-integration FESA element.
- **stress:** local in-plane stress is recovered at bottom/middle/top. `S33=0` is an assumption; pointwise `S13/S23` is not emitted, and S1 notes that transverse shear stress may be inaccurate in distorted cantilever tests.
- **reference:** Abaqus U comparison is model-specific. Rotations are warning-only; reaction, stress, shell force/moment, integration layout, and stabilization energy are not equality gates under P1.
- **units:** user-consistent units. All drilling formulas and geometry tolerances must remain dimensionally invariant under a consistent change of length/force units.
## Research Recommendations and Open Issues
### Recommendations supported for Formulation
1. Retain the original MITC4 five-DOF kinematics and the S1/S2 edge-midpoint covariant shear interpolation.
2. Use a single documented `2x2` midsurface integration path for source S4 and S4R, subject to independent Formulation derivation and Numerical Review rank/patch checks.
3. Use homogeneous-isotropic plane-stress resultants with `5/6` transverse-shear correction as the formulation candidate, and recover linear in-plane stress at `-t/2,0,+t/2`.
4. Project global rotations with deterministic right-handed nodal frames and keep drilling stiffness and energy algebraically separate from all physical shell results.
5. Apply `10^-3` only to the minimum finite positive physical director-tangent rotational diagonal and use the resulting scalar uniformly for the four local drilling coordinates.
6. Do not adopt a calibrated smooth-normal angle or distortion/warp threshold in this feature; retain finite, orientation, topology and positive-Jacobian validation.
7. Keep pinched cylinder, NAFEMS LE3 and Scordelis–Lo as optional future evidence rather than implementation-completion requirements.
### Closed decisions and nonblocking evidence limits
1. **Drilling:** P1 fixes the positive physical-rotational-diagonal scale and `10^-3` factor. Alternative-family comparison, coefficient sweep, conditioning plateau and artificial-energy threshold are not required.
2. **Director/geometry:** `NR-O03` and `NR-O04` are removed. The absence of a calibrated smooth angle or distortion/warp cutoff is not missing evidence.
3. **Reference tolerance:** The approved downstream contract uses fixed absolute `1.0e-5` for every U/UR row without a reference-scale decision term; U exceedance fails and UR exceedance only warns. The B33 mixed tolerance remains unchanged and separate.
4. **Reference case:** the existing `reference/shell/` S4 input/displacement pair is the complete required acceptance inventory because FESA-MITC4 uses full integration. `reference/shellR/` is not consumed by acceptance comparison. Administrative bundle metadata and an expanded portfolio are not gates.
No research-owned numerical decision remains blocking for Implementation Planning.
## Requirement Traceability
| requirement area | research evidence | downstream result |
| --- | --- | --- |
| `006-010` material/section | F-09–F-11 | homogeneous isotropic plane-stress and section recovery candidate; exact I/O remains downstream |
| `011-016` director/geometry | F-20–F-24, `MITC4-DIRECTOR-GEOMETRY` | basic deterministic validity rules; `NR-O03`/`NR-O04` calibration removed |
| `031-038` 5-to-6 DOF/drilling | F-12–F-19, `MITC4-DRILL-FIXED` | fixed dimensionally compatible rotational-diagonal rule; calibration and energy output excluded |
| `037` S4/S4R common path | F-25–F-27, `MITC4-S4-S4R-SAME-PATH` | source mapping supported only as a FESA product decision, never an Abaqus formulation claim |
| `039-048` shell outputs | F-09–F-11/F-18 | physical shell output and bottom/mid/top stress locations; no drilling-specific dataset |
| `049-057` element verification | F-28/F-29 and Candidate Benchmarks | required invariant/patch/fixed-drill checks; broader portfolio remains optional |
| `058-064` U/UR tolerance | F-25–F-27 plus approved user decision | fixed absolute `1.0e-5`; U blocking and UR warning-only |
| `065-072` reference artifacts | S11/S12 and current inventory state | exact existing S4 paths, source-row/component mapping, S4R non-consumption, and immutability |
## Downstream Handoff
### Formulation Agent
- Re-derive the exact bilinear geometry, physical `20x20` kernel, local component order, edge-midpoint shear tying, `B` matrices, plane-stress section matrices, `2x2` quadrature, and bottom/middle/top recovery from S1/S2 rather than copying OCR text blindly.
- Revise the existing formulation draft to expose global six-DOF input/output while keeping only two tangent rotations in physical strains. Define `T`, signs, frame construction, the fixed drilling embedding, and all units explicitly.
- Keep any geometric-nonlinear residual/tangent material in a clearly marked future-only section; it is not part of the approved executable analysis.
- State the approved fixed drilling rule exactly and do not reintroduce candidate sweeps or drilling-specific recovery.
### Numerical Review Agent
- Independently check six physical rigid modes, non-rigid rank, symmetry, transform energy, patch consistency, and every Gauss/tying Jacobian.
- Confirm the fixed drilling rule's dimensions, symmetry, positivity and physical-recovery separation without reopening coefficient calibration.
- Audit the original MITC4 distortion/membrane-locking limitation and set convergence expectations that do not imply MITC4+ behavior.
- Treat `NR-O03`/`NR-O04` and expanded benchmark portfolios as removed/nonblocking scope.
### I/O Definition Agent
- Preserve source S4/S4R identity separately from `FESA-MITC4`, while mapping both to one quadrature/kernel path.
- Define automatic director data, the exact unsupported-drilling-load projection rule, and fail-closed diagnostics for normals, topology, Jacobians, section/material data, and excluded loads without calibrated `theta_smooth`.
- Distinguish Gauss, tying, and section positions in HDF5 identities; do not average mismatched result locations.
### Reference Model Agent
- Record the exact existing S4 and S4R input/displacement paths without creating, renaming, repairing, or normalizing artifacts.
- Define deterministic HDF5-to-CSV source-node/component mapping and the fixed absolute MITC4 tolerance `1.0e-5`; do not require provenance, naming policy, README/metadata, duplicated model descriptions, or an expanded portfolio.
### Implementation Planning Agent
- Start after revised Formulation, Numerical Review, I/O, and lightweight Reference Model inventory are mutually consistent.
- Use the project Harness skill to draft self-contained RED/GREEN/VERIFY Steps, obtain user approval before writing `phases/` planning files, and never run the executor without a separate explicit request.
### Coordinator Agent
- Treat Research as approved and do not track removed drilling calibration, `NR-O03`/`NR-O04`, tolerance calibration, bundle administration, or portfolio expansion as downstream blockers.
- Reopen Requirements only if physical drilling loads, fold/intersection coupling, explicit normals, distributed loads, MITC4+, or nonlinear execution is proposed.