FESADev/docs/io-definitions/linear-static-mitc4-shell-io.md

# Linear Static MITC4 Shell I/O Definition

## Metadata

- feature_id: `linear-static-mitc4-shell`
- source_requirement: `docs/requirements/linear-static-mitc4-shell.md`
- source_research: `docs/research/linear-static-mitc4-shell-research.md`
- source_formulation: `docs/formulations/mitc4-shell-formulation.md`
- source_numerical_review: `docs/numerical-reviews/linear-static-mitc4-shell-review.md`
- source_commits: requirements `5c3025a`, research `02680dc`, formulation
  `6cb0302`, numerical review `ebb2657`, S4 legacy artifacts `57122b0`
- status: `ready-for-reference-model-not-implementation-planning`
- owner_agent: `io-definition-agent`
- date: `2026-08-12`
- authoritative_output: `results.h5`
- hdf5_schema_version: `0`
- current_reference_alias: `reference/shell/` as read-only S4 legacy alias
- missing_reference_family: separate canonical S4R bundle
- implementation_planning_authorized: `false`

This document defines the approved semantic input and output contract for the
linear-static MITC4 shell feature. It does not define parser, model, HDF5-writer, or
comparison-tool C++ APIs and does not claim full Abaqus compatibility or Abaqus
`S4`/`S4R` formulation equivalence.

The user approved the following I/O-specific decisions on `2026-08-12`:

1. `S4` and `S4R` reference artifacts remain separate even though both source types
   map to one internal `FESA-MITC4` formulation.
2. The optional positive integer on a `*SHELL SECTION` thickness row is accepted
   without a warning and has no semantic effect on FESA quadrature. FESA always uses
   the formulation's `2 x 2 x 2` rule.
3. The existing `reference/shell/` files are retained without mutation as an exact
   S4 legacy alias. Missing provenance is supplied only by a separately approved
   Reference Model contract; it is not inferred here.
4. HDF5 schema version `0` is extended additively with MITC4-specific datasets while
   retaining the existing common metadata, nodal-result, diagnostic, CLI, and
   failure-atomicity conventions.

Numerical Review has accepted the current linear formulation but has not approved
the drilling default, geometry/director thresholds, U mixed tolerance, or UR warning
threshold. This I/O contract names where those approved values must appear but does
not invent implementation defaults.

## 1. Abaqus Input Scope

- input_format: Abaqus input file (`.inp`)
- supported_analysis: exactly one small-displacement, small-rotation linear-static
  step containing four-node `S4` and/or `S4R` shell elements
- ordinary_unit_system: user-consistent; FESA does not infer SI or another unit
  system from an `.inp` file
- internal_element_formulation: `FESA-MITC4`
- compatibility_disclaimer: only the keyword locations, parameters, and data grammar
  in this document are supported

`supported` means only the documented subset is semantically interpreted. `warning
no-op` means the syntax is consumed and a structured warning is recorded, but no
Domain, AnalysisModel, numerical, or mandatory-output meaning changes. The optional
`*SHELL SECTION` integration-point field is a separately approved silent provenance
field, not a warning no-op keyword.

