FESADev/docs/io-definitions/euler-beam-3d-io.md

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/<step>/frames/<frame>/nodal/displacement	<nnode, 6>	float64	component names, units, coordinate system	nodal	Components ux,uy,uz,rx,ry,rz.
reaction	/steps/<step>/frames/<frame>/nodal/reaction	<nnode, 6>	float64	component names, units, coordinate system	nodal	Requires constraints/assembly.
internal force	/steps/<step>/frames/<frame>/element/internal_force	<nelem, 12>	float64	component names, units, coordinate system, element ids	element end	Components match beam local/global recovery contract.
stress	/steps/<step>/frames/<frame>/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/<model-id>/.

Required future CSV mappings:

• <model-id>_displacements.csv: step, frame, node id, ux, uy, uz, and future rotational components if approved for comparison.
• <model-id>_reactions.csv: step, frame, node id, force and moment reaction components.
• <model-id>_internalforces.csv: step, frame, element id, end location, component, value.
• <model-id>_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.