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

Abaqus User Subroutines Research Brief

Metadata

• feature_id: abaqus-user-subroutines
• source_requirement: N/A
• status: draft
• owner_agent: research-agent
• date: 2026-06-08

Research Questions

• Abaqus User Subroutine은 어떤 해석 기능을 확장하며, Standard와 Explicit에서 어떤 subroutine family로 나뉘는가?
• User subroutine 개발 시 고정해야 할 ABI, include, 입력 파일, 상태변수, debug, compile/link 계약은 무엇인가?
• UMAT, VUMAT, UEL, VUEL, USDFLD/VUSDFLD, UVARM, UEXTERNALDB/VEXTERNALDB 중 FESA harness에 우선 반영해야 할 개발/검증 패턴은 무엇인가?
• 현재 C++/MSVC/CMake/CTest 중심 harness를 Abaqus user subroutine 개발에 맞추려면 어떤 gate와 artifact 계약이 필요해지는가?

Source Inventory

source_type	title	author_or_org	URL_or_DOI	access_date	reliability_tier	notes
vendor manual mirror	Abaqus Analysis User's Guide 18.1.1, User subroutines: overview	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/usb/pt04ch18s01aus106.html	2026-06-08	Tier 1, version-specific mirror	Core lifecycle, include, execution, debugging, state variable, vectorization, parallelization rules.
vendor manual mirror	Abaqus User Subroutines Reference Guide A.1, User subroutines index	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ap01s01.html	2026-06-08	Tier 1, version-specific mirror	Categorizes Standard, Explicit, CFD user subroutines by function.
vendor manual mirror	Abaqus User Subroutines Reference Guide A.2, User subroutine functions listing	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ap01s02.html	2026-06-08	Tier 1, version-specific mirror	Defines one-line purpose for each user subroutine.
vendor manual mirror	Abaqus Analysis User's Guide 26.7.1, User-defined mechanical material behavior	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/usb/pt05ch26s07abm69.html	2026-06-08	Tier 1, version-specific mirror	UMAT/VUMAT material behavior, stress/strain conventions, material constants, state variables, deletion, hourglass/shear caveats.
vendor manual mirror	Abaqus User Subroutines Reference Guide 1.1.44, UMAT	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ch01s01asb44.html	2026-06-08	Tier 1, version-specific mirror	Standard user material interface; source page had slow/scripted HTML but search/open snippets exposed key warnings and variables.
vendor manual mirror	Abaqus User Subroutines Reference Guide 1.2.22, VUMAT	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ch01s02asb22.html	2026-06-08	Tier 1, version-specific mirror	Explicit vectorized user material interface.
vendor manual mirror	Abaqus User Subroutines Reference Guide 1.1.28, UEL	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ch01s01asb28.html	2026-06-08	Tier 1, version-specific mirror	Standard user element interface and LFLAGS procedure contract.
vendor manual mirror	Abaqus Analysis User's Guide 3.2.18, Making user-defined executables and subroutines	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/usb/pt01ch03s02abx18.html	2026-06-08	Tier 1, version-specific mirror	abaqus make, compile/link environment parameters, shared library deployment.
vendor manual mirror	Abaqus User Subroutines Reference Guide 2.1.15, Terminating an analysis	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ch02s01abu15.html	2026-06-08	Tier 1, version-specific mirror	XIT and XPLB_EXIT instead of Fortran STOP.
vendor manual mirror	Abaqus User Subroutines Reference Guide 2.1.22, Ensuring thread safety	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ch02s01abu22.html	2026-06-08	Tier 1, version-specific mirror	Mutex/thread-safety guidance for common blocks, files, and shared resources.
vendor manual mirror	Abaqus User Subroutines Reference Guide 2.1.23, Allocatable arrays	Dassault Systemes SIMULIA, mirrored by University of Colorado	https://ceae-server.colorado.edu/v2016/books/sub/ch02s01abu23.html	2026-06-08	Tier 1, version-specific mirror	Thread-local/global arrays as safer alternatives to common blocks and save variables.
public code repository	davidmorinNTNU/ABAQUS_subroutines	David Morin, NTNU	https://github.com/davidmorinNTNU/ABAQUS_subroutines	2026-06-08	Tier 3 example repository	Fortran examples for UVARM, USDFLD/VUSDFLD, UHARD/VUHARD, UMAT/VUMAT, UEXTERNALDB/VEXTERNALDB. README states examples were checked in Abaqus 2019 double precision with Intel ifort 16.0.8 but are not guaranteed bug-free or validated.