| keyword | status and allowed location | required parameters and data grammar | semantic mapping | unsupported behavior |
| --- | --- | --- | --- | --- |
| `*HEADING` | supported; optional top-level first keyword | no parameters; zero or more text rows until next keyword | original heading retained as source metadata | nested location or parameters are input errors |
| `*PART` / `*END PART` | supported; top-level model block | `NAME=<part-name>` required; no `*END PART` data | scope for part-local nodes, elements, sets, and shell sections | unclosed/nested part or duplicate name is an input error |
| `*NODE` | supported; part scope | no parameters; each row `node_label,x,y,z` | positive source node label and finite global Cartesian coordinates | wrong arity, duplicate label, or nonfinite value is an input error |
| `*ELEMENT` | supported; part scope | `TYPE=S4` or `TYPE=S4R`; each row `element_label,node_1,node_2,node_3,node_4` | ordered four-node shell connectivity; source type retained separately; internal type is `FESA-MITC4` | another type is `unsupported-element-formulation`; wrong arity, repeated connected node, or dangling node is an error |
| `*NSET` | supported; part or assembly scope | `NSET=<name>`; optional `GENERATE`; assembly scope requires `INSTANCE=<name>`; explicit labels or `first,last,increment` | deterministic node-set membership | mixed-instance set, invalid generate range, duplicate name, or dangling member is an error |
| `*ELSET` | supported; part or assembly scope | `ELSET=<name>`; optional `GENERATE`; assembly scope requires `INSTANCE=<name>`; same row rules as `*NSET` | deterministic element-set membership | mixed-instance set, invalid range, duplicate name, or dangling member is an error |
| `*MATERIAL` | supported; top-level model data | `NAME=<material-name>` required; no data | owns exactly one approved isotropic `*ELASTIC` definition | duplicate name, missing/duplicate elasticity, or another material model is an error |
| `*ELASTIC` | supported; current material scope | no parameters; exactly one row `E,nu` | homogeneous isotropic elasticity; `G=E/(2(1+nu))` | extra row/field, dependency/temperature data, nonfinite value, `E<=0`, or `nu<=-1`/`nu>=0.5` is an error |
| `*SHELL SECTION` | supported; part scope | `ELSET=<name>` and `MATERIAL=<name>` required; exactly one row `thickness[,integration_points]` | one centered homogeneous layer with constant thickness | composite/layer data, offset, orientation, distributed/nodal thickness, missing reference, or conflicting assignment is an error |
| `*ASSEMBLY` / `*END ASSEMBLY` | supported; exactly one top-level assembly | `NAME=<assembly-name>` required; no end data | scope for identity instances and assembly sets | nested/duplicate assembly is `unsupported-nested-assembly` |
| `*INSTANCE` / `*END INSTANCE` | supported; assembly scope | `NAME=<instance-name>`, `PART=<part-name>` required; no intervening data | named identity copy; multiple instances of a part are allowed | translation/rotation data is `unsupported-instance-transform`; duplicate or dangling instance is an error |
| `*BOUNDARY` | supported; top-level model data or sole step | no parameters; each row `target,first_dof,last_dof[,value]`; omitted value is exact zero | prescribed global shell DOFs 1 through 6 | invalid arity/range, unresolved target, or conflicting expanded value is an error |
| `*CLOAD` | supported; sole step | no parameters; each row `target,dof,magnitude` | concentrated global nodal force/moment on DOFs 1 through 6 | invalid arity/DOF, nonfinite magnitude, unresolved target, or drilling-direction aggregate moment is an error |
| `*STEP` / `*END STEP` | supported; exactly one top-level history block | optional `NAME`; optional `NLGEOM=NO`; no end data | one canonical result identity `(Step-1,frame 0)` | second step is `unsupported-multiple-step`; `NLGEOM=YES` is `unsupported-nonlinear-geometry` |
| `*STATIC` | supported; exactly once in sole step | no parameters; exactly one row `initial_increment,time_period,minimum_increment,maximum_increment` | source values retained; exactly one linear solve and frame 0 | another procedure or missing/extra/nonfinite/nonpositive field is an error |
| `*PREPRINT` | warning no-op; top-level | all parameters retained then ignored; no data | accepts generator control | no semantic object is created |
| `*RESTART` | warning no-op; sole step | all parameters retained then ignored; no data | accepts a legacy restart request | no restart state is created |
| `*OUTPUT, FIELD` | warning no-op; sole step | parameters and subordinate variable data retained then ignored | accepts field-output request root | cannot select, suppress, or expand mandatory FESA output |
| `*OUTPUT, HISTORY` | warning no-op; sole step | parameters and subordinate variable data retained then ignored | accepts history-output request root | no history dataset is created |
| `*NODE OUTPUT` | warning no-op; active output request | all parameters and following variable rows ignored | accepts legacy nodal request | cannot change the HDF5 schema |
| `*ELEMENT OUTPUT` | warning no-op; active output request | all parameters and following variable rows ignored | accepts legacy element request | cannot change the HDF5 schema |
| `*CONTACT OUTPUT` | warning no-op; active output request | all parameters and following variable rows ignored | accepts legacy contact-output syntax only | no contact model or output is created |

`*DLOAD`, pressure, gravity, body force, edge traction, follower load, explicit
normal/director input, `*ORIENTATION`, composite/layer controls, `*INCLUDE`, and
model-affecting keywords not listed above are `unsupported-keyword` errors. A mixed
B33/shell model and a shell-beam joint are `unsupported-mixed-element-model`; the
presence of an existing B33 implementation does not expand this feature contract.

Multiple `*ELEMENT` blocks containing `S4`, `S4R`, or both are allowed. Every element
retains its own source element type, and source type never changes FESA quadrature,
tying, drilling, recovery, or numerical path.

### 1.1 Shell-section data rule

The exact accepted data row is

```text
thickness[,integration_points]
```

- `thickness` is a finite `double` strictly greater than zero.
- If present, `integration_points` is a positive base-10 integer.
- The optional field is syntactically accepted without a warning and has no Domain,
  quadrature, recovery, or output effect.
- The raw input remains recoverable through the source file/content identity, but
  no `source_integration_points` physical property is created.
- FESA stiffness remains four midsurface Gauss locations times two thickness Gauss
  locations, including when the source value is `5` as in the S4 legacy deck.

Silently accepting this field is an explicit feature contract, not a general rule
that Abaqus section parameters may be ignored.

### 1.2 Nesting grammar

```text
input-file
  := heading? part+ assembly material+ model-boundary* step EOF

part
  := *PART
       node-block+ element-block+ (nset | elset)* shell-section+
     *END PART

assembly
  := *ASSEMBLY
       instance+ assembly-set*
     *END ASSEMBLY

instance
  := *INSTANCE *END INSTANCE

step
  := *STEP *STATIC step-boundary* cload* allowed-no-op* *END STEP
```

All parts close before assembly. Assembly contains only identity instances and
assembly-level sets. Instance-local node/element redefinition, nested assembly,
instance transforms, and dependent/independent mesh semantics are excluded.

## 2. Syntax Policy

- The first non-whitespace character of a keyword line is `*`; `**` begins a comment.
- Comments have no semantic effect but retain normalized file and 1-based line
  provenance for neighboring parsed records.
- Keyword names, parameter names, enumerated values, and named-reference lookup are
  ASCII case-insensitive. Raw source spelling remains available for identity and
  diagnostics.
- Keyword and data fields are comma-separated with surrounding whitespace removed.
  A required empty field, an unexpected trailing field, or a malformed numeric token
  is an input error.
- Keyword continuation, physical-line continuation, quoted/multiline names, and
  include files are unsupported. Each logical keyword or data row is complete on one
  physical line.
- Node/element labels and explicit set members are positive base-10 integers.
  Internal numeric IDs do not replace preserved source label text.
- All real-valued input is finite. `NaN` and positive/negative infinity are rejected.
- Every parsed keyword, parameter, data row, and semantic entity remains traceable to
  normalized file path, 1-based line, raw keyword, and source identity.
