FESADev/docs/nonlinear-static-newton-raphson/translation-displacement-comparison.md

# Translation Displacement Comparison Report

## 1. Metadata and scope

- feature_id: `nonlinear-static-newton-raphson`
- report_id: `TRANSLATION-REPORT-001`
- date: `2026-08-26`
- owner_agent: `implementation-agent` (bounded diagnostic dispatch)
- dispatch coordination SHA-256: `D7CE6264EE3FD20FB6CD74CF1FC28E05EEEEFA67B25AF737D2DF989059A72D6F`
- status: `translation-diagnostic-pass-not-a-gate`
- tolerance source: `docs/TOLERANCE.md`

This focused report recomputes only global translational displacement components
`U1/U2/U3` for the existing coarse `reference/shellNL` case and the added fine
`reference/shellNL-meshfine` case.  It is diagnostic evidence for the observed
mesh sensitivity; it does not create or replace the canonical Stage 6
`reference-comparison.md`.  In particular, it is not Step 12 implementation
evidence and does not change any workflow gate.

The two meshes are compared separately to their own read-only Abaqus CSV
artifacts.  No coarse-to-fine node interpolation, row pairing, averaging, or
direct FESA-to-FESA error was used.

## 2. Artifact inventory and accepted-frame identity

All paths below are relative to the feature worktree.  SHA-256 and byte counts
were recomputed before comparison.

| mesh | artifact | path | bytes | SHA-256 |
| --- | --- | --- | ---: | --- |
| coarse | input | `reference/shellNL/shellNL.inp` | 4,778 | `4BF3ECB0F7F1E8462C573E993DBC97AC5D920C91CF6F23AD4C6891D77FFBADA2` |
| coarse | translation CSV | `reference/shellNL/shellNL displacements.csv` | 7,542 | `4E0F99CA9372B1ADF7FAF102F43BC0B887DC743FDEDA378E4342D2CF8E0C0786` |
| coarse | FESA HDF5 | `.harness/build-ninja-msvc-debug/reference/nonlinear-static-reference/shellNL/shellnl-s4-final-441600152250700-0/shellNL_results.h5` | 934,602 | `9744814BEBF33486F526F821EDC7D96F072F34E988D70A00AC7AA063570FFA40` |
| fine | input | `reference/shellNL-meshfine/shellNL-meshfine.inp` | 56,516 | `40DF1CE77311C8D799564A21A60F3BDEBB8148D52CAE22B7292FDFAD32018220` |
| fine | translation CSV | `reference/shellNL-meshfine/shellNL-meshfine displacements.csv` | 111,184 | `740819FF8AED0E279961581F7CDBFA12784CFBA3A488C35A652E80103F64433F` |
| fine | FESA HDF5 | `.harness/build-ninja-msvc-debug/reference/meshfine-diagnostic/run-1787669003801/shellNL-meshfine_results.h5` | 10,547,651 | `81A3C431E2977D2482D212877C3C306FFBB19CD1F0C47FBF1C936AE06CC93ACA` |

For both HDF5 artifacts, `/steps/Step-1/accepted_frames` has ten accepted rows.
The unique row satisfying `is_factor_one=1` and `load_factor=1.0` is
`frame_index=9`, `increment_index=10`, and `iteration_count=2`.  Translation
values were projected only from
`/steps/Step-1/frames/9/nodal/displacement`, columns `[UX, UY, UZ]`:

| mesh | HDF5 node rows | displacement shape | CSV wide rows | exact CSV Frame |
| --- | ---: | --- | ---: | --- |
| coarse | 49 | `[49, 6]` | 49 | `Increment     10: Step Time =    1.000` |
| fine | 729 | `[729, 6]` | 729 | `Increment     10: Step Time =    1.000` |

## 3. Source identity and prechecks

The comparison key is

```text
(accepted_state=factor-one, canonical_instance_name, source_node_label, component)
```

`canonical_instance_name` is matched case-insensitively; the CSV/HDF5 source
spelling itself is not rewritten.  CSV columns were selected after trimming only
surrounding header whitespace.  The `U-U1/U-U2/U-U3` columns map respectively to
HDF5 `UX/UY/UZ`.  Row order is not part of the identity and was not used for
matching.

