# Abaqus Input Subset

## Purpose
This document defines the Abaqus `.inp` subset supported by FESA Phase 1.

FESA aims for strict, explicit compatibility with a small subset rather than partial silent interpretation of the full Abaqus language.

## Source Basis
- Abaqus input files use keyword lines, data lines, and comment lines; keyword and parameter names are case-insensitive, comma-separated, and may use continuation lines: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
- Abaqus sets are a central reference mechanism for nodes and elements: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
- Abaqus shell library documents S4 as a 4-node general-purpose shell and S4R as a reduced-integration shell with hourglass control: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-r-shellgeneral.htm
- Abaqus `*BOUNDARY` direct data lines use node or node set, first DOF, optional last DOF, and optional magnitude: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-boundary.htm
- Abaqus `*CLOAD` data lines use node or node set, DOF, and reference load magnitude: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-cload.htm

## Phase 1 Supported Keywords
| Keyword | Status | FESA Object | Notes |
|---|---|---|---|
| `*Node` | Supported | `Node` | 3D coordinates only |
| `*Element` | Supported | `Element` | `TYPE=S4` maps to `MITC4` |
| `*Nset` | Supported | `NodeSet` | Explicit list and `GENERATE` should be supported |
| `*Elset` | Supported | `ElementSet` | Explicit list and `GENERATE` should be supported |
| `*Material` | Supported | `Material` | `NAME` required |
| `*Elastic` | Supported | `LinearElasticMaterial` | Isotropic `E, nu` only |
| `*Shell Section` | Supported | `ShellProperty` | Homogeneous shell section only |
| `*Boundary` | Supported | `FixBoundaryCondition` | Direct zero-valued constraints |
| `*Cload` | Supported | `NodalLoad` | Concentrated forces/moments |
| `*Step` | Supported | `StepDefinition` | Static linear Phase 1 step |
| `*Static` | Accepted inside `*Step` | `LinearStaticAnalysis` | Optional for Phase 1 |
| `*End Step` | Supported | Step delimiter | Required for explicit step closure |

Unsupported keywords must produce a clear diagnostic unless explicitly listed as ignorable metadata.

## General Parser Rules
FESA parser rules:
- Keyword names and parameter names are case-insensitive.
- Keyword lines start with `*`.
- Comment lines start with `**` and are ignored.
- Data fields are comma-separated.
- Empty trailing fields may be ignored.
- Numeric data may use decimal or scientific notation.
- `D` exponents should be accepted and normalized as `E` exponents.
- Keyword continuation with a trailing comma should be supported for keyword lines.
- Data continuation should be supported only where this document explicitly allows it.
- Abbreviated Abaqus keywords are not supported in Phase 1. Require exact keyword names after case normalization.
- Supported keywords may use only the parameters and flags listed in this document. Unknown parameters and flags are errors, even when the keyword itself is supported.
- Fixed-width data rows for `*Node`, `*Element`, `*Elastic`, `*Shell Section`, `*Boundary`, and `*Cload` must not contain extra non-empty fields beyond the supported form.
- Include files through `INPUT=` are not supported in Phase 1.
- Part/Assembly/Instance syntax is not supported in Phase 1 unless added by ADR.
- Normalized derivative inputs such as `references/quad_02_phase1.inp` may be used for Phase 1 parser and solver tests when the original stored Abaqus file contains unsupported Abaqus/CAE scaffolding.

## Stored Reference Inputs vs Supported Subset
Files under `references/` are allowed to preserve the exact Abaqus input used to generate reference results, even when the file contains features outside the current Phase 1 parser subset.

Rules:
- A stored reference input is not automatically a supported FESA input.
- Unsupported reference features must be documented as compatibility notes.
- Parser implementation must still reject unsupported features until this document and ADRs explicitly add support.
- Test harnesses may use normalized or reduced derivative inputs for Phase 1 parser tests, but must keep the original Abaqus reference artifact unchanged.

Current stored reference notes:
- `references/quad_01.inp` was generated by Abaqus/CAE Learning Edition 2024.
- It uses `TYPE=S4R`, `Part`, `Assembly`, `Instance`, `*Density`, and `NLGEOM=YES`, all of which are outside the current Phase 1 parser/solver subset.
- Its paired `references/quad_01_displacements.csv` is still valid as a stored displacement reference artifact for future compatibility and regression work.
- `references/quad_02.inp` uses `TYPE=S4`, so it targets the Phase 1 MITC4 element formulation, and its paired `references/quad_02_displacements.csv` has the accepted displacement CSV shape.
- `references/quad_02_reactionforces.csv` is a paired Abaqus RF/RM result export for the stored `quad_02` case. It is a reference result artifact and does not change parser scope.
- `quad_02.inp` still uses Abaqus/CAE `Part`, `Assembly`, `Instance`, and `*Density`; it is therefore a stored S4 reference artifact and compatibility decision point, not automatic parser acceptance as-is.
- `references/quad_02_phase1.inp` is the normalized Phase 1-compatible derivative input for `quad_02`. It preserves node ids, element ids/connectivity, S4 element type, elastic material, shell thickness, fixed boundary nodes, load node, and concentrated load while removing `Part/Assembly/Instance`, `*Density`, restart/output request keywords, and unsupported step metadata.

## Labels and Names
Rules:
- Set and material labels are stored case-insensitively by default.
- Preserve the original spelling for diagnostics and result metadata.
- Labels must start with a letter unless quoted.
- Quoted labels may be accepted, but Phase 1 should warn if quoting is required for disambiguation.
- Labels beginning and ending with double underscores are reserved and should be rejected.

## `*Node`
Supported form:

```text
*Node
node_id, x, y, z
```

