# 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//` - `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//` 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.