| mesh | component rows | duplicate CSV wide/component/HDF5 keys | nonfinite CSV/HDF5 values | missing HDF5 keys | extra HDF5 keys | precheck |
| --- | ---: | --- | --- | ---: | ---: | --- |
| coarse | 147 | `0 / 0 / 0` | `0 / 0` | 0 | 0 | pass |
| fine | 2,187 | `0 / 0 / 0` | `0 / 0` | 0 | 0 | pass |

Each CSV contains only the exact factor-one `Frame` value shown above.  Thus the
row prechecks required before numerical tolerance evaluation pass for the
translation projection in each mesh.

## 4. Applied tolerance policy

`U1/U2/U3` remain one global-length, blocking translation family within each
case.  The component rows in Section 6 are diagnostics only: they use the same
case-family scale and near-zero band below and do not introduce a component
scale, component-specific tolerance, or a new approved family.

For the reference values `r_i` and FESA values `f_i`, `docs/TOLERANCE.md` is
applied exactly:

\[
S=\max_i|r_i|,\qquad B=0.01S,\qquad e_i=|f_i-r_i|.
\]

- If `|r_i| <= B`, the row passes iff `e_i <= B`.
- Otherwise, the row passes iff `e_i / |r_i| <= 0.05`.
- The whole family also requires `RMS(e_i) / S <= 0.01`.
- There is no independent absolute-error gate, `max(1,S)` floor, zero clamp,
  row omission, or averaging.  A zero-scale family would require exact FESA
  zero; neither translation family has zero reference scale.

## 5. Translation-family results

| mesh | rows | `S` | `B=0.01S` | near-zero / significant rows | row failures | max absolute error | max significant-row relative error | RMS error | `L2(error)` | relative RMS | verdict |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |
| coarse | 147 | `2.3740820300000001e-05` | `2.3740820300000003e-07` | 122 / 25 | 0 | `1.9037855439354404e-07` | `8.5711169439298945e-03` | `2.4530813178127803e-08` | `2.9742030342848264e-07` | `1.0332757195473908e-03` | pass |
| fine | 2,187 | `2.5795705400000001e-05` | `2.5795705400000002e-07` | 1,626 / 561 | 0 | `1.6193812501096337e-07` | `6.2777164841928829e-03` | `5.8615647876386634e-09` | `2.7411825664926473e-07` | `2.2723025777921402e-04` | pass |

Both sets have zero row failures and relative RMS values below the common
`0.01` threshold.  This is a translation-only diagnostic pass; it is not a
full external-reference verdict for the nonlinear-static feature.

## 6. Component diagnostics under the unchanged family scale

The `near-zero/significant` counts and every row decision below use the Section 5
family band `B`, not a component-derived scale.  A dash for maximum relative
error means all rows of that component were near-zero and were therefore judged
only by the approved absolute-band rule.

### 6.1 Coarse mesh

| component | rows | near-zero / significant | row failures | max absolute error | max significant-row relative error | RMS error | `L2(error)` | worst row `(node; fesa; reference; abs error)` |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |
| U1 | 49 | 49 / 0 | 0 | `5.9371608358817413e-12` | — | `1.7563955953584068e-12` | `1.2294769167508847e-11` | `12; -8.7994083858817417e-12; -2.8622475500000000e-12; 5.9371608358817413e-12` |
| U2 | 49 | 49 / 0 | 0 | `5.9379769034414602e-12` | — | `1.7566506185832881e-12` | `1.2296554330083018e-11` | `19; 8.7996068934414599e-12; 2.8616299900000001e-12; 5.9379769034414602e-12` |
| U3 | 49 | 24 / 25 | 0 | `1.9037855439354404e-07` | `8.5711169439298945e-03` | `4.2488614702881049e-08` | `2.9742030292016737e-07` | `2; -2.3550441745606457e-05; -2.3740820300000001e-05; 1.9037855439354404e-07` |

### 6.2 Fine mesh

