FESADev/docs/requirements/euler-beam-3d.md

3D Euler-Bernoulli Beam Kernel Requirements

Metadata

• feature_id: euler-beam-3d
• title: Kernel-first 3D Euler-Bernoulli beam element
• status: draft
• owner_agent: requirement-agent
• date: 2026-06-12

Purpose

Define the first implementable requirements baseline for a two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element kernel. This increment is limited to element-level stiffness and end-force recovery so downstream formulation, numerical review, and C++ implementation can proceed without claiming full solver readiness.

Assumptions

• The element is a two-node straight beam with nonzero length.
• The element uses small-displacement, small-rotation, linear elastic kinematics.
• Each node has six mechanical DOFs in this order: ux, uy, uz, rx, ry, rz.
• The element displacement vector order is node 1 DOFs followed by node 2 DOFs, each in ux, uy, uz, rx, ry, rz order.
• Section and material constants are constant over the element: E, G, A, J, Iy, Iz.
• Iy and Iz are second moments of area about the element local principal bending axes, and J is the torsional constant about the local beam axis.
• Units are user-consistent; the kernel does not perform unit conversion in this increment.
• The local element basis is right-handed and orthonormal. The local x axis follows node 1 to node 2; the source of local y and z orientation for parser or solver integration remains open.
• Boundary conditions, global equation numbering, sparse assembly, linear solve, HDF5 writing, and reference comparison are downstream solver concerns, not kernel responsibilities in this increment.

In Scope

• Two-node, straight, prismatic 3D Euler-Bernoulli beam element kernel.
• Six mechanical DOFs per node in ux, uy, uz, rx, ry, rz order.
• Linear elastic section constants: E, G, A, J, Iy, Iz.
• Local 12x12 stiffness matrix support.
• Global 12x12 stiffness matrix support when a valid local-to-global transformation is supplied.
• Local and global element end-force recovery from compatible 12-entry nodal displacement vectors.
• Kernel-level verification hooks for stiffness symmetry, rigid body modes, and local/global transformation consistency.

Out Of Scope

• Shear deformation, Timoshenko beam behavior, shear correction factors, and shear locking treatment.
• Warping DOFs, warping stiffness, restrained warping, or bimoment recovery.
• End releases, offsets, rigid links, eccentric sections, or joint constraints.
• Distributed loads, equivalent nodal load vectors, body forces, or pressure loads.
• Mass matrix, damping matrix, geometric stiffness, buckling, nonlinear kinematics, dynamics, or thermal coupling.
• Abaqus reference CSV generation or modification.
• Full Abaqus compatibility claims.
• Parser integration, end-to-end assembly, solver execution, HDF5 result output, reference comparison, physics sanity, or release readiness.

Analysis Definition

• analysis_type: linear static kernel only
• element_type: two-node 3D Euler-Bernoulli beam
• nodes_per_element: 2
• dofs_per_node: 6
• dof_order: ux, uy, uz, rx, ry, rz
• element_vector_size: 12
• material_model: linear elastic constants E and G
• section_model: constant section constants A, J, Iy, Iz
• coordinate_system: local Cartesian beam frame and global Cartesian frame
• loads: not in this increment
• boundary_conditions: not in this increment
• official_solver_output: not in this increment

Input Requirements

• The kernel must receive or derive two distinct node positions sufficient to determine element length and local x direction.
• The kernel must receive positive finite constants for E, G, A, J, Iy, and Iz.
• The kernel must receive a valid right-handed orthonormal local basis or equivalent transformation data before producing a global stiffness matrix or global end-force vector.
• The kernel must receive 12-entry nodal displacement vectors ordered as node 1 then node 2, with each node using ux, uy, uz, rx, ry, rz.

Output Requirements

• The kernel must produce a local 12x12 stiffness matrix in the documented element DOF order.
• The kernel must produce a global 12x12 stiffness matrix in the documented global DOF order when supplied with a valid local-to-global transformation.
• The kernel must recover local element end forces from a compatible local nodal displacement vector.
• The kernel must recover global element end forces from a compatible global nodal displacement vector when supplied with the same transformation used for the global stiffness matrix.
• This increment must not write results.h5 and must not create deterministic CSV views or Abaqus reference CSV files.

Verification Quantities

quantity	required_for_kernel	verification intent	downstream owner
displacement DOFs	yes	Confirm 12-entry vectors use the required ux, uy, uz, rx, ry, rz per-node ordering.	Implementation Planning Agent
reactions / end forces	yes	Confirm local and global end-force recovery is consistent with the corresponding stiffness matrix and displacement vector.	Formulation Agent; Implementation Planning Agent
stiffness symmetry	yes	Confirm local and global 12x12 stiffness matrices are symmetric within the formulation-defined numeric tolerance.	Numerical Review Agent; Implementation Planning Agent
rigid body modes	yes	Confirm an unconstrained isolated element has six zero-energy rigid body modes within the formulation-defined numeric tolerance.	Formulation Agent; Numerical Review Agent
local/global transformation consistency	yes	Confirm transformed stiffness and force recovery are mutually consistent for the same basis and displacement vector.	Formulation Agent; Implementation Planning Agent
stress	no	Stress recovery is not part of this kernel increment.	Future requirements
strain	no	Strain recovery is not part of this kernel increment.	Future requirements
energy or residual	downstream hook	Strain energy consistency may be added as a kernel verification hook after formulation review.	Numerical Review Agent

