Abaqus UEXTERNALDB Subroutine | Step-by-Step Guide

When working with complex simulations in Abaqus, there often comes a point where built-in tools aren’t enough. Whether you’re integrating data from a previous run, feeding in external data sets, or saving simulation results for further analysis — this is where UEXTERNALDB Subroutine shines.

In this complete guide, we break down everything you need to know about this powerful user subroutine: what it does, why it matters, and how you can master it.

1. What is Abaqus UEXTERNALDB​ Subroutine and when it’s used?

The UEXTERNALDB user subroutine is invoked at the start of the analysis, at the commencement of each increment, at the conclusion of each increment, and at the end of the analysis.

This subroutine facilitates communication between other software and user subroutines within ABAQUS/Standard. It allows for the opening of external files required by other user subroutines at the start of the analysis and ensures these files are closed at the end of the analysis.

Furthermore, it can be utilized to compute or retrieve historical data at the beginning of each increment, which can then be stored in user-defined COMMON block variables or external files for subsequent use by other user subroutines during the analysis.

2. Why Use UEXTERNALDB Subroutine?

• Key use cases

• • Initialize simulations with data from a previous run
  • Log evolving internal variables (e.g., crack length, damage index)
  • Transfer data between coupled simulations or co-simulation environments

• Benefits over other methods like Python scripting

UEXTERNALDB enables real-time, in-simulation data exchange — unlike Python scripting, which is limited to pre- and post-processing. It ensures persistent data tracking, seamless communication with external programs or databases, and dynamic control throughout the simulation process.

3. How UEXTERNALDB Works: Behind the Scenes

The UEXTERNALDB subroutine is a user-defined entry point that interacts with Abaqus at specific stages of a simulation job. It enables communication between the simulation environment and external data sources, tools, or scripts — without modifying the core model file.

Data Flow and Interaction

• Input: UEXTERNALDB reads in or writes out data such as material properties, boundary conditions, geometry parameters, or custom metadata. This data typically resides in external files (e.g., CSV, text, databases) or is passed through user logic.
• Output: The subroutine can write processed inputs, results, or logs back to external storage, enabling automated tracking or coupling with other tools (e.g., optimization frameworks or ML pipelines).
• Control Flow: Based on flags and variables (like LOP, STEP, or TIME), the subroutine decides what logic to execute at each stage.

Timing of when it’s called during analysis

Abaqus calls UEXTERNALDB at predefined points in the analysis lifecycle:

LOP

LOP=0 indicates that the subroutine is being called at the start of the analysis.

LOP=1 indicates that the subroutine is being called at the start of the current analysis increment. The subroutine can be called multiple times at the beginning of an analysis increment if the increment fails to converge and a smaller time increment is required.

LOP=2 indicates that the subroutine is being called at the end of the current analysis increment. When LOP=2, all information that you need to restart the analysis should be written to external files.

LOP=3 indicates that the subroutine is being called at the end of the analysis.

LOP=4 indicates that the subroutine is being called at the beginning of a restart analysis. When LOP=4, all necessary external files should be opened and properly positioned and all information required for the restart should be read from the external files.

The above explanations are summarized in the table below:

Understanding this flow is critical for writing efficient and error-free subroutines.

4. Basic Syntax and Structure of a UEXTERNALDB Subroutine

User UEXTERNALDB Subroutine interface Fortran code is shown in Figure 1. Here’s the template you’ll typically start with:

Figure 1: UEXTERNALDB Subroutine Interface

Variables to be defined

None.

Variables passed in for information

• LOP
  • LOP=0 indicates that the subroutine is being called at the start of the analysis.
  • LOP=1 indicates that the subroutine is being called at the start of the current analysis increment. The subroutine can be called multiple times at the beginning of an analysis increment if the increment fails to converge and a smaller time increment is required.
  • LOP=2 indicates that the subroutine is being called at the end of the current analysis increment. When LOP=2, all information that you need to restart the analysis should be written to external files.
  • LOP=3 indicates that the subroutine is being called at the end of the analysis.
  • LOP=4 indicates that the subroutine is being called at the beginning of a restart analysis. When LOP=4, all necessary external files should be opened and properly positioned and all information required for the restart should be read from the external files.
• LRESTART
  • LRESTART=0 indicates that an analysis restart file is not being written for this increment.
  • LRESTART=1 indicates that an analysis restart file is being written for this increment.
  • LRESTART=2 indicates that an analysis restart file is being written for this increment and that only one increment is being retained per step so that the current increment overwrites the previous increment in the restart file (see “Restarting an analysis,” Section 9.1.1 of the ABAQUS Analysis User’s Manual).