- Output-request variable data is a warning no-op only while subordinate to an
  allowlisted output keyword. An unexpected standalone data line is an input error.

### 2.1 Duplicate and dangling-reference policy

- Part, assembly, instance, material, set, and section identities are unique in
  their documented case-insensitive scope.
- Node and element source labels are unique within a part.
- Multiple identity instances of the same part are distinct through instance name.
- Connectivity, set membership, instance `PART`, section `ELSET`/`MATERIAL`, assembly
  set `INSTANCE`, boundary target, and load target all resolve before Domain commit.
- Duplicate definitions use `duplicate-entity`; unresolved references use
  `unresolved-reference`. A partial Domain is never passed to analysis.

## 3. Model Data Mapping

### 3.1 Stable source identity and ordering

After identity-instance expansion, each node and element has

```text
SourceEntityId { instance_name, source_label }
```

Raw spelling and the case-insensitive lookup key are separate. Stable internal IDs
follow input part declaration order, instance declaration order, and part-local
entity declaration order. Hash iteration and thread scheduling cannot affect IDs,
director accumulation, result rows, or diagnostics.

Assembly sets name one identity instance and resolve their numeric members to that
instance's part-local source identities. A set cannot mix members from multiple
instances in the approved grammar.

### 3.2 Nodes, elements, sets, material, and section

- A node has global Cartesian coordinates, stable internal ID, source identity,
  geometry-derived initial director, and deterministic tangent frame.
- A shell element has ordered connectivity `[node_1,node_2,node_3,node_4]`, stable
  internal ID, source identity, preserved source type `S4` or `S4R`, internal type
  `FESA-MITC4`, and exactly one resolved section/material.
- Connectivity order fixes natural corners `1=(-1,-1)`, `2=(+1,-1)`,
  `3=(+1,+1)`, `4=(-1,+1)` and positive thickness through
  `A_xi x A_eta`. Connectivity is not silently reversed.
- Explicit set order follows data rows. Generated sets use inclusive
  `first,last,increment` order. Set members remain round-trippable to source identity.
- Material preserves `E` and `nu`; `G=E/(2(1+nu))` is derived.
- Section preserves positive constant thickness and resolved material. It represents
  one centered homogeneous isotropic layer.
- Multiple materials, sections, element sets, `S4` blocks, and `S4R` blocks are
  allowed when each element resolves to exactly one valid assignment.

### 3.3 Director and geometry preprocessing

Initial directors are semantic model data derived after instance expansion, not
parser-provided rotations.

1. Process accepted shell elements in stable source-element order.
2. Compute each source-order-positive center normal candidate and its `2 x 2`
   surface-area weight.
3. At each node, sort incident elements by stable source identity and reject any
   nonpositive pairwise normal dot product before averaging.
4. Form and normalize the deterministic area-weighted director.
5. Apply the approved smooth-patch angle criterion.
6. Select the least-aligned global basis axis with fixed `x,y,z` tie order and form
   right-handed nodal frame `[a,b,d]`.

The complete center, volume-Gauss, tying, and committed-recovery inventory uses the
formulation's `J`, `j_s`, `a_g`, `c_d`, `r_J`, and `theta_w` measures. Exact numerical
thresholds are required inputs from a future approved Numerical Review decision;
this document supplies no fallback, clamp, point omission, normal flip, or default
axis.

Geometry and director failures are model-validation errors. Duplicate connectivity,
self-intersection, degenerate/reversed geometry, invalid Jacobians, opposed incident
normals, and unapproved sharp folds fail closed.

## 4. History Data Mapping

### 4.1 Step and procedure

Exactly one history object is created. The source step name remains provenance, but
the result identity is literal `Step-1`, frame index `0`. The four `*STATIC` values
are finite positive source data and `minimum_increment <= maximum_increment`; they do
not create increments, iteration history, or additional frames.

`NLGEOM=NO` or omission is accepted. `NLGEOM=YES`, another procedure, or another step
is unsupported. The future nonlinear formulation does not expand this history
contract.

### 4.2 Boundary conditions

Boundary target is a direct source node label or node set and expands to stable
source node identities. `first_dof <= last_dof`, with both in `1..6`. Omitted value
is exact zero; a finite nonzero value is supported. Model-level and step-level
boundaries activate in the sole step. Different prescribed values on one expanded
node/DOF are an error.

| DOF | kinematic component | unit dimension |
| ---: | --- | --- |
| 1 | `U1` | length |
| 2 | `U2` | length |
| 3 | `U3` | length |
| 4 | `UR1` | radian/dimensionless angle |
| 5 | `UR2` | radian/dimensionless angle |
| 6 | `UR3` | radian/dimensionless angle |

### 4.3 Concentrated loads and drilling projection

`*CLOAD` target expansion matches boundary expansion. Rows resolving to the same
node/DOF are accumulated in stable source order before physical admissibility is
tested.

| DOF | load component | unit dimension |
| ---: | --- | --- |
| 1 | `F1` | force |
| 2 | `F2` | force |
| 3 | `F3` | force |
| 4 | `M1` | force*length |
| 5 | `M2` | force*length |
| 6 | `M3` | force*length |

For aggregate nodal moment `M_I` and approved unit director `d_I`, exact-zero moment
is accepted as a separate case. Otherwise compute, without denominator clamping,

```text
rho_M = abs(dot(d_I,M_I)) / norm(M_I)
```

and require `rho_M <= 1e-12`. Failure is `unsupported-drilling-load`. No part of a
rejected physical moment is transferred to numerical drilling stabilization.

### 4.4 Output requests

