FESADev/docs/linear-static-mitc4-shell/reference-comparison.md

# 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/linear-static-mitc4-shell/build-test.md`
- source_reference_models:
  `docs/linear-static-mitc4-shell/reference-model.md`
- source_io_definition: `docs/linear-static-mitc4-shell/io.md`
- source_requirements: `docs/linear-static-mitc4-shell/requirements.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.