AbaqusSubroutineDev/docs/abaqus-uel-subroutines-research.md

Abaqus UEL Subroutines Research Brief

Metadata

• feature_id: abaqus-uel-subroutines
• related_feature: uel-3d-euler-beam
• status: ready-for-interface-correction
• owner_agent: research-agent
• date: 2026-06-12

Research Questions

• Abaqus/Standard가 실제로 호출하는 UEL subroutine의 positional ABI는 무엇인가?
• RHS, AMATRX, SVARS, ENERGY, PNEWDT, LFLAGS의 update 책임은 무엇인가?
• *USER ELEMENT와 *UEL PROPERTY가 NDOFEL, NNODE, MCRD, NPROPS, NJPROP, NSVARS에 미치는 영향은 무엇인가?
• 공개 GitHub UEL 예제는 Abaqus-facing wrapper와 testable implementation logic을 어떻게 분리하는가?
• 현재 uel-3d-euler-beam Fortran 구현이 Abaqus UEL 포맷과 맞지 않는 지점은 무엇인가?

Source Inventory

id	source_type	title	author_or_org	URL	access_date	reliability_tier	notes
S1	vendor manual mirror	Abaqus 2016 User Subroutines Reference Guide, user-provided entry URL	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/default.htm?startat=ch01s01asb44.html	2026-06-12	Tier 1 version-specific mirror	The default.htm?startat=... frame URL returned a browser fallback in this environment. The startat=ch01s01asb44.html target is UMAT, not UEL.
S2	vendor manual mirror	Abaqus 2016 User Subroutines Reference Guide, UEL section 1.1.28	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ch01s01asb28.html	2026-06-12	Tier 1 version-specific mirror	Direct 2016 UEL page. Used as the user-requested manual family.
S3	vendor manual mirror	Abaqus 2025 User Subroutines Reference Guide, UEL	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAESUBRefMap/simasub-c-uel.htm	2026-06-12	Tier 1 accessible manual mirror	Used for accessible line-level confirmation of the UEL interface, variables, and LFLAGS. Recheck against the target licensed Abaqus installation before release.
S4	vendor keyword manual mirror	Abaqus 2025 Keywords Reference, *USER ELEMENT	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-userelement.htm	2026-06-12	Tier 1 accessible manual mirror	Defines user element type declaration, active DOF data lines, properties, coordinates, VARIABLES, and UNSYMM.
S5	vendor keyword manual mirror	Abaqus 2025 Keywords Reference, *UEL PROPERTY	Dassault Systemes SIMULIA	https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-uelproperty.htm	2026-06-12	Tier 1 accessible manual mirror	Defines UEL property assignment by ELSET, property data order, and optional ORIENTATION.
S6	vendor analysis manual mirror	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-12	Tier 1 accessible manual mirror	Defines user element invocation, active DOF ordering, and the global-coordinate responsibility of user element matrices.
S7	public example repository	bibekanandadatta/Abaqus-UEL-Elasticity	Bibekananda Datta	https://github.com/bibekanandadatta/Abaqus-UEL-Elasticity	2026-06-12	Tier 3 example repository	Useful implementation-pattern evidence only. The repository is not acceptance evidence for this project.
S8	public example source	src/uel_mech.for	Bibekananda Datta	https://github.com/bibekanandadatta/Abaqus-UEL-Elasticity/blob/main/src/uel_mech.for	2026-06-12	Tier 3 example source	Shows a top-level Abaqus UEL wrapper outside modules, with calculation delegated to modular subroutines.
S9	public example license	LICENSE.md	Bibekananda Datta	https://github.com/bibekanandadatta/Abaqus-UEL-Elasticity/blob/main/LICENSE.md	2026-06-12	Tier 3 license metadata	Source code is under BSD-3-Clause; documentation is CC BY-NC-SA 4.0. Do not copy code without preserving license obligations.

Extracted Facts