Allowlisted Abaqus output requests do not activate history output and cannot change
the mandatory HDF5 inventory. FESA writes all datasets in Section 6 on a successful
run even when the input contains no output request. Requested Abaqus variables that
have no FESA dataset do not create empty synthetic physical results.

## 5. Internal Model Contract

- Domain owns the complete immutable-after-mapping definition of nodes, shell
  elements, sets, materials, sections, boundary/load data, sole static step, stable
  source identities, initial directors, and source formulation labels.
- `S4`/`S4R` remains source metadata. Numerical selection uses one explicit internal
  identity, `FESA-MITC4`.
- AnalysisModel is a non-owning view of active Domain objects and does not copy them.
- Nodes/elements do not own equation IDs. Six-DOF numbering, constrained/free maps,
  scatter maps, and sparse pattern are DofManager responsibilities.
- Boundary and load records retain both the source target and their deterministic
  expanded source-node identities.
- Section/material assignment is resolved before element processing. An element with
  zero or multiple assignments is invalid.
- AnalysisState contains only the current linear-static displacement, external and
  internal force, full residual/reaction, shell recovery, equilibrium, and energy
  rows. No nonlinear director history, iteration state, velocity, or acceleration is
  allocated.
- Midsurface generalized rows, section-position stress rows, nodal rows, global
  equilibrium rows, and drilling evidence have distinct quantity/location identity.
  Values from different locations are never averaged to satisfy a schema.

## 6. Output HDF5 Schema

The sole authoritative output is `results.h5`, schema version `0`. MITC4 extends
that schema additively; it does not migrate or reinterpret B33 datasets. Every
string is UTF-8, every physical real is IEEE-754 float64, stable internal IDs are
uint64, and constraint masks are uint8.

The literal result path identity is `(Step-1,frame 0)`. No history or nonlinear
frame group is created.

### 6.1 Metadata

`/metadata` is a group with these required scalar attributes:

| attribute | required value or meaning |
| --- | --- |
| `schema_version` | integer `0` |
| `feature_id` | `linear-static-mitc4-shell` |
| `solver_version` | executing solver version |
| `source_input_identity` | normalized input path plus auditable content identity |
| `unit_system_label` | ordinary run: `user-consistent-unspecified`; a reference run uses the externally approved label from its Reference Model metadata |
| `coordinate_convention` | `global-cartesian; shell-local=(e1,e2,e3); positive-thickness=+zeta` |
| `internal_formulation` | `FESA-MITC4` |
| `integration_rule` | `2x2x2-gauss; mitc4-edge-midpoint-shear` |
| `step_name` | `Step-1` |
| `frame_index` | integer `0` |
| `drilling_reference_family` | exact approved family identifier used in this run |
| `drilling_nominal_coordinate` | approved dimensionless nominal `rho_d` policy identifier/value |
| `theta_smooth` | approved smooth-patch bound used in validation |
| `tau_ang` | approved `j_s` bound |
| `tau_area` | approved `a_g` bound |
| `tau_dir` | approved `c_d` bound |
| `tau_var` | approved `r_J` bound |
| `theta_warp` | approved `theta_w` bound |
| `drilling_energy_warning_threshold` | approved warning rule identifier/value |

No unapproved stand-in number is legal in these numerical-policy attributes. The writer can
be implementation-ready only after Numerical Review approves their values and
definition identifiers.

### 6.2 Model identity datasets

| exact dataset path | shape/dtype | row identity and fields | attributes/order |
| --- | --- | --- | --- |
| `/model/nodes` | `[node_count]` compound | `internal_node_id:uint64`, `instance_name:utf8`, `source_label:utf8`, `coordinates:float64[3]` | internal node ID ascending; global Cartesian; coordinate unit `length` |
| `/model/elements` | `[element_count]` compound | `internal_element_id:uint64`, `instance_name:utf8`, `source_label:utf8`, `source_element_type:utf8`, `internal_formulation:utf8`, `node_internal_ids:uint64[4]`, `shell_section_internal_id:uint64`, `material_internal_id:uint64` | internal element ID ascending; connectivity in exact source order; source type `S4|S4R`; formulation `FESA-MITC4` |
| `/model/shell/nodal_director` | `[node_count,3]` float64 | `/model/nodes` row | dimensionless global components; unit norm within `1e-12` frame check |
| `/model/shell/nodal_frame` | `[node_count,3,3]` float64 | `/model/nodes` row, axis row `[a,b,d]`, global component column | dimensionless; right-handed and orthonormal |
| `/model/shell/materials` | `[material_count]` compound | `internal_material_id`, raw `name`, `E`, `nu` | stable declaration order; units `[force/length^2,1]` |
| `/model/shell/sections` | `[section_count]` compound | `internal_section_id`, source keyword file/line identity, source ELSET, `material_internal_id`, `thickness` | stable declaration order; centered single layer; thickness unit `length` |
| `/model/nodal_constraint_mask` | `[node_count,6]` uint8 | node row and global DOF order | `0=free`, `1=constrained`; existing HDF5 component names `[UX,UY,UZ,URX,URY,URZ]` |
| `/model/prescribed_displacement` | `[node_count,6]` float64 | same row/component order | constrained entry is prescribed value; free entry is exact zero with mask as authority |
| `/model/shell/midsurface_locations` | `[4,2]` float64 | `location_index` implicit row 1..4; columns `[xi,eta]` | exact order in Section 6.3; dimensionless |
| `/model/shell/section_positions` | `[3]` float64 | rows `BOTTOM,MIDDLE,TOP`; value is `zeta` | exact values `[-1,0,+1]`; physical `z=t*zeta/2` |

The optional source shell-section integration-point field is not written as a
physical model property. Exact source bytes remain auditable through
`source_input_identity`.