Tolerance Policy

• absolute_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent
• relative_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent
• norm_based_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent
• Units: user-consistent structural units; no unit conversion in this increment.
• Coordinate system: local and global Cartesian frames with a right-handed orthonormal element basis.
• Rule: any numerical kernel test added later must state the tolerance source and whether it checks component-wise values, matrix norms, eigenvalue/residual norms, or force vector norms.

Reference Artifact Requirements

Reference artifacts are not required for kernel completion in this increment.

Future end-to-end solver verification may use a bundle under reference/<model-id>/, but this requirements baseline does not authorize creating, modifying, or regenerating Abaqus reference CSV files.

artifact	kernel increment status	future solver-release status
model.inp	not required	required after parser and assembly scope is approved
metadata.json	not required	required with provenance for approved reference artifacts
<model-id>_displacements.csv	not required	required for reference comparison
<model-id>_reactions.csv	not required	required for reaction/end-force comparison
<model-id>_internalforces.csv	not required	required when internal force comparison scope is approved
<model-id>_stresses.csv	not required	not required until stress recovery is in scope

Must Requirements

id	requirement
EB3D-REQ-001	The beam kernel must model only a two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element in this increment.
EB3D-REQ-002	The beam kernel must use six mechanical DOFs per node ordered as ux, uy, uz, rx, ry, rz.
EB3D-REQ-003	The beam kernel must use a 12-entry element vector ordered as all node 1 DOFs followed by all node 2 DOFs.
EB3D-REQ-004	The beam kernel must accept linear elastic constants E and G and section constants A, J, Iy, and Iz.
EB3D-REQ-005	The beam kernel must produce a local 12x12 stiffness matrix in the documented local DOF order.
EB3D-REQ-006	The beam kernel must produce a global 12x12 stiffness matrix when supplied with a valid right-handed orthonormal local-to-global transformation.
EB3D-REQ-007	The beam kernel must recover local element end forces from a compatible local nodal displacement vector.
EB3D-REQ-008	The beam kernel must recover global element end forces from a compatible global nodal displacement vector and the same transformation convention used for global stiffness.
EB3D-REQ-009	The local and global stiffness matrices must be symmetric within the formulation-defined tolerance.
EB3D-REQ-010	The unconstrained isolated element stiffness must preserve six rigid body modes within the formulation-defined tolerance.
EB3D-REQ-011	The local and global stiffness and end-force recovery paths must be mutually consistent under the same transformation.
EB3D-REQ-012	The kernel increment must not include shear deformation, warping, end releases, offsets, distributed loads, mass matrix, geometric stiffness, nonlinear kinematics, dynamics, or thermal coupling.
EB3D-REQ-013	The kernel increment must not create, modify, or regenerate Abaqus reference CSV files.
EB3D-REQ-014	The requirements and downstream implementation must not claim full Abaqus compatibility for this feature.
EB3D-REQ-015	The kernel completion criteria must be separate from full solver release readiness.

Requirement Verification Matrix