| component | rows | near-zero / significant | row failures | max absolute error | max significant-row relative error | RMS error | `L2(error)` | worst row `(node; fesa; reference; abs error)` |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |
| U1 | 729 | 729 / 0 | 0 | `5.6550975712048108e-12` | — | `1.5513648050863109e-12` | `4.1886849737330394e-11` | `27; -1.1143569120481096e-13; 5.5436618799999999e-12; 5.6550975712048108e-12` |
| U2 | 729 | 729 / 0 | 0 | `5.6547834814404039e-12` | — | `1.5512360377367428e-12` | `4.1883373018892053e-11` | `16; -1.1132282144040392e-13; 5.5434606599999999e-12; 5.6547834814404039e-12` |
| U3 | 729 | 168 / 561 | 0 | `1.6193812501096337e-07` | `6.2777164841928829e-03` | `1.0152527787009038e-08` | `2.7411825024924402e-07` | `2; -2.5633767274989038e-05; -2.5795705400000001e-05; 1.6193812501096337e-07` |

## 7. Deterministically ordered largest absolute-error rows

Rows are listed by descending absolute error, then source node label and
component for a deterministic display.  `part-1-1` below is the canonical
case-insensitive instance identity.

| mesh | rank | key `(instance, node, component)` | FESA | reference | absolute error | applied rule and metric |
| --- | ---: | --- | ---: | ---: | ---: | --- |
| coarse | 1 | `(part-1-1, 2, U3)` | `-2.3550441745606457e-05` | `-2.3740820300000001e-05` | `1.9037855439354404e-07` | relative; `8.0190386005130586e-03` |
| coarse | 2 | `(part-1-1, 35, U3)` | `-1.2104431681576916e-05` | `-1.2190867900000000e-05` | `8.6436218423083233e-08` | relative; `7.0902432158323394e-03` |
| coarse | 3 | `(part-1-1, 39, U3)` | `-1.2104431681576916e-05` | `-1.2190867900000000e-05` | `8.6436218423083233e-08` | relative; `7.0902432158323394e-03` |
| fine | 1 | `(part-1-1, 2, U3)` | `-2.5633767274989038e-05` | `-2.5795705400000001e-05` | `1.6193812501096337e-07` | relative; `6.2777164841928829e-03` |
| fine | 2 | `(part-1-1, 21, U3)` | `-2.3863834908375246e-05` | `-2.3782464300000001e-05` | `8.1370608375244783e-08` | relative; `3.4214540322150206e-03` |
| fine | 3 | `(part-1-1, 69, U3)` | `-2.3863834908375246e-05` | `-2.3782464300000001e-05` | `8.1370608375244783e-08` | relative; `3.4214540322150206e-03` |

## 8. Mesh trend interpretation

The fine-mesh translation relative RMS divided by the coarse-mesh translation
relative RMS is

\[
\frac{2.2723025777921402\times10^{-4}}
     {1.0332757195473908\times10^{-3}}
=0.21991251074664606.
\]

This is a `78.008748925335397%` reduction in the separately measured
reference-normalized translation RMS.  It is consistent with the hypothesis
that the coarse-case discrepancy is mesh-sensitive, and the fine case also
passes the same row/RMS policy.

It is not an observed order of convergence, a proof of monotonic convergence,
or a solution-accuracy claim outside these translation rows: the two models have
different meshes and distinct external-reference outputs, and no common-mesh
interpolation or mesh-size-rate study was performed.

## 9. Explicit exclusions and no-change assertion

This report deliberately excludes:

- all reaction quantities;
- `UR1/UR2/UR3` rotations;
- all stress quantities, including the user-noted `reference/shell` element-label
  ordering change;
- Newton convergence lifecycle and iteration-log acceptance beyond identifying
  the accepted factor-one HDF5 frame;
- `USER-DECISION-004` disposition;
- Step 11 and Step 12 status, Physics Evaluation, and Release readiness.

No source, test, CMake, comparator, tolerance policy, phase file, canonical
reference-comparison report, declared input, or reference artifact was modified
for this report.  The report also does not create `implementation-report.md`,
`build-test.md`, or `reference-comparison.md`.

## 10. Handoff

Within this narrow scope there is no artifact, identity, finite-value, or
translation-tolerance blocker.  The report is handed to the Coordinator as
translation-only diagnostic evidence; gate ownership and all excluded work remain
unchanged.