FESADev/docs/shell-surface-pressure-load/reference-model.md

# Shell Surface Pressure Load Reference Model Contract

## 1. Metadata

- feature_id: `shell-surface-pressure-load`
- case_id: `shellnl-meshfine-pressure-s4-follower`
- source_requirements: `docs/shell-surface-pressure-load/requirements.md`
- source_formulation: `docs/shell-surface-pressure-load/formulation.md`
- source_numerical_review: `docs/shell-surface-pressure-load/numerical-review.md`
- status: `pass-for-io-definition`
- owner_agent: `numerical-review-agent`
- date: `2026-08-30`
- tolerance_authority: `docs/TOLERANCE.md`
- artifact_policy: `read-only-exact-existing-paths`

## 2. Reference Acceptance Scope

이 contract의 required acceptance artifacts는 exact stored nonlinear input 하나와 nodal
displacement CSV 하나뿐이다. External comparison은 accepted `Step-1` factor-one frame의
global nodal translation `U1/U2/U3`를 `blocking`, rotation `UR1/UR2/UR3`를
`warning-only`로 분류한다. Abaqus 값은 observable numerical reference이며 FESA pressure
formulation, quadrature, tangent 또는 recovery의 내부 동등성 evidence가 아니다.

Reaction CSV는 존재하는 optional `review-only` inventory이고 stress CSV는 `excluded`다.
README, metadata, provenance, Abaqus version, canonical rename 또는 추가 reference case를
요구하지 않는다. Final HDF5 dataset projection은 Stage 5 I/O Definition Agent가 소유한다.

## 3. Reference Case Inventory

### 3.1 Exact artifacts

| role | exact path | bytes | SHA-256 | observed inventory | status |
| --- | --- | ---: | --- | --- | --- |
| required input | `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure.inp` | 56,665 | `53718ccc9b41c23fcc1b509a51d66f1347e87aca43a74f1d6cec4d2085f4b90e` | 1,498 lines; 729 finite unique nodes; 676 unique S4 elements; no bad connectivity reference | `present-readable-required` |
| required comparison CSV | `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure displacements.csv` | 111,182 | `2fe53f98eac9f04779100721c3edf8049eb1dbfe733ebcbd819aeeed03b81198` | 729 wide data rows; six displacement/rotation components; zero duplicate node keys; zero nonfinite component values | `present-readable-required` |
| optional reaction CSV | `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure reactions.csv` | 108,923 | `a2347f4e88e4b73c75abe7c23e96bcc696c16c1975e2440b3ad9bf7ecda5f2b6` | 729 rows, zero duplicate node keys, zero nonfinite RF/RM values | `present-review-only` |
| excluded stress CSV | `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure stresses.csv` | 1,036,876 | `bc06f3324cc5d6655ded2939b3e1cb9d55a0359fa0d272a6958399464218a128` | 5,408 rows, 676 element labels, 729 node labels, zero duplicate full keys, zero nonfinite S values | `present-excluded` |

Required artifact gaps: `0`. 어떤 artifact도 생성, rename, rewrite 또는 수정하지 않았다.

### 3.2 Exact input-observed case identity

| field | exact observed value |
| --- | --- |
| part / instance | `Part-1` / `Part-1-1`, identity instance |
| nodes | labels `1..729`, count `729`, unique and finite |
| elements | source type `S4`, labels `1..676`, count `676`, four valid node references each |
| section / material | `Set-1`: shell thickness `0.5`, `5` section points; `Material-1`: `E=2.1e+11`, `nu=0.3` |
| surface | `Surf-1`, `TYPE=ELEMENT`, internal member set `_Surf-1_SPOS`, elements `1..676`, side `SPOS` |
| constraints | assembly `Set-2`, DOFs `1..6` constrained |
| step | `Step-1`, `NLGEOM=YES`, one `*STATIC` step; data `0.1, 1.0, 0.001, 0.1` |
| load | one `*DSLOAD` record: `Surf-1, P, 1e+06` |

CSV의 single observed frame text는
`Increment     10: Step Time =    1.000`, instance text는 `PART-1-1`이다. 이 case는
S4/SPOS/positive uniform pressure/current-configuration nonlinear response만 포함한다. S4R,
SNEG, negative/zero pressure, isolated tangent sign, linear reference configuration과 analytical
force/moment exactness를 대신하지 않으며, 이 항목들은 `numerical-review.md`의 internal tests가
담당한다.

## 4. Source Identity and Component Contract

### 4.1 Accepted frame and row identity

Logical case/frame identity is

`(case_id, Step-1, unique accepted load_factor=1.0 frame, source instance, source node label)`.

Reference wide-row key는 raw CSV의
`(Frame, Part Instance Name, Node Label)`이다. `Frame`은 위 single factor-one text여야 하고,
instance는 source identity `Part-1-1`과 case-insensitive하게 대응하되 양쪽의 원문 identity는
보존한다. Node identity는 numeric source label이며 row position 또는 internal index로
대응하지 않는다.

### 4.2 Logical components and disposition

