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

# Linear Static MITC4 Shell Reference Cases

## Metadata

- feature_id: `linear-static-mitc4-shell`
- source_requirement: `docs/linear-static-mitc4-shell/requirements.md`
- source_io_definition: `docs/linear-static-mitc4-shell/io.md`
- status: `approved-for-implementation-planning`
- owner_agent: `reference-model-agent`
- date: `2026-08-13`
- comparison_revalidated_on: `2026-08-18`
- 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

Matched `U1/U2/U3` rows form one blocking translation family and matched
`UR1/UR2/UR3` rows form one warning-only rotation family. For each family:

```text
S = max(abs(abaqus_value_i))
absolute_error_i = abs(fesa_value_i-abaqus_value_i)
near_zero_band = 0.01*S

near-zero row: absolute_error_i <= near_zero_band
other row: absolute_error_i/abs(abaqus_value_i) <= 0.05
relative_rms = sqrt(mean(absolute_error_i^2))/S <= 0.01
```

The scale uses read-only Abaqus values only. No independent absolute-error gate, zero clamp or
row omission is permitted. A zero-scale family passes only when all FESA values are exactly zero;
otherwise it reports `zero-reference-scale-nonzero-error` without NaN/Inf. The U family controls
the verdict and the UR family uses the same numeric rule for deterministic warning-only evidence.

- Every matched `U1/U2/U3` row and the translation family RMS must satisfy the common
  row/RMS rule. Any U row or family-RMS exceedance fails the feature reference comparison.
- `UR1/UR2/UR3` uses the same family-scale row/RMS rule. Every row or family-RMS
  exceedance produces deterministic warning evidence but does not change pass/fail.

The comparison report records every U/UR row decision, family scale, near-zero branch,
maximum absolute error, row relative error, scale-relative RMS, 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.