fact_id	source	fact	relevance
F-UEL-001	S2, S3	Abaqus/Standard calls an external entry point named UEL for each general user-defined element when element calculations are needed.	A module-only helper subroutine is not enough; the linked user source must export the expected UEL entry point.
F-UEL-002	S2, S3	The manual UEL ABI is positional. The argument order is RHS, AMATRX, SVARS, ENERGY, element counts, real properties, coordinates, nodal solution arrays, element/procedure metadata, load arrays, predefined fields, LFLAGS, dimensions, PNEWDT, integer properties, and PERIOD.	The wrapper must not add extra arguments such as status, and it must not omit manual arguments such as DU, V, A, JTYPE, TIME, PARAMS, load arrays, PREDEF, MDLOAD, or PERIOD.
F-UEL-003	S2, S3	The wrapper convention includes ABA_PARAM.INC and manual dimensions such as RHS(MLVARX,*), AMATRX(NDOFEL,NDOFEL), COORDS(MCRD,NNODE), U(NDOFEL), DU(MLVARX,*), and PREDEF(2,NPREDF,NNODE).	The Abaqus-facing layer should use explicit Abaqus dimensions. Assumed-shape arrays are suitable for no-Abaqus module tests only when an explicit interface exists.
F-UEL-004	S2, S3	RHS is the element contribution to the right-hand-side vectors. In the common single-RHS nonlinear/static path it represents residual force, described as external minus internal force.	For a linear static element with no internally generated external load, the expected element residual contribution remains -K_global * U under the existing contract.
F-UEL-005	S2, S3	AMATRX is the element Jacobian, stiffness, damping, mass, or other matrix requested by LFLAGS. Nonzero terms should be defined even for symmetric matrices.	The beam UEL should fill the full requested 12-by-12 stiffness matrix. UNSYMM is unnecessary for the current symmetric linear scope.
F-UEL-006	S2, S3	SVARS are element solution-dependent state variables. ENERGY has eight element energy slots. PNEWDT can suggest automatic time increment changes.	A first-scope linear beam may ignore these physically, but the Abaqus ABI still passes them and the wrapper must handle their allocated sizes safely.
F-UEL-007	S2, S3	LFLAGS controls procedure and requested contribution. Relevant values include small vs large displacement in LFLAGS(2) and residual/Jacobian, stiffness-only, damping-only, mass-only, residual-only, initial-acceleration, and perturbation-output requests in LFLAGS(3).	The wrapper must branch on LFLAGS rather than always assuming one static request.
F-UEL-008	S3	Static analysis requires AMATRX, RHS, and state variable update where applicable. The static procedure values are documented under LFLAGS(1)=1,2.	The first beam wrapper should at least verify static procedure scope, small displacement, and general-step behavior before filling outputs.
F-UEL-009	S3, S6	UEL solution variables are arranged node-major: all active DOFs for node 1, then all active DOFs for node 2, etc.	The current 12-DOF beam ordering is aligned if the input deck declares active DOFs 1,2,3,4,5,6 once for both nodes.
F-UEL-010	S6	Abaqus passes user element quantities in the global system; user element stiffness and related matrices should be provided with respect to global nodal directions.	Local beam stiffness must be transformed to global coordinates before assigning AMATRX or deriving RHS.
F-UEL-011	S4	A general user element declaration uses *USER ELEMENT with TYPE=Un, NODES, optional COORDINATES, PROPERTIES, I PROPERTIES, UNSYMM, and VARIABLES, followed by active DOF data lines.	The input deck is part of the ABI. The subroutine alone cannot define NDOFEL, NNODE, NPROPS, or active DOFs.
F-UEL-012	S4	For a general user element, VARIABLES declares the number of solution-dependent state variables and must be greater than zero; the default is one.	The existing contract NSVARS=0 / VARIABLES=0 is not consistent with this keyword rule. Use at least one state variable or verify a target-version exception before Abaqus-facing implementation.
F-UEL-013	S5	*UEL PROPERTY requires ELSET; when data lines are used, real property values precede integer property values.	A beam property list such as E, G, A, Iy, Iz, J, a_ref_1, a_ref_2, a_ref_3 is a valid real-property strategy when PROPERTIES=9 and I PROPERTIES=0.
F-UEL-014	S5	*UEL PROPERTY has an ORIENTATION parameter in Abaqus/Standard. The plain UEL argument list does not include an orientation matrix argument.	Do not rely on ORIENTATION being directly visible inside plain UEL unless an Abaqus run proves the intended behavior. Passing orientation through PROPS remains the safer first-scope contract.
F-UEL-015	S7, S8	The example repository describes uel_mech.for as the source implementing the UEL, while the main Abaqus UEL wrapper performs checks and delegates calculations to another subroutine.	This supports the project architecture: external UEL wrapper plus testable kernel/adapter logic.
F-UEL-016	S8	The example source keeps modules and helper subroutines in the same Fortran source path, then defines a top-level SUBROUTINE UEL outside those modules, includes ABA_PARAM.INC, dimensions all Abaqus arrays, initializes outputs, checks LFLAGS, and calls an internal element routine.	The pattern is compatible with Abaqus symbol lookup while preserving modular calculation logic.
F-UEL-017	S9	The example code license permits source redistribution under BSD-3-Clause conditions, while documentation is under CC BY-NC-SA 4.0.	The example can inform design, but this project should not copy source text without license handling.

