FESA/docs/ABAQUS_INPUT_SUBSET.md

FESA Phase 1 Abaqus Input Subset

1. Status and scope

This document is the normative input contract for the FESA Phase 1 Abaqus adapter. FESA accepts only the keywords, parameters, scopes, and data forms defined here. It does not implement general Abaqus input syntax, and it never silently ignores an unknown keyword or option.

Two mutually exclusive organizations are supported:

• a flat/orphan mesh whose mesh and set records are in global scope; or
• one or more *PART definitions followed by exactly one *ASSEMBLY that contains exactly one untransformed *INSTANCE of the active Part.

Only the active Part is normalized into Domain. Names and external labels are input identity; generated nonnegative FESA IDs and dense indices are separate. FESA performs no unit conversion.

tests/fixtures/abaqus/contract.tsv is the executable valid/invalid fixture matrix for this document. Its expected diagnostic code and line are part of the contract. A diagnostic for a bad data row points to that row; a keyword, parameter, or scope error points to the keyword row.

2. Common lexical rules

• Input is UTF-8. A UTF-8 BOM is accepted only at the start of the file.
• Blank lines and lines whose first non-whitespace characters are ** are ignored. A comment or blank line does not end the current keyword record.
• Keyword names, parameter names, flag parameters, and the enumerated values named below are ASCII case-insensitive. Entity names are trimmed and then matched exactly.
• Fields are comma-separated and surrounding ASCII whitespace is ignored.
• External node and element labels are positive signed 64-bit integers. DOF numbers are integers 1 through 6. Real fields must be finite.
• A flag parameter has no = value. A valued parameter must have one nonempty value. Duplicate parameters are abaqus.syntax.duplicate_parameter.
• Parameters not listed for a keyword are abaqus.syntax.unsupported_parameter. Unknown keywords, including *INCLUDE, are abaqus.unsupported_keyword.
• A non-comment data line without an open data-bearing keyword is abaqus.syntax.data_without_keyword.

3. Scope and ordering

The parser maintains global, part, assembly, instance, and step scope. *STEP is a global child scope: model-data records already opened in global scope remain model data, while *STATIC, *CLOAD, *RESTART, and *OUTPUT belong to the open Step.

The accepted ordering is:

optional *HEADING and *PREPRINT
flat mesh, or one or more *PART blocks and one *ASSEMBLY block
global materials
optional global model-data *BOUNDARY
one *STEP
  one *STATIC
  optional *BOUNDARY and *CLOAD
  optional no-op *RESTART and *OUTPUT
*END STEP

References are resolved after the complete deck is parsed. A material may therefore follow the Part that uses it, and a nested set may refer to a set declared later in the same scope.

4. Mesh and hierarchy keywords

4.1 *NODE

• Scope: flat global or Part; not Assembly, Instance, or Step.
• Parameters: none.
• Data: one or more label, x, y, z rows, with exactly four nonempty fields.
• Semantics: labels are unique in their mesh scope. Reuse in an inactive Part is allowed because it is a different Part scope.
• Diagnostics: abaqus.syntax.invalid_node_scope, abaqus.semantic.invalid_node_data, abaqus.semantic.duplicate_node_label.

4.2 *ELEMENT

• Scope: flat global or Part.
• Parameters: required TYPE=B31; optional ELSET=<name>; no others.
• Data: one or more element_label, node_1_label, node_2_label rows.
• Semantics: element labels are unique in their mesh scope. Both nodes must exist in that scope. ELSET= adds every row to the named element set and merges with an explicit set of the same name using sorted-unique membership.
• Diagnostics: abaqus.syntax.invalid_element_scope, abaqus.semantic.unsupported_element, abaqus.semantic.invalid_element_data, abaqus.semantic.duplicate_element_label, abaqus.semantic.missing_node.

4.3 Part delimiters

*PART is global-only, requires exactly NAME=<name>, and accepts no data. Part names are unique. *END PART accepts no parameters or data and closes the open Part. Nesting or a mismatched delimiter is invalid.

Diagnostics are abaqus.syntax.invalid_part_scope, abaqus.syntax.unexpected_end_part, abaqus.syntax.unclosed_part, and abaqus.semantic.duplicate_part.

