AbaqusSubroutineDev/docs/io-definitions/uel-3d-euler-beam.md

3D Euler-Bernoulli Beam UEL I/O Definition

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
• source_numerical_review: docs/numerical-reviews/uel-3d-euler-beam.md
• status: ready-for-reference-model-planning
• owner_agent: io-definition-agent
• date: 2026-06-11

Scope and Compatibility Statement

• input_format: Abaqus input file (.inp) plus Abaqus/Standard UEL call data
• entry_point: Abaqus/Standard UEL
• compatibility: only the keyword, argument, and CSV subset defined here is supported
• solver_execution_policy: Abaqus jobs are run outside this repository by the user
• result_policy: this repository validates externally generated ODB-extracted CSV artifacts and does not parse ODB files

This interface contract deliberately avoids claiming full Abaqus input compatibility. It defines the first-scope two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam UEL only.

Abaqus/Standard UEL ABI Contract

The Abaqus/Standard production wrapper must preserve the manual UEL signature and include convention:

      SUBROUTINE UEL(RHS, AMATRX, SVARS, ENERGY, NDOFEL,
     1 NRHS, NSVARS, PROPS, NPROPS, COORDS, MCRD, NNODE,
     2 U, DU, V, A, JTYPE, TIME, DTIME, KSTEP, KINC, JELEM,
     3 PARAMS, NDLOAD, JDLTYP, ADLMAG, PREDEF, NPREDF,
     4 LFLAGS, MLVARX, DDLMAG, MDLOAD, PNEWDT, JPROPS,
     5 NJPROP, PERIOD)

      INCLUDE 'ABA_PARAM.INC'

      DIMENSION RHS(MLVARX,*), AMATRX(NDOFEL,NDOFEL),
     1 SVARS(*), ENERGY(8), PROPS(*), COORDS(MCRD,NNODE),
     2 U(NDOFEL), DU(MLVARX,*), V(NDOFEL), A(NDOFEL),
     3 TIME(2), PARAMS(*), JDLTYP(MDLOAD,*),
     4 ADLMAG(MDLOAD,*), DDLMAG(MDLOAD,*),
     5 PREDEF(2,NPREDF,NNODE), LFLAGS(*), JPROPS(*)

The wrapper must keep aba_param.inc / ABA_PARAM.INC as an Abaqus/Standard include, not a project-local replacement. The no-Abaqus kernel may use its own pure calculation interface, but that kernel interface is not defined in this document as source layout.

Supported ABI Shape

argument or count	supported value	validation rule
NNODE	2	reject anything else
NDOFEL	12	reject anything else
active DOFs per node	1,2,3,4,5,6	input keyword and kernel vector order must match
MCRD	>= 3	read only COORDS(1:3,1:2)
NPROPS	9	reject anything else
NJPROP	0	first scope uses no integer properties
NSVARS	>= 1	Abaqus *USER ELEMENT state-variable allocation must be positive; first scope leaves allocated SVARS entries unchanged
NRHS	1	reject multi-RHS procedures
MLVARX	>= 12	required for RHS(1:12,1) and DU(1:12,1) addressing
NDLOAD	0	element-generated distributed loads are unsupported
MDLOAD	any Abaqus value	no JDLTYP, ADLMAG, or DDLMAG entries are used because NDLOAD=0 is required
NPREDF	any Abaqus value	predefined fields are ignored; thermal and field coupling are unsupported

Unsupported shape values are fatal input-contract violations. They must not silently produce zero stiffness or zero residual.

DOF Ordering and Kernel Mapping

Abaqus element vector ordering is node-major:

1  node 1 U1
2  node 1 U2
3  node 1 U3
4  node 1 UR1
5  node 1 UR2
6  node 1 UR3
7  node 2 U1
8  node 2 U2
9  node 2 U3
10 node 2 UR1
11 node 2 UR2
12 node 2 UR3

The wrapper passes this global vector order directly to the beam kernel as q_global. The kernel then applies the formulation transform:

q_local = T*q_global
K_global = T^T*k_local*T
RHS = -K_global*q_global

No permutation is allowed between Abaqus U(1:12) and the kernel global vector. The local vector has the same node-major layout after projection to the local frame:

[u1, v1, w1, th1_1, th2_1, th3_1, u2, v2, w2, th1_2, th2_2, th3_2]

PROPS and JPROPS Schema

The first-scope interface uses PROPS only. JPROPS is not used.

