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

3D Euler-Bernoulli Beam UEL Research Brief

Metadata

• feature_id: uel-3d-euler-beam
• source_requirement: docs/requirements/uel-3d-euler-beam.md
• status: ready-for-formulation
• owner_agent: research-agent
• date: 2026-06-11

Research Questions

• Abaqus/Standard UEL에서 RHS, AMATRX, SVARS, ENERGY, NDOFEL, NNODE, MCRD, LFLAGS, PROPS, COORDS, U, DU, JPROPS의 책임과 의미는 무엇인가?
• 2-node 3D Euler-Bernoulli beam/frame element의 local stiffness matrix는 어떤 물리 항으로 구성되는가?
• Abaqus user element가 local element stiffness를 제공해야 하는가, global element stiffness를 제공해야 하는가?
• 3D beam local frame은 어떤 orientation reference와 edge case를 가져야 하는가?
• Static UEL에서 RHS residual sign convention은 첫 구현에서 어떻게 해석해야 하는가?
• No-Abaqus verification과 external Abaqus CSV comparison에 적합한 benchmark 후보는 무엇인가?

Source Inventory

id	source_type	title	author_or_org	URL_or_DOI	access_date	reliability_tier	notes
S1	official solver manual	Abaqus 2025 User Subroutines Reference Guide, UEL	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAESUBRefMap/simasub-c-uel.htm	2026-06-11	Tier 1	Publicly accessible Abaqus documentation mirror. If a licensed local SIMULIA help install conflicts, use the licensed install as authoritative.
S2	official solver manual	Abaqus 2025 Analysis User's Guide, User-Defined Elements	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-c-userelem.htm	2026-06-11	Tier 1	Defines user element input, DOF ordering, global-system responsibility, properties, output limits, and loads.
S3	official keyword manual	Abaqus 2025 Keywords Reference, *USER ELEMENT	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-userelement.htm	2026-06-11	Tier 1	Defines TYPE, NODES, COORDINATES, PROPERTIES, I PROPERTIES, VARIABLES, UNSYMM, and active DOF data lines.
S4	official keyword manual	Abaqus 2025 Keywords Reference, *UEL PROPERTY	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-uelproperty.htm	2026-06-11	Tier 1	Defines property values and optional MATERIAL and ORIENTATION parameters.
S5	official solver manual	Abaqus 2025 Conventions	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAEMODRefMap/simamod-c-conventions.htm	2026-06-11	Tier 1	Defines DOF numbers, global coordinate convention, and self-consistent units.
S6	official solver manual	Abaqus Analysis User's Guide Volume IV, Beam element cross-section orientation	Dassault Systemes SIMULIA	Local vault: D:\Obsidian\MultiPhysicsVault\.raw\AbaqusAnalysisUserGuide4\AbaqusAnalysisUserGuide4_031.md	2026-06-11	Tier 1	Used for beam t, n1, n2 orientation facts and edge cases.
S7	textbook	A First Course in the Finite Element Method, 4th ed.	Daryl L. Logan	Local vault source: D:\Obsidian\MultiPhysicsVault\wiki\sources\A-First-Course-in-the-Finite-Element-Method.md	2026-06-11	Tier 2	Used for Euler-Bernoulli beam, torsion, 3D space-frame stiffness, transformation, and analytical benchmark facts.
S8	official verification manual	Abaqus 2025 Verification Guide, UEL	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAEVERRefMap/simaver-c-uel.htm	2026-06-11	Tier 1	Used for verification pattern: compare a user element model against an equivalent native element model and perform extensive checks.

Source-Backed Facts

