AbaqusSubroutineDev/docs/corrections/uel-3d-euler-beam-uel-abi-correction.md

3D Euler-Bernoulli Beam UEL ABI Correction Report

Metadata

• feature_id: uel-3d-euler-beam
• source_failure_report: docs/abaqus-uel-subroutines-research.md
• source_implementation_report: docs/build-test-reports/uel-3d-euler-beam-green.md
• source_implementation_plan: N/A; correction follows the post-review research findings
• status: corrected-for-build-test
• owner_agent: correction-agent
• date: 2026-06-12

Failure Triage

• classification: upstream-contract plus implementation defect
• first_failed_command: python -m unittest scripts.test_uel_3d_euler_beam_uel; python scripts/validate_fortran.py
• failed_target_or_test: missing Abaqus UEL wrapper; adapter rejected NSVARS=1
• evidence_tail: wrapper source-smoke failed because src/fortran/uel_3d_euler_beam_uel.for was missing; Fortran ABI test failed with actual=6 expected=0 for a valid NSVARS=1 static call
• triage_decision: implementation-owned correction allowed after research clarified the Abaqus manual ABI

Root Cause Summary

• root_cause_type: implementation boundary defect and stale interface policy
• summary: the step 7 code implemented a testable kernel and no-Abaqus adapter, but did not expose the top-level Abaqus SUBROUTINE UEL(...). The adapter also kept the pre-research NSVARS=0 policy, conflicting with the documented *USER ELEMENT, VARIABLES requirement for a positive allocation.
• why_minimal_fix_is_allowed: the correction preserves the existing kernel formulation and only fixes the Abaqus-facing call boundary, state-variable allocation check, and static-procedure LFLAGS validation.

Correction Scope

file	change_type	reason	in_scope
src/fortran/uel_3d_euler_beam_uel.for	source	add fixed-form Abaqus UEL wrapper with manual signature, ABA_PARAM.INC, manual dimensions, adapter call, and fatal XIT path	true
src/fortran/uel_3d_euler_beam_abi_adapter.f90	source	accept NSVARS>=1, use explicit/manual-style array bounds, and validate LFLAGS(1) / LFLAGS(4)	true
src/fortran/uel_3d_euler_beam_kernel.f90	source	add status ids for unsupported LFLAGS(1) and LFLAGS(4)	true
scripts/test_uel_3d_euler_beam_uel.py	test	verify wrapper signature, include, dimensions, adapter call, and fatal path without requiring Abaqus include files	true
tests/test_uel_3d_euler_beam_uel.py	test	expose a related test path for the production-source TDD guard	true
tests/fortran/uel_3d_euler_beam/test_abi_static.f90	test	update valid adapter calls to NSVARS=1 and explicit static LFLAGS values	true
tests/fortran/uel_3d_euler_beam/test_invalid_inputs.f90	test	add NSVARS<1, LFLAGS(1), and LFLAGS(4) diagnostics	true
tests/fortran/test_uel_3d_euler_beam_abi_adapter.f90	test	update source-smoke adapter call to the corrected policy	true
docs/io-definitions/uel-3d-euler-beam.md	documentation	align current interface contract with the implemented Abaqus-facing policy	true
docs/reference-models/uel-3d-euler-beam.md	documentation	align test model and input-deck requirements with VARIABLES=1 and wrapper source-smoke	true

Excluded files:

• reference artifacts: unchanged
• tolerances: unchanged
• formulation matrix/residual equations: unchanged

Verification Evidence

order	command	exit_code	result	evidence
1	python -m unittest scripts.test_uel_3d_euler_beam_uel before implementation	1	RED	failed because src/fortran/uel_3d_euler_beam_uel.for did not exist
2	python scripts/validate_fortran.py before implementation	1	RED	uel_3d_euler_beam_abi_static failed because NSVARS=1 returned UEL3DEB_E006_NSVARS
3	python -m unittest scripts.test_uel_3d_euler_beam_uel after implementation	0	pass	wrapper source-smoke passed
4	python scripts/validate_fortran.py after implementation	0	pass	all six no-Abaqus Fortran manifest executables compiled and passed with Intel ifx
5	python -m unittest discover -s scripts -p "test_*.py"	0	pass	60 Python harness/source-smoke tests passed
6	python scripts/validate_workspace.py	0	pass	reference artifact metadata validation and Fortran validation succeeded
7	git diff --check	0	pass	no whitespace errors; line-ending warnings only

Traceability

requirement_or_finding	corrected_file	acceptance_criterion
C-UEL-001 / C-UEL-002	src/fortran/uel_3d_euler_beam_uel.for	top-level external SUBROUTINE UEL(...) exists with manual ABI arguments
C-UEL-003	src/fortran/uel_3d_euler_beam_uel.for, src/fortran/uel_3d_euler_beam_abi_adapter.f90	Abaqus-facing boundary uses manual dimensions; adapter remains testable
C-UEL-004	src/fortran/uel_3d_euler_beam_abi_adapter.f90, docs/io-definitions/uel-3d-euler-beam.md	valid static adapter calls use NSVARS=1; NSVARS<1 returns UEL3DEB_E006_NSVARS
C-UEL-005	src/fortran/uel_3d_euler_beam_abi_adapter.f90	unsupported LFLAGS(1) and LFLAGS(4) return dedicated diagnostics

Handoff Recommendation

target_agent	reason	required_input
Build/Test Executor Agent	run full workspace validation after correction	this report and command evidence
Reference Verification Agent	update external model expectations to VARIABLES=1 before user-generated Abaqus artifacts are prepared	corrected I/O and reference-model documents
Physics Evaluation Agent	no formulation behavior changed; external CSV physics checks remain pending	future user-provided reference bundles

Stop Condition

• repeated_failure: false
• upstream_ambiguity: false
• reference_artifact_gap: true
• environment_blocker: false
• next_required_decision: user must still provide external Abaqus artifacts before solver-result validation can complete