index	name	unit	required rule	semantic
PROPS(1)	E	force / length^2	finite and > 0	Young's modulus
PROPS(2)	G	force / length^2	finite and > 0	shear modulus for Saint-Venant torsion
PROPS(3)	A	length^2	finite and > 0	cross-sectional area
PROPS(4)	Iy	length^4	finite and > 0	second moment about local 2; couples local w/th2
PROPS(5)	Iz	length^4	finite and > 0	second moment about local 3; couples local v/th3
PROPS(6)	J	length^4	finite and > 0	Saint-Venant torsion constant
PROPS(7)	a_ref_1	dimensionless direction component	finite	global approximate local 2 reference x-component
PROPS(8)	a_ref_2	dimensionless direction component	finite	global approximate local 2 reference y-component
PROPS(9)	a_ref_3	dimensionless direction component	finite	global approximate local 2 reference z-component

Orientation vector rules:

• a_ref = [PROPS(7), PROPS(8), PROPS(9)] is a global direction vector, not a point coordinate.
• The vector magnitude is arbitrary because the kernel normalizes its projection.
• Reject norm(a_ref) <= 1.0e-12.
• Reject norm(a_ref - dot(a_ref,e1)*e1) / norm(a_ref) <= 1.0e-8, where e1 is the node 1 to node 2 beam axis.
• The accepted local frame is e1 = node1->node2, e2 = normalized projected a_ref, and e3 = cross(e1,e2).

JPROPS policy:

• NJPROP must be 0.
• No integer flags, versions, orientation modes, or diagnostics are accepted in first scope.
• Any future JPROPS use requires a revised interface contract and new tests.

Abaqus Input Keyword Subset

The reference model plan should use this .inp subset.

keyword	support_status	required parameters	mapped concept	notes
*HEADING	supported	none	model title	optional
*NODE	supported	none	node label and global coordinates	at least 3 coordinates per node for UEL geometry
*ELEMENT	supported	TYPE=U1 or the approved user element type, optional ELSET	two-node UEL connectivity	connectivity order defines local axis 1
*ELSET	supported	ELSET	element set	needed for *UEL PROPERTY
*NSET	supported	NSET	node set	recommended for BC/load/output selection
*USER ELEMENT	supported	TYPE=U1, NODES=2, COORDINATES=3, PROPERTIES=9, VARIABLES=1	UEL declaration	omit UNSYMM; omit I PROPERTIES; SVARS(1) is unused
*UEL PROPERTY	supported	ELSET	real property assignment	data order is PROPS(1:9)
*BOUNDARY	supported	standard nodal DOF constraints	essential boundary conditions	DOFs 1-6 allowed
*CLOAD	supported	standard nodal concentrated load	external nodal loads/moments	loads are assembled by Abaqus outside UEL
*STEP	supported	optional NAME	analysis step	static only
*STATIC	supported	default or direct static data	small-displacement static procedure	no dynamics
*OUTPUT	supported	none	output request root	optional but required for external artifacts
*NODE OUTPUT	supported	NSET recommended	nodal CSV extraction source	request U, optional UR, RF/reaction moments as available
*END STEP	supported	none	step terminator	required

Unsupported in first scope:

• *DLOAD, *DSLOAD, body forces, pressure loads, and distributed load generation
• *MASS, density, modal, transient, damping, and dynamic procedures
• *BEAM SECTION, *BEAM GENERAL SECTION, offsets, warping, and native beam section keywords for this UEL
• *ORIENTATION as the source of UEL orientation; use PROPS(7:9) instead
• material model keywords for UEL stiffness; use *UEL PROPERTY real values instead
• nonlinear geometry, follower loads, thermal expansion, predefined field coupling, plasticity, damage, creep, and viscoelastic behavior

Required *USER ELEMENT Shape

The reference input deck should declare the user element with this logical content:

*USER ELEMENT, TYPE=U1, NODES=2, COORDINATES=3, PROPERTIES=9, VARIABLES=1
1, 2, 3, 4, 5, 6

If the final reference model chooses a different TYPE=Un identifier to avoid conflicts, the same NODES, COORDINATES, PROPERTIES, VARIABLES, and active DOF contract still applies.

Required *UEL PROPERTY Data Order

*UEL PROPERTY, ELSET=<uel_element_set>
E, G, A, Iy, Iz, J, a_ref_1, a_ref_2
a_ref_3

Line breaks may follow Abaqus input formatting rules, but the logical property order is fixed.

Subroutine Parameter Contract