Minimum Abaqus-Facing UEL Contract

The Abaqus-facing production source must expose a top-level external subroutine named UEL with the manual positional ABI. Local argument names can vary, but the order and shape cannot. For the current 3D beam scope the wrapper should preserve these groups:

group	required UEL arguments
element outputs	RHS, AMATRX, SVARS, ENERGY, PNEWDT
element sizes	NDOFEL, NRHS, NSVARS, NPROPS, MCRD, NNODE, MLVARX, MDLOAD, NJPROP
input arrays	PROPS, COORDS, U, DU, V, A, TIME, PARAMS, JDLTYP, ADLMAG, DDLMAG, PREDEF, LFLAGS, JPROPS
scalar metadata	JTYPE, DTIME, KSTEP, KINC, JELEM, NDLOAD, NPREDF, PERIOD

The wrapper should include ABA_PARAM.INC and use manual-style dimensions for all Abaqus arrays. A no-Abaqus adapter can keep assumed-shape arrays and a status output, but that adapter is not itself an Abaqus-callable UEL.

Minimum Input Deck Contract for the Current Beam

For the first-scope two-node 3D Euler-Bernoulli beam, the research-supported .inp shape is:

keyword	required policy
*USER ELEMENT	use TYPE=Un, NODES=2, COORDINATES=3, PROPERTIES=9, and no UNSYMM for the symmetric linear scope
active DOF data line	declare 1,2,3,4,5,6 so NDOFEL=12 for two nodes
VARIABLES	use at least VARIABLES=1 or omit it and accept the default one state variable; do not assume Abaqus accepts zero without target-version evidence
I PROPERTIES	omit or set to zero for the first scope
*ELEMENT	use the same TYPE=Un; node order defines the positive beam axis from node 1 to node 2
*UEL PROPERTY	provide ELSET and nine real properties in project-defined order

The current project interface document should be corrected before an external Abaqus run if it still says VARIABLES=0 or requires NSVARS=0.

Pattern Observed in uel_mech.for

The GitHub example is useful as a layout pattern, not as a source to copy. The relevant pattern is:

• helper modules are available before the Abaqus entry point is compiled;
• the actual Abaqus entry is a top-level external UEL, not a module procedure;
• the wrapper includes ABA_PARAM.INC and manual array dimensions;
• wrapper code initializes Abaqus output arrays before calculation;
• wrapper code checks procedure flags and element type metadata;
• wrapper code delegates the element formulation to a lower-level routine with any extra internal arguments it wants.

This is the missing layer in the current beam implementation. Our project already has a testable kernel and a no-Abaqus adapter, but it still needs the external UEL wrapper that Abaqus will actually call.

Findings Against Current uel-3d-euler-beam Implementation

finding_id	severity	evidence	impact	recommended follow-up
C-UEL-001	high	rg found no SUBROUTINE UEL in src/fortran; only uel3deb_abi_static is public in src/fortran/uel_3d_euler_beam_abi_adapter.f90.	Abaqus will not call the current implementation as a UEL unless another wrapper is provided at compile/link time.	Add src/fortran/uel_3d_euler_beam_uel.for or equivalent top-level UEL wrapper that calls the existing adapter/kernel.
C-UEL-002	high	uel3deb_abi_static adds a status output and omits many manual UEL arguments.	The adapter is valid for no-Abaqus tests but is not the Abaqus ABI.	Keep it as test adapter; do not present it as production UEL wrapper.
C-UEL-003	high	uel3deb_abi_static uses assumed-shape arrays such as rhs(:, :), amatrx(:, :), and props(:).	Abaqus calls external user subroutines without an explicit Fortran module interface; assumed-shape dummy arguments are the wrong boundary for the top-level ABI.	The top-level wrapper should use manual explicit dimensions and pass slices to a module helper.
C-UEL-004	high	Current interface and adapter require NSVARS=0; Abaqus *USER ELEMENT documentation says VARIABLES must be greater than zero and defaults to one.	An Abaqus input deck using VARIABLES=0 may be rejected before the subroutine runs, or a valid deck may pass NSVARS=1 and be rejected by the adapter.	Revise the Abaqus-facing contract to accept at least NSVARS>=1 while ignoring SVARS(1) unless diagnostics are later approved.
C-UEL-005	medium	Current adapter checks LFLAGS(2) and LFLAGS(3) but not LFLAGS(1) or LFLAGS(4).	Non-static or linear perturbation calls could be mishandled by an Abaqus-facing wrapper if forwarded directly.	Wrapper should reject unsupported procedure/general-step states before kernel execution.
C-UEL-006	medium	Current contract excludes NDLOAD and ignores load arrays, which is acceptable for first scope, but the top-level ABI must still receive JDLTYP, ADLMAG, DDLMAG, and MDLOAD.	Omitting these arguments breaks the manual ABI even if distributed loads are unsupported.	Preserve all manual load arguments and then enforce NDLOAD=0 for first scope.

