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

Linear Static MITC4 Shell I/O Definition

Metadata

• feature_id: linear-static-mitc4-shell
• source_requirement: docs/linear-static-mitc4-shell/requirements.md
• source_research: docs/linear-static-mitc4-shell/research.md
• source_formulation: docs/linear-static-mitc4-shell/formulation.md
• source_numerical_review: docs/linear-static-mitc4-shell/numerical-review.md
• source_commits: requirements/research/formulation policy revision 73df844
• status: approved-for-implementation-planning
• owner_agent: io-definition-agent
• date: 2026-08-13
• authoritative_output: results.h5
• hdf5_schema_version: 0
• reference_cases: sole acceptance case is read-only full-integration S4 at reference/shell/; S4R is covered by non-reference source-mapping/kernel/metadata tests
• implementation_planning_authorized: true

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 source types map to one internal full-integration FESA-MITC4 formulation, while only S4 is an Abaqus acceptance reference.
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/ S4 input/displacement files are the sole declared acceptance pair and remain under their current names without mutation. Existing reference/shellR/ files are untouched optional evidence and are not consumed by acceptance comparison. No canonical or legacy-alias classification is required.
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.

The approved requirements fix the drilling rule and the project-wide common family-scale reference tolerance. Drilling calibration/output, NR-O03, NR-O04, bundle-administration metadata, and an expanded reference portfolio are outside this contract.

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

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 in the declared S4 case.

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

1.2 Nesting grammar

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

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. 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 requires finite nonzero surface area, finite covariant/reciprocal bases, and finite positive J. This document supplies no 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 invalid basic mappings fail closed. No calibrated smooth-angle, distortion, aspect, or warpage threshold is applied.

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,

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, and global equilibrium rows have distinct quantity/location identity. Values from different locations are never averaged to satisfy a schema. Drilling-specific result rows do not exist.

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	user-consistent-unspecified; FESA does not infer a named unit system from .inp or reference artifacts
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

No drilling coefficient/ratio/energy, theta_smooth, or distortion/warp calibration attribute is required. The fixed drilling formula is part of the formulation identity, not a per-run result policy.

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
/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
energy	/steps/Step-1/frames/0/global/energy	[1] float64	[PHYSICAL_STRAIN_ENERGY]	force*length; deterministic element reduction; excludes numerical drilling stabilization
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.

Verification-metric definitions and thresholds follow the approved formulation and requirements; they are not reference-bundle metadata.

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. The energy dataset contains only physical shell strain energy; no drilling energy or drilling-to-physical ratio is written.

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 Full-integration reference boundary

• FESA maps S4 and S4R source types to the same full 2 x 2 x 2 FESA-MITC4 path.
• Reference comparison consumes only the declared S4 input/displacement pair.
• Equality of FESA internal numerical rows after changing only source type is a separate implementation test; it does not consume or compare Abaqus S4R rows.

7.2 Declared S4 case

The blocking S4 case uses:

role	exact path	SHA-256	observed inventory
input	reference/shell/shell.inp	4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF	TYPE=S4; declared comparison input
displacement	reference/shell/shell displacements.csv	C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B	49 finite data rows; U and UR columns

The files must not be renamed, rewritten, zero-clamped, normalized, or repaired. The reaction and stress CSV files in the same directory are optional review evidence and are not comparison inputs.

7.3 S4R non-reference coverage

No file under reference/shellR/ is required or consumed by this acceptance comparison. S4R source support is verified by parser mapping, S4/S4R common-kernel and deterministic-assembly equivalence, plus preserved HDF5 source-type metadata. Any existing S4R artifacts remain immutable optional inspection evidence. No README, metadata.json, canonical name, legacy alias, provenance record, or duplicated model description is required.

7.4 Displacement header mapping

After trimming header whitespace, the declared S4 displacement CSV uses:

CSV column	comparison 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 and stress CSVs do not enter MITC4 pass/fail. No row is synthesized from those optional files.

7.5 Normalized comparison row

CSV and HDF5 displacement rows normalize in memory to:

case_id, instance_name, source_node_label, component, value, hdf5_dataset_path