parameter	direction	first-scope responsibility
RHS(MLVARX,*)	output	Initialize requested storage to zero every call; for supported residual requests, set RHS(1:12,1) = -K_global*U(1:12).
AMATRX(NDOFEL,NDOFEL)	output	Initialize all 12x12 entries to zero every call; for supported stiffness requests, set all entries to K_global.
SVARS(*)	input/output	unused; require NSVARS>=1 for Abaqus keyword compatibility; do not store diagnostics in first scope.
ENERGY(8)	input/output	set ENERGY(1:8)=0.0 every supported call; do not use as validation evidence in first scope.
NDOFEL	input	must equal 12.
NRHS	input	must equal 1.
NSVARS	input	must be at least 1.
PROPS(*)	input	must contain the 9 real values defined above.
NPROPS	input	must equal 9.
COORDS(MCRD,NNODE)	input	read COORDS(1:3,1) and COORDS(1:3,2) as original global node coordinates.
MCRD	input	must be at least 3.
NNODE	input	must equal 2.
U(NDOFEL)	input	total current nodal DOF estimate; used for static residual.
DU(MLVARX,*)	input	not used for first-scope static residual; may be used only by no-Abaqus tests to confirm it is ignored.
V(NDOFEL)	input	ignored; dynamics out of scope.
A(NDOFEL)	input	ignored; dynamics out of scope.
JTYPE	input	not used except optional diagnostics; element type compatibility is enforced by .inp contract.
TIME(2)	input	ignored for linear static stiffness/residual; may be copied to diagnostics only.
DTIME	input	ignored; no time-step-dependent behavior.
KSTEP, KINC	input	not used in calculations; may be used only for diagnostics.
JELEM	input	element label for diagnostics and traceability.
PARAMS(*)	input	ignored; no dynamic procedure parameters supported.
NDLOAD	input	must equal 0; distributed loads unsupported.
JDLTYP, ADLMAG, DDLMAG, MDLOAD	input	ignored only after confirming NDLOAD=0.
PREDEF, NPREDF	input	ignored; predefined fields unsupported.
LFLAGS(*)	input	used to identify small-displacement static request and requested contribution.
MLVARX	input	must be at least 12.
PNEWDT	input/output	do not modify for valid supported calls; invalid immutable inputs must fail explicitly rather than rely on cutback recovery.
JPROPS(*), NJPROP	input	require NJPROP=0; JPROPS ignored.
PERIOD	input	ignored; not used in static analysis.

Supported LFLAGS Behavior

The first-scope wrapper supports only small-displacement static calls:

• require LFLAGS(2)=0
• support LFLAGS(3)=1, 2, or 5
• require LFLAGS(1)=1 or 2 for static procedure calls
• require LFLAGS(4)=0 for general-step behavior, not perturbation-only output
• require NRHS=1

Contribution rules:

condition	AMATRX	RHS	policy
LFLAGS(3)=1	K_global	-K_global*U	primary static call
LFLAGS(3)=2	K_global	zero	stiffness-only request
LFLAGS(3)=5	zero	-K_global*U	residual-only request
any other LFLAGS(3)	none	none	unsupported fatal diagnostic

Unsupported request examples include mass, damping, dynamics, half-step residuals, perturbation-only behavior, and large-displacement kinematics.

Validation Rules and Diagnostics

Invalid input must be caught before matrix assembly. The implementation may choose the exact Abaqus-compatible fatal-reporting mechanism later, but it must preserve these diagnostic identifiers and meanings in tests or logs where feasible.

id	condition	expected behavior
UEL3DEB-E001	NDOFEL /= 12	fatal unsupported element DOF count
UEL3DEB-E002	NNODE /= 2	fatal unsupported topology
UEL3DEB-E003	MCRD < 3	fatal missing 3D coordinates
UEL3DEB-E004	NPROPS /= 9	fatal wrong real property count
UEL3DEB-E005	NJPROP /= 0	fatal unsupported integer properties
UEL3DEB-E006	NSVARS < 1	fatal missing Abaqus state-variable allocation
UEL3DEB-E007	NRHS /= 1	fatal unsupported RHS count
UEL3DEB-E008	MLVARX < 12	fatal invalid RHS/DU leading dimension
UEL3DEB-E009	any required coordinate, U, or PROPS value is NaN or infinite	fatal nonfinite input
UEL3DEB-E010	E, G, A, Iy, Iz, or J <= 0	fatal nonpositive physical property
UEL3DEB-E011	element length L <= 1.0e-12*max(1,norm(X1),norm(X2))	fatal zero or near-zero element length
UEL3DEB-E012	norm(a_ref) <= 1.0e-12	fatal zero orientation reference
UEL3DEB-E013	norm(a_perp)/norm(a_ref) <= 1.0e-8	fatal near-parallel orientation reference
UEL3DEB-E014	LFLAGS(2) /= 0	fatal unsupported large-displacement or non-small-displacement request
UEL3DEB-E015	unsupported LFLAGS(3)	fatal unsupported contribution request
UEL3DEB-E016	NDLOAD /= 0	fatal unsupported element load input
UEL3DEB-E017	LFLAGS(1) is not 1 or 2	fatal unsupported non-static procedure request
UEL3DEB-E018	LFLAGS(4) /= 0	fatal unsupported perturbation-output request

For valid supported calls, the wrapper should set deterministic outputs for the requested contribution and should not modify PNEWDT.