Rules:
- `node_id` is signed 64-bit integer.
- Coordinates are `double`.
- 2D node definitions are not supported for MITC4.
- Duplicate node ids are an error.
- Node ids need not be contiguous.

## `*Element`
Supported form:

```text
*Element, type=S4, elset=EALL
element_id, n1, n2, n3, n4
```

Rules:
- `TYPE=S4` maps directly to FESA `MITC4`.
- `TYPE=S4R` is not supported in Phase 1. It is reserved for future support.
- Element and node ids are signed 64-bit integers.
- Four node connectivity entries are required.
- Duplicate element ids are an error.
- Missing nodes are an error.
- If `ELSET` is given, the element is added to that element set.
- Element node ordering follows Abaqus shell ordering and determines the positive normal by right-hand rule.

## `*Nset` and `*Elset`
Supported explicit form:

```text
*Nset, nset=FIXED
1, 2, 3, 4
```

Supported generated form:

```text
*Elset, elset=EALL, generate
1, 100, 1
```

Rules:
- Explicit lists may span repeated data lines.
- `GENERATE` means `start, end, increment`.
- The increment must be positive.
- Set references to other sets are not required in Phase 1.
- `UNSORTED` is not required in Phase 1.
- Duplicates should be deduplicated while preserving a deterministic order for diagnostics.
- Missing referenced ids should be reported when the set is consumed by a property, load, or boundary condition.

## `*Material` and `*Elastic`
Supported form:

```text
*Material, name=STEEL
*Elastic
E, nu
```

Rules:
- Only isotropic linear elasticity is supported in Phase 1.
- Temperature dependence, field-variable dependence, orthotropic elasticity, plasticity, density, and damping are unsupported.
- `E` must be positive.
- `nu` must be in a physically meaningful isotropic range. For Phase 1, reject `nu <= -1.0` or `nu >= 0.5`.

## `*Shell Section`
Supported form:

```text
*Shell Section, elset=EALL, material=STEEL
thickness
```

Rules:
- `ELSET` and `MATERIAL` are required.
- Homogeneous single-layer shell sections only.
- Thickness is `double` and must be positive.
- Offsets, composite layups, section integration controls, orientations, temperature-dependent sections, and transverse shear stiffness overrides are unsupported in Phase 1.
- Thermal-stress coupling is a future feature and must not be inferred from Phase 1 section data.

## `*Boundary`
Supported direct form:

```text
*Boundary
node_or_nset, first_dof, last_dof, magnitude
```

Rules:
- `node_or_nset` may be a node id or node set label.
- DOFs are `1..6`.
- If `last_dof` is omitted, constrain only `first_dof`.
- Phase 1 supports zero-valued constraints. Omitted magnitude means zero.
- Nonzero prescribed displacement/rotation is not a Phase 1 requirement.
- Type-format boundary labels such as `PINNED`, `XSYMM`, or `ENCASTRE` are not supported unless later documented.
- Constrained DOFs are eliminated by `DofManager`.

## `*Cload`
Supported form:

```text
*Cload
node_or_nset, dof, magnitude
```

Rules:
- `node_or_nset` may be a node id or node set label.
- DOFs are `1..6`.
- Translational DOFs define concentrated forces.
- Rotational DOFs define concentrated moments.
- `FOLLOWER`, `AMPLITUDE`, `OP=NEW`, file-based loads, buoyancy/drag/inertia loads, and cyclic symmetry loads are unsupported in Phase 1.

## `*Step`, `*Static`, and `*End Step`
Supported form:

```text
*Step, name=Step-1
*Static
*Cload
...
*Boundary
...
*End Step
```

Rules:
- Phase 1 supports linear static steps.
- `NLGEOM` is ignored only if explicitly false or absent. `NLGEOM=YES` must be rejected until nonlinear analysis is implemented.
- Multiple steps may be parsed into `Domain`, but Phase 1 execution may initially support one active static step if documented in implementation steps.
- Step activation should feed `AnalysisModel`.

## Diagnostics
Required parser diagnostics:
- Unknown keyword.
- Unsupported keyword parameter.
- Missing required parameter.
- Duplicate node, element, material, property, or set definition.
- Missing node in element connectivity.
- Missing set used by shell section, boundary, or load.
- Unsupported element type such as `S4R`.
- Unsupported material or shell section mode.
- Invalid DOF number.
- Invalid generated set range.

Diagnostic messages should include file path, line number, keyword, and offending token.

## Minimum Parser Acceptance
Before Phase 1 parser work is considered ready for solver integration:
- Parse `*Node`, `*Element`, `*Nset`, `*Elset`, `*Material`, `*Elastic`, `*Shell Section`, `*Boundary`, `*Cload`, `*Step`, `*Static`, and `*End Step` smoke cases.
- Preserve original labels for diagnostics while resolving labels case-insensitively.
- Accept explicit and `GENERATE` node/element sets.
- Reject `TYPE=S4R` with an unsupported element diagnostic.
- Reject `NLGEOM=YES`.
- Reject unsupported Part/Assembly/Instance and Include syntax.
- Resolve shell section material and element set references.
- Resolve boundary/load node set references.
- Produce line-numbered diagnostics for malformed numeric fields and invalid DOF ids.

## Explicit Non-Goals
- Abaqus `Part`, `Assembly`, `Instance`, and instance-qualified labels.
- `*Include`.
- `S4R`, `S4R5`, `S8R`, triangular shells, solid elements, beam elements.
- Pressure loads.
- RBE2/RBE3.
- Nonzero prescribed displacements.
- Amplitudes.
- Local coordinate transforms.
- Composite shell sections.
- Thermal-stress input.
- Mesh quality diagnostics.