### 6.3 Fixed shell location ordering

Let `g=1/sqrt(3)`. Every shell result with a four-location axis uses:

| location index | name | `(xi,eta)` |
| ---: | --- | --- |
| 1 | `GP1` | `(-g,-g)` |
| 2 | `GP2` | `(+g,-g)` |
| 3 | `GP3` | `(+g,+g)` |
| 4 | `GP4` | `(-g,+g)` |

Every three-section-position axis uses `BOTTOM(zeta=-1)`, `MIDDLE(zeta=0)`, then
`TOP(zeta=+1)`. Location indices are not Abaqus integration-point numbers and must
not be relabeled as such in a reference comparison.

### 6.4 Step/frame result datasets

All datasets are mandatory after a successful run, independent of Abaqus output
requests.

| quantity | exact dataset path | shape | row identity and component order | units/coordinates/location |
| --- | --- | --- | --- | --- |
| displacement | `/steps/Step-1/frames/0/nodal/displacement` | `[node_count,6]` float64 | `/model/nodes` row; existing HDF5 component names `[UX,UY,UZ,URX,URY,URZ]` | `[length x3,radian x3]`; global; nodal |
| reaction/full residual | `/steps/Step-1/frames/0/nodal/reaction` | `[node_count,6]` float64 | `/model/nodes` row; `[RF1,RF2,RF3,RM1,RM2,RM3]` | `[force x3,force*length x3]`; global; nodal; constrained entry is physical reaction, free entry is residual evidence |
| local frame | `/steps/Step-1/frames/0/element/shell/local_frame` | `[element_count,4,3,3]` float64 | element row, location row, axis row `[e1,e2,e3]`, global component column | dimensionless; location-specific shell local frame |
| generalized strain | `/steps/Step-1/frames/0/element/shell/generalized_strain` | `[element_count,4,8]` float64 | element row, location row; `[E11,E22,G12,K11,K22,K12,G13,G23]` | `[1,1,1,1/length,1/length,1/length,1,1]`; shell local; midsurface location |
| section resultant | `/steps/Step-1/frames/0/element/shell/section_resultant` | `[element_count,4,8]` float64 | element row, location row; `[N11,N22,N12,M11,M22,M12,Q13,Q23]` | `[force/length x3,force x3,force/length x2]`; shell local; midsurface location |
| in-plane stress | `/steps/Step-1/frames/0/element/shell/stress` | `[element_count,4,3,3]` float64 | element row, location row, section-position row, component `[S11,S22,S12]` | `force/length^2`; shell local; direct bottom/middle/top evaluation |
| drilling stiffness | `/steps/Step-1/frames/0/element/shell/drilling_stiffness` | `[element_count,4]` float64 | element row and source-local node position 1..4 | `force*length`; actual positive `k_d,I` used |
| drilling ratio | `/steps/Step-1/frames/0/element/shell/drilling_ratio` | `[element_count,4]` float64 | same row and source-local node position | dimensionless actual `rho_d,I=k_d,I/D_iso` |
| energy | `/steps/Step-1/frames/0/global/energy` | `[2]` float64 | `[PHYSICAL_STRAIN_ENERGY,DRILLING_STABILIZATION_ENERGY]` | `force*length`; deterministic element reduction |
| force/moment balance | `/steps/Step-1/frames/0/global/equilibrium` | `[6]` float64 | `[FORCE_1,FORCE_2,FORCE_3,MOMENT_1,MOMENT_2,MOMENT_3]` | `[force x3,force*length x3]`; global; moment reference point is global origin `[0,0,0]` |
| verification metrics | `/steps/Step-1/frames/0/global/verification_metrics` | `[3]` float64 | `[FREE_RESIDUAL_NORMALIZED,FORCE_BALANCE_NORMALIZED,MOMENT_BALANCE_NORMALIZED]` | dimensionless; metric-definition IDs and thresholds required as attributes |
| diagnostics | `/diagnostics` | `[diagnostic_count]` compound | `severity`, `code`, `file`, `line`, `keyword`, `entity_identity`, `message` | deterministic order; required empty dataset when count is zero |

`S33=0` is a plane-stress assumption and is not emitted. `S13`, `S23`, physical
drilling stress/resultant, and nodally extrapolated/averaged shell stress are not
created. Transverse shear is externally represented through `Q13/Q23`.

Each numeric result dataset has required attributes `component_names`,
`component_unit_dimensions`, `coordinate_system`, `location`, `step_name=Step-1`,
and `frame_index=0`. Shell element results additionally identify their source
element type, internal formulation, midsurface-location dataset, section-position
dataset when applicable, and local-frame dataset.

The verification-metric definitions and approved thresholds remain Numerical Review
dependencies. Until their formula IDs are approved, this path is a fixed schema
reservation and not an implementation default.

### 6.5 Reaction, residual, equilibrium, and energy meaning

`nodal/reaction` stores the assembled full residual `K*d-F`; a duplicate nodal
residual dataset is not written. `/model/nodal_constraint_mask` controls meaning:

- constrained entry: physical reaction;
- free entry: equation-equilibrium residual evidence.

Global force/moment balance uses applied `CLOAD` plus constrained reaction about
the global origin. Free residual entries remain separate evidence and are not added
as physical reactions. Energy is split exactly into physical strain energy and
numerical drilling energy. A near-zero physical-energy denominator is never clamped
to form a misleading ratio; the later approved warning policy must classify that
case explicitly.

### 6.6 Atomic finalization

