11 KiB

Raw Blame History

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:

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:

(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

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:

nodal displacement and rotation;
nodal reaction force and moment;
element-node section force and moment; and
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:

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:

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

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

The canonical component mapping is:

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

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.

11 KiB Raw Blame History