• TIME(1)

Value of current step time.

• TIME(2)

Value of current total time.

Let us explore the concepts of step, increment, and step time: The term ‘step’ denotes the analytical approach you establish to address the issue at hand. This may involve either a singular step or a series of steps. For more details, you can check out this article: “Step by Step Guide to Abaqus DLOAD & VDLOAD Subroutines”

• DTIME

Time increment.

• KSTEP

Current step number. When LOP=4, KSTEP gives the restart step number. 

• KINC

Current increment number. When LOP=4, KINC gives the restart increment number.

5. A Practical Example: Saving and Reading Custom Data

In this section, we are going to talk about how we can import or export data to or from the ABAQUS using the UEXTERNALDB subroutine.

Problem description:

Here’s an example showing how we can use that subroutine. Suppose we have an object that is meshed with 10 elements according to the following figure and we are going to assume that each element is going to have its own strength or young modules etc.

Figure 2: Object which is meshed with 10 elements

Let’s say we’ve already saved the required data in a .inp, .dat, or .txt file, and now we want to import that data into ABAQUS.

Here’s how to do it:

First, we need to open the specific data file. For example, suppose the file is saved at:

C:\Users\txt1.dat.

We’ll load the data from this file and refer to it as file number 15 in the code. We’ll also use the status UNKNOWN, which tells ABAQUS to proceed whether or not the file already exists in the directory.

Required commands:

OPEN (15, file=”C:\\Users\\txt1.dat”, status=’UNKNOWN’,form=’FORMATTED’,iostat=error)

We will use the commands mentioned earlier inside the UEXTERNALDB subroutine. This subroutine is quite straightforward, but there is one important point to keep in mind.

The UEXTERNALDB subroutine is called once at the beginning of each analysis, increment, or step. It can also be used to open external files, read history data, or write history data.

The key part of this subroutine is the LOP variable. LOP is an integer that tells Abaqus when to open, read, or write the file.

For example, if we only want to read or import data at the start of the analysis (and avoid using memory during each increment), we set LOP = 0. This is useful when the analysis has many increments since reading the file at every increment would allocate memory repeatedly.

Alternatively, setting LOP = 1 reads the file at the start of every step, and LOP = 2 reads or writes the file at the end of every increment. And so on, depending on when you want the file to be accessed.

Now, let’s see how to import data for the example problem we discussed earlier.

Continuing with the subroutine, we’ll start by showing the contents of our .dat file. This file contains the strength values of the elements based on their coordinates.

Figure 3: Contents of data file

For example, as shown in Figure 2, elements 1 to 5 are aligned in one side, and elements 6 to 10 are aligned in another side. (See figure 2)

First, elements 1, 2, 3, 4, and 5 will have strength values from the first column, as shown in Figure 3. The other elements — 6, 7, 8, 9, and 10 — will use the strength values from the second column in Figure 3.

Next, we will implement our updated UEXTERNALDB subroutine:

Figure 4: UEXTERNALDB Subroutine Example

First, we’ll define a matrix to hold our data. In this case, it’s a 5×2 matrix, as shown in figure 3. Then, we’ll reshape this matrix into a 1×10 array.

This is because subroutines like UMAT receive the element number directly. So, if we have, for example, 100 elements, it’s much easier to manage the data using a 1×100 array, where each position corresponds to a specific element.

This reshaped format also makes it easier to import values like “randomSigma” and “randomSigma2”, which represent element-specific strengths or properties. (See figure 4 line 5)

In other subroutines, we need to create a common block to store this data in the matrices, which we’ll name matrix.

Next, we’ll set LOP = 0 so that ABAQUS reads the input data only once at the start of the analysis.

To do this, we’ll use the OPEN command with file number 15 for our specific data file. The actual file number doesn’t matter much, as long as it’s consistent throughout the subroutine.

An important part of this command is the keyword IOSTAT, which reports the status of the file operation. For example, if IOSTAT = 0, it means the file was read successfully without any errors.

Figure 5: iostat keyword

Next, we will reshape the “randomSigma” matrix into “randomSigma2”. To do this, we’ll use the reshape function in the following format.

As you can see, the reshape function changes the randomSigma matrix from a 5×2 size into randomSigma2, which is 1×10. (See figure 5 line 21)

Next, we’ll use the path provided by Windows to make Abaqus read our data file.

Remember, Abaqus requires using double backslashes (\) in file paths instead of single backslashes. For example: C:\\Users\\YourFolder\\txt1.dat

