FESADev/docs/io-definitions/abaqus-input-parser-io.md

# Abaqus Input Parser I/O Definition

## Metadata

- feature_id: abaqus-input-parser
- status: ready-for-implementation-planning
- owner_agent: io-definition-agent
- date: 2026-06-12

## Abaqus Input Scope

FESA supports only the Abaqus input keyword subset listed here. This document
does not claim full Abaqus compatibility.

| keyword | support_status | level | required_parameters | mapped_internal_concept | unsupported-case behavior |
| --- | --- | --- | --- | --- | --- |
| `*HEADING` | supported | model | none | model title metadata | accepted; title storage may be deferred |
| `*NODE` | supported | model | none | node id and global coordinates | malformed rows are errors |
| `*ELEMENT` | supported | model | `TYPE` | element id, topology, connectivity | missing/unsupported `TYPE` is an error |
| `*NSET` | supported | model | `NSET` | named node set | missing name is an error |
| `*ELSET` | supported | model | `ELSET` | named element set | missing name is an error |
| `*MATERIAL` | supported | model | `NAME` | material identity | missing name is an error |
| `*ELASTIC` | supported | model | none | linear elastic constants | malformed rows are errors |
| section keyword | supported | model | `ELSET`, `MATERIAL` | property assignment | unsupported section type is an error |
| `*STEP` | supported | history | optional `NAME` | analysis step | malformed parameters are errors |
| `*STATIC` | supported | history | none | static procedure marker | unsupported procedures are errors |
| `*BOUNDARY` | supported | model/history | none | prescribed nodal dof values | malformed rows are errors |
| `*CLOAD` | supported | history | none | concentrated nodal load | malformed rows are errors |
| `*OUTPUT` | supported | history | none | output request root | unsupported options warn or error by context |
| `*NODE OUTPUT` | supported | history | none | nodal output request | unsupported quantities warn or error by context |
| `*ELEMENT OUTPUT` | supported | history | none | element output request | unsupported quantities warn or error by context |

Initial V0 element names are two-node line/bar types only: `T2D2`, `T3D2`,
`C3D2`, and `B31`.

## Syntax Policy

- Keywords and parameter names are case-insensitive.
- Keyword lines begin with `*`.
- Comment lines begin with `**` and are ignored.
- Blank lines are ignored.
- Fields are comma-separated. Leading and trailing whitespace around fields is
  ignored.
- Empty required fields are parse errors.
- Unsupported keywords are errors unless this contract explicitly marks them as
  ignored-with-warning.
- Diagnostics must include severity, a stable code, a human-readable message,
  and enough line context to locate the input row.
- Include files are out of scope for this parser phase.

## Model Data Mapping

- Nodes map an Abaqus node label to a FESA node id and three global coordinate
  components. Missing trailing coordinate components are interpreted as `0.0`
  only when the keyword-specific test documents that behavior.
- Elements map an Abaqus element label, supported element type, and connectivity
  labels to a FESA element. Section assignment supplies material/property
  linkage in a later parser slice.
- Node sets and element sets preserve deterministic membership order.
- Materials map by Abaqus `NAME`. Linear elastic data maps to the semantic
  material contract used by solver implementation.
- Section keywords bind an element set to a material and create the semantic
  property assignment needed by the solver.
- The global coordinate system is assumed. Units are user-consistent and are not
  converted by the parser.

## History Data Mapping

- `*STEP` begins an ordered analysis step. If no name is provided, the parser
  assigns a deterministic step name or id.
- `*STATIC` marks the step as a linear static procedure for V0.
- `*BOUNDARY` maps node id, dof range, and value to prescribed boundary
  conditions.
- `*CLOAD` maps node id, dof component, and magnitude to concentrated loads.
- Output request keywords define requested quantities when semantic storage
  exists; unsupported quantities must not be silently accepted.

## Internal Model Contract

- `Domain` owns model definition data created from the input file.
- Parsed model objects should be treated as immutable after parsing where
  practical.
- `AnalysisStep` owns step-local boundary conditions and loads.
- The parser must not store equation ids on nodes or elements.
- Parser diagnostics are part of the result; callers do not need to inspect
  partial `Domain` state to detect failure.

## Output HDF5 Schema

The parser itself does not write HDF5. Solver output remains authoritative in
`results.h5` and follows the project HDF5 contract:

| quantity | dataset_path | location | component policy |
| --- | --- | --- | --- |
| displacement | `/steps/<step>/frames/<frame>/field_outputs/U` | nodal | `U1`, `U2`, `U3` as applicable |
| reaction | `/steps/<step>/frames/<frame>/field_outputs/RF` | nodal | `RF1`, `RF2`, `RF3` as applicable |
| internal force | `/steps/<step>/frames/<frame>/field_outputs/element_forces` | element | feature-specific |
| stress | `/steps/<step>/frames/<frame>/field_outputs/S` | integration point or element | feature-specific |

Required metadata includes schema version, model id, source input identity,
coordinate system, units policy, solver version, step/frame identity, and row
identity fields.

## FESA HDF5 To Reference CSV Comparison Schema

Reference comparison reads `results.h5` and matches deterministic rows against
Abaqus-generated CSV files under `reference/<model-id>/`. This parser phase does
not generate or modify those reference artifacts.

Common row identity:

- sort order: step, frame, entity id, location, component
- node id and element id are Abaqus labels preserved by the parser
- component names follow the HDF5 component policy

CSV files remain:

- `<model-id>_displacements.csv`
- `<model-id>_reactions.csv`
- `<model-id>_internalforces.csv`
- `<model-id>_stresses.csv`

## Validation Rules

- Duplicate node, element, material, property, set, or step labels are errors.
- Missing references are errors.
- Unsupported keywords are errors unless explicitly documented otherwise.
- Malformed numeric fields are errors.
- Parser unit tests must cover valid subset mapping and invalid subset
  diagnostics before production parser changes.
- Workspace validation remains `python scripts/validate_workspace.py`.

## Downstream Handoff

Implementation planning should split work into mesh keyword parsing,
diagnostics, set/section mapping, material/history mapping, and integration
validation. Reference model work may later use this subset to prepare
`reference/<model-id>/model.inp`, but this phase must not create or modify
Abaqus reference CSV artifacts.