The writer creates a temporary candidate in the final output directory, writes every
mandatory group/dataset/attribute, validates finite values, shape, identity, and
ordering, flushes, closes, reopens read-only, and self-checks the schema. Only then
may it atomically replace/create the requested final path. A failure preserves any
previous valid final output when possible, removes or quarantines the non-authority
candidate, emits an output diagnostic, and returns exit code `6`.

## 7. FESA HDF5 to Reference CSV Comparison Schema

Authoritative comparison reads `results.h5` and read-only Abaqus CSV artifacts.
A deterministic FESA CSV projection is a debugging/review view only; it is neither
solver output nor a reference artifact.

### 7.1 S4/S4R portfolio separation

- S4 and S4R use distinct `model_id`, input, Reference Model Contract records, and CSV bundles. An optional `metadata.json` does not define bundle identity.
- FESA maps both source types to `FESA-MITC4`, but Abaqus S4 and S4R values are not
  expected to equal each other on a finite mesh.
- Reference comparison always compares one FESA run with Abaqus rows generated from
  the same source model/type.
- Equality of FESA internal numerical rows after changing only source type is a
  separate implementation test, not an Abaqus S4-versus-S4R comparison.

### 7.2 Approved S4 legacy alias inventory

The current exact alias is model ID `shell-s4-legacy`:

| role | exact path | SHA-256 | observed inventory |
| --- | --- | --- | --- |
| input | `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` | 164 lines; `TYPE=S4`; one `*STEP,*STATIC`; `NLGEOM=NO`; generator comment `Abaqus/CAE Learning Edition 2024` |
| displacement | `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` | 49 finite data rows; U and UR columns |
| reaction | `reference/shell/shell reactions.csv` | `0E34EEC27E700C3C0C744C1DAFD8A3B95EFEF34B8616FE96665876586FE82D41` | 49 finite data rows; RF and RM columns; review-only |
| stress | `reference/shell/shell stresses.csv` | `CBAA6E90400FE561535C4793B126F5A47020FF3FA60026C6F100253F276EFBBE` | nodal-associated S columns including S33; review-only and not location-compatible with mandatory FESA stress rows |

The files were introduced by source commit
`57122b0a1bdcb1a8d0eed55599742751edd534be`. They must not be renamed, rewritten,
zero-clamped, normalized, or repaired. A hash mismatch is
`needs-reference-artifacts`, not permission to restore or change the bundle.

The alias is `recognized-legacy-alias-needs-reference-contract`. Before numerical
comparison, the Reference Model contract must supply or approve externally:

- generation owner/date and exact provenance;
- user unit system and component unit labels;
- canonical model ID, source input identity, step and final-frame identity;
- global coordinate convention;
- material/section/thickness summary;
- CSV schema version and tolerance policy.

CSV lacks explicit step/frame/unit/coordinate columns. They map to
`(Step-1,frame 0)`, global Cartesian, and documented units if and only if the approved
Reference Model Contract confirms that exact interpretation. Missing contract data or a conflict is a
schema/provenance failure; I/O Definition does not infer values.

### 7.3 Separate canonical S4R bundle

At least one S4R reference bundle is still required:

```text
reference/<s4r-model-id>/
  model.inp
  <s4r-model-id>_displacements.csv
```

`model.inp` must contain the approved subset and `TYPE=S4R`. The approved Reference
Model Contract records generator/version/provenance, unit system, coordinate system,
model/step/frame, material/section/thickness, source element type, schema version, and
tolerance policy. `metadata.json` is optional; if present, it is read-only supplementary
evidence and every overlapping field is checked against the contract and stored artifacts.
Optional reaction/stress artifacts remain nonblocking evidence.

`<s4r-model-id>` is a Reference Model-owned schema variable, not an unresolved
filename placeholder in this I/O contract.

The canonical wide displacement CSV columns are:

```text
step_name,frame_index,instance_name,source_node_label,
coordinate_system,translation_unit,rotation_unit,
U1,U2,U3,UR1,UR2,UR3
```

Rows are unique by `(step_name,frame_index,instance_name,source_node_label)`, all
numeric values are finite, and the component coordinate system is global Cartesian.

### 7.4 Legacy header normalization

After trimming header whitespace, the exact S4 displacement header mapping is:

| legacy column | canonical field/component | FESA HDF5 source |
| --- | --- | --- |
| `Part Instance Name` | `instance_name` | `/model/nodes.instance_name` |
| `Node Label` | `source_node_label` | `/model/nodes.source_label` |
| `U-U1` | displacement `U1` | `nodal/displacement` column 0, HDF5 component `UX` |
| `U-U2` | displacement `U2` | `nodal/displacement` column 1, HDF5 component `UY` |
| `U-U3` | displacement `U3` | `nodal/displacement` column 2, HDF5 component `UZ` |
| `UR-UR1` | displacement `UR1` | `nodal/displacement` column 3, HDF5 component `URX` |
| `UR-UR2` | displacement `UR2` | `nodal/displacement` column 4, HDF5 component `URY` |
| `UR-UR3` | displacement `UR3` | `nodal/displacement` column 5, HDF5 component `URZ` |

Reaction columns are inventoried as `[RF1,RF2,RF3,RM1,RM2,RM3]` when the optional
file passes its schema precheck, but they do not
enter MITC4 Abaqus pass/fail. The legacy stress CSV is not projected onto FESA
integration/section-position rows because it contains a different nodal-associated
location identity and an `S33` column that FESA does not emit. Missing comparison
meaning is recorded as N/A, never repaired by averaging or synthesized rows.

### 7.5 Canonical normalized row

Wide CSV and HDF5 rows normalize in memory to:

```text
model_id, step_name, frame_index, instance_name, source_node_label,
quantity, component, value, unit_dimension, coordinate_system,
hdf5_dataset_path
```