fact_id	source	fact	downstream relevance
F-ABAQUS-UEL-001	S1	UEL is called for each element of a general user-defined element type when element calculations are required. The subroutine interface includes RHS, AMATRX, SVARS, ENERGY, NDOFEL, NRHS, NSVARS, PROPS, NPROPS, COORDS, MCRD, NNODE, U, DU, V, A, JTYPE, TIME, DTIME, LFLAGS, MLVARX, PNEWDT, JPROPS, NJPROP, and PERIOD.	I/O Definition Agent must preserve the Abaqus ABI signature and argument meanings.
F-ABAQUS-UEL-002	S1	RHS contains the element contribution to right-hand-side vectors. For most nonlinear procedures with NRHS=1, RHS contains the residual vector, described as external forces minus internal forces.	Static residual sign convention must be resolved explicitly before implementation.
F-ABAQUS-UEL-003	S1	AMATRX contains the element contribution to the Jacobian, stiffness, or other matrix requested by LFLAGS. Nonzero entries should be defined even for symmetric matrices.	Beam kernel can form a full 12-by-12 matrix; interface must decide whether UNSYMM is unnecessary for the symmetric linear beam.
F-ABAQUS-UEL-004	S1	SVARS contains user-defined solution-dependent state variables. For general nonlinear steps it is passed in at the start of the increment and normally returned at the end of the increment; for KINC=0 it is output-only.	First static elastic beam does not need state variables, but any diagnostic section forces must be treated as SVARS if output is required.
F-ABAQUS-UEL-005	S1	ENERGY has eight element energy slots, including kinetic energy, elastic strain energy, artificial strain energy, and incremental work done by loads applied within the user element.	First implementation may leave energy out only if the interface contract states that no element energy output is required.
F-ABAQUS-UEL-006	S1	PROPS contains user-defined real property values and JPROPS contains user-defined integer property values. NPROPS and NJPROP are their counts.	E, G, A, Iy, Iz, J, and orientation data need an explicit property mapping in the interface gate.
F-ABAQUS-UEL-007	S1	COORDS(K1,K2) contains the original coordinates of node K2; MCRD is the coordinate dimension available for each node; NNODE is the user-defined number of nodes.	This feature requires NNODE=2 and three coordinates per node for 3D geometry.
F-ABAQUS-UEL-008	S1	U contains total current estimates of nodal variables at the end of the increment; DU contains incremental values for the current increment and RHS column. V and A are defined for implicit dynamics only.	First static implementation should use U for the total displacement/rotation vector and not depend on V or A.
F-ABAQUS-UEL-009	S1	LFLAGS(2)=0 identifies small-displacement analysis and LFLAGS(2)=1 identifies large-displacement analysis. LFLAGS(3)=1 requests both residual and Jacobian, 2 requests stiffness only, 5 requests residual or load vector only, and other values request mass, damping, or perturbation quantities.	First scope should accept small-displacement static paths and explicitly reject or ignore out-of-scope mass, damping, and large-displacement requests.
F-ABAQUS-UEL-010	S1	For static analysis procedure values, Abaqus/Standard requires AMATRX and RHS and applies convergence checks to force residuals for mechanical DOFs.	RHS and AMATRX are mandatory for first static benchmark comparisons.
F-ABAQUS-UEL-011	S1	UEL solution variables are arranged by node and degree of freedom, with all DOFs for the first node followed by all DOFs for the second node.	This supports the requirement DOF order: node 1 U1,U2,U3,UR1,UR2,UR3, then node 2.
F-ABAQUS-UEL-012	S2	Abaqus always works in the global system when passing information to and from a user element; user element stiffness, mass, and related matrices should be defined with respect to global directions at nodes.	The beam local stiffness must be transformed to global coordinates before assigning AMATRX and RHS.
F-ABAQUS-UEL-013	S2, S3	A general user element is introduced with *USER ELEMENT, including TYPE=Un, NODES=n, optional COORDINATES, PROPERTIES, I PROPERTIES, VARIABLES, and UNSYMM. Active DOFs are specified on data lines.	Interface gate must define the exact *USER ELEMENT keyword subset and active DOF lines.
F-ABAQUS-UEL-014	S2, S3	For general user elements, real property count and integer property count are declared on *USER ELEMENT, and property values are provided through *UEL PROPERTY; real values precede integer values on data lines.	PROPS and JPROPS ordering must be documented and tested.
F-ABAQUS-UEL-015	S4	*UEL PROPERTY requires ELSET and can carry property values. Its ORIENTATION parameter exists for Abaqus/Standard and names a local coordinate system for material calculations.	Do not assume ORIENTATION is directly available in plain UEL arguments; I/O Definition Agent must verify whether orientation is encoded through properties, extra nodes, or another approved mechanism.
F-ABAQUS-UEL-016	S5	Abaqus DOFs 1, 2, and 3 are x-, y-, and z-displacement; DOFs 4, 5, and 6 are rotations about x-, y-, and z-axes in radians. Abaqus uses self-consistent units and has no built-in mechanical unit system.	Supports 6-DOF-per-node contract and user-consistent unit requirements.
F-ABAQUS-UEL-017	S6	Abaqus beam cross-section orientation uses a local right-handed t, n1, n2 system; t is tangent from first to second node, and n1 and n2 define section axes.	UEL local frame should use the same first-to-second-node axis convention unless interface work chooses a documented alternative.
F-ABAQUS-UEL-018	S6	For 3D beams, an approximate n1 direction can be defined directly or by an additional off-axis node; the additional node takes precedence; if neither is supplied, the default is (0,0,-1). The actual section axes are orthogonalized after a normal direction is determined.	UEL orientation reference must reject parallel or near-parallel references and must not silently rely on an ambiguous default for validation models.
F-ABAQUS-UEL-019	S2	User-defined element output is limited: general user element stress, strain, or other internal quantities must be stored as solution-dependent state variables, and element output to ODB is not generally supported for user-defined elements.	External CSV comparison should initially focus on nodal U and RF; element section-force comparison requires an explicit SVARS output strategy.
F-BEAM-001	S7	Euler-Bernoulli beam theory assumes plane cross-sections normal to the longitudinal centroidal axis before bending remain plane and normal after bending under small rotations.	Confirms exclusion of Timoshenko shear deformation in first implementation.
F-BEAM-002	S7	A two-node Euler-Bernoulli bending element uses cubic Hermite interpolation for transverse displacement and nodal rotation.	No-Abaqus bending tests can compare against closed-form cubic-displacement beam cases.
F-BEAM-003	S7	The 2D Euler-Bernoulli bending stiffness block for transverse displacement and rotation has the familiar 12EI/L^3, 6EI/L^2, 4EI/L, and 2EI/L terms.	Supplies bending subblocks for both local section axes.
F-BEAM-004	S7	The torsional stiffness for a prismatic bar is proportional to GJ/L; axial stiffness is proportional to EA/L.	Supplies axial and torsional subblocks.
F-BEAM-005	S7	A 3D space-frame beam stiffness is obtained by superposing axial, torsion, bending about local y, and bending about local z submatrices.	Supports the first-scope E, G, A, Iy, Iz, J property set.
F-BEAM-006	S7	A 3D frame element is transformed between local and global coordinates using a block-diagonal transformation matrix built from a 3-by-3 direction-cosine matrix.	Required for global AMATRX and RHS.
F-BEAM-007	S7	When the beam local axis aligns with a global axis used to construct the remaining local axes, special orientation cases can make the frame construction singular or ambiguous.	Orientation negative tests must cover near-parallel reference vectors and axis-aligned elements.
F-VERIFY-001	S8	Abaqus UEL verification examples compare equivalent native-element and user-element meshes; the guide warns that extensive verification is needed for UEL use.	External Abaqus validation should include comparison against an equivalent Abaqus native beam model where the physics and keyword support match.