Inferences and Design Guidance

inference_id	basis	inference	downstream owner
I-UEL-001	F-UEL-001 through F-UEL-003, C-UEL-001	The next implementation correction should add a real Abaqus wrapper, not replace the tested kernel.	Implementation Agent
I-UEL-002	F-UEL-012, C-UEL-004	NSVARS=0 is a no-Abaqus convenience that conflicts with documented Abaqus keyword constraints.	I/O Definition Agent
I-UEL-003	F-UEL-010	The existing kernel's local-to-global matrix transformation remains directionally correct for Abaqus; the problem is the call boundary, not the beam matrix concept.	Formulation Agent
I-UEL-004	F-UEL-014	Passing the orientation reference through PROPS(7:9) remains an acceptable first-scope strategy.	I/O Definition Agent
I-UEL-005	F-UEL-016	A robust wrapper can be fixed-form .for for Abaqus compatibility, while calculation modules may remain .f90 if the Abaqus compile path is made explicit.	Implementation Planning Agent

Corrected Handoff for the 3D Beam UEL

I/O Definition Agent

• Replace VARIABLES=0 / NSVARS=0 with an Abaqus-compatible state-variable allocation policy, likely VARIABLES=1 with unused SVARS(1) for first scope.
• Keep PROPERTIES=9 and I PROPERTIES=0 unless a later orientation or diagnostic mode requires integer properties.
• Define exact behavior for LFLAGS(1) static procedure values and LFLAGS(4) general-step requirement.

Implementation Agent

• Add a top-level external SUBROUTINE UEL(...) wrapper with the manual argument order and ABA_PARAM.INC include.
• Use manual explicit dimensions at the wrapper boundary.
• Call the existing no-Abaqus adapter or a small wrapper helper after mapping Abaqus arrays to the tested kernel inputs.
• Do not add Abaqus-specific logic into the matrix kernel unless tests require it.

Test Model Agent

• Add a source-smoke test that scans the production wrapper for SUBROUTINE UEL, ABA_PARAM.INC, the manual argument groups, and manual array dimensions.
• Update no-Abaqus ABI tests to cover the chosen NSVARS policy.
• Keep external Abaqus execution outside this repository; validation still depends on user-generated CSV and log-tail artifacts.

Numerical Review Agent

• Re-review residual sign only after the actual wrapper maps Abaqus U and RHS arrays.
• Confirm that accepting NSVARS>=1 while leaving state values unchanged has no physical side effect for the linear static beam.

Applicability Limits

• This research did not run Abaqus and did not compile the public GitHub example.
• The accessible 2025 documentation mirror was used for line-level confirmation; final release should be checked against the user's installed Abaqus version and licensed documentation.
• The public GitHub example is Tier 3 evidence. It informs wrapper structure but does not validate this project's beam formulation.
• This document intentionally does not change production Fortran source. It identifies the next correction needed before Abaqus execution evidence can be meaningful.

Open Issues

• Target Abaqus version for external validation remains unspecified.
• Exact wrapper file extension and Abaqus compile path for mixed .for wrapper plus .f90 modules must be decided before implementation.
• The current no-Abaqus tests assume NSVARS=0; they need revision if the production Abaqus wrapper requires NSVARS>=1.
• Whether SVARS(1) should be left unchanged, zeroed, or used as a diagnostic status slot requires an interface decision.