The unique key is (case_id,instance_name,source_node_label,component). Stable ordering is case, 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 the declared input and displacement CSV path exists without mutating it.
2. Verify the trimmed displacement headers in Section 7.4.
3. Verify finite values, unique row keys, and exact source node/instance identities.
4. Project HDF5 and reference to the same six-component displacement inventory.
5. Fail on any missing, extra, duplicate, nonfinite, header-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.

Matched U rows form one blocking translation family and matched UR rows form one warning-only rotation family. For each family:

S = max(abs(reference_value_i))
error_i = abs(fesa_value_i-reference_value_i)
near_zero_band = 0.01*S

if abs(reference_value_i) <= near_zero_band:
    row_pass = error_i <= near_zero_band
else:
    row_pass = error_i/abs(reference_value_i) <= 0.05

relative_rms = sqrt(mean(error_i^2))/S
family_pass = all(row_pass) and relative_rms <= 0.01

Reference values alone define S; values are not zero-clamped or omitted and there is no independent absolute-error gate. A zero-scale family passes only if every FESA value is exactly zero, otherwise it fails without emitting NaN/Inf. U row or RMS exceedance fails; the same UR exceedance emits a deterministic warning only.

The report records every U/UR row, blocking/nonblocking decision, family scale, near-zero branch, absolute and applicable row-relative error, scale-relative RMS, worst source row/component, and every UR warning.

8. CLI and Diagnostics Contract

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, zero-area, reversed, or nonfinite surface geometry
opposed-incident-normal	model/4	an incident normal pair has nonpositive dot product before averaging
invalid-shell-director	model/4	candidate, average, interpolation, or tangent-frame construction is invalid
invalid-shell-jacobian	model/4	a required point has nonfinite/nonpositive J or nonfinite basis data
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, finite nonzero area, topology and positive-Jacobian predicates pass	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 orientation, average and frame construction pass	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 case	exact declared input/displacement paths and unique finite U/UR rows	reference precheck
S4R source support	parser/common-kernel/deterministic-assembly/HDF5 metadata tests; no Abaqus artifact consumption	implementation verification
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, basic geometry predicates and fail-closed diagnostics	Implementation Planning tests
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, fixed drilling stabilization and full-integration policy; no drilling output	Implementation Planning tests
039-048	additive HDF5 v0 paths, mandatory quantities, location identity, atomic output	Reference Model and Implementation Planning
049-057	diagnostic/schema hooks and required verification-metric/physical-energy evidence	Numerical Review and planning
058-064	common-policy U/UR families, blocking/warning behavior, report inventory	Reference Verification
065-072	exact current S4 paths, S4R reference non-consumption, immutability and displacement-only gate	Reference Model

11. Open Issues and Downstream Handoff

11.1 Numerical Review boundary

No I/O-owned calibration value remains open. Numerical Review shall verify the exact fixed drilling rule, basic geometry predicates, required HDF5 inventory, and common family-scale row/RMS tolerance mapping. Drilling calibration/energy output, NR-O03, NR-O04, bundle administration and reference-portfolio expansion are removed scope.

11.2 Reference Model Agent

• Write docs/linear-static-mitc4-shell/reference-model.md using this exact keyword/HDF5/reference-row contract.
• Record only the two exact existing input/displacement pairs, comparison components, HDF5 projection, source-row identity, common family-scale tolerance and immutability rule.
• Treat reaction/stress artifacts as nonblocking review evidence and do not create location-equivalence claims absent from this contract.

11.3 Numerical Review Agent

• Confirm cross-document numerical consistency and rerun the gate before authorizing Implementation Planning.

11.4 Implementation Planning Agent

• Planning is authorized by the numerical review; implementation and Harness execution remain separately unauthorized until explicitly requested.
• After approval, convert every supported/unsupported keyword row, source identity, geometry/director error, drilling-load projection, exact HDF5 path/shape/order, atomic failure, source-row normalization, and U-versus-UR decision into RED -> GREEN -> VERIFY tests.
• Use the project Harness skill to draft multiple self-contained Steps and obtain user approval before creating phase-planning files. Do not run the executor without a separate explicit request.
• Keep distributed loads, mixed beam-shell models, Abaqus reduced integration, nonlinear state/tangent, and reference artifact mutation outside the plan.

11.5 Reference Verification Agent

• Enforce artifact/schema precheck before numeric tolerance.
• Match HDF5 and Abaqus rows only by the normalized 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.