# FESA Phase 1 Abaqus Assembly and Reference Comparison Design

## 1. Status and purpose

This document records the approved Phase 1 design changes for:

- parsing both flat/orphan-mesh and Part/Assembly/Instance Abaqus inputs;
- activating only the Part referenced by one untransformed Instance;
- applying Phase 1 transverse-shear defaults when the input omits them; and
- validating displacement, reaction, element internal force, and centroidal
  element stress without per-model metadata files.

It refines the existing Phase 1 product and architecture documents. It does not
authorize solver implementation.

## 2. Phase 1 input scope

FESA supports two mutually exclusive input organizations.

### 2.1 Flat/orphan mesh

Nodes, elements, sets, sections, boundary conditions, and loads are defined in
the global input scope. These records map directly to the solver `Domain`.

### 2.2 Part/Assembly/Instance

The parser preserves the following syntax scopes:

```text
ParsedDeck
├── PartDefinition[]
├── AssemblyDefinition
│   └── InstanceDefinition[1]
├── MaterialDefinition[]
└── StepDefinition
```

Phase 1 accepts exactly one Assembly containing exactly one Instance. The
Instance must:

- reference one defined Part;
- contain no translation or rotation data; and
- contain no instance-local mesh modifications.

Multiple Part definitions may be parsed, but only the Part referenced by the
accepted Instance is expanded into the analysis `Domain`. Unreferenced Parts
remain syntax/semantic input records and do not contribute nodes, elements,
properties, loads, degrees of freedom, or results.

Multiple Instances, multiple Assemblies, mixed flat and hierarchical meshes,
missing Part references, and Instance transformation data are semantic errors.
Diagnostics identify the keyword and source location that caused the failure.

The following non-analysis directives found in the supplied Abaqus sample are
explicitly recognized no-op records rather than silently ignored unknown
keywords:

- `*HEADING`
- `*PREPRINT`
- `*RESTART`
- `*OUTPUT`

Comments and output-request data owned by these directives do not affect the
analysis `Domain`. Any other unsupported keyword or option remains an error.

## 3. Scope and identity resolution

Part-local node and element labels may be reused by future Instances. The
semantic layer therefore identifies instantiated entities by:

```text
(instance_name, part_local_label)
```

The Phase 1 single-Instance restriction means this composite key is not needed
to disambiguate the current equation system, but it is retained as explicit
input and result provenance. Dense internal indices remain separate from
external Abaqus labels.

For a hierarchical input:

- Part `NSET` and `ELSET` definitions resolve in Part scope.
- Material and section references are resolved after the complete deck has
  been parsed, so their textual declaration order does not control validity.
- Section assignments made to a Part `ELSET` are applied to the active
  Instance.
- Assembly `NSET` and `ELSET` definitions with `INSTANCE=` lift local labels
  from the active Part into Assembly scope.
- Nested set references resolve within their declared scope with cycle
  detection and deterministic sorted-unique membership.
- Step-level `*BOUNDARY` and `*CLOAD` references resolve through Assembly sets.

For a flat input, the same semantic contracts use a reserved global scope and
do not require an Instance name.

The normalized `Domain` contains analysis entities and their provenance, but it
does not expose Abaqus keyword records to FEM, element, assembly, constraint, or
solver modules.

## 4. Normalization flow

```text
Abaqus input
-> scoped syntax records
-> complete-deck name and reference resolution
-> organization validation
-> active Part/Instance selection or flat-scope selection
-> set, material, section, load, and boundary resolution
-> normalized immutable Domain
-> existing analysis pipeline
```

The normalization stage is the only production layer that understands both
Abaqus scopes and the flat solver `Domain`. The analysis pipeline is not made
hierarchy-aware in Phase 1.

## 5. Transverse-shear default

If `*TRANSVERSE SHEAR STIFFNESS` is absent, the Phase 1 semantic mapper applies:

\[
A_{sy}=A_{sz}=\frac{5}{6}A
\]

and uses `SCF=0`.

If explicit transverse-shear stiffness is present, its supported values
override the effective shear-area default. An explicitly specified nonzero
`SCF` is unsupported in Phase 1 and produces an input diagnostic.

The result database records whether the effective shear properties came from
the input or the Phase 1 default. This rule is a documented FESA Phase 1
assumption; it is not presented as a general default for arbitrary Abaqus
sections.

## 6. Reference comparison contract

No `metadata.json` file is required. A comparison request explicitly supplies:

- the result quantities to compare;
- the path of each requested reference CSV;
- relative tolerance; and
- quantity-specific absolute scale.

The default relative tolerance is \(10^{-5}\). Absolute scales are defined by
the PRD and test registration rather than by per-model metadata.

The comparison supports four quantities:

1. nodal displacement and rotation;
2. nodal reaction force and moment;
3. element-node section force and moment; and
4. element-node centroidal axial stress.

A requested missing file is an error. A quantity not selected by the comparison
request is not required and is not silently reported as passed.

