AbaqusSubroutineDev/docs/requirements/uel-3d-euler-beam.md

3D Euler-Bernoulli Beam UEL Requirements

Metadata

• feature_id: uel-3d-euler-beam
• title: 3D Euler-Bernoulli Beam Abaqus/Standard UEL
• status: needs-user-decision
• owner_agent: requirement-agent
• date: 2026-06-11

Purpose

Define a measurable requirements baseline for a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam element implemented as an Abaqus/Standard UEL. This document is the handoff contract for research, formulation, interface definition, no-Abaqus test model design, Fortran implementation planning, and external Abaqus result validation.

In Scope

• Abaqus/Standard UEL entry point for static small-displacement analysis.
• Two-node 3D Euler-Bernoulli beam element with 12 total degrees of freedom.
• Six degrees of freedom per node ordered as U1, U2, U3, UR1, UR2, UR3.
• Linear elastic response with axial, bending about two principal local section axes, and Saint-Venant torsion stiffness.
• Static element stiffness contribution through AMATRX.
• Static internal force or residual contribution through RHS, with exact Abaqus sign convention delegated to the interface contract.
• User-consistent units with no unit conversion inside the element.
• No-Abaqus analytical evidence before any Fortran production source changes.
• External Abaqus artifact evidence based on user-generated ODB-extracted CSV files before solver-result comparison.

Out Of Scope

• Geometric nonlinearity, large rotation, follower loads, and corotational updates.
• Timoshenko shear deformation, shear correction factors, and shear locking mitigation.
• Distributed loads, body forces, pressure loads, point-load handling inside UEL, and load interpolation.
• Mass matrix, damping matrix, modal dynamics, transient dynamics, and density-dependent behavior.
• Thermal strain, plasticity, damage, creep, viscoelasticity, warping torsion, section offset, tapered members, and curved beams.
• Direct ODB parsing or Abaqus job execution from this repository.
• Generated reference CSV, .msg, .dat, .log, or .sta evidence produced by Codex.
• Fortran source, no-Abaqus tests, reference artifacts, or implementation plans in this requirements step.

Analysis Definition

• analysis_type: linear static small-displacement
• Abaqus entry point: UEL
• element_family: two-node 3D Euler-Bernoulli beam
• element_nodes: 2
• total_dofs: 12
• dofs_per_node: 6
• dof_order: node 1 U1, U2, U3, UR1, UR2, UR3, then node 2 U1, U2, U3, UR1, UR2, UR3
• material_model: linear elastic beam section stiffness
• required physical properties: E, G, A, Iy, Iz, J
• density: not required for first implementation; required only if a later approved mass-matrix scope is added
• coordinate_system: global nodal coordinates plus a local beam frame defined by the element axis and an orientation reference
• units: user-consistent force-length unit system; every external CSV used for validation must declare units
• boundary_conditions: defined by downstream no-Abaqus and external reference models
• loads: applied outside the UEL; first-scope UEL does not implement distributed or body load generation

Requirement Decisions

• The first implementation shall require independent E and G values rather than deriving G from E and nu.
• The first implementation shall require A, Iy, Iz, and J as positive section properties.
• The first implementation shall not use density because mass and dynamics are out of scope.
• Element local axis 1 shall be the line from node 1 to node 2.
• A nonparallel orientation reference shall be required to define the remaining local beam axes; the exact Abaqus keyword and property mapping belongs to the I/O Definition Agent.
• RHS sign convention shall be resolved by the I/O Definition Agent against Abaqus UEL residual conventions and then tested by no-Abaqus single-element cases.

Must Requirements

• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-001: The feature shall target Abaqus/Standard UEL only.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-002: The element shall be a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-003: The element shall expose exactly 12 active element degrees of freedom with six degrees of freedom per node.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-004: The element degree-of-freedom ordering shall be U1, U2, U3, UR1, UR2, UR3 at node 1 followed by the same order at node 2.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-005: The first-scope material and section contract shall provide E, G, A, Iy, Iz, and J.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-006: The accepted physical properties shall be finite and strictly positive.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-007: The element orientation contract shall define a valid right-handed local beam frame from the node coordinates and a nonparallel orientation reference.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-008: The element shall provide the static tangent stiffness contribution in AMATRX.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-009: The element shall provide the static internal force or residual contribution in RHS according to the interface contract sign convention.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-010: The first implementation shall exclude mass, damping, distributed load, thermal, nonlinear geometry, plasticity, damage, shear deformation, warping torsion, and section offset behavior.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-011: The implementation shall not require this repository to run Abaqus jobs or parse ODB files.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-012: The implementation shall have no-Abaqus evidence before any Fortran production source is changed.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-013: Solver-result comparison shall require externally generated Abaqus artifacts under references/uel-3d-euler-beam/.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-014: Every external solver-result CSV used for comparison shall include identifiers, component labels, coordinate-system labels, units, and numeric values.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-015: Numerical comparisons shall use explicit absolute and relative tolerances rather than informal pass/fail judgment.
• ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-016: The requirements, research, formulation, interface, test model, implementation, and validation artifacts shall remain separate gate outputs.