| logical quantity | reference column | FESA logical component | units / coordinates | expanded row identity | classification |
| --- | --- | --- | --- | --- | --- |
| nodal translation | `U-U1` | `UX` | length, global Cartesian | accepted frame + instance + node + `U1` | `blocking` |
| nodal translation | `U-U2` | `UY` | length, global Cartesian | accepted frame + instance + node + `U2` | `blocking` |
| nodal translation | `U-U3` | `UZ` | length, global Cartesian | accepted frame + instance + node + `U3` | `blocking` |
| nodal rotation | `UR-UR1` | `URX` | dimensionless radian convention, global component | accepted frame + instance + node + `UR1` | `warning-only` |
| nodal rotation | `UR-UR2` | `URY` | dimensionless radian convention, global component | accepted frame + instance + node + `UR2` | `warning-only` |
| nodal rotation | `UR-UR3` | `URZ` | dimensionless radian convention, global component | accepted frame + instance + node + `UR3` | `warning-only` |

Expected raw wide rows: `729`. Expected blocking logical rows: `729*3=2,187`. Expected
warning-only logical rows: `729*3=2,187`. Components with different blocking disposition are not
placed in one comparison family.

Reaction values are not a displacement-family source and remain local `review-only`. Stress values
have no feature comparator family and are `excluded`.

## 5. Row Prechecks

Prechecks run before any numerical tolerance and use the exact existing files.

1. **Artifact/case:** both required paths must exist, be readable and be paired with case
   `shellnl-meshfine-pressure-s4-follower`. Wrong input/reference case or substituted filename fails
   before tolerance.
2. **Step/frame/load factor:** FESA must expose exactly one accepted `Step-1` frame at
   `load_factor=1.0`; the CSV must contain only the exact observed factor-one Frame text. Missing,
   extra, duplicate or wrong step/frame/factor fails before tolerance.
3. **Wide-row inventory:** exact source keys are one row for each
   `(PART-1-1,node label 1..729)`. Missing, extra or duplicate keys, wrong instance, nonnumeric/out-of-
   range node labels or row-order-based matching fail before tolerance.
4. **Components:** all six logical component columns must be present exactly once. Missing, extra,
   duplicate or unknown required component identity fails the affected family before value checks.
5. **Finite values:** every required U/UR value and matched FESA value must be finite. `NaN`, `Inf`,
   absent cells and parse failures are precheck failures; they are not zero and cannot be clamped.
6. **Cardinality after expansion:** blocking and warning families must each contain exactly 2,187
   one-to-one rows. Averaging, duplicate collapse, node-station collapse, missing-row omission or
   component substitution is prohibited.

Per `docs/TOLERANCE.md`, a required artifact/schema/identity precheck failure makes the comparison
non-success before family arithmetic. After successful shared prechecks, a `blocking` family failure
changes the blocking verdict; a `warning-only` row or RMS failure records a deterministic warning
without changing it. Warning rows are always inventoried and reported; they may not be silently
omitted because of their disposition.

## 6. Tolerance and Blocking/Warning Policy

The external policy is reproduced unchanged from `docs/TOLERANCE.md`; no threshold is calibrated to
this case.

Comparison families:

- `pressure_nodal_translation_blocking`: same case, `Step-1` accepted factor-one frame, length,
  global Cartesian, components `U1/U2/U3`, disposition `blocking`.
- `pressure_nodal_rotation_warning`: same case/frame, dimensionless global rotations, components
  `UR1/UR2/UR3`, disposition `warning-only`.

For each family, using reference values only,

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

- If `|r_i|<=B`, row pass requires `e_i<=B`.
- If `|r_i|>B`, row pass requires `e_i/|r_i|<=0.05`.
- All rows and family RMS must pass:
  `sqrt(sum_i(e_i^2)/n)/S<=0.01`.
- Boundaries are inclusive.
- There is no independent absolute-error gate, arbitrary floor, `max(1,S)`, averaging or zero
  clamp.
- If `S=0`, every FESA family value must be exact zero. Otherwise record
  `zero-reference-scale-nonzero-error`; do not emit a nonfinite metric.
- Blocking row/RMS failure fails the blocking comparison. Warning-only row/RMS failure emits a
  deterministic warning and does not change the blocking numerical verdict.

Internal analytical, geometry, tangent, free-residual and global-balance checks use
`numerical-review.md` §6, not this external policy.

## 7. Open Issues and I/O Handoff

### 7.1 Open issues

- Critical user question: 없음.
- Required artifact blocker: 없음.
- Accepted limitation: the single stored case supplies S4/SPOS/positive-`P` nonlinear displacement
  evidence only. S4R, sign reversal, current-area objectivity and tangent consistency remain
  blocking internal tests rather than invented reference cases.
- Optional reaction/stress artifacts remain immutable. Their presence does not expand the approved
  acceptance boundary.

### 7.2 I/O handoff through Coordinator

I/O Definition Agent receives only these logical contracts:

- accepted `Step-1`, unique factor-one frame identity;
- stable source instance `Part-1-1`, source node labels `1..729` and logical component identity;
- `U1/U2/U3 -> UX/UY/UZ` blocking and `UR1/UR2/UR3 -> URX/URY/URZ` warning-only;
- exact 729-wide-row / 2,187-row-per-family inventory, precheck ordering and common tolerance;
- reaction CSV `review-only`, stress CSV `excluded`;
- immutable exact artifact paths and hashes.

Final HDF5 dataset paths, schema projection and comparator serialization remain Stage 5-owned and
are intentionally not defined here.

## 8. Immutable Artifact Rule

Reference input and CSV files must not be renamed, rewritten, reordered, normalized, regenerated,
zero-clamped, repaired or supplemented to obtain a pass. The comparison implementation must adapt
deterministically to the exact current filenames, wide CSV layout, padded exported headers and raw
source identities while retaining the original artifacts byte-for-byte.