Local 3D Beam Stiffness Evidence

The following matrix is recorded as source-backed research evidence from S7, not as the final formulation contract. The Formulation Agent must confirm signs, axis labels, and transform convention before implementation.

Local DOF order:

[u1, v1, w1, rx1, ry1, rz1, u2, v2, w2, rx2, ry2, rz2]

Standard 3D Euler-Bernoulli frame stiffness terms:

a  = E*A/L
t  = G*J/L
by = E*Iy
bz = E*Iz

k_local =
[
 [ a,        0,         0,    0,          0,          0, -a,        0,         0,    0,          0,          0],
 [ 0,  12*bz/L^3,       0,    0,          0,   6*bz/L^2,  0, -12*bz/L^3,       0,    0,          0,   6*bz/L^2],
 [ 0,        0,  12*by/L^3,   0,  -6*by/L^2,        0,  0,        0, -12*by/L^3,   0,  -6*by/L^2,        0],
 [ 0,        0,         0,    t,          0,          0,  0,        0,         0,   -t,          0,          0],
 [ 0,        0,  -6*by/L^2,   0,    4*by/L,          0,  0,        0,   6*by/L^2,   0,    2*by/L,          0],
 [ 0,   6*bz/L^2,       0,    0,          0,    4*bz/L,  0,  -6*bz/L^2,       0,    0,          0,    2*bz/L],
 [-a,        0,         0,    0,          0,          0,  a,        0,         0,    0,          0,          0],
 [ 0, -12*bz/L^3,       0,    0,          0,  -6*bz/L^2, 0,  12*bz/L^3,       0,    0,          0,  -6*bz/L^2],
 [ 0,        0, -12*by/L^3,   0,   6*by/L^2,        0,  0,        0,  12*by/L^3,   0,   6*by/L^2,        0],
 [ 0,        0,         0,   -t,          0,          0,  0,        0,         0,    t,          0,          0],
 [ 0,        0,  -6*by/L^2,   0,    2*by/L,          0,  0,        0,   6*by/L^2,   0,    4*by/L,          0],
 [ 0,   6*bz/L^2,       0,    0,          0,    2*bz/L,  0,  -6*bz/L^2,       0,    0,          0,    4*bz/L]
]