Should Requirements

• The no-Abaqus test suite should include independent single-element checks for axial extension, torsion, bending about local y, bending about local z, rigid-body modes, stiffness symmetry, and coordinate transformation.
• External Abaqus reference models should include at least one cantilever-style displacement/reaction check and one rotated-orientation check.
• The interface contract should name the exact PROPS or alternative property mapping only after the orientation convention and RHS sign convention are settled.
• The formulation document should document local-to-global transformation, rigid-body modes, and expected matrix symmetry without changing the requirements scope.

Could Requirements

• A later approved scope could add density and consistent or lumped mass matrix behavior.
• A later approved scope could add distributed load vector generation.
• A later approved scope could add Timoshenko shear deformation as a separate element family or variant.
• A later approved scope could add section offset or warping-torsion behavior after new requirements and validation artifacts are approved.

Input Requirements

• Conceptual physical inputs: E, G, A, Iy, Iz, J, node coordinates, and one orientation reference that is not parallel to the element axis.
• The I/O Definition Agent must define the Abaqus-facing source of these values, including property ordering, keyword support, validation behavior for invalid inputs, and mapping to UEL arguments.
• The requirements step does not approve a final PROPS, JPROPS, COORDS, or PARAMS layout.

Output Requirements

• AMATRX: required for the static stiffness contribution.
• RHS: required for the static internal force or residual contribution.
• SVARS: not required for first implementation unless later interface work identifies a minimal diagnostic need.
• ENERGY: not required for first implementation; if populated later, it requires a separate requirement and verification method.
• ODB-extracted validation outputs: nodal displacement and reaction CSV evidence are required before solver-result comparison.

Verification Quantities

• nodal_displacement: required for external Abaqus reference comparison.
• reaction: required for external Abaqus reference comparison.
• element_internal_force_or_residual: required for no-Abaqus verification; external CSV is optional unless a downstream extraction contract exposes it.
• stiffness_matrix: required for no-Abaqus verification.
• rigid_body_modes: required for no-Abaqus verification.
• stress: not-applicable for first implementation unless a later output recovery contract is approved.
• strain: not-applicable for first implementation unless a later output recovery contract is approved.
• energy_or_residual: residual required for no-Abaqus verification; energy not required for first implementation.

Tolerance Policy

• no_abaqus_stiffness_absolute_tolerance: 1.0e-10 in user-consistent force-length units after nondimensional or scale-aware comparison.
• no_abaqus_stiffness_relative_tolerance: 1.0e-10.
• no_abaqus_vector_absolute_tolerance: 1.0e-10 in user-consistent force or moment units after scale-aware comparison.
• no_abaqus_vector_relative_tolerance: 1.0e-10.
• no_abaqus_symmetry_absolute_tolerance: 1.0e-12 for AMATRX - transpose(AMATRX) after scale-aware normalization.
• external_displacement_absolute_tolerance: 1.0e-8 in declared length units unless the reference model contract justifies a tighter value.
• external_reaction_relative_tolerance: 1.0e-6 for externally generated Abaqus CSV comparison.
• tolerance_owner: Reference Model Agent may tighten or scale these tolerances only by documenting the physical quantity, units, scale, and rationale.

Required No-Abaqus Evidence Before Fortran Production Changes

• A no-Abaqus test or driver must check that the 12-by-12 stiffness matrix has the expected symmetry, rank behavior, and rigid-body null modes for an unconstrained element.
• A no-Abaqus test or driver must check axial stiffness against a closed-form two-node beam expectation.
• A no-Abaqus test or driver must check torsional stiffness against a closed-form two-node beam expectation.
• A no-Abaqus test or driver must check bending response about both local section axes.
• A no-Abaqus test or driver must check at least one rotated element orientation against an independently computed transformation expectation.
• A no-Abaqus test or driver must check that RHS is consistent with the accepted AMATRX and displacement vector sign convention.
• tests/fortran/manifest.json or an approved equivalent no-Abaqus validation entry must exist before production Fortran source is changed.

Required External Abaqus Artifact Evidence Before Solver-Result Comparison

Expected location: references/uel-3d-euler-beam/<model-id>/