The unique key is all fields except `value`, `unit_dimension`,
`coordinate_system`, and `hdf5_dataset_path`; those remaining fields must agree for
the matched key. Stable ordering is model, step, frame, instance declaration order,
stable source node order, then component order
`[U1,U2,U3,UR1,UR2,UR3]`.

### 7.6 Row-set precheck and comparison policy

Before tolerance evaluation:

1. Verify exact artifact inventory/hash or canonical bundle metadata.
2. Verify input source type matches model contract.
3. Verify one approved static step and final frame identity.
4. Verify expected trimmed headers, finite values, unique row keys, units, coordinate
   system, and exact source node/instance identities.
5. Project HDF5 and reference to the same six-component displacement inventory.
6. Fail on any missing, extra, duplicate, nonfinite, schema-mismatched, or
   identity-mismatched projected row.

Only `U1/U2/U3` affect pass/fail. `UR1/UR2/UR3` are always compared and reported but
can emit only an approved deterministic nonblocking warning.

For each model, step/frame, quantity, and component group:

```text
reference_scale_c = max(abs(reference_value_i))
row_tolerance_c = absolute_floor_c
                + relative_coefficient_c * reference_scale_c
row_pass = abs(fesa_value-reference_value) <= row_tolerance_c
```

Reference scale uses finite Abaqus values only. A zero scale makes the relative term
zero. No reference or result value is zero-clamped, no row-specific relative
denominator replaces the component scale, and B33 floors/coefficient are not
inherited.

The exact `absolute_floor_c`, `relative_coefficient_c`, and UR warning threshold are
`needs-reference-model-and-numerical-review`. Comparison implementation cannot begin
until those values and their unit context are approved.

The report records every U/UR row, blocking/nonblocking decision, absolute error,
component-scale normalized error, RMS error, displacement/rotation vector-norm
error, worst source row/component, and every UR warning.

## 8. CLI and Diagnostics Contract

```powershell
fesa.exe <model.inp> --output <results.h5>
```

Omitting `--output` uses `results.h5` in the current directory. Unknown option,
missing input, missing output argument, or repeated `--output` is usage failure.

| exit code | meaning |
| ---: | --- |
| `0` | successful analysis and authoritative HDF5 finalization |
| `2` | CLI usage error |
| `3` | input syntax or semantic mapping error, including unsupported keyword, formulation, wrapper, step, or distributed load |
| `4` | model validation error, including section/material property, geometry, director, Jacobian, or drilling-direction aggregate moment |
| `5` | factorization or substitution error |
| `6` | HDF5 write, schema validation, or atomic finalization error |

Each stderr and HDF5 diagnostic has exact field order `severity`, `code`, `file`,
`line`, `keyword`, `entity_identity`, `message`. Source-backed records carry
normalized file and 1-based line; source-less solver/output records use explicit
empty source fields. Order is source declaration order, file line, stable entity ID,
diagnostic code, then discovery order for an otherwise equal key.

The approved shell-specific diagnostic inventory includes:

| code | class/exit | meaning |
| --- | --- | --- |
| `unsupported-element-formulation` | input/3 | element type is not S4/S4R in this feature |
| `unsupported-mixed-element-model` | input/3 | shell and non-shell element/joint semantics are mixed |
| `invalid-shell-connectivity` | input/3 | connectivity arity is not four, a node repeats, or a connected source node is unresolved |
| `unresolved-shell-section` | input/3 | section/material/ELSET reference is unresolved |
| `invalid-shell-section-assignment` | input/3 | an element resolves to zero or multiple shell sections |
| `unsupported-shell-section-option` | input/3 | composite, offset, orientation, variable thickness, or other excluded meaning appears |
| `invalid-shell-thickness` | model/4 | thickness is nonfinite or nonpositive |
| `invalid-shell-material` | model/4 | isotropic material violates finite `E,nu` bounds |
| `invalid-shell-geometry` | model/4 | duplicate, self-intersecting, collapsed, reversed, or threshold-invalid surface geometry |
| `opposed-incident-normal` | model/4 | an incident normal pair has nonpositive dot product before averaging |
| `sharp-shell-fold` | model/4 | incident deviation exceeds approved `theta_smooth` |
| `invalid-shell-director` | model/4 | candidate, average, interpolation, or tangent-frame construction is invalid |
| `invalid-shell-jacobian` | model/4 | required point violates `J/j_s/a_g/c_d/r_J/theta_w` contract |
| `unsupported-drilling-load` | model/4 | nonzero aggregate moment violates `rho_M<=1e-12` |
| `unsupported-distributed-load` | input/3 | DLOAD, pressure, gravity, body/edge/follower load is requested |

The accepted optional `*SHELL SECTION` integration-point field emits no diagnostic.
Allowlisted `*PREPRINT`, `*RESTART`, and output-request no-ops retain their existing
warning behavior.

## 9. Validation Rules