Extracted Facts

Scope and execution model

• Abaqus user subroutines extend features where normal data input is too restrictive. They can be written in C, C++, or Fortran and are supplied at analysis execution time with abaqus job=job-name user={source-file | object-file} or through Abaqus/CAE's user subroutine file field.
• User subroutines are not saved to restart files. A restarted run must include the subroutine again and may include a revised one.
• User subroutines cannot call one another directly. They can call Abaqus-provided utility routines where supported.
• Fortran user subroutines must include aba_param.inc for Standard or vaba_param.inc for Explicit as the first statement after the argument list. C/C++ user subroutines must include aba_for_c.h, use Abaqus Fortran-callable naming conventions, and pass arguments by reference.
• User code must only define variables listed by the subroutine documentation as variables to be defined. Rewriting information-only variables has unpredictable effects.
• The command abaqus make can build user postprocessing executables and user subroutine object/shared libraries. The relevant environment parameters include compile_cpp, compile_fortran, link_exe, and link_sl. Prebuilt user subroutine shared libraries can be found through usub_lib_dir.

Development and debugging constraints

• Abaqus recommends thorough testing on small examples before production use. The manual specifically emphasizes small models where the user subroutine is the only complicated part.
• Debug output can be written to Abaqus-owned units: Standard .msg through unit 7, Standard .dat or Explicit .log through unit 6. Those units must not be opened by user code. Other user files should use allowed unit ranges and full paths because Abaqus uses scratch directories.
• ABA_PARALLEL_DEBUG can increase verbosity and expose compile/link/debug information.
• Use XIT in Standard and XPLB_EXIT in Explicit instead of STOP so Abaqus closes analysis files properly.
• Large arrays should not live on the stack. Native allocatable arrays or Abaqus allocatable-array utilities should be used for large or persistent data.
• Parallel jobs are allowed, but common blocks, common files, global arrays, and shared resources must be guarded for thread safety. Abaqus provides mutex utilities and local/global allocatable array utilities.

Model identity and data conventions

• Coordinates passed to user subroutines are generally global assembly coordinates unless a specific interface says otherwise.
• Node and element numbers passed into user subroutines are Abaqus internal global numbers. GETPARTINFO/VGETPARTINFO and GETINTERNAL/VGETINTERNAL are available when original part instance names and local numbers are needed, but their use is not free.
• Set and surface names passed into user subroutines are uppercase and, for assemblies, prefixed by assembly and part instance names.
• Solution-dependent state variables are allocated differently depending on the subroutine family. Common material subroutines usually use *DEPVAR; UEL uses *USER ELEMENT, VARIABLES=...; contact/interface subroutines use their own option-specific DEPVAR contracts.
• State variable output is available through SDV/SDVn for supported material/integration-point cases.

Standard vs Explicit API shape

• Abaqus/Standard subroutines are generally scalar per material point, element, node, or contact point. Standard material/element/interface subroutines are often called twice in the first iteration of an increment to form initial stiffness and once in later iterations, with extra calls in some dynamic procedures.
• Abaqus/Explicit subroutines use a vector interface: blocks of data for nblock material points are passed to routines such as VUMAT. vaba_param.inc defines maxblk for dimensioning temporary arrays.
• Abaqus/Explicit has single and double precision executables. The precision is determined by the executable and vaba_param.inc; user code should follow Abaqus precision conventions instead of hard-coding incompatible types.

UMAT and VUMAT