Verification notes for this evidence:

• The matrix is symmetric for the linear elastic first scope.
• The axial, torsion, local-y bending, and local-z bending subblocks can be tested independently by selecting displacement vectors that activate one physical mode at a time.
• The final document must define whether the project labels Iy and Iz exactly as S7's local y and z axes or maps them to Abaqus-style n1 and n2 section axes.

Inferences From Facts

inference_id	basis	inference	required downstream check
I-UEL-001	F-ABAQUS-UEL-002, F-ABAQUS-UEL-012	For the first static linear beam with no distributed loads generated inside UEL, externally applied nodal loads are handled by Abaqus outside the subroutine; therefore the element RHS contribution should likely be -K_global * U under the residual definition external minus internal.	I/O Definition Agent must confirm with the Abaqus UEL residual convention and no-Abaqus sign tests.
I-UEL-002	F-ABAQUS-UEL-003, F-BEAM-005, F-BEAM-006	AMATRX should be the global 12-by-12 stiffness matrix T^T k_local T or the equivalent convention selected by the Formulation Agent, not the raw local matrix.	Formulation Agent must define the transform direction and test identity, rotated, and axis-aligned elements.
I-UEL-003	F-ABAQUS-UEL-009, F-ABAQUS-UEL-010	First implementation should respond to LFLAGS(3)=1, 2, and 5 for static use and treat mass/damping request values as out of scope.	Interface contract must define exact behavior for unsupported LFLAGS values, including whether to report an error or return zero contribution.
I-UEL-004	F-ABAQUS-UEL-006, F-ABAQUS-UEL-014, F-ABAQUS-UEL-015	Orientation should be encoded explicitly in project-controlled properties or extra geometry data unless the interface gate proves that a named *ORIENTATION is available to plain UEL in a usable form.	I/O Definition Agent must choose and document one orientation path.
I-UEL-005	F-ABAQUS-UEL-019	External Abaqus CSV comparison should start with nodal displacements and reactions. Element force or section-force CSV comparison should wait until the interface defines SVARS output or another explicit extraction route.	Reference Model Agent must separate initial nodal comparison from optional element-output comparison.
I-BEAM-001	F-BEAM-001, F-BEAM-002, F-BEAM-003	Cantilever tip-load cases are strong no-Abaqus checks because Euler-Bernoulli cubic displacement fields reproduce nodal displacement and rotation exactly for nodal end loads.	Reference Model Agent should include at least one end-load cantilever bending case about each local bending axis.
I-BEAM-002	F-BEAM-004, F-BEAM-005	Pure axial and pure torsion tests can isolate EA/L and GJ/L terms and catch property-ordering mistakes.	Reference Model Agent should include axial extension and torsion-only single-element tests.
I-BEAM-003	F-BEAM-006, F-BEAM-007, F-ABAQUS-UEL-018	A robust orientation algorithm should reject element length near zero and orientation references nearly parallel to the element axis rather than silently normalizing an ill-conditioned cross product.	Numerical Review Agent should set numerical thresholds and negative tests.