| validation area | required pass condition | failure class |
| --- | --- | --- |
| keyword inventory | supported or exact allowlisted no-op | input, exit 3 |
| nesting/cardinality | closed part/assembly/instance/step; one assembly and one static step | input, exit 3 |
| source identity | duplicates absent; all references resolved; multi-instance identity unique | input, exit 3 |
| element syntax/semantics | only four-node S4/S4R, distinct resolved connectivity, internal FESA-MITC4, no mixed element model | input, exit 3 |
| resolved element geometry | source order satisfies orientation and every approved geometry measure | model, exit 4 |
| material/section syntax | exact row grammar, resolvable references, exactly one centered homogeneous assignment per element | input, exit 3 |
| material/section values | finite approved `E,nu,t` bounds | model, exit 4 |
| director/geometry | deterministic pairwise/average/frame construction and every approved measure threshold passes | model, exit 4 |
| boundary/load syntax | global DOF 1..6, resolved finite values, no conflicting prescribed values | input, exit 3 |
| aggregate nodal moment | exact-zero case or nonzero `rho_M<=1e-12` | model, exit 4 |
| history | sole static Step-1/frame 0, NLGEOM disabled | input, exit 3 |
| HDF5 model | exact paths, dtypes, shapes, IDs, source types, directors, sections, and finite values | output, exit 6 |
| HDF5 results | every mandatory row/location/component exists in stable order and is finite | output, exit 6 |
| S4 legacy alias | exact paths/hashes/headers plus approved external metadata | reference precheck |
| S4R canonical bundle | canonical files, metadata, S4R input, unique finite U/UR rows | reference precheck |
| comparison | exact normalized row-set; U blocking; UR warning-only; approved tolerance | reference verification |

No successful parser/HDF5 implementation, numerical solution, reference comparison,
physics review, or release status follows from approval of this document alone.

## 10. Requirement Traceability

| requirement group | I/O contract coverage | remaining owner |
| --- | --- | --- |
| `001-004`, `021-023`, `030`, `037` | exact step, S4/S4R mapping, source/internal identity, wrapper and no-op policies | Implementation Planning tests |
| `005-010` | six global DOFs, isotropic ELASTIC, single-row SHELL SECTION, exact assignment | Implementation Planning tests |
| `011-016` | auto-director semantic mapping, geometry inventory, fail-closed diagnostics | Numerical Review for thresholds |
| `017-020` | BOUNDARY/CLOAD grammar, deterministic aggregation, `rho_M<=1e-12`, distributed-load rejection | Implementation Planning tests |
| `024-029` | Domain/AnalysisModel/DofManager/AnalysisState semantic ownership and residual meaning | Implementation Planning |
| `031-038` | source-independent MITC4 identity, drilling output evidence, full-integration policy | Numerical Review for coefficient/energy rule |
| `039-048` | additive HDF5 v0 paths, mandatory quantities, location identity, atomic output | Reference Model and Implementation Planning |
| `049-057` | diagnostic/schema hooks and mandatory verification-metric/energy evidence | Numerical Review and planning |
| `058-064` | normalized U/UR rows, row-set precheck, blocking/warning behavior, report inventory | Reference Model and Numerical Review for values |
| `065-072` | exact S4 legacy alias, separate S4R canonical bundle, immutability, displacement-only gate | Reference Model |

## 11. Open Issues and Downstream Handoff

### 11.1 Upstream metadata corrections

The requirements metadata says the previously unobserved `reference/shell/` candidate
was declared as S4R. The observed immutable input is `TYPE=S4`, and the user has now
approved separate S4 and S4R artifacts. A later Requirement/Numerical Review metadata
refresh should correct that observation without changing the core requirement that
both source types map to one FESA formulation.

The current Numerical Review also records `reference/shell/` as unobserved because it
predates the dev-branch merge. Its next rerun should consume this exact alias
inventory and the Reference Model contract.

### 11.2 Numerical Review dependencies

The following values remain explicitly unapproved and have no I/O default:

1. drilling reference family, nodewise `rho_d` range, stable plateau, and nominal;
2. scaled rank/conditioning and U/N/M/Q contamination bounds;
3. drilling-to-physical energy warning classification and threshold;
4. `theta_smooth`;
5. `tau_ang`, `tau_area`, `tau_dir`, `tau_var`, and `theta_warp`;
6. verification-metric formula IDs and acceptance thresholds where not already fixed;
7. component-specific U absolute floors/relative coefficients and UR warning threshold.

Until these are approved, this document is ready for Reference Model design but not
Implementation Planning.

### 11.3 Reference Model Agent

- Write `docs/reference-models/linear-static-mitc4-shell-reference-models.md` using
  this exact keyword/HDF5/reference-row contract.
- Register `shell-s4-legacy` without modifying its four files and supply verified
  provenance, units, coordinate system, and final-frame identity.
- Provide a separate canonical S4R bundle and additional flat/thin/thick/distorted/
  curved models needed for tolerance and director/geometry calibration.
- Propose U mixed-tolerance values and the UR nonblocking warning threshold for
  Numerical Review approval.
- Treat reaction/stress artifacts as nonblocking review evidence and do not create
  location-equivalence claims absent from this contract.

### 11.4 Numerical Review Agent

- Review Reference Model evidence and close every dependency in Section 11.2.
- Confirm that actual HDF5 drilling and geometry policy attributes reproduce the
  approved calibration decision.
- Rerun the numerical gate before authorizing Implementation Planning.

### 11.5 Implementation Planning Agent

- Do not start while `implementation_planning_authorized=false`.
- After approval, convert every supported/unsupported keyword row, source identity,
  geometry/director error, drilling-load projection, exact HDF5 path/shape/order,
  atomic failure, legacy/canonical row normalization, and U-versus-UR decision into
  `RED -> GREEN -> VERIFY` tests.
- Keep distributed loads, mixed beam-shell models, Abaqus reduced integration,
  nonlinear state/tangent, and reference artifact mutation outside the plan.

### 11.6 Reference Verification Agent

- Enforce artifact/schema precheck before numeric tolerance.
- Match HDF5 and Abaqus rows only by the canonical identity in Section 7.5.
- Never ignore missing/extra/nonfinite rows, synthesize S33/S13/S23, average location
  mismatches, or let UR warnings change U pass/fail.