4.4 Assembly delimiters

*ASSEMBLY is global-only, requires exactly NAME=<name>, and accepts no data. Phase 1 accepts exactly one Assembly. *END ASSEMBLY has no parameters or data and closes the open Assembly.

Diagnostics are abaqus.syntax.invalid_assembly_scope, abaqus.syntax.multiple_assemblies, abaqus.syntax.unexpected_end_assembly, and abaqus.syntax.unclosed_assembly.

4.5 Instance delimiters

*INSTANCE is Assembly-only and requires exactly NAME=<name>, PART=<name>. Phase 1 accepts exactly one Instance. No translation or rotation data and no keyword record are allowed inside it. *END INSTANCE has no parameters or data.

Diagnostics are abaqus.syntax.invalid_instance_scope, abaqus.syntax.instance_local_keyword, abaqus.syntax.unexpected_end_instance, abaqus.syntax.unclosed_instance, abaqus.semantic.instance_count, abaqus.semantic.instance_transform, and abaqus.semantic.missing_part. A transform diagnostic points to the first transform data row.

Flat *NODE/*ELEMENT records combined with any Part/Assembly organization are abaqus.semantic.mixed_mesh_organization.

5. Sets

*NSET and *ELSET are allowed in flat global, Part, or Assembly scope.

• Required parameter: respectively NSET=<name> or ELSET=<name>.
• Optional flag: GENERATE.
• Assembly scope additionally requires INSTANCE=<active-instance-name>. INSTANCE= is forbidden in flat global and Part scope.
• Explicit data consists of comma-separated positive labels and/or names of sets of the same kind and scope. Empty trailing fields are ignored.
• GENERATE data consists of exactly one start, end, increment row. All values are positive integers, start <= end, and (end-start) is divisible by increment.
• Repeated declarations of the same set merge. Nested references are resolved independent of declaration order, cycles are rejected, and final membership is deterministic sorted-unique.
• An Assembly set lifts active-Part local labels through its named Instance. It cannot reference an inactive or unknown Instance.

Diagnostics are abaqus.syntax.invalid_set_scope, abaqus.semantic.invalid_generate, abaqus.semantic.set_cycle, abaqus.semantic.missing_set_member, and abaqus.semantic.wrong_instance.

6. Material and Beam section

6.1 *MATERIAL and *ELASTIC

*MATERIAL is global-only, requires exactly NAME=<name>, and has no data. Material names are unique. Its *ELASTIC child is global model data, has no parameters, and has exactly one young_modulus, poisson_ratio row. Young's modulus is finite and positive; Poisson's ratio is finite and satisfies -1 < nu < 0.5. Temperature and field dependencies are not supported.

Diagnostics are abaqus.syntax.invalid_material_scope, abaqus.semantic.duplicate_material, abaqus.semantic.elastic_without_material, abaqus.semantic.missing_elastic, and abaqus.semantic.invalid_elastic_data.

6.2 *BEAM GENERAL SECTION

• Scope: flat global or Part.
• Parameters: required SECTION=GENERAL, ELSET=<name>, and MATERIAL=<name>; no others.
• First data row: exactly A, I_y, I_yz, I_z, J. A, I_y, I_z, and J are finite and positive; I_yz must be finite and exactly zero for Phase 1.
• Second data row: exactly three finite components of the local section-axis reference direction. Model validation rejects a zero direction or one parallel to an assigned element axis.
• The material and set may be declared later, but must resolve. Every active B31 element has exactly one section assignment.

Diagnostics are abaqus.syntax.invalid_section_scope, abaqus.semantic.unsupported_section, abaqus.semantic.invalid_section_data, abaqus.semantic.missing_material, abaqus.semantic.missing_element_set, abaqus.semantic.missing_section, and abaqus.semantic.duplicate_section_assignment.

6.3 *TRANSVERSE SHEAR STIFFNESS

This optional record is in the same flat-global or Part scope as, and must immediately follow, the affected *BEAM GENERAL SECTION. It has no parameters and exactly one K23, K13, SCF data row. K23 and K13 are finite and positive. Phase 1 accepts only numeric SCF=0; omitted/default 0.25, nonzero values, and the Abaqus SCF label are unsupported.

For isotropic G=E/[2(1+nu)], FESA stores A_sy=K23/G and A_sz=K13/G with source input. If this keyword is absent, the semantic mapper stores A_sy=A_sz=5A/6, SCF=0, with source phase1_default.

The data order follows the Abaqus 2024 TRANSVERSE SHEAR STIFFNESS reference; the restriction to numeric zero SCF and the effective-area mapping are FESA Phase 1 decisions.

Diagnostics are abaqus.syntax.invalid_transverse_shear_scope, abaqus.semantic.orphan_transverse_shear, abaqus.semantic.invalid_transverse_shear_data, and abaqus.semantic.nonzero_scf.

7. Linear static step, BC, and load

7.1 *BOUNDARY

*BOUNDARY is allowed as global model data before the Step or inside the sole Step. It has no parameters. Each row is node-or-nset, first_dof[, last_dof[, value]]. last_dof defaults to first_dof; value defaults to zero. The inclusive DOF range is 1 through 6. Repeated identical prescriptions are deduplicated; differing values for one node/DOF are rejected.

Diagnostics are abaqus.syntax.invalid_boundary_scope, abaqus.semantic.invalid_boundary_data, abaqus.semantic.invalid_dof, abaqus.semantic.invalid_dof_range, abaqus.semantic.missing_node_target, and abaqus.semantic.conflicting_boundary.

7.2 *CLOAD

*CLOAD is Step-only and has no parameters. Each row is exactly node-or-nset, dof, magnitude; DOF is 1 through 6 and magnitude is finite. Loads on the same node/DOF are summed in input order after target resolution.

Diagnostics are abaqus.syntax.invalid_cload_scope, abaqus.semantic.invalid_cload_data, abaqus.semantic.invalid_dof, and abaqus.semantic.missing_node_target.

7.3 *STEP, *STATIC, and *END STEP

*STEP is global-only. Optional parameters are NAME=<name> and NLGEOM=NO; omitted name becomes Step-1. Exactly one Step is required. NLGEOM=YES and every other option are unsupported.

Exactly one *STATIC occurs inside the Step. It has no parameters and accepts either no data row or one row of one through four finite positive values initial_increment[, time_period[, minimum_increment[, maximum_increment]]]. The values are accepted as load-step metadata; Phase 1 performs one linear solve.

*END STEP has no parameters or data and closes the Step.

Diagnostics are abaqus.syntax.invalid_step_scope, abaqus.syntax.unexpected_end_step, abaqus.syntax.unclosed_step, abaqus.semantic.step_count, abaqus.semantic.unsupported_step_option, abaqus.semantic.missing_static, and abaqus.semantic.invalid_static_data.

8. Recognized no-op directives

These records are deliberately recognized and do not create Domain entities:

• *HEADING: global-only, no parameters, zero or more text data rows.
• *PREPRINT: global-only, optional ECHO, MODEL, HISTORY, and CONTACT parameters, each with value YES or NO; no data.
• *RESTART: Step-only, optional WRITE flag and optional nonnegative integer FREQUENCY; no data.
• *OUTPUT: Step-only, exactly one FIELD or HISTORY flag and optional VARIABLE=PRESELECT; no data.

Diagnostics are the common unsupported-parameter diagnostic plus abaqus.syntax.invalid_heading_scope, abaqus.syntax.invalid_preprint_scope, abaqus.syntax.invalid_restart_scope, and abaqus.syntax.invalid_output_scope. There is no general no-op or ignore-unknown path.

9. Fixture matrix contract

The tab-separated manifest columns are:

case_id, outcome, fixture, expected_stage, expected_code, expected_line,
node_count, element_count, node_set_count, element_set_count,
prescribed_dof_count, nodal_load_count, shear_source, shear_area_y,
shear_area_z, checked_node_set, checked_element_set

For a valid case, the public parse_deck() and map_deck_to_domain() path must produce a Domain matching every populated expected field. Set checks use name:local-label,.... For an invalid case, that same public path must fail and contain the exact stage, code, and source line in the manifest. Partial decks and test-only semantic construction are not accepted.