Applicability Limits

• linear_or_nonlinear: first implementation is linear static small-displacement only.
• deformation: small displacement and small rotation formulation only; Abaqus finite rotation update behavior is out of scope.
• element_type: two-node 3D beam/frame user element with 6 mechanical DOFs per node.
• material_model: linear elastic section stiffness only; no plasticity, damage, thermal strain, creep, viscoelasticity, or user material library coupling.
• geometry: initially straight prismatic member between two distinct nodes.
• beam_theory: Euler-Bernoulli bending only; shear deformation and shear correction factors are out of scope.
• torsion: Saint-Venant torsion represented by GJ/L; warping torsion and open-section warping DOF 7 are out of scope.
• loads: external nodal forces and moments may be applied by Abaqus; distributed load generation inside UEL is out of scope for first implementation.
• mass_damping: mass, inertia, rotary inertia, Rayleigh damping, and structural damping are out of scope.
• coordinate_system: AMATRX and RHS must be in global nodal DOF coordinates; local beam axes are an internal calculation frame.
• units: Abaqus does not enforce a unit system; all properties and CSV evidence must use self-consistent declared units.
• output: ODB element output for user elements is limited; first external comparison should rely on nodal displacement and reaction CSVs.
• source_limit: public example repositories, forums, and blogs were not used as acceptance evidence for this research step.

Candidate Benchmarks

benchmark_id	source	benchmark_type	physics	target_quantities	artifact_needs	applicability
BM-NOA-AXIAL-001	S7	analytical no-Abaqus	axial extension/compression of a two-node member	local/global stiffness entries, end forces, EA/L response	no-Abaqus driver expected values	Isolates E, A, length, and DOF ordering.
BM-NOA-TORSION-001	S7	analytical no-Abaqus	torsion about local beam axis	torsional stiffness entries, end torques, GJ/L response	no-Abaqus driver expected values	Isolates G, J, and rotational DOFs UR1.
BM-NOA-BEND-Y-001	S7	analytical no-Abaqus	bending in local x-z plane about local y axis	stiffness terms using Iy, tip displacement, tip rotation, local end moments	no-Abaqus driver expected values	Catches Iy sign and axis mapping errors.
BM-NOA-BEND-Z-001	S7	analytical no-Abaqus	bending in local x-y plane about local z axis	stiffness terms using Iz, tip displacement, tip rotation, local end moments	no-Abaqus driver expected values	Catches Iz sign and axis mapping errors.
BM-NOA-RBM-001	S7	no-Abaqus matrix property	unconstrained element rigid-body modes	six near-zero eigenvalues or residual under rigid translations/rotations, matrix symmetry	no-Abaqus linear algebra check	Detects stiffness assembly and coupling mistakes.
BM-NOA-ROT-001	S6, S7	no-Abaqus transformation	arbitrarily oriented 3D beam with nonparallel orientation reference	T orthonormality, K_global=T^T k_local T, transformed residual consistency	no-Abaqus driver expected matrix	Verifies local-to-global transformation and orientation edge cases.
BM-NOA-RHS-001	S1, S2	no-Abaqus residual check	linear static residual under prescribed displacement vector	RHS sign and equality to chosen residual convention	no-Abaqus sign-convention check	Must be RED before implementation if RHS is not implemented.
BM-EXT-UEL-B31-001	S8 plus approved input deck	external Abaqus comparison	straight cantilever UEL versus equivalent native beam model	nodal U, support RF, convergence status, log tails	model.inp, ODB-extracted nodal CSVs, .msg/.dat/.log/.sta tails, metadata	Valid only after user runs Abaqus externally and provides artifacts.
BM-EXT-UEL-ROT-001	S6, S8 plus approved input deck	external Abaqus comparison	rotated straight beam with explicit orientation reference	nodal U, support RF, coordinate labels, units	same external artifact bundle as above	Validates Abaqus-facing orientation and global DOF mapping.