• User-defined mechanical behavior is implemented through UMAT for Abaqus/Standard and VUMAT for Abaqus/Explicit. This interface allows arbitrary mechanical constitutive models but is explicitly not a routine exercise.
• UMAT and VUMAT operate on Cauchy stress components. VUMAT quantities are expressed in a corotational coordinate system at the material point, and Abaqus uses the Green-Naghdi stress rate in VUMAT; built-in Explicit materials may use different objective stress rates.
• Mechanical material constants are supplied through *USER MATERIAL. Abaqus/Explicit also requires *DENSITY.
• In Standard, UMAT must return updated stress, updated state variables, and the material Jacobian DDSDDE. The Jacobian strongly controls Newton convergence and computational efficiency. If the Jacobian is nonsymmetric, UNSYMM should be requested.
• In Explicit, VUMAT receives blocks of points and must return stressNew and stateNew; it can also update internal and inelastic energy arrays.
• Element deletion can be controlled by a state variable with *DEPVAR, DELETE=...; deleted material points carry no stress and cannot be reactivated.
• For reduced-integration, beam, shell, and transverse-shear cases, user material behavior may require explicit hourglass or transverse shear stiffness choices because Abaqus may not be able to infer them from user material data.
• Hybrid element behavior with UMAT has special total/incremental/incompressible formulations. Nearly incompressible hyperelastic user materials can converge poorly if the wrong hybrid formulation is used.

UEL and VUEL

• UEL defines an Abaqus/Standard user element. The core interface includes RHS, AMATRX, SVARS, ENERGY, element-level DOF counts, properties, coordinates, displacements, velocities/accelerations as relevant, time, step/increment, and flags.
• LFLAGS drives what the UEL must compute. For normal implicit time incrementation, UEL must define residual vector RHS and Jacobian/stiffness matrix AMATRX; other flag values request stiffness-only, damping-only, mass-only, residual-only, initial acceleration, or perturbation output contributions.
• UEL examples in the manual include a two-node structural user element behaving as a linear truss, with *USER ELEMENT, *ELEMENT, and *UEL PROPERTY input contracts. This is a strong candidate for a first reproducible artifact pattern if the project targets user elements.
• VUEL is the Explicit user element analogue, but this investigation did not yet drill into its detailed interface. It should be treated as a separate research item before implementation planning.

Other relevant subroutine families

• USDFLD/VUSDFLD: redefine field variables at material points; useful for field-dependent material behavior and damage/softening controls.
• UFIELD/VUFIELD: define predefined field variables, often nodal or field-level before interpolation.
• UVARM: generate custom element output in Standard; useful for exposing derived variables from existing material state.
• UEXTERNALDB/VEXTERNALDB: manage external databases, files, cross-subroutine data exchange, or coupling with external programs at key analysis points.
• UHARD/VUHARD: define hardening/yield surface size behavior without replacing the full material update.
• ORIENT: define material/local directions.
• DLOAD/VDLOAD, DISP/VDISP, UAMP/VUAMP: load, motion, and amplitude customization.
• UINTER/VUINTER/VUINTERACTION, FRIC/VFRIC: contact/interface behavior customization.

Observed public example repository patterns

• The NTNU repository contains examples for UVARM, USDFLD/VUSDFLD, UHARD/VUHARD, UMAT/VUMAT, UEXTERNALDB/VEXTERNALDB, plus a Modified Johnson-Cook example combining VUHARD and VUSDFLD.
• Each example folder generally contains a Fortran subroutine, Abaqus input files, post-processing Python scripts, plotting scripts, and a PDF describing the subroutine, input file structure, and results.
• The V_UMAT folder includes paired Standard/Explicit material examples: UMAT.f, UMAT_MODEL.f, VUMAT.f, VUMAT_SHELL.f, Standard/Explicit .inp files, post-processing scripts, plotting scripts, and a talk PDF.
• The V_USDFLD folder contains Standard and Explicit field-variable variants and both patch and two-element post-processing scripts.
• The repository README cautions that the examples were checked but may not be bug-free and are not necessarily validation-quality. Therefore this repository is useful as a development-pattern source, not as acceptance evidence.

