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.