Next, to use our input data, we will save it into the “randomSigma2” variable within our UMAT subroutine and store it in the “statev” array.

Figure 6: statev array

We have data for 10 elements or 10 measurements. Abaqus passes the number of elements to the UMAT subroutine, and UMAT reads the corresponding values from the randomSigma2 matrix. These values are then assigned to xfx parameters. We will use the statev array to store and display this data. When we run the simulation, we can verify that the statev(1) parameter is correctly assigned with these values, as shown in the following figure.

Figure 7: UEXTERNALDB Example results

6. Common Pitfalls and Debugging Tips

Implementing UEXTERNALDB can be challenging, especially when dealing with compilation or runtime issues. Here are common pitfalls and how to address them:

Compilation and Linking Issues

• Compiler Compatibility: Ensure you’re using a compiler supported by your version of Abaqus (e.g., Intel Fortran).
• Environment Setup: Verify that environment variables (e.g., ABAQUS_FORT_COMPILER) are correctly configured.
• Missing Symbols: Check that all subroutines and libraries are properly declared and linked. Use consistent naming conventions.
• Static vs. Dynamic Linking: Be aware of platform-specific differences, especially when linking to external libraries or DLLs.

Common Logical Errors and How to Trace Them

• Incorrect File Paths: Use debug print statements to confirm file locations and names at runtime.
• Uninitialized Variables: Initialize all variables explicitly to avoid unpredictable behavior.
• Wrong Step/Stage Execution: Use the LOP and TIME variables to confirm which phase of the analysis the subroutine is in.
• Silent Failures: If the subroutine doesn’t behave as expected, insert log messages or write debug info to an external file.
• Data Type Mismatches: Be careful with integer vs. real precision. Use consistent types across function calls.

Tip: Start simple—test with a minimal working example before scaling up. This makes it easier to isolate issues and build confidence in your implementation.

7. Best Practices for Writing Efficient UEXTERNALDB Code

Writing efficient UEXTERNALDB code is key to maintaining robust, scalable simulation workflows. Below are best practices to ensure performance and maintainability:

File Handling

• Use absolute paths or relative paths based on environment variables to avoid file access issues.
• Open files only when needed, and close them promptly to prevent file locks or memory leaks.
• Avoid redundant reads/writes, especially in large-scale parametric studies. Buffer data when possible.

Performance Tips

• Minimize I/O operations inside loops or large simulations; pre-load or cache data early in the workflow.
• Profile your subroutine to identify bottlenecks using timers or lightweight logs.
• Use binary or structured file formats (e.g., HDF5, CSV) for large datasets to speed up read/write operations.

Modularization

• Separate logic into reusable subroutines (e.g., for reading data, processing parameters, logging outputs).
• Use meaningful variable names and comments to improve code readability and reduce debugging time.
• Encapsulate configuration (e.g., file paths, constants) in a single module to ease future updates.

Efficient UEXTERNALDB code not only accelerates simulations but also makes your workflow easier to debug, extend, and share across teams.

8. Advanced Use Cases

The UEXTERNALDB subroutine extends Abaqus functionality by enabling seamless integration with external tools and advanced automation. Two key areas where it excels are:

• Coupling with external tools or databases
• Material property retrieval from centralized databases.
• Automated logging of input/output data for traceability.
• Integration with design tools like DoE frameworks or custom scripts.
• Communication with other software, including optimization engines or cloud APIs.

This ensures data consistency, reduces manual effort, and supports complex workflows.

• Automating parametric studies or ML integration

UEXTERNALDB is ideal for automating large simulation campaigns and supporting AI-driven methods:

• Parametric simulations can be controlled via external input files, reducing manual updates.
• Surrogate or ML model integration, where predictions are imported to guide simulations.
• Automated data extraction for building or updating machine learning datasets.
• Adaptive workflows, where simulation results influence the next run in an optimization loop.

9. Comparison with Other User Subroutines

Use UEXTERNALDB when you need persistent, external, model-independent data handling during the analysis.

10. Conclusion

Mastering the UEXTERNALDB subroutine in Abaqus enables advanced simulations by allowing integration with external data sources. This article focused on the UEXTERNALDB subroutine in Abaqus, and explains its purpose, benefits, and structure, helping users at all levels implement it effectively. Key uses include initializing data, exporting results, and facilitating communication between steps—offering advantages over methods like Python scripting. The article also covers how UEXTERNALDB interacts with the simulation process, explains its syntax, and provides a practical coding example. Finally, it highlights common errors, debugging tips, and the broader benefits of using UEXTERNALDB to enhance simulation control and automation.