Candidate Benchmarks and Verification Artifacts

benchmark_id	source	benchmark_type	physics	target_quantities	artifact_needs	applicability
umat-single-element-elastic	Abaqus manuals, inferred from single-element testing guidance	smoke / analytical	Standard user material	stress, DDSDDE, state variables, convergence behavior	one-element .inp, user material constants, expected analytical stress/Jacobian CSV, .msg summary	Best first harness target for UMAT ABI and constitutive update tests.
vumat-single-element-elastic	Abaqus manuals, inferred from single-element testing guidance	smoke / analytical	Explicit vectorized user material	stressNew, stateNew, energy arrays, stable explicit response	one-element Explicit .inp, density, expected stress history CSV	Tests nblock loop and tensor ordering/precision assumptions.
umat-vs-built-in-linear-elastic	Abaqus material docs and UMAT/VUMAT contract	regression / reference comparison	Standard Cauchy stress update	stress, strain, SDV, reaction/displacement if run through Abaqus	built-in and UMAT .inp pair, reference CSVs from approved Abaqus run	Requires user-generated Abaqus artifacts; not generated by agents.
vumat-vs-built-in-linear-elastic	Abaqus material docs and VUMAT contract	regression / reference comparison	Explicit user material	stress, strain, internal energy, displacement/reaction	built-in and VUMAT .inp pair, reference CSVs	Must control objective-rate and tensor-ordering assumptions.
uel-two-node-truss	Abaqus UEL manual example	analytical / user element	Standard user element	element residual, stiffness, nodal displacement, reaction, energy	*USER ELEMENT truss .inp, UEL source, expected truss analytical CSV	Strong first UEL target; maps cleanly to existing FESA truss/bar solver ideas.
usdfld-field-update	NTNU V_USDFLD examples plus Abaqus field-variable docs	regression / patch	Field-dependent material data	field values, SDV, stress changes driven by field	Standard/Explicit .inp, field/SDV CSVs, post scripts	Example repository useful for structure; official acceptance must come from controlled reference artifacts.
uexternaldb-file-exchange	Abaqus overview and NTNU V_UEXTERNALDB examples	integration / harness	External file/database lifecycle	call order, file creation, increment/step metadata	.inp, user subroutine, expected external log file schema	Useful for harnessing file I/O and thread-safety policy.

Verification Relevance

• code_verification: High. UMAT/VUMAT/UEL logic can be unit-tested outside Abaqus if constitutive kernels or element kernels are factored away from the Abaqus ABI wrapper.
• solution_verification: High but artifact-dependent. Abaqus runs must be performed by a human or approved external process and stored as reference artifacts.
• validation: Out of scope for this first research pass. Public examples and single-element checks do not validate physical material models against experiments.
• reference_comparison: High. The current FESA reference-comparison pattern can be adapted to compare approved Abaqus .odb-extracted CSVs, .dat/.msg summaries, and post-processing outputs.

Applicability Limits

• The main manual sources are Abaqus 2016 mirrors. Interface details must be rechecked against the target installed Abaqus version before implementation.
• Official Dassault documentation may require customer access; the accessible sources here are university mirrors of the 2016 manuals.
• This research does not approve any specific material model, element formulation, stress integration algorithm, or tangent derivation.
• This research does not create, modify, or validate reference CSVs.
• This research does not run Abaqus, compile Fortran, or test compiler/linker compatibility.
• The project harness currently assumes C++17/MSVC/CMake/CTest. Abaqus user subroutine development will likely require a new or extended validation path for Fortran/C/C++ source plus abaqus job=... user=... and/or abaqus make, guarded by environment detection.
• The NTNU examples are useful for repository layout and one/two-element workflows, but their README explicitly limits their verification/validation claims.

Implications for This Project Harness

