AbaqusSubroutineDev/docs/numerical-reviews/uel-3d-euler-beam.md

3D Euler-Bernoulli Beam UEL Numerical Review

Metadata

• feature_id: uel-3d-euler-beam
• source_requirement: docs/requirements/uel-3d-euler-beam.md
• source_research: docs/research/uel-3d-euler-beam-research.md
• source_formulation: docs/formulations/uel-3d-euler-beam.md
• status: pass-for-interface-definition
• owner_agent: numerical-review-agent
• date: 2026-06-11

Review Verdict

• verdict: pass-for-interface-definition
• implementation_readiness: not blocked by formulation, but not approved for production implementation until the interface and no-Abaqus test-model gates are complete
• reason: The formulation has a complete linear static Euler-Bernoulli beam stiffness, consistent local/global transformation, no persistent state requirement, and explicit numerical validity checks. Remaining open items are Abaqus-facing interface decisions and downstream test-model obligations, not formulation blockers.

Critical Findings

No blocking numerical findings were identified.

No needs-change finding is raised against docs/formulations/uel-3d-euler-beam.md. The items that remain unresolved are already assigned to the I/O Definition Agent or Reference Model Agent.

Finding Register

id	status	review target	finding	required follow-up
NR-001	pass	Local Element Stiffness Matrix	The 12-by-12 local stiffness includes axial EA/L, torsion GJ/L, local 2 bending with E*Iy, and local 3 bending with E*Iz. The matrix is complete for the first-scope linear elastic beam.	Reference Model Agent must test each subblock independently.
NR-002	pass	Local Element Stiffness Matrix	The matrix is symmetric by construction. A scratch numerical check gave maxabs(k-k^T)=0.0 for representative positive properties.	No-Abaqus tests should include scale-aware symmetry checks.
NR-003	pass	Local Element Stiffness Matrix	The free element is positive semidefinite before boundary conditions. A representative eigenvalue check found six small modes and six positive deformational modes; tiny negative values were roundoff scale.	No-Abaqus tests should check six rigid-body modes using a relative threshold tied to the largest stiffness eigenvalue.
NR-004	pass	Primary Variables and DOFs, Local Element Stiffness Matrix	The Iy and Iz association is internally consistent: Iy is bending about local 2 and couples w/th2; Iz is bending about local 3 and couples v/th3. The signs are consistent with th2=-dw/dx and th3=dv/dx.	Test-model gate must include separate local 2 and local 3 bending cases to catch axis swaps.
NR-005	pass	Local Frame and Transformation to Global Coordinates	The transform convention q_local=T*q_global and K_global=T^T*k_local*T is consistent with virtual work and Abaqus global matrix responsibility.	Interface gate must preserve the same ordering for translation and rotation blocks.
NR-006	pass	Local Frame and Transformation to Global Coordinates	The orientation construction gives an orthonormal right-handed frame when the reference vector has a nonzero perpendicular component. Scratch check: maxabs(R*R^T-I)=2.22e-16, det(R)=0.9999999999999998.	Interface gate must define the source and units/meaning of the orientation reference.
NR-007	pass	Local Frame and Transformation to Global Coordinates	Reversed node order is numerically consistent when interpreted with swapped nodal DOF ordering. Scratch check: K_reversed = P^T*K_forward*P to roundoff for a representative element.	Reference Model Agent should include a reversed-node or equivalent orientation permutation test.
NR-008	pass	Element Equations and Residual Convention	RHS=-K_global*U follows the researched Abaqus residual convention external minus internal for no element-generated loads. The formulation correctly keeps exact Abaqus fill behavior assigned to the I/O Definition Agent.	Interface gate must confirm the RHS array fill convention and no-Abaqus tests must lock the sign.
NR-009	pass	AMATRX and RHS Contribution Rules by Supported LFLAGS	The supported LFLAGS(3)=1,2,5 contribution split is numerically coherent for static requests. Unsupported mass, damping, dynamics, and large-displacement paths are explicitly out of scope.	Interface gate must define exact behavior for unsupported requests.
NR-010	pass	Numerical Tolerances and Validity Checks	Zero-length, nonfinite inputs, nonpositive properties, near-parallel orientation, orthonormality, determinant, and symmetry checks are present. The 1.0e-8 near-parallel threshold is conservative enough for first implementation.	Test-model gate must include invalid length, invalid property, zero orientation, and near-parallel orientation negative cases.
NR-011	pass	State Variables, Energy, and Output Recovery	No persistent SVARS are needed for a linear elastic, path-independent static element. Energy expression is correct but not required for first scope.	Interface gate should keep SVARS and ENERGY unused unless it adds an explicit output contract.
NR-012	pass	Mapping and Numerical Integration	Analytical stiffness avoids integration-order and hourglass risks. The straight two-node centerline mapping is adequate for first-scope prismatic members.	Do not introduce reduced numerical integration in implementation planning.

Independent Scratch Checks

The review included a local scratch calculation using representative positive properties, non-axis-aligned coordinates, and a nonparallel orientation reference. This was not committed as a test because step 3 is a documentation-only review gate.

L = 4.69041575982
local_sym = 0.000e+00
global_sym_raw = 7.451e-09
maxabs_K = 5.871224e+07
global_sym_normalized = 1.269e-16
scaled_symmetry_tolerance = 5.871e-05
R_orthonormality_error = 2.220e-16
detR = 0.9999999999999998
eig_small_count = 6
identity_orientation_K_equals_k = 0.000e+00
reversed_node_permuted_diff = 0.000e+00

Interpretation:

• The raw transformed symmetry difference is harmless because it is far below the formulation's scale-aware symmetry tolerance.
• Six near-zero eigenvalues match the expected rigid-body modes for a free two-node 3D beam element.
• The identity-orientation and reversed-node checks support the transformation convention.

Numerical Risk Assessment

risk	assessment	review result
rigid_body_modes	Free element must have six rigid-body modes. Formulation states this, and scratch eigenvalue count supports it.	pass
patch_test	A constant axial strain, constant torsion rate, and constant curvature bending patch are representable by the interpolation. Multi-element patch expectations still need test-model specification.	pass
symmetry	Linear elastic closed-form stiffness and orthonormal transform preserve symmetry to roundoff.	pass
positive_definiteness	Free element is semidefinite; constrained models should become positive definite after removing rigid modes.	pass
hourglass	Not applicable because no reduced integration is used.	pass
shear_locking	Not applicable to this Euler-Bernoulli formulation; shear deformation is excluded. Applicability to deep beams is a modeling-scope risk, not a numerical defect.	pass
volumetric_locking	Not applicable.	pass
distortion	Curved, distorted, or tapered geometry is out of scope. Straight element validity reduces to nonzero length and valid orientation.	pass
singular_jacobian	Zero-length member and near-parallel orientation checks address the relevant singular cases.	pass
conditioning	Very short/long members and extreme property ratios can produce ill-conditioned matrices. The formulation flags this; downstream tests should cover scale-aware thresholds.	pass
convergence	For supported linear static cases, the tangent is constant and exactly consistent with internal force. Convergence risk is mainly interface sign/fill mistakes.	pass

Consistency Checks

check	result	notes
units	pass	EA/L, 12EI/L^3, 6EI/L^2, 4EI/L, and GJ/L have the expected force, force/length, force, moment, and moment/radian roles under self-consistent units.
dimensions	pass	AMATRX is 12-by-12; RHS, U, local force, and residual vectors are length 12.
signs	pass	Bending signs are consistent with th2=-dw/dx and th3=dv/dx; residual sign remains an interface confirmation item.
dof_ordering	pass	Local ordering is consistent with Abaqus six-DOF node order after local/global projection.
coordinate_transforms	pass	q_local=T*q_global, f_global=T^T*f_local, and K_global=T^T*k_local*T preserve virtual work.
matrix_vector_dimensions	pass	All matrix-vector products in the algorithm pseudocode are dimensionally valid.
integration_weights	pass	Analytical closed-form stiffness avoids numerical quadrature ambiguity.
output_locations	pass	External comparison is limited to nodal global U and RF; element force output is deferred until an interface output path exists.
state_update	pass	No history state is needed for path-independent linear elasticity.
consistent_tangent	pass	K_global is the exact derivative of f_int=K_global*U for the first-scope linear static element.

Verification Readiness

Downstream no-Abaqus tests should include:

• BM-NOA-AXIAL-001: axial extension/compression checks for EA/L.
• BM-NOA-TORSION-001: torsion checks for GJ/L.
• BM-NOA-BEND-Y-001: local 2 bending with w/th2 and E*Iy.
• BM-NOA-BEND-Z-001: local 3 bending with v/th3 and E*Iz.
• BM-NOA-RBM-001: six free-element rigid-body modes and matrix symmetry.
• BM-NOA-ROT-001: arbitrary rotated element and identity-orientation transform checks.
• BM-NOA-REVNODE-001: reversed node order or equivalent nodal permutation check.
• BM-NOA-RHS-001: residual sign check for RHS=-K_global*U under the approved interface convention.
• invalid-input tests for zero length, nonfinite coordinates, nonpositive properties, zero orientation reference, and near-parallel orientation reference.

Patch/regression tests should include:

• one-element constant axial strain patch
• one-element pure torsion patch
• cantilever end-force bending about local 2 and local 3
• two-element collinear patch to catch assembly-order or transform mismatches
• rotated cantilever with non-axis-aligned local frame

External Abaqus reference comparison should remain limited to user-generated artifacts:

• nodal displacement U
• support reaction RF
• convergence/log tail evidence
• coordinate-system labels and units in extracted CSVs

No MMS case is required for this first linear structural element; closed-form beam benchmarks and matrix invariants are more direct.

Required Revisions

Formulation Agent

• None.

Research Agent

• None.

I/O Definition Agent

• Confirm the exact Abaqus UEL RHS fill convention for static NRHS=1.
• Define the PROPS/JPROPS or alternate mapping for E, G, A, Iy, Iz, J, and the orientation reference.
• Define the exact behavior for invalid inputs and unsupported LFLAGS requests.
• Define whether ENERGY remains untouched/zeroed or is populated in a later approved scope.
• Keep SVARS unused unless an explicit diagnostic output route is approved.

Reference Model Agent

• Convert the verification readiness list above into no-Abaqus test cases before any production Fortran source changes.
• Define external Abaqus reference bundles only as user-generated model.inp, extracted CSV, tail logs, and metadata under references/uel-3d-euler-beam/<model-id>/.

Downstream Handoff

I/O Definition Agent

The formulation is numerically coherent enough to proceed to interface definition. Preserve the documented local DOF order, Iy/Iz axis mapping, transformation convention, and static residual physics.

Implementation Planning Agent

Do not start production Fortran implementation from this review alone. Implementation planning may use this formulation after the interface contract and no-Abaqus test model plan are complete.

Reference Model Agent

Use the Verification Readiness section as the minimum no-Abaqus regression set. Treat reversed-node behavior and residual sign as required tests, not optional checks.