• metadata.json: required with schema version, artifact status, Abaqus version, precision, compiler information, entry point list, source file hashes, input file reference, CSV declarations, and extraction provenance.
• model.inp: required.
• job.msg.tail.txt: required.
• job.dat.tail.txt: required.
• job.log.tail.txt: required.
• job.sta.tail.txt: required.
• extracted/*.csv: required for declared comparison quantities.
• result.odb.sha256: optional when the ODB is not stored but provenance needs to identify the source result database.
• Minimum CSV comparison quantities for first external evidence: nodal displacement and reaction at selected nodes for static benchmark models.

Requirement Verification Matrix

id	statement	category	rationale	source	priority	verification_method	acceptance_criteria	tolerance	downstream_agents	status
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-001	The feature shall target Abaqus/Standard UEL only.	scope	Prevents mixed ABI assumptions.	user; step0	must	document-inspection	Requirements, interface, and later source identify UEL as the only entry point.	not-applicable	I/O Definition Agent; Implementation Planning Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-002	The element shall be a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam.	functional	Defines the element family and excludes shear deformation and nonlinear kinematics.	user; step0	must	formulation-review; no-abaqus-tests	Formulation and tests cover axial, torsion, and two bending modes without shear terms or nonlinear update terms.	no-Abaqus relative 1.0e-10 for analytical checks	Research Agent; Formulation Agent; Reference Model Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-003	The element shall expose exactly 12 active element degrees of freedom with six degrees of freedom per node.	interface	Fixes the element topology for UEL assembly.	user; step0	must	interface-review; no-abaqus-tests	Interface contract and tests use NDOFEL=12 and two six-DOF nodes.	not-applicable	I/O Definition Agent; Reference Model Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-004	The element degree-of-freedom ordering shall be U1, U2, U3, UR1, UR2, UR3 at node 1 followed by the same order at node 2.	interface	Prevents stiffness and residual component permutation errors.	user; step0	must	interface-review; no-abaqus-tests	Unit tests or driver checks map all 12 components to the documented order.	exact index match	I/O Definition Agent; Reference Model Agent; Implementation Planning Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-005	The first-scope material and section contract shall provide E, G, A, Iy, Iz, and J.	input	Provides all stiffness scalars needed for linear axial, torsion, and bending response.	user; requirement decision	must	interface-review; no-abaqus-tests	Interface contract defines all six required physical properties and no-Abaqus tests exercise each property.	not-applicable for presence; numerical checks per quantity tolerances	I/O Definition Agent; Reference Model Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-006	The accepted physical properties shall be finite and strictly positive.	input-validation	Prevents singular or nonphysical stiffness definitions.	requirement decision	must	no-abaqus-tests	Invalid zero, negative, NaN, or infinite properties are rejected or reported by the approved interface behavior before matrix assembly.	exact validation outcome	I/O Definition Agent; Reference Model Agent; Implementation Planning Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-007	The element orientation contract shall define a valid right-handed local beam frame from the node coordinates and a nonparallel orientation reference.	orientation	3D bending requires stable local section axes.	requirement decision	must	formulation-review; interface-review; no-abaqus-tests	Formulation and interface define the local frame, reject parallel orientation references, and pass a rotated-orientation test.	no-Abaqus relative 1.0e-10 for transformed stiffness checks	Formulation Agent; I/O Definition Agent; Reference Model Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-008	The element shall provide the static tangent stiffness contribution in AMATRX.	output	AMATRX is the primary static contribution for Abaqus/Standard assembly.	user; step0	must	no-abaqus-tests; external-reference-comparison	No-Abaqus tests match analytical stiffness expectations; external reference models converge and match displacement/reaction evidence.	no-Abaqus relative 1.0e-10; external reaction relative 1.0e-6	Formulation Agent; Reference Model Agent; Implementation Planning Agent; Validation Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-009	The element shall provide the static internal force or residual contribution in RHS according to the interface contract sign convention.	output	Static equilibrium requires a consistent residual vector.	user; step0	must	interface-review; no-abaqus-tests; external-reference-comparison	Interface defines the sign convention; no-Abaqus tests verify consistency with AMATRX and displacement; external models match reactions and displacements.	no-Abaqus vector relative 1.0e-10; external displacement absolute 1.0e-8	I/O Definition Agent; Reference Model Agent; Validation Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-010	The first implementation shall exclude mass, damping, distributed load, thermal, nonlinear geometry, plasticity, damage, shear deformation, warping torsion, and section offset behavior.	non-scope	Keeps the first implementation verifiable and linear.	user; step0	must	document-inspection; source-review	Requirements, formulation, interface, tests, and source contain no approved behavior from the excluded list.	not-applicable	Research Agent; Formulation Agent; Implementation Planning Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-011	The implementation shall not require this repository to run Abaqus jobs or parse ODB files.	validation-boundary	Preserves project architecture and reproducibility.	AGENTS.md; ADR-004	must	workspace-validation; reference-artifact-review	Validation commands use no-Abaqus tests and artifact metadata checks; no repository script is required to run Abaqus or parse ODB.	not-applicable	Reference Model Agent; Validation Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-012	The implementation shall have no-Abaqus evidence before any Fortran production source is changed.	process	Enforces RED -> GREEN -> VERIFY for numerical code.	AGENTS.md; ADR-007	must	manifest-review; validation-command	A no-Abaqus test manifest or approved equivalent exists and fails for expected missing behavior before production source changes.	exact process evidence	Reference Model Agent; Implementation Planning Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-013	Solver-result comparison shall require externally generated Abaqus artifacts under references/uel-3d-euler-beam/.	reference-artifact	Ensures solver evidence has provenance.	AGENTS.md; ADR-006	must	reference-artifact-validation	python scripts/validate_reference_artifacts.py accepts only complete externally generated artifact bundles before comparison.	not-applicable	Reference Model Agent; Validation Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-014	Every external solver-result CSV used for comparison shall include identifiers, component labels, coordinate-system labels, units, and numeric values.	csv-schema	Prevents ambiguous numerical comparison.	ARCHITECTURE.md	must	schema-validation; reference-artifact-review	CSV schema includes step/frame or time, node or element identifier as applicable, component, coordinate system, unit, and value columns.	exact schema match	I/O Definition Agent; Validation Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-015	Numerical comparisons shall use explicit absolute and relative tolerances rather than informal pass/fail judgment.	tolerance	Makes verification reproducible.	requirements skill	must	test-review; validation-review	Test model and validation artifacts name absolute and relative tolerances for each compared quantity.	values in Tolerance Policy unless narrowed by owner	Reference Model Agent; Validation Agent	draft
ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-016	The requirements, research, formulation, interface, test model, implementation, and validation artifacts shall remain separate gate outputs.	process	Avoids mixing unreviewed decisions into implementation.	AGENTS.md; ADR-003	must	document-inspection; workspace-validation	Each downstream phase writes to its own documented artifact family and does not replace requirements with implementation details.	not-applicable	Coordinator Agent; all downstream agents	draft

Open Questions

• Exact Abaqus input keyword subset for assigning UEL properties and orientation: owner I/O Definition Agent.
• Exact PROPS, JPROPS, COORDS, and orientation reference mapping: owner I/O Definition Agent.
• Exact RHS sign convention and treatment of LFLAGS static requests: owner I/O Definition Agent.
• Whether SVARS or ENERGY should carry diagnostics in a later scope: owner Formulation Agent and I/O Definition Agent.
• Exact external benchmark model set and CSV filenames: owner Reference Model Agent.
• Whether any first-scope reference model needs element-level force extraction beyond nodal U and RF: owner Reference Model Agent and Validation Agent.

Downstream Handoff

Research Agent

• Confirm Abaqus/Standard UEL static contribution expectations for RHS, AMATRX, LFLAGS, and required argument semantics.
• Collect reliable references for 3D Euler-Bernoulli beam stiffness, local coordinate construction, and transformation behavior.
• Separate manual-backed facts from implementation inference.

Formulation Agent

• Define the local stiffness matrix, local-to-global transformation, rigid-body mode expectations, and internal force/residual relation without adding out-of-scope physics.
• Define how the right-handed local frame is constructed from node coordinates and orientation reference.
• Identify numerical risks such as near-zero element length or nearly parallel orientation references.

I/O Definition Agent

• Define the exact Abaqus-facing input contract for E, G, A, Iy, Iz, J, coordinates, and orientation.
• Define UEL argument responsibilities, including RHS, AMATRX, SVARS, ENERGY, LFLAGS, tensor/component ordering, units, and validation behavior.
• Define CSV schema requirements for external solver-result comparison.

Reference Model Agent

• Design no-Abaqus tests for axial, torsion, two bending modes, matrix symmetry, rigid-body modes, orientation transformation, and RHS consistency.
• Define required tests/fortran/manifest.json entries or approved equivalent no-Abaqus validation entries before Fortran production changes.
• Define external Abaqus reference artifact bundles under references/uel-3d-euler-beam/<model-id>/ without generating reference CSVs in this repository.

Implementation Planning Agent

• Do not create or modify Fortran production source until no-Abaqus RED evidence exists.
• Keep the Abaqus UEL wrapper thin and isolate testable beam calculations where the approved interface contract permits.
• Use python scripts/validate_fortran.py, python scripts/validate_reference_artifacts.py, and python scripts/validate_workspace.py for VERIFY evidence.