• The project should not simply rename the existing C++ solver harness. Abaqus user subroutine development has a different execution boundary: source is compiled and linked by the Abaqus execution procedure, not by CMake alone.
• A pragmatic architecture is to split each subroutine into:
  • a thin Abaqus ABI wrapper matching the exact manual signature;
  • a testable kernel for constitutive update, field update, element residual/tangent, or external database behavior;
  • small Abaqus .inp reference models and approved CSV/log artifacts.
• The current TDD guard should be extended or complemented for Fortran/C/C++ Abaqus source. For production subroutine changes, require either:
  • a kernel unit test, or
  • an Abaqus artifact comparison test, or
  • both for UMAT/VUMAT/UEL.
• Workspace validation should gain explicit modes:
  • no-Abaqus mode: run Python harness tests and pure kernel tests only;
  • Abaqus-available mode: run compile/link smoke tests and selected abaqus job=... user=... reference cases;
  • artifact-comparison mode: compare stored solver output CSV/log artifacts without rerunning Abaqus.
• Reference artifact contracts should include .inp, user subroutine source version/hash, Abaqus version, compiler version, precision, command line, .msg/.dat/.log tail, extracted CSVs, and post-processing script provenance.
• For UMAT/VUMAT, the first implementation gate should focus on a simple elastic or J2 plastic single-element model before complex material laws.
• For UEL, the first implementation gate should focus on a two-node truss/bar element because it has analytical residual/stiffness checks and aligns with the existing FESA solver roadmap.

Downstream Handoff

Requirement Agent

• Decide the primary target: UMAT, VUMAT, UEL/VUEL, field subroutines, output subroutines, or external database routines.
• Record target Abaqus version, operating system, compiler/toolchain, and whether Abaqus is available for local validation.
• Define whether the project will develop Fortran-first subroutines, C/C++ subroutines, or Fortran ABI wrappers over C++ kernels.

I/O Definition Agent

• Define supported Abaqus input keyword subset for each target subroutine family:
  • UMAT/VUMAT: *MATERIAL, *USER MATERIAL, *DEPVAR, *DENSITY, output requests.
  • UEL: *USER ELEMENT, *UEL PROPERTY, *ELEMENT, output requests.
  • USDFLD/VUSDFLD: *FIELD, *DEPVAR, material field dependency contracts.
• Define CSV schemas for stress, strain, state variables, element residual/stiffness summaries, displacement, reaction, energy, and call-log/debug outputs.

Reference Model Agent

• Start with one-element UMAT/VUMAT and two-node UEL truss models.
• Require metadata for Abaqus version, compiler version, precision, command, input deck, source hash, and extraction script.
• Treat all generated Abaqus outputs as read-only reference artifacts after approval.

Implementation Planning Agent

• Plan RED tests around pure kernels first, then ABI wrapper compile smoke, then Abaqus artifact comparison if Abaqus is available.
• Require targeted tests for tensor component ordering, state variable allocation, material constant parsing, element deletion flags, and DDSDDE symmetry/unsymmetry policy.
• Preserve no-Abaqus validation path so the repository remains testable without commercial solver access.

Numerical Review Agent

• For UMAT, review stress update algorithm, objective rates, state integration, consistent tangent, symmetry, and hybrid/incompressible assumptions.
• For VUMAT, review corotational frame assumptions, vectorization loop, stable explicit response, energy accounting, and deleted material point behavior.
• For UEL, review residual sign convention, tangent consistency, mass/damping/stiffness contributions, LFLAGS branching, and energy terms.

Open Issues

• Target Abaqus version is not yet specified. The cited manuals are Abaqus 2016.
• Target implementation language is not yet specified. Abaqus supports Fortran, C, and C++, but most public examples and legacy workflows are Fortran-first.
• Windows compiler compatibility is not yet specified. Abaqus, Visual Studio, Intel Fortran/oneAPI, and MSVC versions must be aligned.
• It is not yet clear whether local Abaqus execution is available in this workspace. The current harness should keep a no-Abaqus path.
• The project needs a license policy for third-party example code before copying or adapting code from public repositories.