id	source	priority	verification_method	acceptance_criteria	tolerance	downstream_agents	status
EB3D-REQ-001	user step scope	must	formulation review; C++ unit tests in later implementation steps	Formulation and implementation address only the scoped Euler-Bernoulli beam kernel and do not add excluded behaviors.	not numeric	Formulation Agent; Implementation Planning Agent	draft
EB3D-REQ-002	user step scope	must	unit test; code review	Tests or implementation checks demonstrate the exact per-node DOF order ux, uy, uz, rx, ry, rz.	not numeric	Implementation Planning Agent	draft
EB3D-REQ-003	user step scope	must	unit test; code review	Tests or implementation checks demonstrate the 12-entry node 1 then node 2 vector order.	not numeric	Implementation Planning Agent	draft
EB3D-REQ-004	user step scope	must	input validation test in later implementation steps	Nonpositive or nonfinite constants are rejected or diagnosed according to the downstream implementation contract.	not numeric for this baseline	I/O Definition Agent; Implementation Planning Agent	draft
EB3D-REQ-005	user step scope	must	formulation review; local stiffness unit test	Local stiffness is 12x12, uses the documented local DOF order, and matches formulation-specified benchmark values.	formulation-defined	Formulation Agent; Numerical Review Agent; Implementation Planning Agent	draft
EB3D-REQ-006	user step scope	must	transformation unit test	Global stiffness is 12x12 and matches the formulation-specified transformation of the local matrix.	formulation-defined	Formulation Agent; Implementation Planning Agent	draft
EB3D-REQ-007	user step scope	must	local force recovery unit test	Local end-force output is consistent with the local stiffness matrix and local displacement vector.	formulation-defined	Formulation Agent; Implementation Planning Agent	draft
EB3D-REQ-008	user step scope	must	global force recovery unit test	Global end-force output is consistent with global stiffness, global displacement, and the local/global transformation convention.	formulation-defined	Formulation Agent; Implementation Planning Agent	draft
EB3D-REQ-009	user verification notes	must	matrix symmetry unit test	Local and global stiffness matrices satisfy symmetry checks within the selected matrix tolerance.	needs-downstream-decision	Numerical Review Agent; Implementation Planning Agent	draft
EB3D-REQ-010	user verification notes	must	rigid body mode unit test; numerical review	Six rigid body modes produce zero or tolerance-bounded internal force/energy for an unconstrained isolated element.	needs-downstream-decision	Formulation Agent; Numerical Review Agent	draft
EB3D-REQ-011	user verification notes	must	transformation consistency unit test	Stiffness transformation and end-force transformation use one consistent convention for the same local basis.	formulation-defined	Formulation Agent; Implementation Planning Agent	draft
EB3D-REQ-012	user exclusions	must	scope review; code review	No excluded behavior appears in requirements, formulation, or kernel implementation for this increment.	not numeric	Coordinator Agent; Implementation Planning Agent	draft
EB3D-REQ-013	user forbidden list	must	git diff review	No file under reference/ and no Abaqus reference CSV is created or modified in this increment.	not numeric	Reference Model Agent; Coordinator Agent	draft
EB3D-REQ-014	ADR-003; user verification notes	must	documentation review; I/O contract review	Documentation states this is a limited feature subset and does not claim full Abaqus compatibility.	not numeric	I/O Definition Agent; Coordinator Agent	draft
EB3D-REQ-015	project acceptance gates	must	release gate review	Kernel completion can be marked separately, while full solver release remains blocked until parser, assembly, HDF5 output, reference comparison, physics sanity, and release readiness gates pass.	not numeric	Release Agent; Coordinator Agent	draft

Acceptance Criteria

This Documentation Step

• docs/requirements/euler-beam-3d.md exists and contains metadata, assumptions, non-goals, must requirements, verification quantities, acceptance criteria, and open issues.
• The document does not create source, test, or reference artifact files.
• The document does not claim full Abaqus compatibility.
• Every must requirement has an acceptance criterion or downstream verification hook in the Requirement Verification Matrix.
• The following validation commands pass:

python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py

Kernel Completion

Kernel completion may be claimed only after downstream implementation steps provide C++ tests and implementation evidence for:

• local 12x12 stiffness matrix generation;
• global 12x12 stiffness matrix transformation;
• local and global end-force recovery;
• DOF ordering;
• stiffness symmetry;
• six rigid body modes;
• local/global transformation consistency.

Kernel completion does not require Abaqus reference CSV files, results.h5, parser integration, global sparse assembly, or release readiness.

Full Solver Release Readiness

Full solver release readiness is not in scope for this increment. It requires later evidence for:

• parser and I/O contract approval for the beam feature;
• Domain, AnalysisModel, DofManager, assembly, constraints, solve, and ResultsWriter integration;
• HDF5 result schema coverage;
• approved reference artifacts under reference/<model-id>/;
• FESA results.h5 to Abaqus reference CSV comparison;
• physics sanity review;
• release readiness review with known limitations.

Open Issues

• Parser integration: define the approved Abaqus keyword subset, beam section mapping, orientation input, and unsupported keyword diagnostics before parser work starts.
• Reference artifact availability: no Abaqus reference CSV files are required or generated in this kernel increment; approved reference artifacts are still needed for later solver-level verification.
• Full end-to-end assembly: global sparse assembly, boundary condition application, reaction recovery, solve flow, and HDF5 output are not covered by this kernel baseline.
• Local orientation convention: downstream formulation and I/O contract must define how local y and z axes are supplied, derived, validated, and reported.
• Tolerance values: downstream numerical review must select tolerances for matrix symmetry, rigid body mode residuals, transformation consistency, and force recovery.

Downstream Handoff

Research Agent

• Confirm authoritative Euler-Bernoulli 3D beam references and benchmark cases for stiffness, transformation, and rigid body checks.

Formulation Agent

• Define local stiffness, transformation convention, end-force recovery convention, rigid body mode checks, and edge cases for invalid geometry or constants.

Numerical Review Agent

• Review stiffness symmetry, rank/rigid body modes, sign conventions, transformation convention, conditioning risks, and numerical tolerances.

I/O Definition Agent

• Define future parser and semantic model mapping for beam geometry, section constants, material constants, and local orientation without claiming full Abaqus compatibility.

Reference Model Agent

• Define future reference model bundles only after parser and end-to-end solver scope is approved; do not generate reference CSV files in this increment.

Implementation Planning Agent

• Plan C++ tests before production code for local stiffness, global transformation, end-force recovery, DOF order, symmetry, rigid body modes, and invalid inputs.