# 3D Euler-Bernoulli Beam I/O Definition ## Metadata - feature_id: euler-beam-3d - source_requirement: docs/requirements/euler-beam-3d.md - source_formulation: docs/formulations/euler-beam-3d-formulation.md - source_numerical_review: docs/numerical-reviews/euler-beam-3d-review.md - source_research: docs/research/euler-beam-3d-research.md - status: ready-for-implementation-planning - owner_agent: io-definition-agent - date: 2026-06-12 ## Abaqus Input Scope - input_format: Abaqus input file (`.inp`) in a future parser integration phase. - compatibility_disclaimer: FESA will support only the keyword subset defined for this feature; full Abaqus compatibility is not claimed. - kernel_increment_status: no parser, HDF5 writer, or reference comparison implementation is included in the current kernel phase. | keyword | support_status | level | required_parameters | mapped_internal_concept | notes | | --- | --- | --- | --- | --- | --- | | `*NODE` | future-supported | model | none | node id and global coordinates | Required for future beam geometry. | | `*ELEMENT` | future-supported | model | `TYPE` | two-node beam topology | Candidate Abaqus-equivalent type: `B31`; exact subset remains future parser work. | | `*MATERIAL` | future-supported | model | `NAME` | material identity | Required before solver integration. | | `*ELASTIC` | future-supported | model | none | `E`, Poisson ratio or `E,G` derivation policy | Future contract must define `G` source. | | beam section keyword | future-supported | model | section assignment | `A`, `J`, `Iy`, `Iz` | Exact Abaqus keyword subset is not implemented in this kernel phase. | | orientation data | future-supported | model | orientation vector | local axis construction | Must define nonparallel orientation vector. | | `*BOUNDARY` | future-supported | history | DOF range | constrained DOFs | DOF numbers `1..6` map to `ux,uy,uz,rx,ry,rz`. | | `*CLOAD` | future-supported | history | node, DOF, magnitude | concentrated load | Distributed loads are out of this kernel increment. | | `*STEP` / procedure | future-supported | history | procedure data | linear static step | Solver integration gate. | | output keywords | future-supported | history | output variables | HDF5 field/history requests | Authoritative output remains `results.h5`. | ## Syntax Policy - case_insensitivity: future parser should treat Abaqus keyword names case-insensitively. - comma_separated_fields: future parser should follow the existing parser subset policy when this feature is integrated. - comment_lines: lines beginning with `**`. - unsupported_keywords: unsupported with a clear diagnostic unless a future I/O contract explicitly marks them ignored-with-warning. - ascii_assumption: input text policy follows the parser project contract. ## Model Data Mapping - nodes: node label and three global Cartesian coordinates. - elements: two node labels and semantic topology `beam2`. - material: linear elastic constants sufficient to obtain `E` and `G`. - section: constants `A`, `J`, `Iy`, `Iz` assigned to the beam element set. - coordinates: global Cartesian coordinates plus a local orientation vector. - units: user-consistent and recorded in future metadata. ## History Data Mapping - boundary_conditions: Abaqus DOF numbers map as `1=ux`, `2=uy`, `3=uz`, `4=rx`, `5=ry`, `6=rz`. - loads: future `*CLOAD` concentrated nodal loads may use the same DOF numbering. - output_requests: future nodal displacement, reaction, and element internal force requests must map to HDF5 datasets. ## Internal Model Contract - element_type: two-node 3D Euler-Bernoulli beam semantic model, not an Abaqus compatibility claim. - connectivity: exactly two distinct nodes. - orientation: nonzero vector not parallel to the beam axis. - section_constants: positive finite `A`, `J`, `Iy`, `Iz`. - material_constants: positive finite `E` and `G`. - unsupported_cases: shear deformation, warping, releases, offsets, distributed loads, mass, geometric stiffness, nonlinear kinematics, dynamics, and thermal coupling. ## Output HDF5 Schema This kernel phase does not write HDF5. Future solver integration should extend authoritative `results.h5` output with: | quantity | dataset_path | shape | dtype | required_attributes | location | notes | | --- | --- | --- | --- | --- | --- | --- | | displacement | `/steps//frames//nodal/displacement` | `` | float64 | component names, units, coordinate system | nodal | Components `ux,uy,uz,rx,ry,rz`. | | reaction | `/steps//frames//nodal/reaction` | `` | float64 | component names, units, coordinate system | nodal | Requires constraints/assembly. | | internal force | `/steps//frames//element/internal_force` | `` | float64 | component names, units, coordinate system, element ids | element end | Components match beam local/global recovery contract. | | stress | `/steps//frames//element/stress` | TBD | float64 | component names, units, location | TBD | Placeholder only; stress recovery is not approved in this kernel increment. | ## FESA HDF5 to Reference CSV Comparison Schema Future reference comparison must read FESA HDF5 rows and compare them to Abaqus-generated CSV files under `reference//`. Required future CSV mappings: - `_displacements.csv`: step, frame, node id, `ux`, `uy`, `uz`, and future rotational components if approved for comparison. - `_reactions.csv`: step, frame, node id, force and moment reaction components. - `_internalforces.csv`: step, frame, element id, end location, component, value. - `_stresses.csv`: not required until stress recovery is approved. ## Validation Rules - Reject elements whose connectivity does not contain exactly two distinct nodes. - Reject missing or nonpositive `E`, `G`, `A`, `J`, `Iy`, or `Iz`. - Reject missing, zero, or parallel orientation vectors when global transform construction is required. - Reject unsupported beam keywords with a clear diagnostic in future parser work. - Do not generate or modify Abaqus reference CSV files in this kernel phase. ## Open Issues and Downstream Handoff ### Reference Model Agent - Future `model.inp` files must stay within the subset documented here or record open parser issues. ### Implementation Planning Agent - Current implementation may add only kernel-level C++ tests and source files. Parser/HDF5 work remains out of scope. ### Reference Verification Agent - Use HDF5 as authoritative FESA output when future reference comparison is implemented.