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.