The supplied `reference/cantilever beam` test initially requests only
displacement and reaction. The element-force and stress readers and comparison
kernels are still implemented and tested with synthetic reference tables.
When the corresponding Abaqus CSV files are added, the same reference test can
select all four quantities without changing the comparison kernel.

## 7. Reference CSV schemas

CSV readers trim surrounding whitespace from headers and values. A UTF-8 byte
order mark on the first header is tolerated. Entity rows must be unique for the
key required by their result type.

### 7.1 Displacement

The existing Abaqus field-report columns are accepted:

```text
Part Instance Name, Node Label,
U-U1, U-U2, U-U3, UR-UR1, UR-UR2, UR-UR3
```

For a single Instance, `Part Instance Name` may be omitted.

### 7.2 Reaction

The existing Abaqus field-report columns are accepted:

```text
Part Instance Name, Node Label,
RF-RF1, RF-RF2, RF-RF3, RM-RM1, RM-RM2, RM-RM3
```

For a single Instance, `Part Instance Name` may be omitted.

### 7.3 Element internal force

```text
Part Instance Name, Element Label, Node Label,
SF-SF1, SF-SF2, SF-SF3, SM-SM1, SM-SM2, SM-SM3
```

The canonical component mapping is:

```text
SF1 -> N
SF2 -> Vy
SF3 -> Vz
SM1 -> T
SM2 -> My
SM3 -> Mz
```

The element label and element-end node label together identify the result
position. For a single Instance, `Part Instance Name` may be omitted.

### 7.4 Element stress

```text
Part Instance Name, Element Label, Node Label, Sxx
```

`Sxx` is compared with the FESA element-end stress at the section centroid:

\[
\sigma_{xx,\mathrm{centroid}}=\frac{N}{A}
\]

The reference comparison does not use bending stress at an unspecified
recovery point. FESA may still store explicitly identified non-centroid
recovery-point stresses in its HDF5 result contract. For a single Instance,
`Part Instance Name` may be omitted.

## 8. Comparison behavior

Each scalar component uses the normalized error:

\[
e_n=\frac{|a-r|}{a_\mathrm{scale}+r_\mathrm{tol}|r|}
\]

and passes when \(e_n\leq1\).

Before evaluation, the comparison layer rejects:

- nonfinite actual or reference values;
- duplicate entity/result-position rows;
- unknown Instance, node, or element labels;
- an element-node pair that is not part of the referenced element;
- missing requested components; and
- reference rows that cannot be matched to one FESA result.

The comparison report identifies the quantity, entity key, component,
reference value, actual value, tolerance, and normalized error for every
failure.

## 9. Required tests

### 9.1 Parser and semantic normalization

- A flat deck still produces a valid `Domain`.
- The supplied hierarchical cantilever deck produces an active Domain from its
  single referenced Part.
- Unreferenced Parts do not contribute analysis entities.
- Part and Assembly sets resolve in the correct scope.
- Material definitions declared after the Part resolve correctly.
- Multiple Instances and multiple Assemblies are rejected.
- Translation and rotation data are rejected.
- Missing Part references and wrong Instance names are rejected.
- Unsupported keywords are not silently ignored.
- Omitted transverse-shear data yields \(A_{sy}=A_{sz}=5A/6\) and `SCF=0`.

### 9.2 Reference adapters and comparison

- Existing displacement and reaction CSV files parse after whitespace
  normalization.
- Optional single-Instance columns are handled without weakening multi-scope
  identity checks.
- Synthetic internal-force rows verify all six component mappings.
- Synthetic stress rows verify centroidal \(N/A\) comparison.
- Requested missing files, duplicates, invalid IDs, invalid element-node pairs,
  missing columns, and nonfinite values fail.
- Relative and absolute tolerance behavior is tested near zero and at
  representative scales.
- The current cantilever integration test selects displacement and reaction
  only.

## 10. Phase-plan impact

The existing ten Harness phases remain. Four phases receive revised steps:

- `domain-and-input-skeleton`: add scoped Part/Assembly/single-Instance syntax
  records and minimal normalization.
- `abaqus-subset-completion`: complete scoped set resolution, active-Part
  expansion, no-op directive handling, and transverse-shear defaults.
- `result-contract-completion`: recover and expose element-end internal force
  and centroidal `Sxx` alongside the complete result contract.
- `beam-reference-qualification`: replace metadata-driven discovery with
  explicit comparison requests and use the supplied cantilever displacement
  and reaction files as the initial real reference.

Phase step files must keep parser syntax handling, semantic normalization,
result recovery, CSV adaptation, and numeric comparison in separate
module-bounded steps.

## 11. Completion criteria for this design change

Planning is consistent when:

- PRD, architecture, ADR, detailed implementation plan, and Harness step draft
  describe the same single-Instance scope;
- no planning artifact requires reference metadata;
- the current cantilever reference requires only displacement and reaction;
- element internal-force and centroidal-stress comparison remain mandatory
  implementation work; and
- no document claims support for multiple or transformed Instances in Phase 1.