Verification Relevance

• code_verification: no-Abaqus matrix, residual, rigid-body, and transformation checks can verify the element kernel before any production Fortran source changes.
• solution_verification: external Abaqus reference bundles can compare the implemented UEL against native beam behavior and analytical expectations, but only after user-generated artifacts are registered.
• validation: no physical experiment is part of this first scope; this is verification of a linear elastic element formulation, not validation of a real beam test.
• reference_comparison: first comparison should use ODB-extracted nodal displacement and reaction CSV files with explicit units and coordinate labels.

Open Issues

• RHS sign convention should be treated as evidence-backed but not final until the interface contract defines the exact residual sign and no-Abaqus sign test.
• The final orientation input path is unresolved. Options include real properties, integer flags plus real vector values, additional nodes, or an approved Abaqus keyword mechanism if it is actually visible to plain UEL.
• Iy and Iz mapping must be tied to project local axes and not assumed from textbook notation alone.
• Whether ENERGY(2) should be populated for linear static elastic strain energy is unresolved and belongs to the interface/formulation gates.
• Whether any element-level section forces should be stored in SVARS for CSV extraction is unresolved. Initial comparison can proceed with nodal U and RF.
• External benchmark input decks and CSV filenames are not approved in this step.

Downstream Handoff

Formulation Agent

• Use S7 as the primary mathematical source for local 3D beam stiffness, but independently verify sign convention and axis labels for the project DOF order.
• Define the local frame construction from node coordinates and orientation reference, including zero-length and near-parallel thresholds.
• Define K_global, RHS, rigid-body modes, and scale-aware matrix checks without adding shear deformation or nonlinear geometry.

Numerical Review Agent

• Review local stiffness symmetry, rank, six rigid-body modes, conditioning for short/long elements, and orientation singularities.
• Review whether Euler-Bernoulli assumptions are acceptable for the candidate benchmark dimensions.
• Review tolerance scaling for stiffness entries with different units: force/length, moment/radian, and force/radian coupling terms.

I/O Definition Agent

• Define *USER ELEMENT and *UEL PROPERTY keyword subset, including TYPE, NODES=2, active DOFs 1,2,3,4,5,6, COORDINATES, PROPERTIES, I PROPERTIES, VARIABLES, and UNSYMM.
• Define PROPS/JPROPS ordering for E, G, A, Iy, Iz, J, and orientation.
• Define behavior for unsupported LFLAGS requests and invalid properties.
• Define whether SVARS and ENERGY are unused, zeroed, or populated in first scope.

Reference Model Agent

• Include no-Abaqus axial, torsion, two bending, rigid-body, transformation, and residual sign checks before implementation.
• Design external Abaqus comparison against native beam behavior only after an approved input deck and artifact contract exist.
• Keep ODB extraction external and require metadata.json, model.inp, extracted CSVs, and .msg/.dat/.log/.sta tail files.

Implementation Planning Agent

• Do not write production Fortran until no-Abaqus RED evidence exists.
• Plan a thin Abaqus UEL wrapper around a testable local/global beam stiffness and residual kernel.
• Keep public example repositories out of acceptance evidence unless license, version, provenance, and generated artifacts are documented later.