Thin Wrapper Boundary

The Abaqus ABI wrapper owns:

• preserving the exact UEL signature and ABA_PARAM.INC include
• validating argument counts, dimensions, request flags, and property values
• extracting X1, X2, U(1:12), and PROPS(1:9)
• mapping LFLAGS to requested stiffness/residual operations
• writing AMATRX, RHS, SVARS, ENERGY, and PNEWDT according to this contract
• reporting diagnostics with JELEM, KSTEP, and KINC when available

The no-Abaqus beam kernel conceptually owns:

• local frame construction from X1, X2, and a_ref
• local stiffness matrix assembly
• local-to-global transformation
• internal force and residual calculation
• numerical status reporting for invalid geometry or properties

This document does not prescribe Fortran module names, source files, helper APIs, or data structures.

External CSV Extraction Schema

All CSV files are externally generated from Abaqus results by the user. They must be placed under references/uel-3d-euler-beam/<model-id>/extracted/ and declared in that model's metadata.json.

Required Common Columns

Every comparison CSV row must include:

column	type	rule
step	string	Abaqus step name or stable step index
frame	integer	frame or increment index
time	float	step time or total time used by extraction
instance	string	Abaqus instance name, or ASSEMBLY if not applicable
node_label	integer	Abaqus node label for nodal files
quantity	string	extracted output quantity, for example U, UR, RF, or RM
component	string	component label listed below
coordinate_system	string	must be GLOBAL for first-scope comparison
unit	string	declared user-consistent unit
value	float	numeric extracted value

The CSV schema uses long format, one component per row, to avoid ambiguity between translational and rotational quantities.

nodal_displacements.csv

Required for external solver-result comparison.

Allowed component rows:

quantity	component	unit type	required
U	U1, U2, U3	length	yes
UR	UR1, UR2, UR3	radian	optional unless the reference model compares rotations

Tolerance defaults:

• displacement absolute tolerance: 1.0e-8 in declared length units
• rotation absolute tolerance: 1.0e-8 radians unless the reference model narrows it
• relative tolerance: reference model may add scale-aware relative tolerance when needed

reactions.csv

Required for external solver-result comparison at constrained nodes.

Allowed component rows:

quantity	component	unit type	required
RF	RF1, RF2, RF3	force	yes for constrained translational DOFs
RM	RM1, RM2, RM3	force*length	required when constrained rotational DOFs are part of the benchmark comparison

If the user's Abaqus extraction names rotational reactions differently, metadata.json must map the raw Abaqus variable/component name to the project component labels above.

Tolerance defaults:

• force and moment relative tolerance: 1.0e-6
• absolute tolerance: Reference Model Agent must define a scale-aware floor for each benchmark if the expected reaction can be near zero

Optional Element-Level CSVs

No element force, stress, strain, section force, or energy CSV is required or approved for first-scope external comparison. Such CSVs require a later SVARS or output-recovery contract.

Reference Artifact Metadata Requirements

Each external reference model must include metadata fields sufficient for scripts/validate_reference_artifacts.py plus feature-level declarations:

• feature_id: uel-3d-euler-beam
• Abaqus version and precision
• compiler vendor/name/version used for the user subroutine build, when applicable
• user subroutine source file hashes after implementation exists
• model.inp path and hash
• declared extracted CSV files and their schema version
• ODB extraction provenance, including extraction script name/version if available
• unit declarations for length, force, stress, moment, and rotation
• coordinate system declaration: GLOBAL for nodal comparison CSVs

Open Issues and Downstream Handoff

Reference Model Agent

• Use the keyword subset and property order in this document for model.inp examples.
• Include no-Abaqus tests for exact PROPS(1:9) mapping, NJPROP=0, NSVARS>=1, NDOFEL=12, NNODE=2, and active DOF order.
• Include negative tests for every UEL3DEB-E### validation rule that is practical in the no-Abaqus harness.
• Define benchmark-specific CSV filenames and near-zero absolute reaction tolerances.
• Keep external artifact generation outside this repository.

Implementation Planning Agent

• Preserve the Abaqus UEL signature exactly in the wrapper.
• Keep the wrapper thin and route only validated arrays/scalars to a no-Abaqus beam kernel.
• Implement deterministic zeroing for non-requested AMATRX/RHS in no-Abaqus drivers so tests are stable.
• Do not implement SVARS, ENERGY, distributed loads, dynamics, JPROPS, or *ORIENTATION support in first scope.

Reference Verification Agent

• Validate only externally generated CSVs declared in metadata.
• Match rows by step, frame, instance, node_label, quantity, component, coordinate_system, and unit.
• Reject CSVs with missing units, missing coordinate systems, unsupported component labels, or undeclared files.
• Compare first-scope external results using nodal displacement and reaction CSVs only.